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

# External Agent Onboarding

## Overview

External agents are services hosted by partners or customers outside of watsonx Orchestrate. They expose an API that watsonx Orchestrate can call when needed. External agents cannot be chatted with directly — they must be attached to a native agent as collaborators.

This guide walks you through creating and listing an external agent in the watsonx Orchestrate Agent Catalog.

## Prerequisites

Before you begin, ensure you have:

* A REST service that exposes a `/chat/completions` endpoint or an agent that uses the [A2A protocol](https://a2a-protocol.org/latest/) version 0.3.0.
* API credentials for your service (API key or bearer token)
* Your service endpoint URL
* An SVG icon for your agent (square, 64-100px, max 200KB)

## Steps to create and list your external agent

<Warning>
  **Persistent test credentials required**:

  Provide persistent test credentials so IBM QA can validate consistently, ensuring repeatable tests, stable automation, and faster defect triage without disruptions from expiring tokens. These credentials should remain valid throughout the onboarding and validation process.
</Warning>

<Steps>
  <Step title="Build your external agent service">
    Choose the protocol that best fits your agent implementation:

    <Tabs>
      <Tab title="Chat Completions">
        Create a service that exposes a `/chat/completions` endpoint with the following requirements:

        * **Accepts conversation history**: Your endpoint must accept the conversation history in the request payload.
        * **Streaming support**: Always expects `"stream": true` in the payload and returns streams of SSE (Server-Sent Events).
        * **Authentication**: Secure the endpoint with API key or bearer token. The `api-key` header will always be `x-api-key`.
        * **Conforms to the spec**: Follow the [chat completions specification <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/blob/main/external_agent/spec.yaml).

        **Example implementations:**

        See the [External Agent GitHub Samples <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/external_agent) for reference implementations.
      </Tab>

      <Tab title="A2A Protocol">
        Create a service that implements the [Agent-to-Agent (A2A) protocol <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://a2a-protocol.org/latest/), an open standard for agent interoperability:

        * **Agent Card**: Expose an agent card (JSON file) that describes your agent's capabilities, skills, supported modalities, and authentication requirements. This serves as your agent's "business card" for discovery.
        * **Task-based communication**: Implement task lifecycle management with states: `submitted`, `working`, `input-required`, `completed`, `failed`.
        * **Supported transports**:
          * HTTP POST (synchronous)
          * Server-Sent Events (SSE) for streaming responses
          * Webhook push notifications
          * gRPC (v0.3.0)
        * **Authentication**: Support security schemes aligned with OpenAPI specification (API keys, OAuth 2.0, OpenID Connect).
        * **Version compatibility**: watsonx Orchestrate currently supports A2A version **0.3.0**. Set `provider` to `external_chat/A2A/0.3.0` when registering your agent.

        <Note>
          A2A protocol enables multi-agent collaboration where agents can discover each other's capabilities, delegate tasks, and coordinate actions across different platforms.
        </Note>

        **Example implementations:**

        * [A2A Sample Agents <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/a2a-samples) - LangGraph-based A2A agents
        * [A2A Protocol Specification <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://a2a-protocol.org/latest/) - Full protocol documentation
      </Tab>
    </Tabs>
  </Step>

  <Step title="Test your agent endpoint">
    Before submitting your agent, verify that your implementation works correctly:

    <Tabs>
      <Tab title="Chat Completions">
        Verify that:

        1. Your endpoint is publicly accessible (or accessible from watsonx Orchestrate)
        2. Authentication is working correctly
        3. The endpoint returns properly formatted SSE responses
        4. The agent handles conversation history appropriately

        You can test your endpoint using tools like `curl` or Postman to ensure it responds correctly to chat completion requests.
      </Tab>

      <Tab title="A2A Protocol">
        Verify that:

        1. Your agent card is accessible via URL and contains valid metadata
        2. Authentication is working correctly according to your chosen security scheme
        3. Task lifecycle states transition properly (`submitted` → `working` → `completed`/`failed`)
        4. Your agent handles multi-turn conversations with `input-required` state when needed
        5. Streaming responses work correctly if using SSE transport
        6. The agent exposes capabilities and skills accurately in the agent card

        Test your A2A agent using:

        * HTTP clients like `curl` or Postman to verify agent card retrieval and task submission
        * A2A-compatible client agent to test full protocol compliance
        * watsonx Orchestrate ADK for integration testing
      </Tab>
    </Tabs>
  </Step>

  <Step title="Create TSV validation file">
    Prepare a TSV (Tab-Separated Values) file for validation testing:

    **Format:**

    * Column 1: User query or prompt
    * Column 2: Expected agent response
    * Column 3: Agent identifier

    **Example:**

    ```tsv test.tsv theme={null}
    Find me a hotel in Tokyo	Here are available hotels in Tokyo: [list]	travel_agent
    What is the weather in Paris?	The current weather in Paris is 18°C and sunny.	weather_agent
    ```

    <Note>
      This file will be used by IBM QA to validate your agent's functionality during the onboarding process.
    </Note>
  </Step>

  <Step title="Prepare agent metadata">
    Gather the following information for your agent submission:

    <Tabs>
      <Tab title="Chat Completions">
        **Required information:**

        * **Agent name**: A unique identifier for your agent
        * **Display title**: The name users will see in the catalog
        * **Description**: Clear explanation of what your agent does
        * **API endpoint URL**: Your service's `/chat/completions` endpoint (e.g., `https://your-service.com/chat/completions`)
        * **Authentication details**:
          * Authentication scheme (API key or bearer token)
          * Your service credentials (managed by you, not watsonx Orchestrate)
        * **Publisher**: Your company/organization name
        * **Category tags**: Select from catalog categories (e.g., Sales, Productivity, Research, IT, Procurement, HR)
        * **Language support**: Languages your agent supports (e.g., English, Spanish)
        * **External protocol**: Select **External agent via chat completion**
        * **Icon**: SVG format, square shape, 64-100px, max 200KB

        **Optional information:**

        * **Related links**: Support, documentation, demo, training, terms and conditions
        * **Supported channels**: Teams, WhatsApp, Facebook Messenger, Genesys Connector
      </Tab>

      <Tab title="A2A Protocol">
        **Required information:**

        * **Agent name**: A unique identifier for your agent
        * **Display title**: The name users will see in the catalog
        * **Description**: Clear explanation of what your agent does and its capabilities
        * **Agent card URL**: URL where your agent card JSON is accessible (e.g., `https://your-service.com/agent-card`)
        * **API endpoint URL**: Your A2A service endpoint (e.g., `https://your-service.com/tasks`)
        * **Authentication details**:
          * Security scheme as defined in your agent card (API key, OAuth 2.0, OpenID Connect)
          * Your service credentials (managed by you, not watsonx Orchestrate)
        * **Agent capabilities**: Skills and tasks your agent can perform (defined in agent card)
        * **Supported modalities**: Input/output modes (e.g., text/plain, application/json)
        * **Publisher**: Your company/organization name
        * **Category tags**: Select from catalog categories (e.g., Sales, Productivity, Research, IT, Procurement, HR)
        * **Language support**: Languages your agent supports (e.g., English, Spanish)
        * **External protocol**: Select **External agent via A2A standard**
        * **A2A protocol version**: The only supported version is 0.3.0
        * **Icon**: SVG format, square shape, 64-100px, max 200KB

        **Optional information:**

        * **Related links**: Support, documentation, demo, training, terms and conditions
        * **Supported channels**: Teams, WhatsApp, Facebook Messenger, Genesys Connector
        * **Transport preferences**: HTTP POST, SSE, webhooks, or gRPC

        <Note>
          Your agent card should be publicly accessible and contain all metadata about your agent's capabilities, authentication requirements, and supported operations.
        </Note>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Submit via IBM Concierge app">
    Submit your external agent through the IBM Concierge web form:

    1. Log in to the **IBM Concierge** app.

    2. Navigate to **My AI products** → **Agent**.

    3. Select **External** as the agent type.

    4. Fill in the web form with your agent details:
       * Agent name and description
       * Domain tags
       * Agent role
       * LLM that will be used by the agent
       * Version
       * Channels where your agent will be deployed
       * [Style <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://developer.watson-orchestrate.ibm.com/agents/agent_styles)
       * Language support
       * External protocol
         * **External agent via chat completion**: Use this option if your external agent implements the standard chat completions API.
         * **External agent via A2A standard**: Select this option if your external agent uses the A2A protocol.

    5. Upload your agent icon:
       * SVG format
       * Square shape
       * Width and height between 64 and 100px
       * Maximum file size: 200KB

    6. Provide any related links (support, documentation, demo, training, terms and conditions).

    7. Click **Validate your agent** to provide your agent credentials for testing.

       * **Authentication details** (your service credentials - API key or bearer token)
       * **API endpoint URL** (your service endpoint, e.g., `https://your-service.com/chat/completions`)

           <Warning>
             **Service credentials**: The API endpoint URL and authentication credentials you provide are for **your external service**, not watsonx Orchestrate. These credentials are managed by you and used by watsonx Orchestrate to connect to your agent.
           </Warning>

    8. **Submit your TSV file** to **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with subject "TSV Validation - \[Agent Name]"

    9. Click **Save** once you are ready to submit your agent.

    10. Scroll to the top of the page and click **Request approval**.

    11. Select the deployment version, check the box **I confirm that my company is authorized to use all materials**, and click **Request approval**.
  </Step>
</Steps>

## What happens next

After submission:

1. **IBM review**: The IBM onboarding team will review your submission, validate your agent's functionality, and check that all required metadata is present.

2. **Approval**: Once approved, your agent will be published to the watsonx Orchestrate Agent Catalog.

3. **Availability**: Users can discover your agent in the catalog and add it as a collaborator to their native agents.

4. **Updates**: To update your agent, submit a new version through the IBM Concierge app with an incremented version number.

## Need help?

**Chat Completions resources:**

* Review the [chat completions specification <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/blob/main/external_agent/spec.yaml)
* Check the [External Agent GitHub Samples <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/external_agent)

**A2A Protocol resources:**

* Review the [A2A Protocol Specification <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://a2a-protocol.org/latest/)
* Check the [A2A Protocol GitHub Samples <Icon icon="arrow-up-right-from-square" iconType="solid" />](https://github.com/a2aproject/a2a-samples/tree/main/samples/python)

**General support:**

* Email questions to: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* Contact [IBM Support](https://ibm.com/mysupport) for technical assistance