Manifest-Based Agent Offline Discoverability

[matoushavlena]

Related discussions:

• Agent Manifest File Format #427

Problem

In the Pre-alpha version of ACP, we introduced a tight coupling between agent providers and agents, meaning they run in the same runtime. To be discoverable, an agent must first be "installed" (including dependencies). This presents several challenges:

• Agents are only discoverable if the provider is running.
• Agents require installation to become discoverable, possibly consuming significant resources.
• Agents become discoverable only if successfully installed, but sometimes agents depend on external configurations that aren't available until discovery occurs.
• Agents built using different languages/runtimes cannot coexist within the same provider.
• Environment management currently occurs on the agent provider's side, yet should be coupled directly to the agent.
• Agents might depend on local resources (e.g., locally installed models) that must be prepared before runtime.
• Agent installation currently happens implicitly—it should instead occur explicitly at user request (to handle failures transparently).
• A single agent should be deployable independently rather than deploying an entire provider.
• Fatal errors in the provider or agent currently affect both, impacting stability.

Current Implementation

Currently, the platform functions as a service registry (through provider-registry.yaml). Providers register via the beeai provider add command, pointing to a manifest file specifying deployment configurations. Platform discovers the agents through providers.

Discoverability Process

{ "id": 1, "jsonrpc": "2.0", "method": "agents/list" }

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "agents": [
      {
        "name": "gpt-researcher",
        "description": "The agent conducts in-depth local and web research using a language model to generate comprehensive reports with citations, aimed at delivering factual, unbiased information.",
        "inputSchema": {},
        "outputSchema": {},
        "fullDescription": "...",
        "framework": "...",
        "license": "...",
        "languages": ["Python"],
        "githubUrl": "...",
        "examples": {
          "cli": [
            {
              "command": "beeai run gpt-researcher \"Impact of climate change on global agriculture\"",
              "name": null,
              "description": "Conducting Research on Climate Change",
              "output": null,
              "processingSteps": [
                "Initializes task-specific agents to interpret the query",
                "Generates a series of questions to form an objective opinion on the topic",
                "Uses a crawler agent to gather and summarize information for each question",
                "Aggregates and filters these summaries into a final comprehensive report"
              ]
            }
          ]
        },
        "avgRunTimeSeconds": 2.1,
        "avgRunTokens": 111,
        "ui": {
          "type": "hands-off",
          "userGreeting": "What topic do you want to research?"
        },
        "provider": "git+https://github.com/i-am-bee/[email protected]#path=agents/community/gpt-researcher-agent/beeai-provider.yaml"
      }
    ]
  }
}

Provider Manifest Format

manifestVersion: int # manifest version, incremented on breaking changes

# canonical name incl. domain
# ex. "github.com/i-am-bee/beeai", "github.com/i-am-bee/beeai/nested/folder", "example.com", "example.com/something/else"
# for remotely loaded manifests, the domain of the manifest must match prefix -- e.g. "github.com/i-am-bee/beeai/nested/folder" can be loaded from "https://github.com/i-am-bee/beeai" but not from "https://example.com"
name: str

# how to run the provider server
driver: nodejs | python | container | unmanaged # can later contain new versions like "nodejs@2"

# valid for driver: nodejs | python
# either a NPM/PyPI package name, or "git:..." URL, or (not allowed in remote manifests) "file:..." URL
# can include version for pinning
package: str

# valid for driver: container
# container image identifier (e.g. "docker.io/something/here:latest")
# include version for pinning
image: str

# valid for driver: nodejs | python | container
# command with arguments to run
command: str[]

# whether the server communicates through stdin/stdout, or a HTTP server spawned at $PORT
# for unmanaged provider, only http is available
serverType: stdio | http

mcpTransport: ws | wss | sse | sses | none

# for serverType=http, an array of endpoints
ui: str[] # absolute for "remote" driver, relative for managed drivers

# manifest files can contain multiple entries separated by ---

Example:

manifestVersion: 1
name: github.com/i-am-bee/beeai/agents/community/something
driver: nodejs
package: git+https://github.com/i-am-bee/beeai/agents/community/something
command: ["something", "--transport", "http"]
serverType: http
mcpTransport: sse

Goal

Reevaluate the agent manifest and provider concepts. While grouping agents under providers has usability advantages (and is MCP-compatible approach), it introduces complexities outlined above. We propose shifting the provider details directly into individual agent manifests, enabling offline discovery and simplifying deployment. The new agent manifest (discussed here) should clearly describe:

1. Deployment and consumption (as a service or deployable artifact)
2. Interface definition (input/output schemas)
3. Configuration requirements (secrets, environment variables)
4. Dependencies (including other agents, tools, or external resources)
5. Capabilities (sessions, interruptions) and metadata (license, description, skills, etc.)

Open Questions

• Should the agent manifest be compatible or inspired by Kubernetes manifests, or do we need a completely different schema due to ACP-specific requirements?
• Should MCP resources (e.g., tools, prompts) be combined in a single manifest or maintain separate manifests for clarity and modularity?

Additional Resources

• Llama stack - Support for providers outside of this codebase
• MCP - .well-known/mcp directory
• MCP - Service discovery for MCPs
• MCO - MCP server registry

Call to Action

Join the discussion and help shape agent offline discoverability 👋

[deghislain]

@matoushavlena great idea but as developer I was wondering how I will be charged if I use an external agent. I am asking because I initially pictured an external agent as an external service in a distributed system and it seemed easier for me to see the financial aspect but with the offline discovery I am not too sure. Could you provide more information about this particular point?

[matoushavlena]

@deghislain Offline discovery means that the Agent Detail is discoverable without the need to run the agent (meaning that the agent detail is embedded directly into the distribution package, for example container image with labels). It has no implication on the use of the agent, therefore billing. If you are concerned about how billing would work for external agents, the billing would likely happen through an AI gateway.

More details can be also found here: https://agentcommunicationprotocol.dev/core-concepts/agent-discovery.

[deghislain]

@matoushavlena Thanks for your prompt replied. Sorry for the confusion. I thought the idea was about having external agents run locally in some way. However, that means as developer building a team of agents with a common goal I may add an agent who might not be available at runtime is that correct?
This is just for my personal understanding because an agent(or provider) can still provide its details and not be available at runtime. So this is not a big deal.
Great, thank you for your time.