Agno Agents API

openapi: 3.1.0
info:
  title: Agno API Reference A2A Agents API
  description: The all-in-one, private, secure agent platform that runs in your cloud.
  version: 2.5.6
tags:
- name: Agents
paths:
  /agents/{agent_id}/runs:
    post:
      tags:
      - Agents
      summary: Create Agent Run
      description: 'Execute an agent with a message and optional media files. Supports both streaming and non-streaming responses.


        **Features:**

        - Text message input with optional session management

        - Multi-media support: images (PNG, JPEG, WebP), audio (WAV, MP3), video (MP4, WebM, etc.)

        - Document processing: PDF, CSV, DOCX, TXT, JSON

        - Real-time streaming responses with Server-Sent Events (SSE)

        - User and session context preservation


        **Streaming Response:**

        When `stream=true`, returns SSE events with `event` and `data` fields.'
      operationId: create_agent_run
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_agent_run'
      responses:
        '200':
          description: Agent run executed successfully
          content:
            application/json:
              schema: {}
            text/event-stream:
              examples:
                event_stream:
                  summary: Example event stream response
                  value: 'event: RunStarted

                    data: {"content": "Hello!", "run_id": "123..."}


                    '
        '400':
          description: Invalid request or unsupported file type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
    get:
      tags:
      - Agents
      summary: List Agent Runs
      description: 'List runs for an agent within a session, optionally filtered by status.


        Useful for monitoring background runs and viewing run history.'
      operationId: list_agent_runs
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: session_id
        in: query
        required: true
        schema:
          type: string
          description: Session ID to list runs for
          title: Session Id
        description: Session ID to list runs for
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by run status (PENDING, RUNNING, COMPLETED, ERROR)
          title: Status
        description: Filter by run status (PENDING, RUNNING, COMPLETED, ERROR)
      responses:
        '200':
          description: List of runs retrieved successfully
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /agents/{agent_id}/runs/{run_id}/cancel:
    post:
      tags:
      - Agents
      summary: Cancel Agent Run
      description: 'Cancel a currently executing agent run. This will attempt to stop the agent''s execution gracefully.


        **Note:** Cancellation may not be immediate for all operations.'
      operationId: cancel_agent_run
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Failed to cancel run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /agents/{agent_id}/runs/{run_id}/continue:
    post:
      tags:
      - Agents
      summary: Continue Agent Run
      description: 'Continue a paused or incomplete agent run with updated tool results.


        **Use Cases:**

        - Resume execution after tool approval/rejection

        - Provide manual tool execution results

        - Resume after admin approval (tools can be empty; resolution fetched from DB)


        **Tools Parameter:**

        JSON string containing array of tool execution objects with results.

        Can be empty when an admin-required approval has been resolved.'
      operationId: continue_agent_run
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_continue_agent_run'
      responses:
        '200':
          description: Agent run continued successfully
          content:
            application/json:
              schema: {}
            text/event-stream:
              example: 'event: RunContent

                data: {"created_at": 1757348314, "run_id": "123..."}


                '
        '400':
          description: Invalid JSON in tools field or invalid tool structure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '403':
          description: Run has a pending admin approval and cannot be continued by the user yet.
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '409':
          description: Run is not paused (e.g. run is already running, continued, or errored). Only PAUSED runs can be continued.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /agents:
    get:
      tags:
      - Agents
      summary: List All Agents
      description: 'Retrieve a comprehensive list of all agents configured in this OS instance.


        **Returns:**

        - Agent metadata (ID, name, description)

        - Model configuration and capabilities

        - Available tools and their configurations

        - Session, knowledge, memory, and reasoning settings

        - Only meaningful (non-default) configurations are included'
      operationId: get_agents
      responses:
        '200':
          description: List of agents retrieved successfully
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/AgentResponse'
                type: array
                title: Response Get Agents
              example:
              - id: main-agent
                name: Main Agent
                db_id: c6bf0644-feb8-4930-a305-380dae5ad6aa
                model:
                  name: OpenAIChat
                  model: gpt-4o
                  provider: OpenAI
                sessions:
                  session_table: agno_sessions
                knowledge:
                  knowledge_table: main_knowledge
                system_message:
                  markdown: true
                  add_datetime_to_context: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
      - HTTPBearer: []
  /agents/{agent_id}:
    get:
      tags:
      - Agents
      summary: Get Agent Details
      description: 'Retrieve detailed configuration and capabilities of a specific agent.


        **Returns comprehensive agent information including:**

        - Model configuration and provider details

        - Complete tool inventory and configurations

        - Session management settings

        - Knowledge base and memory configurations

        - Reasoning capabilities and settings

        - System prompts and response formatting options'
      operationId: get_agent
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      responses:
        '200':
          description: Agent details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
              example:
                id: main-agent
                name: Main Agent
                db_id: 9e064c70-6821-4840-a333-ce6230908a70
                model:
                  name: OpenAIChat
                  model: gpt-4o
                  provider: OpenAI
                sessions:
                  session_table: agno_sessions
                knowledge:
                  knowledge_table: main_knowledge
                system_message:
                  markdown: true
                  add_datetime_to_context: true
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /agents/{agent_id}/runs/{run_id}:
    get:
      tags:
      - Agents
      summary: Get Agent Run
      description: 'Retrieve the status and output of an agent run. Use this to poll for background run completion.


        Requires the `session_id` that was returned when the run was created.'
      operationId: get_agent_run
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_id
        in: path
        required: true
        schema:
          type: string
          title: Agent Id
      - name: run_id
        in: path
        required: true
        schema:
          type: string
          title: Run Id
      - name: session_id
        in: query
        required: true
        schema:
          type: string
          description: Session ID for the run
          title: Session Id
        description: Session ID for the run
      responses:
        '200':
          description: Run output retrieved successfully
          content:
            application/json:
              schema: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Agent or run not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  schemas:
    AgentResponse:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        db_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Db Id
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        model:
          anyOf:
          - $ref: '#/components/schemas/ModelResponse'
          - type: 'null'
        tools:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tools
        sessions:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Sessions
        knowledge:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Knowledge
        memory:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Memory
        reasoning:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Reasoning
        default_tools:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Default Tools
        system_message:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: System Message
        extra_messages:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Extra Messages
        response_settings:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Response Settings
        introduction:
          anyOf:
          - type: string
          - type: 'null'
          title: Introduction
        streaming:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Streaming
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
        input_schema:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Input Schema
        is_component:
          type: boolean
          title: Is Component
          default: false
        current_version:
          anyOf:
          - type: integer
          - type: 'null'
          title: Current Version
        stage:
          anyOf:
          - type: string
          - type: 'null'
          title: Stage
      type: object
      title: AgentResponse
    ModelResponse:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Name of the model
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Model identifier
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: Model provider name
      type: object
      title: ModelResponse
    BadRequestResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
      - detail
      title: BadRequestResponse
      example:
        detail: Bad request
        error_code: BAD_REQUEST
    ValidationErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
      - detail
      title: ValidationErrorResponse
      example:
        detail: Validation error
        error_code: VALIDATION_ERROR
    InternalServerErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
      - detail
      title: InternalServerErrorResponse
      example:
        detail: Internal server error
        error_code: INTERNAL_SERVER_ERROR
    UnauthenticatedResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
      - detail
      title: UnauthenticatedResponse
      example:
        detail: Unauthenticated access
        error_code: UNAUTHENTICATED
    Body_continue_agent_run:
      properties:
        tools:
          type: string
          title: Tools
          default: ''
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        stream:
          type: boolean
          title: Stream
          default: true
      type: object
      title: Body_continue_agent_run
    NotFoundResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
      - detail
      title: NotFoundResponse
      example:
        detail: Not found
        error_code: NOT_FOUND
    Body_create_agent_run:
      properties:
        message:
          type: string
          title: Message
        stream:
          type: boolean
          title: Stream
          default: true
        session_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Session Id
        user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: User Id
        files:
          anyOf:
          - items:
              type: string
              contentMediaType: application/octet-stream
            type: array
          - type: 'null'
          title: Files
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        background:
          type: boolean
          title: Background
          default: false
      type: object
      required:
      - message
      title: Body_create_agent_run
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer