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

# Add an A2A agent

> Register an external agent (Snowflake Cortex, Bedrock AgentCore, M365 Copilot) over A2A.



## OpenAPI

````yaml openapi.yaml POST /v1/agents
openapi: 3.1.0
info:
  title: ForceAI Gateway API
  version: 1.0.0
  description: >
    Core ForceAI Gateway operations: add a model, mint a virtual key, register
    an A2A agent, and run a chat completion. The gateway is OpenAI compatible,
    so any OpenAI SDK works by pointing base_url at it. Management operations
    (add model, add key, add agent) are admin actions on the control plane; chat
    completions run on the gateway data plane.
servers:
  - url: https://gateway.your-domain.com
    description: >-
      ForceAI endpoint (gateway for chat completions; control plane for admin
      operations)
security:
  - bearerAuth: []
tags:
  - name: Chat
    description: OpenAI-compatible inference
  - name: Models
    description: Add and manage models (admin)
  - name: Keys
    description: Mint and scope virtual keys (admin)
  - name: Agents
    description: Register A2A agents (admin)
paths:
  /v1/agents:
    post:
      tags:
        - Agents
      summary: Add an A2A agent
      description: >
        Register an external agent (Snowflake Cortex, Bedrock AgentCore, M365
        Copilot) as an A2A endpoint. Backend-specific fields go in
        `forceai_params`. The agent lands in `pending` and must be approved
        (`POST /v1/agents/{agent_id}/approve`) before it can be invoked.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddAgentRequest'
            example:
              agent_name: forceai-echo-agentcore
              agent_card_params:
                protocolVersion: '0.3'
                name: AgentCore Echo
                description: Bedrock AgentCore runtime over A2A
                url: https://bedrock-agentcore.us-east-1.amazonaws.com/
                capabilities:
                  streaming: false
                defaultInputModes:
                  - text
                defaultOutputModes:
                  - text
                skills:
                  - id: echo
                    name: Echo
                    description: echoes text
                    tags:
                      - demo
              forceai_params:
                model: >-
                  bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-agent
                custom_llm_provider: bedrock
      responses:
        '200':
          description: The created agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
              example:
                agent_id: 7e2dbe6d-...
                agent_name: forceai-echo-agentcore
                state: pending
                forceai_params:
                  model: >-
                    bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-agent
                  custom_llm_provider: bedrock
                litellm_params:
                  model: >-
                    bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-agent
                  custom_llm_provider: bedrock
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AddAgentRequest:
      type: object
      required:
        - agent_name
        - agent_card_params
        - forceai_params
      properties:
        agent_name:
          type: string
        agent_card_params:
          $ref: '#/components/schemas/AgentCard'
        forceai_params:
          $ref: '#/components/schemas/ForceaiParams'
    AgentResponse:
      type: object
      properties:
        agent_id:
          type: string
        agent_name:
          type: string
        state:
          type: string
          example: pending
        forceai_params:
          type: object
          additionalProperties: true
        litellm_params:
          type: object
          additionalProperties: true
          description: Back-compat mirror of forceai_params.
    AgentCard:
      type: object
      required:
        - protocolVersion
        - name
        - url
        - capabilities
        - skills
      properties:
        protocolVersion:
          type: string
          enum:
            - '0.3'
            - '1.0'
        name:
          type: string
        description:
          type: string
        url:
          type: string
        capabilities:
          type: object
          properties:
            streaming:
              type: boolean
        defaultInputModes:
          type: array
          items:
            type: string
        defaultOutputModes:
          type: array
          items:
            type: string
        skills:
          type: array
          items:
            type: object
    ForceaiParams:
      type: object
      description: >
        Provider or backend configuration. `forceai_params` is the
        customer-facing name; `litellm_params` is accepted as a back-compat
        alias.
      required:
        - model
      properties:
        model:
          type: string
          example: openai/gpt-4o
        custom_llm_provider:
          type: string
          example: openai
        api_key:
          type: string
        api_base:
          type: string
      additionalProperties: true
  responses:
    Unauthorized:
      description: Missing or invalid key
      content:
        application/json:
          example:
            error:
              message: Authentication Error, No api key passed in.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A ForceAI virtual key or the master key, sent as `Authorization: Bearer
        <key>`.

````