Skip to main content
GET
/
v1
/
agents
Discover Agents
curl --request GET \
  --url https://your-agent-server.com/agent-connect/v1/agents
{
  "agents": [
    {
      "name": "<string>",
      "description": "<string>",
      "provider": {
        "organization": "<string>",
        "url": "<string>"
      },
      "version": "<string>",
      "capabilities": {
        "streaming": true
      },
      "metadata": {},
      "documentation_url": "<string>"
    }
  ]
}

​
Agent Discovery

The Agent Discovery endpoint enables the identification of available agents and their capabilities within the Agent Connect Framework (ACF), eliminating the need for hardcoded knowledge of their existence.

​
Overview

The GET /v1/agents endpoint provides a detailed list of agents, including their metadata and capabilities, allowing clients to:
  1. Identify available agents within the ecosystem.
  2. Understand each agent’s capabilities and areas of expertise.
  3. Determine interaction protocols for each agent.
  4. Make informed decisions regarding agent selection for specific tasks.

​
Agent Cards

Each agent is represented by an “Agent Card” containing essential information: 
{
  "name": "My Custom Agent",
  "description": "A specialized agent for specific tasks",
  "provider": {
    "organization": "Your Organization",
    "url": "https://your-organization.com"
  },
  "version": "1.0.0",
  "documentation_url": "https://docs.example.com/my-agent",
  "capabilities": {
    "streaming": true
  }
}

​
Key Fields

  • name: Unique identifier for the agent.
  • description: Human-readable description of the agent’s functionality.
  • provider: Information about the organization providing the agent.
  • version: Agent version.
  • documentation_url: URL to the agent’s documentation.
  • capabilities: List of supported capabilities.
    • streaming: Indicates if the agent supports streaming responses.

​
Implementation

To implement the Agent Discovery endpoint, create a GET /v1/agents endpoint that returns a list of agent cards: 
app.get('/v1/agents', (req, res) => {
  res.json({
    agents: [
      {
        name: 'My Custom Agent',
        description: 'A specialized agent for specific tasks',
        provider: {
          organization: 'Your Organization',
          url: 'https://your-organization.com'
        },
        version: '1.0.0',
        documentation_url: 'https://docs.example.com/my-agent',
        capabilities: {
          streaming: true
        }
      }
    ]
  });
});

​
Planning for the implementation

Consider the following concepts and guidance when implementing the Agent Discovery endpoint:
  • Accurate Descriptions: Provide clear and precise descriptions of your agent’s capabilities to help clients understand its functionality and appropriate use cases.
  • Version Information: Include version information to inform clients about the specific version of your agent they are interacting with, especially when breaking changes occur.
  • Documentation Links: Include links to comprehensive documentation detailing your agent’s capabilities and usage instructions.
  • Capability Flags: Use capability flags to indicate supported features, aiding clients in determining the suitability of your agent for their needs.
  • Metadata: Include relevant metadata to provide insights into your agent’s specialties, limitations, and other critical characteristics.

​
Using Agent Discovery

Clients can use the Agent Discovery endpoint to find and interact with agents: 
async function discoverAgents() {
  const response = await fetch('https://your-agent-server.com/agent-connect/v1/agents');
  const data = await response.json();
  
  console.log('Available agents:');
  data.agents.forEach(agent => {
    console.log(`- ${agent.name}: ${agent.description}`);
    console.log(`  Provided by: ${agent.provider.organization}`);
    console.log(`  Supports streaming: ${agent.capabilities.streaming}`);
    console.log('');
  });
  
  return data.agents;
}

​
Integration with watsonx Orchestrate

When you register your agent with watsonx Orchestrate, it automatically discovers your agent’s capabilities through this endpoint. This enables watsonx Orchestrate to:
  • Display your agent in the agent catalog
  • Show accurate information about your agent’s capabilities
  • Enable appropriate interaction patterns based on your agent’s supported features
  • Facilitate collaboration between your agent and other agents in the ecosystem

​
Example Response

Here’s an example response from the Agent Discovery endpoint: 
{
  "agents": [
    {
      "name": "Research Assistant",
      "description": "An agent that helps with research tasks, including web searches and information synthesis",
      "provider": {
        "organization": "Research AI Inc.",
        "url": "https://research-ai.example.com"
      },
      "version": "2.1.0",
      "documentation_url": "https://docs.research-ai.example.com",
      "capabilities": {
        "streaming": true
      }
    },
    {
      "name": "Code Helper",
      "description": "An agent specialized in helping with coding tasks and software development",
      "provider": {
        "organization": "Dev Tools Ltd.",
        "url": "https://devtools.example.com"
      },
      "version": "1.3.5",
      "documentation_url": "https://docs.devtools.example.com/code-helper",
      "capabilities": {
        "streaming": true
      }
    }
  ]
}

​
Next Steps

After implementing the Agent Discovery endpoint, you should:
  1. Implement the Chat Completion endpoint to enable agent-to-agent communication
  2. Consider how your agent will interact with the AI Gateway
  3. Test your agent’s discovery and interaction capabilities with watsonx Orchestrate

Response

200 - application/json

Successful Response

​
agents
AgentCard · object[]
required