# Run an agent from the API

Create an agent, send it a message and stream its transcript as server-sent events with curl.

Start an agent, send it a task and follow its progress over HTTP. To do it, you need an API key for a service account with Owner, Editor, Agents Admin or Agents User on the project, and a model already added to the project ([Add models to a project](/guides/llm-gateway/add-models-to-a-project)).

Set your API key ([Call the API](/get-started/call-the-api)) and your project's ID first:

```sh
export KOSEM_API_KEY='kosem_sk_…'
export KOSEM_PROJECT='prj_01m5r9dh9mf0ps98ktkap3562c'
```

## Create an agent [#create-an-agent]

`POST /v1/projects/{project}/agents` takes the agent's complete configuration: its `model` alias, `environment` size and timeouts, and the `tools` it can call (`GET /v1/tools` lists every tool ID).

```sh
curl -s -X POST "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/agents" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "model": "fast",
      "tools": ["exec", "read_file", "write_file"],
      "environment": {
        "vcpus": 2,
        "memoryMib": 8192,
        "diskGib": 10,
        "idleTimeoutSeconds": 300,
        "stoppedTtlSeconds": 172800
      }
    }
  }'
```

kosem answers with the new agent in `IDLE` state. Keep its ID from `name`:

```json
{
  "name": "projects/prj_01m5r9dh9mf0ps98ktkap3562c/agents/ags_01m5rg8kq2e9vbt6g0d4x7qz1s",
  "state": "IDLE",
  "visibility": "PROJECT",
  "lastSequence": 1
}
```

```sh
export KOSEM_AGENT='ags_01m5rg8kq2e9vbt6g0d4x7qz1s'
```

## Send a message [#send-a-message]

Send a user message with `POST /v1/projects/{project}/agents/{agent}/events`. Pass a UUID in `requestId` so retrying after a network error doesn't add the message twice:

```sh
curl -s -X POST "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/agents/$KOSEM_AGENT/events?requestId=9a1c3f10-7b3d-4e0e-8d12-1b9c6e2f4a01" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "message": {
          "parts": [
            { "text": "Write a Python script that prints the first 10 prime numbers, run it, and show me what it prints." }
          ]
        }
      }
    ]
  }'
```

## Stream events [#stream-events]

Follow the agent live over server-sent events with `GET /v1/projects/{project}/agents/{agent}/events/stream`. Pass `after=0` to receive the full transcript, or the last `sequence` you saw when reconnecting:

```sh
curl -s -N "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/agents/$KOSEM_AGENT/events/stream?after=0" \
  -H "Authorization: Bearer $KOSEM_API_KEY"
```

The stream emits these event types:

- `event` — a committed transcript event (message, tool call, tool result, status change or config change), numbered by `sequence`.
- `delta` — streamed text or reasoning tokens while the model writes.
- `toolOutput` — live output from a running command.
- `agent` — the updated agent resource whenever its `state` or environment changes (watch for `state: "IDLE"` or `state: "AWAITING_INPUT"`).
- `heartbeat` — emitted after 15 seconds of silence.
- `error` — ends the stream if an error occurs after it started.

Streams close after 15 minutes; reconnect with `after` set to the last `sequence` you received to resume without gaps.

## Interrupt an agent [#interrupt-an-agent]

To stop an agent while it's working, send an `interrupt` event:

```sh
curl -s -X POST "https://api.kosem.ai/v1/projects/$KOSEM_PROJECT/agents/$KOSEM_AGENT/events" \
  -H "Authorization: Bearer $KOSEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"interrupt": {}}]}'
```

## Related [#related]

- [Agents](/concepts/agents)
- [Give an agent a secret](/guides/secrets/give-an-agent-a-secret)
- [API conventions](/reference/api-conventions)
- [Errors](/reference/errors#agents)
