openapi: 3.1.0
info:
title: Agno API Reference A2A API
description: The all-in-one, private, secure agent platform that runs in your cloud.
version: 2.5.6
tags:
- name: A2A
paths:
/a2a/agents/{id}/.well-known/agent-card.json:
get:
tags:
- A2A
summary: Get Agent Card
operationId: get_agent_card_a2a_agents__id___well_known_agent_card_json_get
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/agents/{id}/v1/message:send:
post:
tags:
- A2A
summary: Run Message Agent
description: 'Send a message to an Agno Agent (non-streaming). The Agent is identified via the path parameter ''{id}''. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata.'
operationId: run_message_agent
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageSuccessResponse'
example:
jsonrpc: '2.0'
id: request-123
result:
task:
id: task-456
context_id: context-789
status: completed
history:
- message_id: msg-1
role: agent
parts:
- kind: text
text: Response from agent
'400':
description: Invalid request
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/agents/{id}/v1/tasks:get:
post:
tags:
- A2A
summary: Get Agent Task
description: Get the status and result of an agent task by ID.
operationId: get_agent_task
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/agents/{id}/v1/tasks:cancel:
post:
tags:
- A2A
summary: Cancel Agent Task
description: Cancel a running agent task.
operationId: cancel_agent_task
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/agents/{id}/v1/message:stream:
post:
tags:
- A2A
summary: Stream Message Agent
description: 'Stream a message to an Agno Agent (streaming). The Agent is identified via the path parameter ''{id}''. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata. Returns real-time updates as newline-delimited JSON (NDJSON).'
operationId: stream_message_agent
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Streaming response with task updates
content:
application/json:
schema: {}
text/event-stream:
example: 'event: TaskStatusUpdateEvent
data: {"jsonrpc":"2.0","id":"request-123","result":{"taskId":"task-456","status":"working"}}
event: Message
data: {"jsonrpc":"2.0","id":"request-123","result":{"messageId":"msg-1","role":"agent","parts":[{"kind":"text","text":"Response"}]}}
'
'400':
description: Invalid request
'404':
description: Agent not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/teams/{id}/.well-known/agent-card.json:
get:
tags:
- A2A
summary: Get Team Card
operationId: get_team_card_a2a_teams__id___well_known_agent_card_json_get
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/teams/{id}/v1/message:send:
post:
tags:
- A2A
summary: Run Message Team
description: 'Send a message to an Agno Team (non-streaming). The Team is identified via the path parameter ''{id}''. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata.'
operationId: run_message_team
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageSuccessResponse'
example:
jsonrpc: '2.0'
id: request-123
result:
task:
id: task-456
context_id: context-789
status: completed
history:
- message_id: msg-1
role: agent
parts:
- kind: text
text: Response from agent
'400':
description: Invalid request
'404':
description: Team not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/teams/{id}/v1/tasks:get:
post:
tags:
- A2A
summary: Get Team Task
description: Get the status and result of a team task by ID.
operationId: get_team_task
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/teams/{id}/v1/tasks:cancel:
post:
tags:
- A2A
summary: Cancel Team Task
description: Cancel a running team task.
operationId: cancel_team_task
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/teams/{id}/v1/message:stream:
post:
tags:
- A2A
summary: Stream Message Team
description: 'Stream a message to an Agno Team (streaming). The Team is identified via the path parameter ''{id}''. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata. Returns real-time updates as newline-delimited JSON (NDJSON).'
operationId: stream_message_team
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Streaming response with task updates
content:
application/json:
schema: {}
text/event-stream:
example: 'event: TaskStatusUpdateEvent
data: {"jsonrpc":"2.0","id":"request-123","result":{"taskId":"task-456","status":"working"}}
event: Message
data: {"jsonrpc":"2.0","id":"request-123","result":{"messageId":"msg-1","role":"agent","parts":[{"kind":"text","text":"Response"}]}}
'
'400':
description: Invalid request
'404':
description: Team not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/workflows/{id}/.well-known/agent-card.json:
get:
tags:
- A2A
summary: Get Workflow Card
operationId: get_workflow_card_a2a_workflows__id___well_known_agent_card_json_get
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/workflows/{id}/v1/message:send:
post:
tags:
- A2A
summary: Run Message Workflow
description: 'Send a message to an Agno Workflow (non-streaming). The Workflow is identified via the path parameter ''{id}''. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata.'
operationId: run_message_workflow
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageSuccessResponse'
example:
jsonrpc: '2.0'
id: request-123
result:
task:
id: task-456
context_id: context-789
status: completed
history:
- message_id: msg-1
role: agent
parts:
- kind: text
text: Response from agent
'400':
description: Invalid request
'404':
description: Workflow not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/workflows/{id}/v1/message:stream:
post:
tags:
- A2A
summary: Stream Message Workflow
description: 'Stream a message to an Agno Workflow (streaming). The Workflow is identified via the path parameter ''{id}''. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata. Returns real-time updates as newline-delimited JSON (NDJSON).'
operationId: stream_message_workflow
parameters:
- name: id
in: path
required: true
schema:
type: string
title: Id
responses:
'200':
description: Streaming response with task updates
content:
application/json:
schema: {}
text/event-stream:
example: 'event: TaskStatusUpdateEvent
data: {"jsonrpc":"2.0","id":"request-123","result":{"taskId":"task-456","status":"working"}}
event: Message
data: {"jsonrpc":"2.0","id":"request-123","result":{"messageId":"msg-1","role":"agent","parts":[{"kind":"text","text":"Response"}]}}
'
'400':
description: Invalid request
'404':
description: Workflow not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/a2a/message/send:
post:
tags:
- A2A
summary: Send Message
description: '[DEPRECATED] Send a message to an Agno Agent, Team, or Workflow. The Agent, Team or Workflow is identified via the ''agentId'' field in params.message or X-Agent-ID header. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata.'
operationId: send_message
responses:
'200':
description: Message sent successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SendMessageSuccessResponse'
example:
jsonrpc: '2.0'
id: request-123
result:
task:
id: task-456
context_id: context-789
status: completed
history:
- message_id: msg-1
role: agent
parts:
- kind: text
text: Response from agent
'400':
description: Invalid request or unsupported method
'404':
description: Agent, Team, or Workflow not found
/a2a/message/stream:
post:
tags:
- A2A
summary: Stream Message
description: '[DEPRECATED] Stream a message to an Agno Agent, Team, or Workflow. The Agent, Team or Workflow is identified via the ''agentId'' field in params.message or X-Agent-ID header. Optional: Pass user ID via X-User-ID header (recommended) or ''userId'' in params.message.metadata. Returns real-time updates as newline-delimited JSON (NDJSON).'
operationId: stream_message
responses:
'200':
description: Streaming response with task updates
content:
application/json:
schema: {}
text/event-stream:
example: 'event: TaskStatusUpdateEvent
data: {"jsonrpc":"2.0","id":"request-123","result":{"taskId":"task-456","status":"working"}}
event: Message
data: {"jsonrpc":"2.0","id":"request-123","result":{"messageId":"msg-1","role":"agent","parts":[{"kind":"text","text":"Response"}]}}
'
'400':
description: Invalid request or unsupported method
'404':
description: Agent, Team, or Workflow not found
components:
schemas:
Task:
properties:
artifacts:
anyOf:
- items:
$ref: '#/components/schemas/Artifact'
type: array
- type: 'null'
title: Artifacts
contextId:
type: string
title: Contextid
history:
anyOf:
- items:
$ref: '#/components/schemas/Message'
type: array
- type: 'null'
title: History
id:
type: string
title: Id
kind:
type: string
const: task
title: Kind
default: task
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
status:
$ref: '#/components/schemas/TaskStatus'
type: object
required:
- contextId
- id
- status
title: Task
description: Represents a single, stateful operation or conversation between a client and an agent.
Role:
type: string
enum:
- agent
- user
title: Role
description: Identifies the sender of the message. `user` for the client, `agent` for the service.
TaskStatus:
properties:
message:
anyOf:
- $ref: '#/components/schemas/Message'
- type: 'null'
state:
$ref: '#/components/schemas/TaskState'
timestamp:
anyOf:
- type: string
- type: 'null'
title: Timestamp
examples:
- '2023-10-27T10:00:00Z'
type: object
required:
- state
title: TaskStatus
description: Represents the status of a task at a specific point in time.
SendMessageSuccessResponse:
properties:
id:
anyOf:
- type: string
- type: integer
- type: 'null'
title: Id
jsonrpc:
type: string
const: '2.0'
title: Jsonrpc
default: '2.0'
result:
anyOf:
- $ref: '#/components/schemas/Task'
- $ref: '#/components/schemas/Message'
title: Result
type: object
required:
- result
title: SendMessageSuccessResponse
description: Represents a successful JSON-RPC response for the `message/send` method.
FileWithUri:
properties:
mimeType:
anyOf:
- type: string
- type: 'null'
title: Mimetype
name:
anyOf:
- type: string
- type: 'null'
title: Name
uri:
type: string
title: Uri
type: object
required:
- uri
title: FileWithUri
description: Represents a file with its content located at a specific URI.
DataPart:
properties:
data:
additionalProperties: true
type: object
title: Data
kind:
type: string
const: data
title: Kind
default: data
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
type: object
required:
- data
title: DataPart
description: Represents a structured data segment (e.g., JSON) within a message or artifact.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
TextPart:
properties:
kind:
type: string
const: text
title: Kind
default: text
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
text:
type: string
title: Text
type: object
required:
- text
title: TextPart
description: Represents a text segment within a message or artifact.
TaskState:
type: string
enum:
- submitted
- working
- input-required
- completed
- canceled
- failed
- rejected
- auth-required
- unknown
title: TaskState
description: Defines the lifecycle states of a Task.
Artifact:
properties:
artifactId:
type: string
title: Artifactid
description:
anyOf:
- type: string
- type: 'null'
title: Description
extensions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Extensions
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
name:
anyOf:
- type: string
- type: 'null'
title: Name
parts:
items:
$ref: '#/components/schemas/Part'
type: array
title: Parts
type: object
required:
- artifactId
- parts
title: Artifact
description: Represents a file, data structure, or other resource generated by an agent during a task.
FileWithBytes:
properties:
bytes:
type: string
title: Bytes
mimeType:
anyOf:
- type: string
- type: 'null'
title: Mimetype
name:
anyOf:
- type: string
- type: 'null'
title: Name
type: object
required:
- bytes
title: FileWithBytes
description: Represents a file with its content provided directly as a base64-encoded string.
Message:
properties:
contextId:
anyOf:
- type: string
- type: 'null'
title: Contextid
extensions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Extensions
kind:
type: string
const: message
title: Kind
default: message
messageId:
type: string
title: Messageid
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
parts:
items:
$ref: '#/components/schemas/Part'
type: array
title: Parts
referenceTaskIds:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Referencetaskids
role:
$ref: '#/components/schemas/Role'
taskId:
anyOf:
- type: string
- type: 'null'
title: Taskid
type: object
required:
- messageId
- parts
- role
title: Message
description: Represents a single message in the conversation between a user and an agent.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
FilePart:
properties:
file:
anyOf:
- $ref: '#/components/schemas/FileWithBytes'
- $ref: '#/components/schemas/FileWithUri'
title: File
kind:
type: string
const: file
title: Kind
default: file
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Metadata
type: object
required:
- file
title: FilePart
description: 'Represents a file segment within a message or artifact. The file content can be
provided either directly as bytes or as a URI.'
Part:
anyOf:
- $ref: '#/components/schemas/TextPart'
- $ref: '#/components/schemas/FilePart'
- $ref: '#/components/schemas/DataPart'
title: Part
securitySchemes:
HTTPBearer:
type: http
scheme: bearer