Agno Teams API
The Teams API from Agno — 5 operation(s) for teams.
OpenAPI Specification
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