Native Agent Onboarding - IBM Agent Connect

Overview

Native agents are built and deployed directly within watsonx Orchestrate. They use IBM-managed models, tools, and runtime. Native agents can call tools, use external 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) installed
Python 3.8 or higher (for building tools)
An SVG icon for your agent (square, 64-100px, max 200KB)

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

Install the watsonx Orchestrate Agent Development Kit

Follow the instructions in the Getting started with the ADK to:

Install the Agent Development Kit
Connect it to your watsonx Orchestrate environment
Configure your credentials

Create a native agent

Build your native agent following the Getting started with the ADK tutorial.To learn more about native agent capabilities, see Authoring agents .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

Build tools for your agent

Native agents can call tools to perform tasks. Define tools as Python or YAML (OpenAPI) files.

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']

To learn more about tools, see Overview of Tools .

Import agent into Orchestrate

Import your agent into your draft environment:

orchestrate agents import -f my_native_agent.yaml

For more information, see Importing/Deploying agents .

Test your agent

Option 1: Test in watsonx Orchestrate UI

Log in to your watsonx Orchestrate instance and open the Agent Builder:
In the Build agents and tools page, select your agent:
Use the test chat to verify your agent’s behavior:

Option 2: Test with watsonx Orchestrate Developer EditionIf you have installed watsonx Orchestrate Developer Edition , use the ADK command line:

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

Validate your agent

Create a comprehensive TSV test file with AT LEAST THREE prompts and expected outputs:

test.tsv

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:

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 with subject “TSV Validation - [Agent Name]”

For more information, see Validating your agent.

Scaffold your offering folder

Create a packaging workspace for your offering:

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.yaml
├── 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 YAML 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

Place validation results

Copy your evaluation results archive into the evaluations/ folder:

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.

Update agent metadata

Before packaging, ensure your agent configuration file has all required fields:

my_native_agent.yaml

spec_version: v1
kind: native
name: my_native_agent
display_name: "My Native Agent"  # Human-readable name
llm: groq/openai/gpt-oss-120b
style: default
description: "Your agent description"
instructions: "Your agent instructions"

# Required metadata for catalog listing
tags: ["Sales", "Productivity"]  # Use catalog categories
publisher: "Your Company Name"
language_support:
  - "English"
icon: "<svg>...</svg>"  # Inline SVG string
category: "agent"  # Do not edit
restrictions: "editable"  # or "non-editable", "custom"
hidden: false  # Set to true to hide from catalog

# Version history
version: "1.0.0" # New versions must increment this value
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"

# Do not edit these fields
agent_role: "collaborator"
delete_by: null

# Optional: Supported channels
channels:
  - "Teams"
  - "WhatsAppTwilio"
  - "FacebookMessenger"
  - "GenesysConnector"
  - "Slack"

# Optional: Part numbers for different platforms
part_number:
  aws: null
  ibmcloud: "your_part_number"
  cp4d: null

# Optional: Scope and form factor
scope:
  form_factor:
    aws: "free"  # or "paid"
    ibmcloud: "paid"  # or "free"
    cp4d: "free"  # or "paid"

# Your agent's tools and collaborators
tools: []
collaborators: []

Show Agent Configuration Fields

spec_version

required

The specification version. Use v1.

kind

required

The type of agent. For native agents, use native.

name

required

The unique identifier for your agent. Use lowercase with underscores (e.g., my_native_agent).

display_name

Human-readable name for your agent that will be shown in the UI (e.g., “My Native Agent”).

llm

required

The language model to use for your agent (e.g., groq/openai/gpt-oss-120b).

style

required

The agent’s interaction style. Use default or react.

description

required

A brief description of what your agent does. This will be displayed in the catalog.

instructions

required

Detailed instructions that define your agent’s behavior, personality, and how it should respond to user queries.

version

required

The version number of your agent (e.g., 1.0.0). Must be incremented for each update.

category

required

The catalog category. Always use agent for agents. Do not edit this field.

restrictions

required

Defines how users can modify the agent. Options: editable, non-editable, or custom.

hidden

Set to true to hide the agent from the catalog, false to make it visible. Default is false.

change_log

string[]

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

agent_role

required

The role of the agent. Always use collaborator. Do not edit this field.

delete_by

Deletion timestamp. Always use null. Do not edit this field.

channels

string[]

List of supported communication channels. Options include: Teams, WhatsAppTwilio, FacebookMessenger, GenesysConnector, Slack.

part_number

object

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)

scope

object

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)

tools

array

Array of tool definitions that your agent can use. Can be empty [] if no tools are needed.

collaborators

array

Array of external agents that this agent can collaborate with. Can be empty [] if no collaborators are needed.

Package your offering

Package everything into a distributable ZIP:

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 package

Submit your packaged agent through the IBM Concierge app:

Log in to the IBM Concierge app.
Navigate to My AI products → Agent.
Select Native as the agent type.
Upload your package file (my_offering-1.0.zip).
Click Validate your agent and provide necessary details for test validation.
Review validation results and address any issues.
Click Save once you are ready to submit your package.
Scroll to the top of the page and click Request approval.
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:

IBM review: The IBM onboarding team validates your package structure, metadata, and evaluation results.
Approval: Once approved, your agent is published to the watsonx Orchestrate Agent Catalog.
Availability: Users can discover and provision your agent into their environments.
Updates: To update your agent, increment the version number, repackage, and resubmit through the IBM Concierge app.

Need help?

Review the ADK documentation
Check the Authoring agents guide
See Tools overview
Email questions to: IBMAgentConnect@ibm.com
Contact IBM Support for technical assistance

IBM Agent Connect

Legal notices

​Overview

​Prerequisites

​Steps to create and list your native agent

​What happens next

​Need help?

Overview

Prerequisites

Steps to create and list your native agent

What happens next

Need help?