# Send agent events

`POST /v1/projects/{project}/agents/{agent}/events`, operation `agents.SendAgentEvents`

Sends events to an agent, in order: messages, config changes, answers to its questions and interrupts. They are added to the transcript, which the response returns them as, and the agent acts on them.

A message or an answer makes the agent act on the caller's turn, so the caller needs only to write to the agent. What changes nothing adds no event: an interrupt of an idle agent, a config change to the config the agent has, and an answer to a call of the last agentMessage that has its result. An answer to a call that is not in the last agentMessage fails with failed_precondition and the reason CALL_NOT_OPEN.

## Parameters

| Name | In | Required | Type | Description |
| --- | --- | --- | --- | --- |
| `project` | path | Yes | `string` | The project's ID. |
| `agent` | path | Yes | `string` | The agent's ID. |
| `requestId` | query | No | `string (uuid)` | Makes retries safe: sending again with the same ID to the agent returns the events the first request added, rather than adding them again. While the agent's model writes, what the first sent waits for its answer, and a retry adds nothing more. |

## Request body

Content-Type: `application/json` (required)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | `AgentInput[]` | Yes | The events. |

## Responses

### 200

OK

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `agent` | `Agent` | Yes | The agent after them. |
| `agent.activityTime` | `string (date-time)` | Yes | When the agent was last active, as people see it, which lists order agents by: when it was created, someone wrote to it or answered it, or it stopped, as it finished its turn, asked a question, was interrupted or failed. Unlike updateTime, the steps of a turn leave it. |
| `agent.awaitingCalls` | `string[]` | Yes | The tool calls that the agent waits for answers to, in AWAITING_INPUT. |
| `agent.config` | `AgentConfig` | Yes | How the agent works. Set when the agent is created, then changed only by configChange events. |
| `agent.createTime` | `string (date-time)` | Yes | When the agent was created. |
| `agent.creator` | `string` | Yes | Who created the agent, such as user:usr_…. |
| `agent.environment` | `AgentEnvironment` | No | The agent's environment, which its first command makes; absent while it has none. |
| `agent.jobs` | `AgentJob[]` | Yes | The background jobs that the agent left running and is told the end of, while its environment runs. As each ends, it starts a turn of an IDLE agent, unless someone interrupted its last turn, so an agent that finished its turn with jobs goes on when they end. |
| `agent.lastSequence` | `integer (int64)` | Yes | The sequence of the transcript's last event. |
| `agent.lastStop` | `AgentStop` | No | Why the agent last stopped; absent until it first does. |
| `agent.name` | `string` | Yes | Resource name, projects/{project_id}/agents/{agent_id}. |
| `agent.state` | `string` | Yes | What the agent is doing: IDLE with nothing to do, as lastStop says, until a message starts it again; QUEUED with work it starts on shortly; RUNNING; or AWAITING_INPUT, waiting for answers to the tool calls in awaitingCalls, such as a question it asked. Values: `IDLE`, `QUEUED`, `RUNNING`, `AWAITING_INPUT`. |
| `agent.title` | `string` | Yes | A title for people, at most 200 characters. Empty until the agent writes one after its first answer, unless someone set it. |
| `agent.unread` | `boolean` | Yes | Whether the agent stopped since the caller last read it: it finished its turn, failed or reached a limit, and is IDLE. Only for agents the caller follows, as people follow those they created, sent to or marked unread; always false for service accounts. MarkAgentRead marks it read. |
| `agent.updateTime` | `string (date-time)` | Yes | When the agent last changed, or had an event. |
| `agent.usage` | `AgentUsage` | Yes | What the agent used, all told. |
| `agent.visibility` | `string` | Yes | Who sees the agent: PROJECT, everyone who may see the project's agents, by their roles on it; PRIVATE, its owner, those it is shared with through its IAM policy, and those who hold agents.agents.accessPrivate on the project. Values: `PROJECT`, `PRIVATE`. |
| `events` | `AgentEvent[]` | Yes | The events the inputs added, in order. An input may add none, or several: an interrupt adds the results of the calls it closes, and a status. |

### default

Error

Base URL: `https://api.kosem.ai`. See [API conventions](https://docs.kosem.ai/reference/api-conventions.md) for authentication, pagination and errors, and [https://docs.kosem.ai/openapi.yaml](https://docs.kosem.ai/openapi.yaml) for the full OpenAPI document.