# Get started
Source: https://connect.watson-orchestrate.ibm.com/agent-connect/get-started
Learn how to apply for the watsonx Orchestrate Agent Connect program and how you can provide your solutions in the watsonx Orchestrate platform
## Requirements
Use this checklist to prepare what you'll need before you start. If something isn't ready yet, you can still sign in and begin.
### Account and Access
* Valid [watsonx Orchestrate ](https://www.ibm.com/products/watsonx-orchestrate) license
* [IBM Cloud account ](https://cloud.ibm.com/) for your company
* Permissions to create or edit product listings and submit onboarding information
### Business Information and Documents
* **Company legal details**: official name, address, and contact information
* **Required documents**:
* Tax documentation (W-9, W-8, or local equivalent)
* Banking information for payouts
* Additional documents for international entities (if applicable)
* You'll accept agreements and upload these documents in the IBM Concierge app
### Product Listing Information
* **Product name and description**: clear, customer-friendly language
* **Category or domain**: helps customers discover your offering
* **Support contact**: email address or support URL
* **Pricing model**: plan details and pricing structure
### Your Agent
Determine your agent type:
* **Native agent**: runs within watsonx Orchestrate, built with the [Agent Development Kit ](https://developer.watson-orchestrate.ibm.com/). Requires packaging and submission. See [Native Agent Onboarding](../agent/onboard-native) for details.
* **External agent**: hosted outside watsonx Orchestrate, connected via API. Requires service endpoint and credentials. See [External Agent Onboarding](../agent/onboard-external) for details.
**For external agents**: Prepare persistent test credentials for IBM QA validation. These credentials should remain valid throughout the onboarding process.
### MCP Server Integration (Optional)
If your agent requires MCP (Model Context Protocol) server capabilities:
* Review the [MCP Server Integration guide](../agent/mcp-server) (temporary solution)
* Prepare your JSON metadata template with agent and MCP server configuration
* Submit to **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with subject "MCP Server Metadata - \[Your Company Name]"
* IBM will build the MCP server for you during the onboarding process
* Timeline: Typically 3-5 business days for MCP server setup
**Temporary solution**: IBM currently builds MCP servers for partners. Self-service capabilities are coming soon.
### Team Roles (Recommended)
* **Business or Admin**: handles agreements, documents, listing details, pricing, and support information
* **Technical or Engineer**: manages agent packaging (Native) or connection setup (External)
**Tip:** Keep your listing descriptions concise and your support info accurate. This speeds reviews and avoids back-and-forth.
## Setup
Follow these steps the first time you use the IBM Concierge app. You can complete them in order or split them across your team.
1. Navigate to the [IBM Agent Connect ](https://www.ibm.com/products/watsonx-orchestrate/agent-connect) page.
2. Sign up and provide your company's information.
3. Wait until you receive an email with an invitation link.
1. **Open the invitation link** you received by email.
2. **Sign in** with your IBM credentials.
3. Watch the introductory videos.
4. Click the **My AI products** section or the **Get started** button to begin.
1. On the **Get started** page, provide the legal name of your company.
2. Click **Save**.
3. Assign access to other members of your team, if needed.
4. Click **Let's go** to proceed.
1. Click **Create** to add your AI product.
2. Select your product type.
3. Click **Next**.
4. Provide a **Display name** and a **Programmatic name**. The display name is used to show your product's name in the UI, and the programmatic name is a unique identifier used by IBM's services and tools.
5. Click **Next**.
6. Review your product details and click **Create** to proceed.
7. If you want to change your product's programmatic name, you must do it before you click the **Confirm** button in the **Product details** page.
8. After confirming the programmatic name, your product is sent for review and approval. Wait until the product is approved to proceed.
While you are waiting for approval, you can start working on your agent.
An agent is the core component you're onboarding to work with watsonx Orchestrate.
Choose the appropriate guide based on your agent type:
* **Native agents**: Follow the [Native Agent Onboarding](../agent/onboard-native) guide to build, package, and prepare your agent using the ADK.
* **External agents**: Follow the [External Agent Onboarding](../agent/onboard-external) guide to prepare your service endpoint and credentials.
**Optional - MCP Server Integration:**
If your agent needs MCP server capabilities, review the [MCP Server Integration guide](../agent/mcp-server) and prepare your metadata for submission to **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**.
Wait until you can submit your agent to complete the process.
1. After approval, go to the **Payments to me** section.
2. Follow the instructions on the page and fill out the forms.
3. Send the appropriate documentation to the provided email addresses.
4. Check the **I confirm that I have completed and emailed all of the required documents** box and click **Request approval**.
5. Once approved, you can continue with your product's listing.
1. Navigate to **My AI products** → **Catalog entry**.
2. You can add details for your product's entry in this section.
3. Upload a custom icon (optional). See [Icon design guidelines](../agent-connect/icon-design-guidelines) for format, size, and design requirements.
4. Go to the **Support** page and add information about how users can get support for your product.
5. Navigate to the **Brokers** page and provide a broker to connect your product to the IBM Concierge app. To learn how to create and onboard a broker, see [Service Broker](../broker/broker).
6. On the **Pricing** page, define your pricing details, and provide your **Export Control Classification Number** (ECCN). To learn more about pricing and how to find your ECCN, refer to [Pricing and metering](../pricing).
After the approval of your listing, you can proceed with the steps to onboard your agent:
* **Native agents**: Complete the packaging and submission steps in [Native Agent Onboarding](../agent/onboard-native).
* **External agents**: Submit your agent details through the IBM Concierge webform as described in [External Agent Onboarding](../agent/onboard-external).
**Important**: Both agent types require TSV validation files. See [Validating your agent](../evaluate/evaluate) for details.
For questions or support, contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**.
# Icon design guidelines
Source: https://connect.watson-orchestrate.ibm.com/agent-connect/icon-design-guidelines
Design and format requirements for the logo or icon you upload when listing your agent in the watsonx Orchestrate catalog.
When you create your catalog entry, you can upload a custom icon to represent your agent. A well-designed icon helps customers recognise your product and builds trust. Follow these guidelines to avoid validation failures and ensure your icon looks correct across all themes and screen sizes.
## File requirements
| Requirement | Value |
| ----------------- | ----------- |
| Format | SVG only |
| Maximum file size | 200 KB |
| Background | Transparent |
Upload an SVG file only. SVG files scale cleanly without losing clarity at any resolution, support transparency, and load quickly. PNG or other raster formats are not accepted.
Keep the file size under 200 KB. Optimise your SVG by removing unused metadata, comments, and hidden elements before uploading.
Icons that do not meet these requirements will fail validation during onboarding. Ensure your file is an SVG with a transparent background and is under 200 KB before you upload it.
## Design guidelines
### Use a transparent background
Do not include a coloured, white, or black background in your icon. The catalog renders icons on different backgrounds depending on the user's theme (light or dark). A transparent background ensures your icon blends in correctly in both themes.
### Represent your brand clearly
Your icon should be your company logo or a recognisable brand mark — not a generic illustration or clipart. The icon appears as a small tile in the catalog and must be identifiable at a glance.
### Keep it simple and high contrast
Icons display at small sizes in the catalog grid. Avoid fine details, thin strokes, or complex patterns that become illegible when scaled down. Use bold shapes and sufficient contrast between foreground elements and any backgrounds they will appear on.
### Use vector shapes only
Build your icon entirely from vector paths. Do not embed raster images (PNG, JPEG, GIF) inside your SVG — they cannot scale cleanly and increase file size.
### Avoid embedded fonts
Do not use text inside your icon, or if you must, convert all text to outlines (paths) before exporting. Embedded fonts can cause rendering inconsistencies across environments and increase file size.
## Dos and don'ts
* Upload a clean SVG with a transparent background.
* Use your company's official logo or brand mark.
* Ensure the icon reads clearly at 48 × 48 px.
* Optimise the SVG to remove unused elements and reduce file size.
* Test your icon on both light and dark backgrounds before uploading.
* Don't use a white, black, or coloured background rectangle.
* Don't upload a PNG, JPEG, or any raster format.
* Don't embed raster images or fonts inside the SVG.
* Don't use fine details or decorative elements that are illegible at small sizes.
* Don't exceed 200 KB.
## How to export an SVG correctly
The steps vary by tool, but the key principles are the same across Figma, Adobe Illustrator, and Inkscape:
1. Select your icon frame or component.
2. In the right panel, scroll to **Export** and click **+**.
3. Select **SVG** from the format drop-down.
4. Enable **Include "id" attribute** if needed; otherwise leave defaults.
5. Click **Export**.
6. Check that the exported SVG does not include a background rectangle.
1. Go to **File** → **Export** → **Export As**.
2. Choose **SVG** as the format.
3. In the SVG Options dialog, set **Styling** to **Presentation Attributes** and **Images** to **Embed**.
4. Ensure no background rectangle is included on the artboard.
5. Click **Export**.
1. Go to **File** → **Save As** and select **Plain SVG** or **Optimised SVG**.
2. Remove any background `` elements from the SVG source before saving.
3. Use **File** → **Clean Up Document** to strip unused elements.
## Optimising your SVG
After exporting, run your SVG through an optimiser to reduce file size before uploading:
* **[SVGO](https://github.com/svg/svgo)** — command-line optimiser (recommended)
* **[SVGOMG](https://svgomg.net/)** — browser-based interface for SVGO
A typical logo SVG should come in well under 200 KB after optimisation.
```bash theme={null}
# Install SVGO globally
npm install -g svgo
# Optimise your icon
svgo your-icon.svg -o your-icon-optimised.svg
```
## Where to upload your icon
Upload your icon in the IBM Concierge app when completing your catalog entry:
1. Navigate to **My AI products** → **Catalog entry**.
2. On the listing details page, click **Upload custom icon**.
3. Select your optimised SVG file.
4. Preview the icon and confirm it looks correct on both light and dark backgrounds.
The custom icon field is optional. If you do not upload an icon, the catalog displays a default placeholder icon for your product.
## Reference
For the equivalent guidelines in the main watsonx Orchestrate product documentation, see [Design guidelines for agent icons](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=catalog-design-guidelines-agent-icons) in the IBM Documentation.
# MCP Server Integration (Paid Listing)
Source: https://connect.watson-orchestrate.ibm.com/agent/mcp-server
## Overview
The Model Context Protocol (MCP) server integration allows builders to add partner Remote MCP servers directly from the watsonx Orchestrate catalog to their agents. This guide covers the submission process for **paid listings** where pricing and billing are managed through IBM.
Looking for BYOL (Bring Your Own License) instructions? See [MCP Server BYOL Integration](./mcp-server-byol).
## Quick Start: Accessing the Paid Listing Form
To begin submitting your paid MCP server listing:
1. Navigate to the **IBM Concierge** platform
2. Go to the **My AI products** page
3. Click the **Create** button
4. Select **Create a paid listing** in the License type section
5. Select **MCP Server** as the Product type
6. Follow the detailed steps below to complete your submission
Paid listings require completing a checklist and IBM approval before publishing. The entire process typically takes 5-7 business days for approval, plus up to 3 weeks for the MCP server to appear in the catalog.
## Prerequisites
Before submitting your MCP server, ensure you have:
* **Remote MCP server**: A functioning Remote MCP server endpoint
* **APP\_ID**: Unique identifier provided by IBM Ecosystem team (obtained via email)
* **Test credentials**: Valid credentials for IBM to create test connections
* **Documentation**: Setup documentation and at least one use case for testing
* **Authentication**: Supported authentication schema configured (OAuth2, API Key, Bearer Token, Basic Auth, or Key-Value)
* **Icon**: Square icon for your application (max size 200×200px)
## Supported Authentication Schemas
The MCP server supports all authentication schemas available in the watsonx Orchestrate platform:
* **OAuth2** (without Dynamic Client Registration)
* **API Key**
* **Bearer Token**
* **Basic Auth**
* **Key-Value**
For detailed authentication implementation guidance, see the [Remote MCP Toolkits documentation ](https://developer.watson-orchestrate.ibm.com/tools/toolkits/remote_mcp_toolkits).
## Obtaining Your APP\_ID
Before you can submit your MCP server through Concierge, you need to obtain an APP\_ID from the IBM Ecosystem team.
### Request Process
Contact the IBM Ecosystem team to request your APP\_ID:
* **Email**: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* **Subject**: "MCP APP\_ID Request - \[Your Company Name]"
* **Include**:
* Company name
* MCP server name
* Brief description
* Submission type: **Paid Listing**
The IBM Ecosystem team will respond via email with your unique APP\_ID. This APP\_ID is required when configuring your MCP server in the Concierge platform.
**Important**: Save the APP\_ID from the email response. You will need it when filling out the product details in Concierge.
## Submission Process
### Step 1: Create Your MCP Server Product
Navigate to the IBM Concierge platform and go to the **My AI products** page.
Click the **Create** button to start creating a new AI product.
In the **License type** section, select **Create a paid listing**.
Click **Next** to continue.
In the **Product type** section:
1. Select **MCP Server**
2. Click **Next**
In the **Product details** section:
* **Display name**: Enter a user-friendly name for your MCP server
* **Programmatic name**: Programmatic name is automatically derived from the display name
**Naming Requirements:**
**Display Name** - Allowed characters:
* Lowercase letters: `a-z`
* Numbers: `0-9`
* Space: ` `
* Forward slash: `/`
* Parentheses: `(` `)`
* Period: `.`
* Hyphen: `-`
Click **Next** to continue.
Review your product details and click **Create** to create your MCP server product.
### Step 2: Configure Your MCP Server
After creating your product, you'll be able to edit and configure all the details.
Configure the basic product information:
* **Name**: Validate the programmatic MCP server name (provided during creation)
The programmatic name cannot be edited. You can only validate that it's correct. If it needs to be changed, contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**.
* **Display Name**: User-friendly name for the catalog tile
* **Description**: Detailed description of your MCP server capabilities and features
* **Version**: MCP version (e.g., "1.0.0")
* **Change log**: Document changes in this version
Configure categorization and language support:
* **Domain tags**: Select 1-3 catalog categories:
* Customer Care
* Finance
* Healthcare
* HR
* Legal
* News
* Procurement
* Productivity
* Research
* Sales
* Security
* Talent Management
* **Language support**: Select all supported languages (e.g., English)
Configure application-specific settings:
* **Application ID**: Enter your APP\_ID (received via email from IBM Ecosystem team)
* **Application Name**: Your company name (recommended for searchability, though you can use any name)
* **Application icon**: Upload your square icon (max size 200×200px)
**Application Name**: It's best to use your actual company name to make your MCP server easily searchable in the catalog.
Provide your MCP server endpoint configuration:
* **Server end-point URL**: Your Remote MCP server endpoint URL
* **Transport**: Select transport type:
* Streamable HTTP
* SSE
Click the **Connect** button to provide authentication details for your MCP server:
* Select your authentication schema (OAuth2, API Key, Bearer Token, Basic Auth, or Key-Value)
* Provide the required credentials and configuration for the selected schema
* Test the connection to ensure it works correctly
Under **Related links**, click **Add custom links** to provide:
* **Support** (required): Link to your support resources
* **Terms and Conditions** (required): Link to your end-customer EULA
* **Documentation** (optional): Link to setup and usage documentation
* **Demo** (optional): Link to demo video or materials
* **Training** (optional): Link to training materials
Click **Save** to save your MCP server configuration.
### Step 3: Complete Checklist and Submit for Approval
For paid listings, you must complete a checklist before publishing:
Review the checklist in Concierge to see what needs to be completed. The checklist will include items such as:
* Validating the programmatic name
* Providing all required information
* Completing documentation requirements
* Providing test credentials and use cases
Work through each item in the checklist:
* Ensure all required fields are populated
* Validate that the programmatic name is correct
* Provide comprehensive documentation
* Submit test credentials for IBM validation
* Include at least one use case for testing
Once all checklist items are completed, submit your MCP server for IBM approval.
IBM will validate your submission:
1. Review submission completeness
2. Validate functionality and connectivity
3. Test use cases with provided credentials
4. Approve for catalog listing
**Timeline**: Validation typically takes 5-7 business days
Once IBM approves your submission, you can click **Publish** to initiate the publishing process.
**Publishing Timeline**: After clicking Publish, your MCP server will go through the watsonx Orchestrate release pipeline. It can take **up to 3 weeks** for your MCP server to appear in the catalog.
## What Happens After Publishing
Once your MCP server is published and appears in the catalog:
1. **Catalog listing**: Your MCP server appears in the watsonx Orchestrate catalog as a distinct listing type
2. **Builder access**: Builders can discover and add your Remote MCP server to their agents directly from the catalog
3. **Connection management**: Builders configure connections using the authentication schema you specified
4. **Usage tracking**: Monitor adoption and usage through IBM Ecosystem team reports
5. **IBM-managed billing**: Pricing and billing are handled through IBM's systems
## Updating Your MCP Server
To update your MCP server listing:
1. Access your MCP server product in IBM Concierge
2. Navigate to the **My AI products** page
3. Select your MCP server product
4. Update the relevant fields:
* Increment the version number
* Update description, documentation links, or other details
* Add notes to the change log explaining the updates
5. Click **Save**
6. Complete any checklist items if required
7. Submit for IBM approval
8. Once approved, click **Publish**
Updates follow the same approval process as initial submissions. Allow 5-7 business days for validation, plus up to 3 weeks for the update to appear in the catalog after publishing.
If you've lost your APP\_ID, contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with your MCP server name to retrieve it.
## Troubleshooting
### Common Issues
**APP\_ID not received:**
* Contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with subject "APP\_ID Request - \[Company Name]"
* Allow 2-3 business days for APP\_ID assignment
**Naming validation errors:**
* Verify programmatic name uses only allowed characters: `a-z`, `0-9`, `-`, `.`
* Verify display name uses only allowed characters: `a-z`, `0-9`, space, `/`, `(`, `)`, `.`, `-`
**Concierge form validation errors:**
* Ensure all required fields are populated
* Check that APP\_ID matches the one provided by IBM via email
* Validate URLs are properly formatted and accessible
* Verify icon file meets size and format requirements
**Authentication connection failures:**
* Confirm test credentials are valid and not expired
* Verify authentication schema matches your MCP server configuration
* Check that credentials have appropriate permissions
* Test connection manually before saving
**MCP server endpoint issues:**
* Ensure MCP server endpoint is publicly accessible
* Verify transport type (Streamable HTTP or SSE) is correctly specified
* Check firewall and security settings allow IBM access
* Test endpoint connectivity from external networks
**Checklist completion:**
* Review all checklist items carefully
* Ensure programmatic name is validated (not edited)
* Provide all required documentation and testing materials
* Contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** if you're unsure about any checklist item
**Publishing blocked:**
* Complete all checklist items
* Wait for IBM approval (5-7 business days)
* Check for any validation errors in the form
* Ensure all required fields have been saved
**MCP server not appearing in catalog:**
* Remember that it can take up to 3 weeks after publishing for your MCP server to appear
* Check the watsonx Orchestrate release schedule
* Contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** if it's been longer than 3 weeks
## Need Help?
For questions or support:
* **Email**: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* **Subject format**: "MCP Support - \[Your Company Name] - \[Issue Type]"
* **Include**: MCP server name, APP\_ID, error messages, and relevant details
**Useful resources:**
* [Remote MCP Toolkits Documentation ](https://developer.watson-orchestrate.ibm.com/tools/toolkits/remote_mcp_toolkits)
* [MCP Server BYOL Integration](./mcp-server-byol)
* [AI Product Onboarding](./onboard)
* [IBM Support](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=notes-getting-help-support)
# MCP Server Integration (BYOL)
Source: https://connect.watson-orchestrate.ibm.com/agent/mcp-server-byol
## Overview
The Model Context Protocol (MCP) server integration allows builders to add partner Remote MCP servers directly from the watsonx Orchestrate catalog to their agents. This guide covers the submission process for **BYOL (Bring Your Own License)** listings where you maintain your own licensing agreements with end customers.
Looking for paid listing instructions? See [MCP Server Integration (Paid Listing)](./mcp-server).
## Quick Start: Accessing the BYOL Form
To begin submitting your BYOL MCP server:
1. Navigate to the **IBM Concierge** platform
2. Go to the **My AI products** page
3. Click the **Create** button
4. Select **Create BYOL listing** in the License type section
5. Select **MCP Server** as the Product type
6. Follow the detailed steps below to complete your submission
The BYOL path bypasses several approval steps required for paid listings, allowing you to publish immediately after configuration.
## Prerequisites
Before submitting your MCP server, ensure you have:
* **Remote MCP server**: A functioning Remote MCP server endpoint
* **APP\_ID**: Unique identifier provided by IBM Ecosystem team (obtained via email)
* **Test credentials**: Valid credentials for IBM to create test connections
* **Documentation**: Setup documentation and at least one use case for testing
* **Authentication**: Supported authentication schema configured (OAuth2, API Key, Bearer Token, Basic Auth, or Key-Value)
* **Icon**: Square icon for your application (max size 200×200px)
* **Licensing system**: Your own license validation and management system
## Supported Authentication Schemas
The MCP server supports all authentication schemas available in the watsonx Orchestrate platform:
* **OAuth2** (without Dynamic Client Registration)
* **API Key**
* **Bearer Token**
* **Basic Auth**
* **Key-Value**
For detailed authentication implementation guidance, see the [Remote MCP Toolkits documentation ](https://developer.watson-orchestrate.ibm.com/tools/toolkits/remote_mcp_toolkits).
## Obtaining Your APP\_ID
Before you can submit your MCP server through Concierge, you need to obtain an APP\_ID from the IBM Ecosystem team.
### Request Process
Contact the IBM Ecosystem team to request your APP\_ID:
* **Email**: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* **Subject**: "MCP APP\_ID Request - \[Your Company Name]"
* **Include**:
* Company name
* MCP server name
* Brief description
* Submission type: **BYOL**
The IBM Ecosystem team will respond via email with your unique APP\_ID. This APP\_ID is required when configuring your MCP server in the Concierge platform.
**Important**: Save the APP\_ID from the email response. You will need it when filling out the product details in Concierge.
## Submission Process
### Step 1: Create Your MCP Server Product
Navigate to the IBM Concierge platform and go to the **My AI products** page.
Click the **Create** button to start creating a new AI product.
In the **License type** section, select **Create BYOL listing**.
Click **Next** to continue.
In the **Product type** section:
1. Select **MCP Server**
2. Click **Next**
In the **Product details** section:
* **Display name**: Enter a user-friendly name for your MCP server
**Display Name** - Allowed characters:
* Lowercase letters: `a-z`
* Numbers: `0-9`
* Space: ` `
* Forward slash: `/`
* Parentheses: `(` `)`
* Period: `.`
* Hyphen: `-`
For BYOL listings, you do not provide the programmatic name during creation. It will be automatically generated from your display name in the configuration step.
Click **Next** to continue.
Review your product details and click **Create** to create your MCP server product.
### Step 2: Configure Your MCP Server
After creating your product, you'll be able to edit and configure all the details.
Configure the basic product information:
* **Name**: The programmatic MCP server name (derived from Display Name, read-only)
* **Display Name**: User-friendly name for the catalog tile (used to auto-generate the programmatic name)
* **Description**: Detailed description of your MCP server capabilities and features
* **Version**: MCP version (e.g., "1.0.0")
* **Change log**: Document changes in this version
Configure categorization and language support:
* **Domain tags**: Select 1-3 catalog categories:
* Customer Care
* Finance
* Healthcare
* HR
* Legal
* News
* Procurement
* Productivity
* Research
* Sales
* Security
* Talent Management
* **Language support**: Select all supported languages (e.g., English)
Configure application-specific settings:
* **Application ID**: Enter your APP\_ID (received via email from IBM Ecosystem team)
* **Application Name**: Your company name (recommended for searchability, though you can use any name)
* **Application icon**: Upload your square icon (max size 200×200px)
**Application Name**: It's best to use your actual company name to make your MCP server easily searchable in the catalog.
Provide your MCP server endpoint configuration:
* **Server end-point URL**: Your Remote MCP server endpoint URL
* **Transport**: Select transport type:
* Streamable HTTP
* SSE
Click the **Connect** button to provide authentication details for your MCP server:
* Select your authentication schema (OAuth2, API Key, Bearer Token, Basic Auth, or Key-Value)
* Provide the required credentials and configuration for the selected schema
* Test the connection to ensure it works correctly
Under **Related links**, click **Add custom links** to provide:
* **Support** (required): Link to your support resources
* **Terms and Conditions** (required): Link to your end-customer EULA
* **Documentation** (optional): Link to setup and usage documentation
* **Demo** (optional): Link to demo video or materials
* **Training** (optional): Link to training materials
Click **Save** to save your MCP server configuration.
### Step 3: Publish Your MCP Server
For BYOL listings, you can publish without IBM approval:
Review your MCP server configuration to ensure all information is correct and complete.
Click **Publish** to initiate the publishing process.
**Publishing Timeline**: After clicking Publish, your MCP server will go through the watsonx Orchestrate release pipeline. It can take **up to 3 weeks** for your MCP server to appear in the catalog.
## BYOL-Specific Considerations
### Licensing Management
* **Custom licensing**: You maintain your own licensing agreements with end customers
* **License validation**: Your MCP server must handle license validation independently
* **APP\_ID usage**: The APP\_ID provided by IBM is used for catalog identification, not license management
* **Customer onboarding**: You're responsible for customer licensing and onboarding workflows
### Support Model
* **Direct support**: You provide direct support to your customers
* **License issues**: Handle all license-related inquiries and issues
* **Technical support**: Provide technical support for your MCP server functionality
### Catalog Visibility
* **Immediate publishing**: BYOL listings can be published without IBM approval
* **Release pipeline**: Still subject to the watsonx Orchestrate release schedule (up to 3 weeks)
* **Catalog presence**: Your MCP server appears in the catalog with BYOL designation
## What Happens After Publishing
Once your MCP server is published and appears in the catalog:
1. **Catalog listing**: Your MCP server appears in the watsonx Orchestrate catalog as a BYOL listing
2. **Builder access**: Builders can discover and add your Remote MCP server to their agents directly from the catalog
3. **Connection management**: Builders configure connections using the authentication schema you specified
4. **License validation**: Your MCP server validates licenses according to your licensing system
5. **Usage tracking**: Monitor adoption and usage through IBM Ecosystem team reports
6. **Direct billing**: You handle all billing and licensing directly with your customers
## Updating Your MCP Server
To update your MCP server listing:
1. Access your MCP server product in IBM Concierge
2. Navigate to the **My AI products** page
3. Select your MCP server product
4. Update the relevant fields:
* Increment the version number
* Update description, documentation links, or other details
* Add notes to the change log explaining the updates
5. Click **Save**
6. Click **Publish** to publish the update
Updates still go through the watsonx Orchestrate release pipeline. Allow up to 3 weeks for the update to appear in the catalog after publishing.
If you've lost your APP\_ID, contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with your MCP server name to retrieve it.
## Troubleshooting
### Common Issues
**APP\_ID not received:**
* Contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with subject "APP\_ID Request - \[Company Name]"
* Specify "BYOL" in your request
* Allow 2-3 business days for APP\_ID assignment
**Naming validation errors:**
* Verify display name uses only allowed characters: `a-z`, `0-9`, space, `/`, `(`, `)`, `.`, `-`
**Concierge form validation errors:**
* Ensure all required fields are populated
* Check that APP\_ID matches the one provided by IBM via email
* Validate URLs are properly formatted and accessible
* Verify icon file meets size and format requirements
**Authentication connection failures:**
* Confirm test credentials are valid and not expired
* Verify authentication schema matches your MCP server configuration
* Check that credentials have appropriate permissions
* Test connection manually before saving
**MCP server endpoint issues:**
* Ensure MCP server endpoint is publicly accessible
* Verify transport type (Streamable HTTP or SSE) is correctly specified
* Check firewall and security settings allow IBM access
* Test endpoint connectivity from external networks
**Publishing blocked:**
* Ensure all required fields are saved
* Check for any validation errors in the form
* Verify programmatic name has been provided
**MCP server not appearing in catalog:**
* Remember that it can take up to 3 weeks after publishing for your MCP server to appear
* Check the watsonx Orchestrate release schedule
* Contact **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** if it's been longer than 3 weeks
**License validation issues:**
* Ensure your MCP server properly validates licenses
* Test license validation with various scenarios
* Provide clear error messages to users when licenses are invalid
* Document license requirements in your support materials
## Need Help?
For questions or support:
* **Email**: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* **Subject format**: "MCP BYOL Support - \[Your Company Name] - \[Issue Type]"
* **Include**: MCP server name, APP\_ID, error messages, and relevant details
**Useful resources:**
* [Remote MCP Toolkits Documentation ](https://developer.watson-orchestrate.ibm.com/tools/toolkits/remote_mcp_toolkits)
* [MCP Server Integration (Paid Listing)](./mcp-server)
* [AI Product Onboarding](./onboard)
* [IBM Support](https://ibm.com/mysupport)
# AI Product Onboarding
Source: https://connect.watson-orchestrate.ibm.com/agent/onboard
## Introduction
**watsonx Orchestrate** supports two types of agents: **native agents** and **external agents**.
* **External agents** are services hosted by partners or customers outside of WXO. They expose an API that watsonx Orchestrate can call when needed.
* **Native agents** are built and deployed directly within Orchestrate. They use IBM-managed models, tools, and runtime.
An external agent is typically implemented as a REST service that conforms to a [chat completions ](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/blob/main/external_agent/spec.yaml) interface. This allows it to receive conversation history and return structured responses in real time.
Because external agents cannot be chatted with directly, they are always used as collaborators to a native agent. The native agent acts as the **host agent**, and delegates specific tasks to the external agent when appropriate.
## Video guide
## Choose your agent type
Select the type of agent you want to create and list in the watsonx Orchestrate Agent Catalog:
Host your agent externally and connect it to watsonx Orchestrate via API. Submit your agent details through the IBM Concierge web form.
Build and deploy your agent directly within watsonx Orchestrate using the Agent Development Kit (ADK). Package and submit your agent for catalog listing.
## MCP Server Integration (Optional)
List your Remote MCP server in the watsonx Orchestrate catalog. Partners can submit MCP specifications through the IBM Concierge web form or manual submission. Requires APP\_ID from IBM Ecosystem team.
**Interim solution**: MCP listing capability available end of March. Submit your MCP specification through the IBM Concierge app or via email with your assigned APP\_ID.
## What IBM checks during onboarding
When you submit your agent, the IBM Concierge and IBM onboarding team validate:
* **Offering metadata**: publisher, tags, category, and icon are properly set. See [Icon design guidelines](../agent-connect/icon-design-guidelines) for icon requirements.
* **Agent definition**: API details, authentication scheme, and structure are correct.
* **TSV validation files**: test cases are provided for both native and external agents.
* **Evaluation artifacts**: validation results and metrics are included and show that the agent is functional.
* **Folder structure** (native agents only): matches the required scaffold (agents, offerings, evaluations, etc.).
* **App ID** (native agents with tools): unique identifier is properly configured.
* **MCP server specification** (if applicable): JSON configuration is complete, APP\_ID is assigned, and test credentials are provided.
If something is missing, the onboarding team will ask you to repackage and resubmit.
## What happens after approval
* **Catalog publishing**: Once your submission is reviewed and approved, your agent enters the publishing queue for the watsonx Orchestrate Catalog.
* **Discovery & provisioning**: End-users will then be able to find your agent in the catalog, provision it into their own environment, and use it directly in Orchestrate flows.
* **Ongoing updates**: To ship new features or fixes, simply increment the version number in your agent definition, re-run the packaging process (for native agents) or update your submission (for external agents), and resubmit through the IBM Concierge app. The same validation and approval process applies.
## Need help?
For questions or support during the onboarding process:
* Email: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* Include your agent name and company name in the subject line
* Contact [IBM Support](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=notes-getting-help-support) for technical assistance
# External Agent Onboarding
Source: https://connect.watson-orchestrate.ibm.com/agent/onboard-external
## 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 — see [Icon design guidelines](../agent-connect/icon-design-guidelines) for requirements
## 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.
Choose the protocol that best fits your agent implementation:
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 ](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/blob/main/external_agent/spec.yaml).
**Example implementations:**
See the [External Agent GitHub Samples ](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/external_agent) for reference implementations.
Create a service that implements the [Agent-to-Agent (A2A) protocol ](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.
A2A protocol enables multi-agent collaboration where agents can discover each other's capabilities, delegate tasks, and coordinate actions across different platforms.
**Example implementations:**
* [A2A Sample Agents ](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/a2a-samples) - LangGraph-based A2A agents
* [A2A Protocol Specification ](https://a2a-protocol.org/latest/) - Full protocol documentation
Before submitting your agent, verify that your implementation works correctly:
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.
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
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
```
This file will be used by IBM QA to validate your agent's functionality during the onboarding process.
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)
* **External protocol**: Select **External agent via chat completion**
* **Icon**: SVG format — see [Icon design guidelines](../agent-connect/icon-design-guidelines) for requirements
**Optional information:**
* **Related links**: Support, documentation, demo, training, terms and conditions
* **Supported channels**: Teams, WhatsApp, Facebook Messenger, Genesys Connector
**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 — see [Icon design guidelines](../agent-connect/icon-design-guidelines) for requirements
**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
Your agent card should be publicly accessible and contain all metadata about your agent's capabilities, authentication requirements, and supported operations.
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 ](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. See [Icon design guidelines](../agent-connect/icon-design-guidelines) for format, size, and design requirements.
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. **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**.
## 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 ](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/blob/main/external_agent/spec.yaml)
* Check the [External Agent GitHub Samples ](https://github.com/watson-developer-cloud/watsonx-orchestrate-developer-toolkit/tree/main/external_agent)
**A2A Protocol resources:**
* Review the [A2A Protocol Specification ](https://a2a-protocol.org/latest/)
* Check the [A2A Protocol GitHub Samples ](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://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=notes-getting-help-support) for technical assistance
# Native Agent Onboarding
Source: https://connect.watson-orchestrate.ibm.com/agent/onboard-native
## Overview
Native agents are built and deployed directly within watsonx Orchestrate. They use IBM-managed models, tools, and runtime. Native agents can call tools, other native agents as collaborators, and be chatted with directly by end-users.
This guide walks you through building, validating, packaging, and listing a native agent in the watsonx Orchestrate Agent Catalog using the Agent Development Kit (ADK).
**Catalog onboarding limitations**: We currently don't support onboarding certain native agent components and tools into the Catalog, including Knowledge, Flows, Model Gateway, OpenAPI Tools, and Langflow Tools. The team is actively working on expanding this capability, so stay tuned — we'll announce updates as soon as these become available.
Note that these components are fully supported by the watsonx Orchestrate platform for your own use; this limitation applies only to catalog onboarding for partner distribution.
## Prerequisites
Before you begin, ensure you have:
* Access to a watsonx Orchestrate environment
* The [Agent Development Kit (ADK) ](https://developer.watson-orchestrate.ibm.com/) installed
* Python 3.8 or higher (for building tools)
* An SVG icon for your agent — see [Icon design guidelines](../agent-connect/icon-design-guidelines) for requirements
**App ID Required**: Native agents with custom tools require a unique App ID issued by IBM. This identifier is essential for your agent's integration within the watsonx Orchestrate ecosystem. IBM will generate and provide your App ID during the onboarding process BEFORE submission. The app\_id will be embedded in the code itself that is part of the submission.
## Steps to create and list your native agent
Follow the instructions in the [Getting started with the ADK ](https://developer.watson-orchestrate.ibm.com/getting_started/installing) to:
1. Install the Agent Development Kit
2. Connect it to your watsonx Orchestrate environment
3. Configure your credentials
Build your native agent following the [Getting started with the ADK ](https://developer.watson-orchestrate.ibm.com/getting_started/installing) tutorial.
To learn more about native agent capabilities, see [Authoring agents ](https://developer.watson-orchestrate.ibm.com/agents/build_agent).
**Key components of a native agent:**
* **LLM selection**: Choose from IBM-managed models (e.g., Granite, Llama)
* **Instructions**: Define your agent's behavior and personality
* **Tools**: Add capabilities through Python or OpenAPI tools
* **Collaborators**: Connect to external agents for specialized tasks
Native agents can call tools to perform tasks. Define tools as Python or YAML (OpenAPI) files.
```python search_healthcare.py theme={null}
from typing import List
import requests
from pydantic import BaseModel, Field
from enum import Enum
from ibm_watsonx_orchestrate.agent_builder.tools import tool
class ContactInformation(BaseModel):
phone: str
email: str
class HealthcareSpeciality(str, Enum):
GENERAL_MEDICINE = 'General Medicine'
CARDIOLOGY = 'Cardiology'
PEDIATRICS = 'Pediatrics'
ORTHOPEDICS = 'Orthopedics'
ENT = 'Ear, Nose and Throat'
MULTI_SPECIALTY = 'Multi-specialty'
class HealthcareProvider(BaseModel):
provider_id: str = Field(None, description="The unique identifier of the provider")
name: str = Field(None, description="The providers name")
provider_type: str = Field(None, description="Type of provider")
specialty: HealthcareSpeciality = Field(None, description="Medical speciality")
address: str = Field(None, description="The address of the provider")
contact: ContactInformation = Field(None, description="Contact information")
@tool
def search_healthcare_providers(
location: str,
specialty: HealthcareSpeciality = HealthcareSpeciality.GENERAL_MEDICINE
) -> List[HealthcareProvider]:
"""
Retrieve healthcare providers based on location and specialty.
Args:
location: Geographic location (city, state, zip code)
specialty: Medical specialty to filter by
Returns:
A list of healthcare providers
"""
resp = requests.get(
'https://find-provider.example.com',
params={'location': location, 'speciality': specialty}
)
resp.raise_for_status()
return resp.json()['providers']
```
```yaml search_healthcare.yaml theme={null}
servers:
- url: https://find-provider.example.com
paths:
/:
get:
operationId: getHealthCareProviders
summary: Gets a list of healthcare providers
parameters:
- in: query
name: location
schema:
type: string
description: The city, state or zipcode
- in: query
name: speciality
schema:
type: string
enum: ["General Medicine", "Cardiology", "Pediatrics", "Orthopedics", "ENT", "Multi-specialty"]
description: The speciality of the healthcare provider
responses:
'200':
description: Successfully retrieved list
content:
application/json:
schema:
type: object
properties:
providers:
type: array
items:
type: object
```
To learn more about tools, see [Overview of Tools ](https://developer.watson-orchestrate.ibm.com/tools/overview).
Import your agent into your draft environment:
```bash theme={null}
orchestrate agents import -f my_native_agent.yaml
```
For more information, see [Importing/Deploying agents ](https://developer.watson-orchestrate.ibm.com/agents/import_agent).
**Option 1: Test in watsonx Orchestrate UI**
1. Log in to your watsonx Orchestrate instance and open the **Agent Builder**:
2. In the **Build agents and tools** page, select your agent:
3. Use the test chat to verify your agent's behavior:
**Option 2: Test with watsonx Orchestrate Developer Edition**
If you have [installed watsonx Orchestrate Developer Edition ](https://developer.watson-orchestrate.ibm.com/developer_edition/wxOde_setup), use the ADK command line:
```bash theme={null}
orchestrate chat start
```
To install watsonx Orchestrate Developer Edition, you need a valid license. You can obtain a license by:
* Purchasing a license for watsonx Orchestrate SaaS (on AWS or IBM Cloud)
* Contacting the IBM sales department to purchase the Developer Edition exclusively
Create a comprehensive TSV test file with AT LEAST THREE prompts and expected outputs:
```txt test.tsv theme={null}
You are Jane Doe in the US. What holiday is on 06/13/2025? National Sewing Machine Day
What is the capital of France? Paris
```
**Important**: This TSV file is required for IBM validation and must be included in your submission package.
Run validation with ADK:
```bash theme={null}
orchestrate evaluations validate-native \
-t ./evaluations/test.tsv \
-o ./evaluations/output
```
This generates an evaluation results archive containing:
* `test.tsv` - your original test file
* `validation_results.json` - detailed pass/fail logs
* `summary_metrics.csv` - aggregate metrics
**Submit your TSV file:**
* Include in your package under `evaluations/`
* Email a copy to: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)** with subject "TSV Validation - \[Agent Name]"
For more information, see [Validating your agent](../evaluate/evaluate).
Create a packaging workspace for your offering:
```bash theme={null}
orchestrate partners offering create \
--offering my_offering \
--publisher partner_company \
--type native \
--agent-name my_native_agent
```
This command creates a folder structure:
```
my_offering/
├── agents/ # Your agent definition(s)
│ └── my_native_agent.json
├── connections/ # (Optional) Connection definitions
│ └── my_connections.json
├── offerings/ # Top-level offering metadata
│ └── my_offering.json
├── tools/ # (Optional) Custom tools
│ └── ...
└── evaluations/ # Validation artifacts (you add these next)
└── my_native_agent_eval.zip
```
**Folder contents:**
* `agents/`: Your agent JSON file with required metadata (publisher, tags, icon, etc.)
* `connections/` (optional): Credential or endpoint definitions
* `offerings/`: Offering identity and type metadata
* `tools/` (optional): Tool definitions
* `evaluations/`: Validation results from Step 6
Copy your evaluation results archive into the `evaluations/` folder:
```bash theme={null}
cp ./evaluations/output/my_native_agent_eval.zip ./my_offering/evaluations/
```
These artifacts prove your agent behaves correctly and are required for IBM onboarding review.
Before packaging, ensure your agent configuration file (`config.json`) has all required fields:
```json config.json theme={null}
{
"spec_version": "v1",
"kind": "native",
"name": "my_native_agent",
"display_name": "My Native Agent",
"llm": "groq/openai/gpt-oss-120b",
"style": "default",
"description": "Your agent description",
"instructions": "Your agent instructions",
"tags": ["Sales", "Productivity"],
"publisher": "Your Company Name",
"language_support": ["English"],
"icon": "",
"category": "agent",
"restrictions": "editable",
"hidden": false,
"version": "1.0.0",
"change_log": ["Initial release"],
"related_links": [
{
"key": "support",
"value": "https://your-support-url.com",
"type": "hyperlink"
},
{
"key": "documentation",
"value": "https://your-docs-url.com",
"type": "hyperlink"
},
{
"key": "terms_and_conditions",
"value": "https://your-terms-url.com",
"type": "hyperlink"
}
],
"agent_role": "collaborator",
"delete_by": null,
"channels": ["Teams", "WhatsAppTwilio", "FacebookMessenger", "GenesysConnector", "Slack"],
"part_number": {
"aws": null,
"ibmcloud": "your_part_number",
"cp4d": null
},
"scope": {
"form_factor": {
"aws": "free",
"ibmcloud": "paid",
"cp4d": "free"
}
},
"tools": [],
"collaborators": []
}
```
The specification version. Use `v1`.
The type of agent. For native agents, use `native`.
The unique identifier for your agent. Use lowercase with underscores (e.g., `my_native_agent`).
Human-readable name for your agent that will be shown in the UI (e.g., "My Native Agent").
The language model to use for your agent (e.g., `groq/openai/gpt-oss-120b`).
The agent's interaction style. Use `default` or `react`.
A brief description of what your agent does. This will be displayed in the catalog.
Detailed instructions that define your agent's behavior, personality, and how it should respond to user queries.
The version number of your agent (e.g., `1.0.0`). Must be incremented for each update.
Categories for catalog organization. Use existing catalog categories like `Sales`, `Productivity`, `IT`, `Security`, `Compliance`, etc.
Your company or organization name (e.g., "Your Company Name").
List of supported languages (e.g., `English`, `French`, `Spanish`, `Japanese`).
Inline SVG string for your agent's icon. See [Icon design guidelines](../agent-connect/icon-design-guidelines) for format, size, and design requirements.
The catalog category. Always use `agent` for agents. Do not edit this field.
Defines how users can modify the agent. Options: `editable`, `non-editable`, or `custom`.
Set to `true` to hide the agent from the catalog, `false` to make it visible. Default is `false`.
Version history describing changes in each release (e.g., `["Initial release", "Added new features"]`).
Array of related links for support, documentation, and terms. Each link object contains:
* `key`: Link label (e.g., `support`, `documentation`, `terms_and_conditions`)
* `value`: URL string
* `type`: Always use `hyperlink`
The role of the agent. Always use `collaborator`. Do not edit this field.
Deletion timestamp. Always use `null`. Do not edit this field.
List of supported communication channels. Options include: `Teams`, `WhatsAppTwilio`, `FacebookMessenger`, `GenesysConnector`, `Slack`.
Platform-specific part numbers for billing and provisioning. Contains:
* `aws`: Part number for AWS deployments (or `null`)
* `ibmcloud`: Part number for IBM Cloud deployments
* `cp4d`: Part number for Cloud Pak for Data deployments (or `null`)
Defines the pricing model per platform. Contains `form_factor` object with:
* `aws`: Pricing model for AWS (`free` or `paid`)
* `ibmcloud`: Pricing model for IBM Cloud (`free` or `paid`)
* `cp4d`: Pricing model for Cloud Pak for Data (`free` or `paid`)
Array of tool definitions that your agent can use. Can be empty `[]` if no tools are needed.
Array of external agents that this agent can collaborate with. Can be empty `[]` if no collaborators are needed.
Package everything into a distributable ZIP:
```bash theme={null}
orchestrate partners offering package \
--offering my_offering \
--folder .
```
This command:
* Validates folder structure and required files
* Bundles artifacts into a portable archive
* Outputs a versioned package (e.g., `my_offering-1.0.zip`)
The ZIP contains:
* `agents/` - your agent definitions with metadata
* `offerings/` - top-level metadata
* `connections/` - if defined
* `tools/` - if defined
* `evaluations/` - validation results
Submit your packaged agent through the IBM Concierge app:
1. Log in to the **IBM Concierge** app.
2. Navigate to **My AI products** → **Agent**.
3. Select **Native** as the agent type.
4. Upload your package file (`my_offering-1.0.zip`).
5. Check the fields from the **Agent details** form. The form should reflect the values from your package file.
6. Click **Save** once you are ready to submit your package.
7. Scroll to the top of the page and click **Request approval**.
8. 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 validates your package structure, metadata, and evaluation results.
2. **Approval**: Once approved, your agent is published to the watsonx Orchestrate Agent Catalog.
3. **Availability**: Users can discover and provision your agent into their environments.
4. **Updates**: To update your agent, increment the version number, repackage, and resubmit through the IBM Concierge app.
## Need help?
* Review the [ADK documentation ](https://developer.watson-orchestrate.ibm.com/)
* Check the [Authoring agents guide ](https://developer.watson-orchestrate.ibm.com/agents/build_agent)
* See [Tools overview ](https://developer.watson-orchestrate.ibm.com/tools/overview)
* Email questions to: **[IBMAgentConnect@ibm.com](mailto:IBMAgentConnect@ibm.com)**
* Contact [IBM Support](https://www.ibm.com/docs/en/watsonx/watson-orchestrate/base?topic=notes-getting-help-support) for technical assistance
# Onboard a Service Broker
Source: https://connect.watson-orchestrate.ibm.com/broker/broker
## What is a Service Broker
A service broker manages the lifecycle of services. Platforms interact with service brokers to create, access, and manage services. The broker functions as middleware, handling automatic provisioning of service instances and tracking their usage.
## How the Partner Service Broker Works
When a user creates or purchases a service from the IBM Cloud Catalog, the process includes:
1. IBM Cloud validates the user’s permission to create the service instance using IBM Cloud IAM.
2. The platform associates the user with the service instance and selected pricing plan, generating a unique Cloud Resource Name (CRN).
3. Based on service specifications and user input, the partner service broker provisions the service instance or sets up the environment by calling the broker’s creation endpoint.
The IBM Cloud Resource Controller performs the first two steps. The partner service broker handles the third step, which includes:
1. Provisioning new service instances according to the catalog and pricing plan.
2. Connecting or disconnecting applications and containers from service instances.
3. Deprovisioning service instances.
## watsonx Orchestrate Partner Agent Service Broker
Onboarding watsonx Orchestrate (wxO) partner agents or tools requires registering them in the IBM Cloud Catalog for sales, purchase, and billing. Partners must create a service broker for their agents. However, because the IBM Cloud Catalog targets SaaS offerings, wxO partners may not need to implement the full provisioning lifecycle or all service broker endpoints.
## Design Considerations
When designing a service broker, consider:
1. **Authentication**: Review [IBM Cloud authentication ](https://cloud.ibm.com/docs/sell?topic=sell-broker-onboard\&interface=ui) options and choose the best fit.
2. **Deployment Model**: Determine how agents or tools are deployed and how customers will use them. This affects the broker’s required functionality.
Here's a comparison between IBM Cloud's recommended Bearer CRN token and the Bearer token:
### Authentication
Partners must follow IBM Cloud authentication guidelines. IBM recommends using Bearer CRN tokens or Bearer tokens. See the following code for JWT authorization example:
```typescript authorization_middleware.ts [expandable] theme={null}
import crypto, { JsonWebKey } from 'node:crypto'
import { RequestHandler } from 'express'
import jwt from 'jsonwebtoken'
import axios from 'axios'
import logger from '../utils/logger'
const KEYS_ENDPOINT = `${process.env.IAM_ENDPOINT as string}/identity/keys`
interface IAMIdentityKeysResponse {
keys: JsonWebKey[]
}
interface AuthenticatorParams {
basicAuthUsername: string
basicAuthPassword: string
allowlistedIds: string[]
}
export class Authenticator {
private IAMPublicKeys: JsonWebKey[] = []
private basicAuthUsername: string
private basicAuthPassword: string
private allowlistedIds: Set
private basicCredential: string
private intervalHandle: NodeJS.Timeout | undefined
public static async build(params: AuthenticatorParams) {
const instance = new Authenticator(params)
await instance.init()
return instance
}
constructor({
allowlistedIds,
basicAuthPassword,
basicAuthUsername,
}: AuthenticatorParams) {
this.allowlistedIds = new Set(allowlistedIds)
this.basicAuthPassword = basicAuthPassword
this.basicAuthUsername = basicAuthUsername
this.basicCredential = Buffer.from(
`${basicAuthUsername}:${basicAuthPassword}`,
).toString('base64')
}
private async fetchIdentityKeys(): Promise {
try {
const resp = await axios.get(KEYS_ENDPOINT)
return resp.data.keys
} catch (e) {
logger.error(`Error fetching IAM Identity keys ${e}`)
throw e
}
}
public async init(): Promise {
this.IAMPublicKeys = await this.fetchIdentityKeys()
const to = setInterval(
async arg => {
arg.IAMPublicKeys = await arg.fetchIdentityKeys()
},
20 * 60 * 1000,
this,
)
to.unref()
this.intervalHandle = to
}
private verifyJWT(credential: string): string | jwt.JwtPayload {
const decodedToken = jwt.decode(credential, { complete: true })
if (!decodedToken) {
throw new Error('token could not be decoded')
}
const { kid, alg } = decodedToken.header
const matchingKey = this.IAMPublicKeys.find(
key => key.kid === kid && key.alg === alg,
)
if (!matchingKey) {
logger.error('could not find matching key for token validation')
throw new Error('invalid token')
}
try {
return jwt.verify(
credential,
crypto.createPublicKey({
key: matchingKey,
format: 'jwk',
}),
)
} catch (e) {
logger.error(e)
throw new Error('invalid token')
}
}
private authorizeBasicCredential(credential: string): boolean {
return credential === this.basicCredential
}
private authorizeBearerCredential(credential: string): boolean {
let token
try {
token = this.verifyJWT(credential)
} catch (e) {
logger.error('invalid token')
return false
}
if (typeof token !== 'object') {
logger.error('invalid token type')
return false
}
const { id } = token
if (!this.allowlistedIds.has(id)) {
logger.error('identity not allowed')
return false
}
return true
}
public authorizeRequest: RequestHandler = (req, res, next) => {
const authHeader = req.headers['authorization']
if (!authHeader) {
logger.warn('Authorization header is missing')
return res.sendStatus(401)
}
const [authType, credentials] = authHeader.split(' ')
if (!authType) {
return res.sendStatus(401)
}
if (!credentials) {
return res.sendStatus(401)
}
switch (authType.toLowerCase()) {
case 'basic':
if (!this.authorizeBasicCredential(credentials)) {
return res.sendStatus(403)
}
break
case 'bearer':
if (!this.authorizeBearerCredential(credentials)) {
return res.sendStatus(403)
}
break
default:
return res.sendStatus(401)
}
next()
}
}
```
## Partner Agent Scenarios
### External Agents
Partners host agents in their own environment. Customers access these agents via predefined URLs or APIs. The broker must:
* Return credentials or access details (e.g., token, URL).
* Provision customer-specific deployments or environments as needed.
### Native Agents
Partners host agents within watsonx Orchestrate. In most cases, the broker does not need to provision resources because agents run on the watsonx Orchestrate platform. The broker may only return IBM Cloud Resource Controller context.
If additional setup is required (e.g., creating a customer-specific knowledge base), the broker must:
* Perform the necessary setup based on customer input, or
* Provide credentials for the customer to complete the setup.
### Partner Tools
Partners provide tools that connect to services or databases. The broker must return URLs, API keys, or credentials to enable tool usage.
## Implement, Test, and Onboard
* **Implementation**: See the following example Python implementation:
```python service_broker.py [expandable] theme={null}
import asyncio
from abc import ABC, abstractmethod
from typing import Optional, Dict, Any
import json
class Context:
def __init__(self, details: Any):
my_dict = json.loads(details)
self.account_id = my_dict["account_id"]
self.resource_group_crn = my_dict["resource_group_crn"]
self.target_crn = my_dict["target_crn"]
self.name = my_dict["name"]
self.crn = my_dict["crn"]
self.platform = my_dict["platform"]
class CreateServiceInstanceResponse:
def __init__(self, instance_id: str, status: str, context: Optional[Context], metadata: Optional[Dict[str, Any]]):
self.instance_id = instance_id
self.status = status
self.context = context
self.metadata = metadata
class Catalog:
def __init__(self, items: list[str]):
self.items = items
class BrokerService(ABC):
@abstractmethod
async def provision(self, instance_id: str, details: Any, iam_id: str, region: str) -> CreateServiceInstanceResponse:
pass
@abstractmethod
async def deprovision(self, instance_id: str, plan_id: str, service_id: str, iam_id: str) -> bool:
pass
@abstractmethod
async def last_operation(self, instance_id: str, iam_id: str) -> str:
pass
@abstractmethod
async def import_catalog(self, file_path: str) -> str:
pass
@abstractmethod
async def get_catalog(self) -> Catalog:
pass
@abstractmethod
async def update_state(self, instance_id: str, update_data: Any, iam_id: str) -> str:
pass
@abstractmethod
async def get_state(self, instance_id: str, iam_id: str) -> str:
pass
# This class to demo no-op provision, return context for customer reference
class NoopBrokerServiceImpl(BrokerService):
def __init__(self):
self.instances = {}
self.catalog = Catalog(items=["basic", "premium"])
async def provision(self, instance_id: str, details: Any, iam_id: str, region: str) -> CreateServiceInstanceResponse:
context = Context(details)
return CreateServiceInstanceResponse(instance_id, "no-op", context, None)
async def deprovision(self, instance_id: str, plan_id: str, service_id: str, iam_id: str) -> bool:
return True
async def last_operation(self, instance_id: str, iam_id: str) -> str:
return "no-op"
async def import_catalog(self, file_path: str) -> str:
return "no-op"
async def get_catalog(self) -> Catalog:
return self.catalog
async def update_state(self, instance_id: str, update_data: Any, iam_id: str) -> str:
return "no-op"
async def get_state(self, instance_id: str, iam_id: str) -> str:
return "no-op"
# This class to demo a simple provision to return some metadata for customer usage.
class SimpleBrokerServiceImpl(BrokerService):
def __init__(self):
self.instances = {}
self.catalog = Catalog(items=["basic", "premium"])
async def provision(self, instance_id: str, details: Any, iam_id: str, region: str) -> CreateServiceInstanceResponse:
self.instances[instance_id] = {"details": details, "iam_id": iam_id, "region": region, "state": "provisioned"}
metadata = self._metadataCreation()
return CreateServiceInstanceResponse(instance_id, "provisioned", details, metadata)
def _metadataCreation(self) -> Dict:
# Creating some metadata based on business operation requirements, for example, customer specific
# remote access token, userId and password, some remote url, etc.
metadata = {"user_id": "my_id", "token": "this_token"}
return metadata
async def deprovision(self, instance_id: str, plan_id: str, service_id: str, iam_id: str) -> bool:
if instance_id in self.instances:
del self.instances[instance_id]
return True
return False
async def last_operation(self, instance_id: str, iam_id: str) -> str:
return self.instances.get(instance_id, {}).get("state", "unknown")
async def import_catalog(self, file_path: str) -> str:
# For simplicity, assume each line in file is a catalog item
with open(file_path, "r") as f:
self.catalog.items = [line.strip() for line in f.readlines()]
return "Catalog imported successfully"
async def get_catalog(self) -> Catalog:
return self.catalog
async def update_state(self, instance_id: str, update_data: Any, iam_id: str) -> str:
if instance_id in self.instances:
self.instances[instance_id].update(update_data)
return "updated"
return "not found"
async def get_state(self, instance_id: str, iam_id: str) -> str:
return self.instances.get(instance_id, {}).get("state", "not found")
async def main():
broker = SimpleBrokerServiceImpl()
res = await broker.provision("123", {"plan": "basic"}, "iam1", "us-south")
print(res.instance_id, res.status)
state = await broker.get_state("123", "iam1")
print("State:", state)
await broker.update_state("123", {"state": "running"}, "iam1")
print("Updated state:", await broker.get_state("123", "iam1"))
print("Deprovisioned:", await broker.deprovision("123", "plan1", "svc1", "iam1"))
if __name__ == "__main__":
asyncio.run(main())
```
* **Setup and Testing**:
* [Example repository for an IBM Cloud compatible OSB written in NodeJs ](https://github.com/IBM/onboarding-osb-node)
* [Developing, hosting, and testing your service brokers ](https://cloud.ibm.com/docs/sell?topic=sell-broker-dev-host\&interface=ui#pc-broker-test)
* [Sample Resource Service Brokers ](https://github.com/IBM/sample-resource-service-brokers/blob/master/README.md)
* **Onboarding**: Add the broker in [IBM Cloud Concierge ](https://cloud.ibm.com/partner-center/sell/global-configuration).
## Questions & Answers
### Q1: What is the “Setup SSO” option in IBM Cloud Concierge?
This optional feature enables IBM Cloud single sign-on for your service and allows adding redirect URLs for authentication and authorization. See [IBM Cloud SSO documentation ](https://cloud.ibm.com/docs/sell?topic=sell-broker-onboard\&interface=ui#broker-sso) for details.
# Validating your native agent
Source: https://connect.watson-orchestrate.ibm.com/evaluate/evaluate
The evaluation framework is a tool that composes the [watsonx Orchestrate Agent Development Kit (ADK)](https://developer.watson-orchestrate.ibm.com), which allows you to test, evaluate and analyze native agents that you have created. To test your agents, you have to set up a file with the expected interaction responses, and run the agent evaluation to check if your agent matches the expectations.
**External agents**: External agents require TSV validation files but do not use the ADK validation framework. See the [TSV File Requirements for External Agents](#tsv-file-requirements-for-external-agents) section below and [External Agent Onboarding](../agent/onboard-external) for details.
## Before you begin
* You must have a **native agent** built with the [Agent Development Kit ](https://developer.watson-orchestrate.ibm.com/).
* If you need to run the framework with model-proxy and a `WO_INSTANCE` that points to a non-Dallas region, you can supply the model override flag:
```bash theme={null}
export MODEL_OVERRIDE="meta-llama/llama-3-2-90b-vision-instruct"
```
```bash theme={null}
export MODEL_OVERRIDE="meta-llama/llama-3-3-70b-instruct"
```
* Install the watsonx Orchestrate Agent Development Kit. For more information, see [Installing the ADK ](https://developer.watson-orchestrate.ibm.com/getting_started/installing).
* Install the watsonx Orchestrate Developer Edition. For more information, see [Installing the Developer Edition ](https://developer.watson-orchestrate.ibm.com/getting_started/wxOde_setup).
* For more information about the evaluation framework, see the [Evaluation framework overview ](https://developer.watson-orchestrate.ibm.com/evaluate/overview).
## Validating your native agent
**Native agents** refer to agents that were created with the **watsonx Orchestrate Agent Development Kit** or inside the watsonx Orchestrate platform.
The `validate-native` command validates the native agent and registered tools, collaborator agents, and knowledge bases against a set of inputs.
### Running the Validation
Prepare a TSV file with three columns:
* The first column contains user stories.
* The second column is the expected summary or output.
* The third column is the name of the native agent that you want to validate.
For example:
```tsv example.tsv theme={null}
My username is nwaters. I want to find out my timeoff schedule from: 2025-01-01 to: 2025-03-03. Your timeoff schedule for 20250101 to 20250303 is: 20250105 hr_agent
```
The provided user stories and expected output are used to generate the json formatted test case used to evaluate the agent. The generated test cases are saved at the path: `/native_agent_evaluations/generated_test_data`
**Running the command**
```bash theme={null}
orchestrate evaluations validate-native -t -o