> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Register external A2A agent

> Register an external A2A-compliant agent into Orquesta. The agent card will be fetched during registration to validate the agent and cache its capabilities.



## OpenAPI

````yaml post /v2/agents/a2a
openapi: 3.1.0
info:
  title: orq.ai API
  version: '2.0'
  description: orq.ai API documentation
servers:
  - url: https://api.orq.ai
security:
  - ApiKey: []
tags:
  - name: Guardrail Rules
  - name: Policies
  - name: Routing Rules
  - name: Files
    description: File upload and retrieval operations.
  - name: FilesService
  - name: Projects
    description: Projects organize resources within a workspace
  - name: ProjectsService
  - name: Skills
    description: >-
      Skills are modular instructions you can use to codify processes and
      conventions
  - name: SkillsService
  - name: Responses
  - description: >-
      Run agents on a cadence — cron, interval, or one-off. Minimum firing
      interval is 1 hour.
    name: Agent Schedules
  - name: Reporting
    description: >-
      GenAI reporting API over canonical analytics rollups. Accepts a metric
      name, time range, grain, group-by, and filters; returns a typed time
      series and optional totals.
  - name: ReportingService
    description: |-
      ReportingService exposes a single QueryReport RPC that maps allowlisted
       analytics payloads onto safe rollup queries. Callers never send SQL;
       the backend picks the rollup family and grain from the metric
       catalogue, the requested range, and the requested grouping.
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
paths:
  /v2/agents/a2a:
    post:
      tags:
        - Agents
      summary: Register external A2A agent
      description: >-
        Register an external A2A-compliant agent into Orquesta. The agent card
        will be fetched during registration to validate the agent and cache its
        capabilities.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                  pattern: ^[A-Za-z][A-Za-z0-9]*([._-][A-Za-z0-9]+)*$
                  description: Unique identifier for the agent
                display_name:
                  type: string
                  minLength: 1
                  description: Display name for the agent
                description:
                  type: string
                  description: Description of the agent
                path:
                  type: string
                  description: Project path for organizing the agent
                agent_url:
                  type: string
                  format: uri
                  description: The A2A agent endpoint URL
                card_url:
                  type: string
                  format: uri
                  description: >-
                    Optional explicit agent card URL (must be different from
                    agent_url)
                headers:
                  type: object
                  description: Authentication headers for the A2A agent
                  additionalProperties:
                    type: object
                    properties:
                      value:
                        type: string
                        maxLength: 2048
                        description: >-
                          Header value. **Update behavior**: Provide empty
                          string ("") to preserve existing encrypted value
                          without re-entering credentials. Provide new value to
                          rotate. Omit header entirely to remove.
                      encrypted:
                        type: boolean
                        default: false
                    required:
                      - value
              required:
                - key
                - display_name
                - description
                - path
                - agent_url
      responses:
        '201':
          description: A2A agent registered successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  _id:
                    type: string
                  type:
                    type: string
                    enum:
                      - a2a
                      - internal
                  key:
                    type: string
                  display_name:
                    type: string
                  description:
                    type: string
                  workspace_id:
                    type: string
                  project_id:
                    type: string
                  created_by_id:
                    type:
                      - string
                      - 'null'
                  updated_by_id:
                    type:
                      - string
                      - 'null'
                  role:
                    type: string
                  instructions:
                    type: string
                  status:
                    type: string
                  path:
                    type: string
                  metrics:
                    type: object
                    properties:
                      total_cost:
                        type: number
                    required:
                      - total_cost
                  memory_stores:
                    type: array
                    items:
                      type: string
                  team_of_agents:
                    type: array
                    items: {}
                  created:
                    type: string
                  updated:
                    type: string
                  a2a:
                    type: object
                    properties:
                      agent_url:
                        type: string
                      card_url:
                        type: string
                      headers:
                        type: object
                        additionalProperties: {}
                      cached_card: {}
                    required:
                      - agent_url
                      - headers
                required:
                  - _id
                  - type
                  - key
                  - display_name
                  - description
                  - workspace_id
                  - project_id
                  - status
                  - path
                  - metrics
                  - memory_stores
                  - team_of_agents
        '400':
          description: Invalid request or agent card fetch failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '409':
          description: Agent with this key already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````