openapi: 3.1.0
info:
  title: Agno API Reference A2A Teams API
  description: The all-in-one, private, secure agent platform that runs in your cloud.
  version: 2.5.6
tags:
- name: Teams
paths:
  /teams/{team_id}/runs:
    post:
      tags:
      - Teams
      summary: Create Team Run
      description: 'Execute a team collaboration with multiple agents working together on a task.


        **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_team_run
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
          title: Team Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_team_run'
      responses:
        '200':
          description: Team run executed successfully
          content:
            application/json:
              schema: {}
            text/event-stream:
              example: '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: Team 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:
      - Teams
      summary: List Team Runs
      description: 'List runs for a team within a session, optionally filtered by status.


        Useful for monitoring background runs and viewing run history.'
      operationId: list_team_runs
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
          title: Team 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: Team 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'
  /teams/{team_id}/runs/{run_id}/cancel:
    post:
      tags:
      - Teams
      summary: Cancel Team Run
      description: 'Cancel a currently executing team run. This will attempt to stop the team''s execution gracefully.


        **Note:** Cancellation may not be immediate for all operations.'
      operationId: cancel_team_run
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
          title: Team 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: Team 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 team run
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
  /teams:
    get:
      tags:
      - Teams
      summary: List All Teams
      description: 'Retrieve a comprehensive list of all teams configured in this OS instance.


        **Returns team information including:**

        - Team metadata (ID, name, description, execution mode)

        - Model configuration for team coordination

        - Team member roster with roles and capabilities

        - Knowledge sharing and memory configurations'
      operationId: get_teams
      responses:
        '200':
          description: List of teams retrieved successfully
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/TeamResponse'
                type: array
                title: Response Get Teams
              example:
              - team_id: basic-team
                name: Basic Team
                mode: coordinate
                model:
                  name: OpenAIChat
                  model: gpt-4o
                  provider: OpenAI
                tools:
                - name: transfer_task_to_member
                  description: 'Use this function to transfer a task to the selected team member.

                    You must provide a clear and concise description of the task the member should achieve AND the expected output.'
                  parameters:
                    type: object
                    properties:
                      member_id:
                        type: string
                        description: (str) The ID of the member to transfer the task to. Use only the ID of the member, not the ID of the team followed by the ID of the member.
                      task_description:
                        type: string
                        description: (str) A clear and concise description of the task the member should achieve.
                      expected_output:
                        type: string
                        description: (str) The expected output from the member (optional).
                    additionalProperties: false
                    required:
                    - member_id
                    - task_description
                members:
                - agent_id: basic-agent
                  name: Basic Agent
                  model:
                    name: OpenAIChat
                    model: gpt-4o
                    provider: OpenAI gpt-4o
                  memory:
                    app_name: Memory
                    model:
                      name: OpenAIChat
                      model: gpt-4o
                      provider: OpenAI
                  session_table: agno_sessions
                  memory_table: agno_memories
                enable_agentic_context: false
                memory:
                  app_name: agno_memories
                  app_url: /memory/1
                  model:
                    name: OpenAIChat
                    model: gpt-4o
                    provider: OpenAI
                async_mode: false
                session_table: agno_sessions
                memory_table: agno_memories
        '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: []
  /teams/{team_id}:
    get:
      tags:
      - Teams
      summary: Get Team Details
      description: Retrieve detailed configuration and member information for a specific team.
      operationId: get_team
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
          title: Team Id
      responses:
        '200':
          description: Team details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TeamResponse'
              example:
                team_id: basic-team
                name: Basic Team
                mode: coordinate
                model:
                  name: OpenAIChat
                  model: gpt-4o
                  provider: OpenAI
                tools:
                - name: transfer_task_to_member
                  description: 'Use this function to transfer a task to the selected team member.

                    You must provide a clear and concise description of the task the member should achieve AND the expected output.'
                  parameters:
                    type: object
                    properties:
                      member_id:
                        type: string
                        description: (str) The ID of the member to transfer the task to. Use only the ID of the member, not the ID of the team followed by the ID of the member.
                      task_description:
                        type: string
                        description: (str) A clear and concise description of the task the member should achieve.
                      expected_output:
                        type: string
                        description: (str) The expected output from the member (optional).
                    additionalProperties: false
                    required:
                    - member_id
                    - task_description
                members:
                - agent_id: basic-agent
                  name: Basic Agent
                  model:
                    name: OpenAIChat
                    model: gpt-4o
                    provider: OpenAI gpt-4o
                  memory:
                    app_name: Memory
                    model:
                      name: OpenAIChat
                      model: gpt-4o
                      provider: OpenAI
                  session_table: agno_sessions
                  memory_table: agno_memories
                enable_agentic_context: false
                memory:
                  app_name: Memory
                  model:
                    name: OpenAIChat
                    model: gpt-4o
                    provider: OpenAI
                async_mode: false
                session_table: agno_sessions
                memory_table: agno_memories
        '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: Team 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'
  /teams/{team_id}/runs/{run_id}:
    get:
      tags:
      - Teams
      summary: Get Team Run
      description: 'Retrieve the status and output of a team run. Use this to poll for background run completion.


        Requires the `session_id` that was returned when the run was created.'
      operationId: get_team_run
      security:
      - HTTPBearer: []
      parameters:
      - name: team_id
        in: path
        required: true
        schema:
          type: string
          title: Team 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: Team 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
    Body_create_team_run:
      properties:
        message:
          type: string
          title: Message
        stream:
          type: boolean
          title: Stream
          default: true
        monitor:
          type: boolean
          title: Monitor
          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: integer
          - type: 'null'
          title: Version
        background:
          type: boolean
          title: Background
          default: false
      type: object
      required:
      - message
      title: Body_create_team_run
    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
    TeamResponse:
      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
        mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Mode
        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
        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
        members:
          anyOf:
          - items:
              anyOf:
              - $ref: '#/components/schemas/AgentResponse'
              - $ref: '#/components/schemas/TeamResponse'
            type: array
          - type: 'null'
          title: Members
        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: TeamResponse
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer