Skip to Content
kosemdocs
GuidesAgents

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).

Set your API key (Call the API) and your project's ID first:

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

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).

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:

{
  "name": "projects/prj_01m5r9dh9mf0ps98ktkap3562c/agents/ags_01m5rg8kq2e9vbt6g0d4x7qz1s",
  "state": "IDLE",
  "visibility": "PROJECT",
  "lastSequence": 1
}
export KOSEM_AGENT='ags_01m5rg8kq2e9vbt6g0d4x7qz1s'

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:

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

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:

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

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

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": {}}]}'

On this page