Agent Discovery

Agent discovery is the process by which ACP clients locate and connect to available agents. The Agent Manifest enables clients to find the appropriate ACP server and retrieve the necessary metadata to establish communication.

The discovery process provides clients with agent name, description, capabilities, operational status, and additional metadata.

Agent discovery can occur through these primary methods:

• Basic Discovery: Query running ACP servers directly (online)
• Open Discovery: Use public manifest files at well-known URLs (online)
• Registry-Based Discovery: Use a centralized registry (online or offline)
• Embedded Discovery: Find agents using embedded metadata or manifest files (offline)

​

Basic Discovery

Query a running ACP server to discover its agents:

curl http://localhost:8000/agents

curl http://localhost:8000/agents

import asyncio
from acp_sdk.client import Client

async def main():
    client = Client(base_url="http://localhost:8000")
    async for agent in client.agents():
        print(agent.name, agent.description)

asyncio.run(main())

​

Open Discovery

Open discovery allows Agent Manifest to be made publicly accessible through a standardized manifest file. This lets apps, websites, and tools discover agent capabilities by knowing only the agent’s domain.

Publish your agent metadata using a YAML file at a well-known location:

https://your-domain.com/.well-known/agent.yml

Important: The Agent Manifest specification only describes agent capabilities, not deployment or consumption instructions.

• Managed agents (packaged for deployment) need standardized build and deployment instructions
• Unmanaged agents (already running services) need metadata on how to access and consume the service

These deployment details aren’t part of the official ACP specification yet. We’re exploring options for standardizing both types using containers, uvx, and npx for simpler distribution.

​

Registry-Based Discovery

Registry-based discovery provides a centralized view of agents across multiple ACP servers, making it easier to manage agents in large deployments. Registries can work online (live queries) or offline (cached/synced databases).

Benefits:

• Centralized agent listings
• Scalable management across multiple servers
• Simplified search and discovery

While not yet part of the official ACP spec, this feature is implemented in the BeeAI Platform. We’re gauging community interest in making this part of the core ACP specification. Share your feedback on our Contribute page.

​

Embedded Discovery

Offline discovery lets you find agents without network connectivity by embedding agent metadata directly into distribution packages (like container image labels or bundled metadata files).

By embedding metadata during build time, the Agent Manifest remains synchronized with the agent’s actual implementation. This approach:

• Prevents mismatches between advertised capabilities and actual behavior
• Provides value in secure, disconnected, or automated deployment environments
• Simplifies distribution and deployment

We recommend embedding Agent Manifest metadata directly into container images during builds. The BeeAI Platform stores standardized metadata in container image labels, which:

• Integrates with CI/CD pipelines
• Ensures metadata consistency throughout the deployment lifecycle
• Simplifies offline agent discovery

To participate in ongoing discussions about manifest standardization and best practices, visit our Contribute page or join these existing discussions:

• Agent Manifest File Format #427
• Manifest-Based Agent Offline Discoverability #344