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

# 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](/guides/agents).



## OpenAPI

````yaml /api-reference/agents.json post /v1/agent/{agent_id}/run
openapi: 3.1.0
info:
  title: SynapsAI Agents API
  version: 1.0.0
servers:
  - url: https://api.synapsai.cloud
    description: Production server
security: []
paths:
  /v1/agent/{agent_id}/run:
    post:
      summary: Run an agent
      description: >-
        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](/guides/agents).
      operationId: runAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
          description: Agent id from the dashboard, for example `agt_...`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAgentInput'
      responses:
        '200':
          description: >-
            AG-UI Server-Sent Events. Event types include `RUN_STARTED`,
            `TEXT_MESSAGE_CONTENT`, `TOOL_CALL_START`, `TOOL_CALL_RESULT`,
            `RUN_FINISHED`, and `RUN_ERROR`.
          content:
            text/event-stream:
              schema:
                type: string
        '404':
          description: Agent not found
components:
  schemas:
    RunAgentInput:
      type: object
      description: AG-UI run input. Field names are camelCase on the wire.
      properties:
        threadId:
          type: string
        runId:
          type: string
        parentRunId:
          type: string
          nullable: true
        messages:
          type: array
          items:
            type: object
            required:
              - id
              - role
            properties:
              id:
                type: string
              role:
                type: string
                enum:
                  - user
                  - assistant
                  - system
                  - developer
                  - tool
              content: {}
              toolCallId:
                type: string
              toolCalls:
                type: array
                items:
                  type: object
                  additionalProperties: true
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            Forwarded for protocol compatibility. Does not add tools to the
            agent.
        context:
          type: array
          items:
            type: object
            additionalProperties: true
        state:
          type: object
          additionalProperties: true
          description: May set `max_steps` (1–500) and `compress_context`.
        forwardedProps:
          type: object
          additionalProperties: true
        resume: {}
      required:
        - threadId
        - runId
        - messages

````

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