Skip to main content

​
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
  • 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

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.
1

Build your external agent service

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 .
Example implementations:See the External Agent GitHub Samples for reference implementations.
2

Test your agent endpoint

Before submitting your agent, 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.
3

Prepare agent metadata

Gather the following information for your agent submission: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)
  • 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
4

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
    • Language support
  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)
    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.
  8. Click Save once you are ready to submit your agent.
  9. Scroll to the top of the page and click Request approval.
  10. Select the deployment version, check the box I confirm that my company is authorized to use all materials, and click Request approval.

​
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?