Run an agent and stream its events

Send an AG-UI RunAgentInput body to a run route and read the AG-UI events it streams back.

Endpoints

All paths start with /api/v1/agents-v2 and need X-Space-Slug.

• The /runs/ routes need background runs enabled on the server; otherwise they return 404 Background agent runs are disabled.
• Background run events are kept for a limited time after the run ends.

Chat history

• Saved history is a chat; the chat routes are bearer only (Read and share chats). With an API key, read a background run's events through /runs/{run_id}/history/, or an agent's chats through Lab with the lab scope.
• To continue a conversation, reuse its threadId. With saved history the server replays the stored conversation and uses only the last user message from messages.
• With ?save_history=false or an inline config nothing is stored: send the whole conversation in messages on every run.

Request fields

Every top-level key is required: threadId, runId, state, messages, tools, context and forwardedProps.

Stream a run

1. Pick a threadId, or reuse one to continue a conversation.

2. Send the body with Accept: text/event-stream:

   curl -N -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/run-stream/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Accept: text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "contract-demo-1",
       "runId": "run-1",
       "state": null,
       "messages": [{"id": "m1", "role": "user", "content": "Summarize the renewal terms."}],
       "tools": [],
       "context": [],
       "forwardedProps": {}
     }'

3. Read events until RUN_FINISHED or RUN_ERROR; either one ends the run.

Run in the background

1. Start the run with the same body; the response holds its run_id (chat_id is null when history is not saved):

   curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/runs/?agent_id=42" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Content-Type: application/json" \
     -d '{"threadId": "contract-demo-2", "runId": "run-1", "state": null, "messages": [{"id": "m1", "role": "user", "content": "Summarize the renewal terms."}], "tools": [], "context": [], "forwardedProps": {}}'

2. Stream its events from GET /api/v1/agents-v2/runs/{run_id}/events/?last_id=0. Each chunk starts with an id: line; after a disconnect, reconnect with last_id set to the last id you received. The stream closes with a : done comment.

3. To stop the run, send POST /api/v1/agents-v2/runs/{run_id}/cancel/.

Override settings for one run

1. Put the overrides in forwardedProps.runtimeConfig; connections you list are added to the agent's own:

   curl -N -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/run-stream/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -H "Accept: text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "contract-demo-1",
       "runId": "run-2",
       "state": null,
       "messages": [{"id": "m2", "role": "user", "content": "Compare it with last year."}],
       "tools": [],
       "context": [],
       "forwardedProps": {
         "mode": "act",
         "runtimeConfig": {
           "connection_ids": [17],
           "mcp_connection_ids": [7],
           "model_config_id": 12
         }
       }
     }'

Attach files

1. Upload the file; the response is 201 with {id, name, mime_type, size, gc_url, file_metadata, presigned_url}:

   curl -X POST "$CENTRAL_HUB_URL/api/v1/agents-v2/files/upload/" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG" \
     -F "file=@contract.pdf;type=application/pdf"

2. Add {"id": "<id>"} to forwardedProps.files. The file is copied into the agent's sandbox at /home/user/uploads/<id>-<name> and the agent is told its path. Only your own uploads are resolved.

3. Optional: to let the model read the file directly, add a content part to the last user message; use "type": "image" for images. Files the model cannot take directly are left to the sandbox copy.

   {"type": "document", "source": {"type": "url", "id": "<id>", "name": "contract.pdf", "mimeType": "application/pdf", "value": "<presigned_url>"}}

Download a generated file

1. Take path and fileId from the run's FILE_GENERATED event, {type, toolCallId, path, name, mimeType, size} plus fileId once the file is stored.

2. Request a link with the run's agent_id and thread_id:

   curl "$CENTRAL_HUB_URL/api/v1/agents-v2/agents/42/sandbox/files/presigned-url/?path=/home/user/report.xlsx&thread_id=contract-demo-1&file_id=<fileId>&expires_in_seconds=600" \
     -H "X-API-Key: $ALO_API_KEY" \
     -H "X-Space-Slug: $WORKSPACE_SLUG"

3. Download from url in the response, {url, expires_in_seconds}.

Troubleshooting