API Reference
Run an agent
Runs a persisted agent and streams AG-UI events (text/event-stream). Tools, MCP servers, knowledge bases, and the system prompt come from the stored agent. A tools array on this request does not add capabilities. state may override max_steps and compress_context for this run only. Nested model calls use /v1/chat/completions. See Agents.
POST
/
v1
/
agent
/
{agent_id}
/
run
Run an agent
curl --request POST \
--url https://api.synapsai.cloud/v1/agent/{agent_id}/run \
--header 'Content-Type: application/json' \
--data '
{
"threadId": "<string>",
"runId": "<string>",
"messages": [
{
"id": "<string>",
"content": "<unknown>",
"toolCallId": "<string>",
"toolCalls": [
{}
]
}
],
"parentRunId": "<string>",
"tools": [
{}
],
"context": [
{}
],
"state": {},
"forwardedProps": {},
"resume": "<unknown>"
}
'import requests
url = "https://api.synapsai.cloud/v1/agent/{agent_id}/run"
payload = {
"threadId": "<string>",
"runId": "<string>",
"messages": [
{
"id": "<string>",
"content": "<unknown>",
"toolCallId": "<string>",
"toolCalls": [{}]
}
],
"parentRunId": "<string>",
"tools": [{}],
"context": [{}],
"state": {},
"forwardedProps": {},
"resume": "<unknown>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<string>Body
application/json
AG-UI run input. Field names are camelCase on the wire.
Response
AG-UI Server-Sent Events. Event types include RUN_STARTED, TEXT_MESSAGE_CONTENT, TOOL_CALL_START, TOOL_CALL_RESULT, RUN_FINISHED, and RUN_ERROR. The run keeps going if the client disconnects. X-Run-Id identifies it.
The response is of type string.
⌘I
Run an agent
curl --request POST \
--url https://api.synapsai.cloud/v1/agent/{agent_id}/run \
--header 'Content-Type: application/json' \
--data '
{
"threadId": "<string>",
"runId": "<string>",
"messages": [
{
"id": "<string>",
"content": "<unknown>",
"toolCallId": "<string>",
"toolCalls": [
{}
]
}
],
"parentRunId": "<string>",
"tools": [
{}
],
"context": [
{}
],
"state": {},
"forwardedProps": {},
"resume": "<unknown>"
}
'import requests
url = "https://api.synapsai.cloud/v1/agent/{agent_id}/run"
payload = {
"threadId": "<string>",
"runId": "<string>",
"messages": [
{
"id": "<string>",
"content": "<unknown>",
"toolCallId": "<string>",
"toolCalls": [{}]
}
],
"parentRunId": "<string>",
"tools": [{}],
"context": [{}],
"state": {},
"forwardedProps": {},
"resume": "<unknown>"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<string>