> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsai.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Deploy a persisted agent on one of your models, attach tools and knowledge bases, and run it over the AG-UI stream

An **agent** is a saved configuration on top of a model you have already [deployed](/guides/deploy-model). It stores the system prompt, built-in tools, MCP servers, [knowledge bases](/guides/knowledge-bases), and loop limits. You create and edit agents in the [dashboard](https://platform.synapsai.cloud). You run them with the API.

The run endpoint streams [AG-UI](https://docs.ag-ui.com/) 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](/guides/knowledge-bases) |
| 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](/manage/api-keys). The key must be allowed to call the agent's model.

<CodeGroup>
  ```python title="Python" theme={null}
  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()
  ```

  ```bash title="cURL" theme={null}
  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": {}
    }'
  ```
</CodeGroup>

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.

<CodeGroup>
  ```python title="Python" theme={null}
  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)
  ```

  ```bash title="cURL" theme={null}
  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": {}
    }'
  ```
</CodeGroup>

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

```python theme={null}
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](/resources/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](/examples/responses) for the same store behavior on `/v1/responses`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.