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 bysequence.delta— streamed text or reasoning tokens while the model writes.toolOutput— live output from a running command.agent— the updated agent resource whenever itsstateor environment changes (watch forstate: "IDLE"orstate: "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": {}}]}'