Agents

An agent is a saved configuration on top of a model you have already deployed. It stores the system prompt, built-in tools, MCP servers, knowledge bases, and loop limits. You create and edit agents in the dashboard. You run them with the API. The run endpoint streams AG-UI events. Tools, MCP servers, knowledge bases, and the system prompt always come from the stored agent. A tools array on the request is accepted for protocol compatibility and does not add capabilities.

What you configure

Setting	Purpose
Model	A deployed model the agent calls through `/v1/chat/completions`
System prompt	Instructions inserted ahead of the conversation
Tools	Built-in tools the model may call
MCP servers	Your own Model Context Protocol servers
Knowledge bases	Collections the agent can search. On the API these are vector stores
Max steps	Cap on graph steps (1–500). Omit it for the platform default
Compress context	Summarize older turns when the context grows
Data store	Persist the run when you want it stored with the account

Built-in tools:

Tool	What it does
`web_search`	Search the public web
`http_fetch`	Fetch a public page and return readable text. Private and loopback addresses are refused
`run_python`	Run Python in a fresh sandboxed interpreter
`calculator`	Evaluate a math expression
`delegate_task`	Hand a subtask to a sub-agent with its own context

When the agent has knowledge bases, SynapsAI also attaches search_knowledge_base and retrieve_knowledge_base_content. Those are not listed in the tool picker. MCP servers use streamable_http or sse and require a url. Each server needs a name. Stdio MCP is disabled unless the deployment explicitly allows it.

Run an agent

POST /v1/agent/{agent_id}/run returns text/event-stream. Authenticate with your API key. The key must be allowed to call the agent’s model.

from synapsai import SynapsAI

client = SynapsAI()

for event in client.agents.run(
    "agt_your_agent_id",
    messages=["What does the handbook say about API keys?"],
):
    if event.type == "TEXT_MESSAGE_CONTENT" and event.delta:
        print(event.delta, end="", flush=True)
    elif event.type == "RUN_ERROR":
        print("\nError:", event.message)
    elif event.type == "RUN_FINISHED":
        print()

curl https://api.synapsai.cloud/v1/agent/agt_your_agent_id/run \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -N \
  -d '{
    "threadId": "thread-1",
    "runId": "run-1",
    "messages": [
      {"id": "m1", "role": "user", "content": "What does the handbook say about API keys?"}
    ],
    "tools": [],
    "context": [],
    "forwardedProps": {}
  }'

The Python SDK accepts plain strings, message dicts, or AgentMessage objects. It fills in threadId and runId when you omit them. The JSON body uses AG-UI camelCase (threadId, runId, forwardedProps). state can override max_steps and compress_context for that run. It cannot change tools, MCP servers, knowledge bases, or the system prompt.

Send a conversation

messages can be a list of turns. Include prior user and assistant messages, then the latest user message.

for event in client.agents.run(
    "agt_your_agent_id",
    messages=[
        {"id": "m1", "role": "user", "content": "What does the handbook say about API keys?"},
        {"id": "m2", "role": "assistant", "content": "Rotate them from the dashboard and store the new key in your secret manager."},
        {"id": "m3", "role": "user", "content": "How often should I rotate them?"},
    ],
):
    if event.type == "TEXT_MESSAGE_CONTENT" and event.delta:
        print(event.delta, end="", flush=True)

curl https://api.synapsai.cloud/v1/agent/agt_your_agent_id/run \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -N \
  -d '{
    "threadId": "thread-1",
    "runId": "run-2",
    "messages": [
      {"id": "m1", "role": "user", "content": "What does the handbook say about API keys?"},
      {"id": "m2", "role": "assistant", "content": "Rotate them from the dashboard and store the new key in your secret manager."},
      {"id": "m3", "role": "user", "content": "How often should I rotate them?"}
    ],
    "tools": [],
    "context": [],
    "forwardedProps": {}
  }'

Events

`type`	Meaning
`RUN_STARTED`	The run began
`TEXT_MESSAGE_START`	An assistant message started
`TEXT_MESSAGE_CONTENT`	A text delta (`delta`)
`TEXT_MESSAGE_END`	The assistant message ended
`TOOL_CALL_START` / `TOOL_CALL_ARGS` / `TOOL_CALL_END`	A tool call
`TOOL_CALL_RESULT`	Tool output (`content`)
`RUN_FINISHED`	The run completed
`RUN_ERROR`	The run failed (`message`)

Python SDK

Create and edit the agent in the dashboard. Run it from the SDK against https://api.synapsai.cloud/v1. The SDK turns strings and message dicts into the AG-UI body and yields parsed events.

from synapsai import SynapsAI

client = SynapsAI()

for event in client.agents.run(
    "agt_your_agent_id",
    messages=["What does the handbook say about API keys?"],
):
    if event.type == "TEXT_MESSAGE_CONTENT" and event.delta:
        print(event.delta, end="", flush=True)

AsyncSynapsAI supports async for event in client.agents.run(...). Optional arguments include thread_id, run_id, and state (max_steps, compress_context). Passing tools does not add tools beyond the saved agent.

Billing

Each model call inside the loop goes through /v1/chat/completions, so usage, tracing, and rate limits apply to the underlying model. The agent id scopes which configuration is loaded; it is not a separate inference endpoint for the model itself. Enable the data store on the agent if you want runs retained. See Responses for the same store behavior on /v1/responses.

Getting started

Products

Guides

Examples

Manage

Platform

Resources

Support

Legal

What you configure

Run an agent

Send a conversation

Events

Python SDK

Billing

​What you configure

​Run an agent

​Send a conversation

​Events

​Python SDK

​Billing

What you configure

Run an agent

Send a conversation

Events

Python SDK

Billing