openapi: 3.2.0 info: title: LiteLLM [beta] A2A Agents API description: 'Proxy Server to call 100+ LLMs in the OpenAI format. **Customize Swagger Docs** 👉 ```LiteLLM Admin Panel on /ui```. Create, Edit Keys with SSO. Having issues? Try ```Fallback Login``` 💸 ```LiteLLM Model Cost Map```. 🔎 ```LiteLLM Model Hub```. See available models on the proxy. **Docs**' version: 1.102.1 tags: - name: '[beta] A2A Agents' paths: /v1/agents: get: tags: - '[beta] A2A Agents' summary: Get Agents description: 'Example usage: ``` curl -X GET "http://localhost:4000/v1/agents" -H "Content-Type: application/json" -H "Authorization: Bearer your-key" ``` Pass `?health_check=true` to filter out agents whose URL is unreachable: ``` curl -X GET "http://localhost:4000/v1/agents?health_check=true" -H "Content-Type: application/json" -H "Authorization: Bearer your-key" ``` Pass `?query=` to get the best matching agents ranked by semantic similarity: ``` curl -X GET "http://localhost:4000/v1/agents?query=translate+a+PDF+document&top_k=5" -H "Content-Type: application/json" -H "Authorization: Bearer your-key" ``` Returns: List[AgentResponse]' operationId: get_agents_v1_agents_get security: - APIKeyHeader: [] parameters: - name: health_check in: query required: false schema: type: boolean description: When true, performs a GET request to each agent's URL. Agents with reachable URLs (HTTP status < 500) and agents without a URL are returned; unreachable agents are filtered out. default: false title: Health Check description: When true, performs a GET request to each agent's URL. Agents with reachable URLs (HTTP status < 500) and agents without a URL are returned; unreachable agents are filtered out. - name: query in: query required: false schema: anyOf: - type: string minLength: 1 - type: 'null' description: Describe the task in natural language to rank the agents you can reach by semantic similarity over their name, description, and skills. Each result carries a search_score. Requires litellm_settings.agent_search_embedding_model. title: Query description: Describe the task in natural language to rank the agents you can reach by semantic similarity over their name, description, and skills. Each result carries a search_score. Requires litellm_settings.agent_search_embedding_model. - name: top_k in: query required: false schema: type: integer maximum: 100 minimum: 1 description: 'With query: the maximum number of ranked agents to return.' default: 5 title: Top K description: 'With query: the maximum number of ranked agents to return.' responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/AgentResponse' title: Response Get Agents V1 Agents Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - '[beta] A2A Agents' summary: Create Agent description: 'Create a new agent Example Request: ```bash curl -X POST "http://localhost:4000/v1/agents" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d ''{ "agent_name": "my-custom-agent", "agent_card_params": { "protocolVersion": "1.0", "name": "Hello World Agent", "description": "Just a hello world agent", "url": "http://localhost:9999/", "version": "1.0.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true }, "skills": [ { "id": "hello_world", "name": "Returns hello world", "description": "just returns hello world", "tags": ["hello world"], "examples": ["hi", "hello world"] } ] }, "litellm_params": { "make_public": true } }'' ```' operationId: create_agent_v1_agents_post security: - APIKeyHeader: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentConfig' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}: get: tags: - '[beta] A2A Agents' summary: Get Agent By Id description: 'Get a specific agent by ID Example Request: ```bash curl -X GET "http://localhost:4000/v1/agents/123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer " ```' operationId: get_agent_by_id_v1_agents__agent_id__get security: - APIKeyHeader: [] parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' put: tags: - '[beta] A2A Agents' summary: Update Agent description: 'Update an existing agent Example Request: ```bash curl -X PUT "http://localhost:4000/v1/agents/123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d ''{ "agent_name": "updated-agent", "agent_card_params": { "protocolVersion": "1.0", "name": "Updated Agent", "description": "Updated description", "url": "http://localhost:9999/", "version": "1.1.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true }, "skills": [] }, "litellm_params": { "make_public": false } }'' ```' operationId: update_agent_v1_agents__agent_id__put security: - APIKeyHeader: [] parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentConfig' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' patch: tags: - '[beta] A2A Agents' summary: Patch Agent description: 'Update an existing agent Example Request: ```bash curl -X PATCH "http://localhost:4000/v1/agents/123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d ''{ "agent_name": "updated-agent", "agent_card_params": { "protocolVersion": "1.0", "name": "Updated Agent", "description": "Updated description", "url": "http://localhost:9999/", "version": "1.1.0", "defaultInputModes": ["text"], "defaultOutputModes": ["text"], "capabilities": { "streaming": true }, "skills": [] }, "litellm_params": { "make_public": false } }'' ```' operationId: patch_agent_v1_agents__agent_id__patch security: - APIKeyHeader: [] parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PatchAgentRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/{agent_id}/make_public: post: tags: - '[beta] A2A Agents' summary: Make Agent Public description: 'Make an agent publicly discoverable Example Request: ```bash curl -X POST "http://localhost:4000/v1/agents/123e4567-e89b-12d3-a456-426614174000/make_public" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" ``` Example Response: ```json { "agent_id": "123e4567-e89b-12d3-a456-426614174000", "agent_name": "my-custom-agent", "litellm_params": { "make_public": true }, "agent_card_params": {...}, "created_at": "2025-11-15T10:30:00Z", "updated_at": "2025-11-15T10:35:00Z", "created_by": "user123", "updated_by": "user123" } ```' operationId: make_agent_public_v1_agents__agent_id__make_public_post security: - APIKeyHeader: [] parameters: - name: agent_id in: path required: true schema: type: string title: Agent Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentMakePublicResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/agents/make_public: post: tags: - '[beta] A2A Agents' summary: Make Agents Public description: 'Make multiple agents publicly discoverable Example Request: ```bash curl -X POST "http://localhost:4000/v1/agents/make_public" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d ''{ "agent_ids": ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001"] }'' ``` Example Response: ```json { "agent_id": "123e4567-e89b-12d3-a456-426614174000", "agent_name": "my-custom-agent", "litellm_params": { "make_public": true }, "agent_card_params": {...}, "created_at": "2025-11-15T10:30:00Z", "updated_at": "2025-11-15T10:35:00Z", "created_by": "user123", "updated_by": "user123" } ```' operationId: make_agents_public_v1_agents_make_public_post requestBody: content: application/json: schema: $ref: '#/components/schemas/MakeAgentsPublicRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AgentMakePublicResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: PatchAgentRequest: properties: agent_name: type: string title: Agent Name agent_card_params: $ref: '#/components/schemas/AgentCard' litellm_params: additionalProperties: true type: object title: Litellm Params object_permission: $ref: '#/components/schemas/AgentObjectPermission' tpm_limit: anyOf: - type: integer - type: 'null' title: Tpm Limit rpm_limit: anyOf: - type: integer - type: 'null' title: Rpm Limit session_tpm_limit: anyOf: - type: integer - type: 'null' title: Session Tpm Limit session_rpm_limit: anyOf: - type: integer - type: 'null' title: Session Rpm Limit static_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Static Headers extra_headers: anyOf: - items: type: string type: array - type: 'null' title: Extra Headers type: object title: PatchAgentRequest AgentExtension: properties: uri: type: string title: Uri description: anyOf: - type: string - type: 'null' title: Description required: anyOf: - type: boolean - type: 'null' title: Required params: anyOf: - additionalProperties: true type: object - type: 'null' title: Params type: object title: AgentExtension description: A declaration of a protocol extension supported by an Agent. OpenIdConnectSecurityScheme: properties: description: anyOf: - type: string - type: 'null' title: Description type: type: string const: openIdConnect title: Type openIdConnectUrl: type: string title: Openidconnecturl type: object required: - type - openIdConnectUrl title: OpenIdConnectSecurityScheme description: Defines a security scheme using OpenID Connect. OAuthFlows: properties: authorizationCode: anyOf: - additionalProperties: true type: object - type: 'null' title: Authorizationcode clientCredentials: anyOf: - additionalProperties: true type: object - type: 'null' title: Clientcredentials implicit: anyOf: - additionalProperties: true type: object - type: 'null' title: Implicit password: anyOf: - additionalProperties: true type: object - type: 'null' title: Password type: object title: OAuthFlows description: Defines the configuration for the supported OAuth 2.0 flows. MakeAgentsPublicRequest: properties: agent_ids: items: type: string type: array title: Agent Ids type: object required: - agent_ids title: MakeAgentsPublicRequest AgentKeySummary: properties: token: type: string title: Token key_alias: anyOf: - type: string - type: 'null' title: Key Alias key_name: anyOf: - type: string - type: 'null' title: Key Name type: object required: - token title: AgentKeySummary AgentConfig: properties: agent_name: type: string title: Agent Name agent_card_params: $ref: '#/components/schemas/AgentCard' litellm_params: additionalProperties: true type: object title: Litellm Params object_permission: $ref: '#/components/schemas/AgentObjectPermission' tpm_limit: anyOf: - type: integer - type: 'null' title: Tpm Limit rpm_limit: anyOf: - type: integer - type: 'null' title: Rpm Limit session_tpm_limit: anyOf: - type: integer - type: 'null' title: Session Tpm Limit session_rpm_limit: anyOf: - type: integer - type: 'null' title: Session Rpm Limit static_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Static Headers extra_headers: anyOf: - items: type: string type: array - type: 'null' title: Extra Headers type: object required: - agent_name - agent_card_params title: AgentConfig 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 AgentCapabilities: properties: streaming: anyOf: - type: boolean - type: 'null' title: Streaming pushNotifications: anyOf: - type: boolean - type: 'null' title: Pushnotifications stateTransitionHistory: anyOf: - type: boolean - type: 'null' title: Statetransitionhistory extensions: anyOf: - items: $ref: '#/components/schemas/AgentExtension' type: array - type: 'null' title: Extensions type: object title: AgentCapabilities description: Defines optional capabilities supported by an agent. AgentProvider: properties: organization: type: string title: Organization url: type: string title: Url type: object title: AgentProvider description: Represents the service provider of an agent. MutualTLSSecurityScheme: properties: description: anyOf: - type: string - type: 'null' title: Description type: type: string const: mutualTLS title: Type type: object required: - type title: MutualTLSSecurityScheme description: Defines a security scheme using mTLS authentication. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentMakePublicResponse: properties: message: type: string title: Message public_agent_groups: items: type: string type: array title: Public Agent Groups updated_by: type: string title: Updated By type: object required: - message - public_agent_groups - updated_by title: AgentMakePublicResponse OAuth2SecurityScheme: properties: description: anyOf: - type: string - type: 'null' title: Description type: type: string const: oauth2 title: Type flows: $ref: '#/components/schemas/OAuthFlows' oauth2MetadataUrl: anyOf: - type: string - type: 'null' title: Oauth2Metadataurl type: object required: - type - flows title: OAuth2SecurityScheme description: Defines a security scheme using OAuth 2.0. AgentResponse: properties: agent_id: type: string title: Agent Id agent_name: type: string title: Agent Name litellm_params: anyOf: - additionalProperties: true type: object - type: 'null' title: Litellm Params agent_card_params: additionalProperties: true type: object title: Agent Card Params object_permission: anyOf: - additionalProperties: true type: object - type: 'null' title: Object Permission spend: anyOf: - type: number - type: 'null' title: Spend tpm_limit: anyOf: - type: integer - type: 'null' title: Tpm Limit rpm_limit: anyOf: - type: integer - type: 'null' title: Rpm Limit session_tpm_limit: anyOf: - type: integer - type: 'null' title: Session Tpm Limit session_rpm_limit: anyOf: - type: integer - type: 'null' title: Session Rpm Limit static_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Static Headers extra_headers: anyOf: - items: type: string type: array - type: 'null' title: Extra Headers keys: anyOf: - items: $ref: '#/components/schemas/AgentKeySummary' type: array - type: 'null' title: Keys search_score: anyOf: - type: number - type: 'null' title: Search Score created_at: anyOf: - type: string format: date-time - type: 'null' title: Created At updated_at: anyOf: - type: string format: date-time - type: 'null' title: Updated At created_by: anyOf: - type: string - type: 'null' title: Created By updated_by: anyOf: - type: string - type: 'null' title: Updated By type: object required: - agent_id - agent_name - agent_card_params title: AgentResponse AgentInterface: properties: url: type: string title: Url transport: type: string title: Transport type: object title: AgentInterface description: Declares a combination of a target URL and a transport protocol. AgentSkill: properties: id: type: string title: Id name: type: string title: Name description: type: string title: Description tags: items: type: string type: array title: Tags examples: anyOf: - items: type: string type: array - type: 'null' title: Examples inputModes: anyOf: - items: type: string type: array - type: 'null' title: Inputmodes outputModes: anyOf: - items: type: string type: array - type: 'null' title: Outputmodes security: anyOf: - items: additionalProperties: items: type: string type: array type: object type: array - type: 'null' title: Security type: object title: AgentSkill description: Represents a distinct capability or function that an agent can perform. AgentObjectPermission: properties: mcp_servers: anyOf: - items: type: string type: array - type: 'null' title: Mcp Servers mcp_access_groups: anyOf: - items: type: string type: array - type: 'null' title: Mcp Access Groups mcp_toolsets: anyOf: - items: type: string type: array - type: 'null' title: Mcp Toolsets mcp_tool_permissions: anyOf: - additionalProperties: items: type: string type: array type: object - type: 'null' title: Mcp Tool Permissions models: anyOf: - items: type: string type: array - type: 'null' title: Models agents: anyOf: - items: type: string type: array - type: 'null' title: Agents type: object title: AgentObjectPermission AgentCardSignature: properties: protected: type: string title: Protected signature: type: string title: Signature header: anyOf: - additionalProperties: true type: object - type: 'null' title: Header type: object title: AgentCardSignature description: Represents a JWS signature of an AgentCard. AgentCard: properties: protocolVersion: type: string title: Protocolversion name: type: string title: Name description: type: string title: Description url: type: string title: Url version: type: string title: Version capabilities: $ref: '#/components/schemas/AgentCapabilities' defaultInputModes: items: type: string type: array title: Defaultinputmodes defaultOutputModes: items: type: string type: array title: Defaultoutputmodes skills: items: $ref: '#/components/schemas/AgentSkill' type: array title: Skills preferredTransport: anyOf: - type: string - type: 'null' title: Preferredtransport additionalInterfaces: anyOf: - items: $ref: '#/components/schemas/AgentInterface' type: array - type: 'null' title: Additionalinterfaces iconUrl: anyOf: - type: string - type: 'null' title: Iconurl provider: anyOf: - $ref: '#/components/schemas/AgentProvider' - type: 'null' documentationUrl: anyOf: - type: string - type: 'null' title: Documentationurl securitySchemes: anyOf: - additionalProperties: anyOf: - $ref: '#/components/schemas/APIKeySecurityScheme' - $ref: '#/components/schemas/HTTPAuthSecurityScheme' - $ref: '#/components/schemas/OAuth2SecurityScheme' - $ref: '#/components/schemas/OpenIdConnectSecurityScheme' - $ref: '#/components/schemas/MutualTLSSecurityScheme' type: object - type: 'null' title: Securityschemes security: anyOf: - items: additionalProperties: items: type: string type: array type: object type: array - type: 'null' title: Security supportsAuthenticatedExtendedCard: anyOf: - type: boolean - type: 'null' title: Supportsauthenticatedextendedcard signatures: anyOf: - items: $ref: '#/components/schemas/AgentCardSignature' type: array - type: 'null' title: Signatures type: object title: AgentCard description: 'The AgentCard is a self-describing manifest for an agent. It provides essential metadata including the agent''s identity, capabilities, skills, supported communication methods, and security requirements.' HTTPAuthSecurityScheme: properties: description: anyOf: - type: string - type: 'null' title: Description type: type: string const: http title: Type scheme: type: string title: Scheme bearerFormat: anyOf: - type: string - type: 'null' title: Bearerformat type: object required: - type - scheme title: HTTPAuthSecurityScheme description: Defines a security scheme using HTTP authentication. APIKeySecurityScheme: properties: description: anyOf: - type: string - type: 'null' title: Description type: type: string const: apiKey title: Type in_: type: string enum: - query - header - cookie title: In name: type: string title: Name type: object required: - type - in_ - name title: APIKeySecurityScheme description: Defines a security scheme using an API key. securitySchemes: APIKeyHeader: type: apiKey description: Bearer token in: header name: x-litellm-api-key