Service discovery

• Runtime registry -- every agent auto-registers its reasoners and skills on startup.
• Tag-based filtering -- find agents by domain ("insurance", "nlp") instead of memorizing node IDs.
• Health-aware routing -- filter to only active agents so you never call a dead endpoint.
• Schema introspection -- request input/output schemas to build dynamic tool calling at runtime.
• Three output formats -- json for programmatic use, compact for LLM context windows, xml for legacy integrations.

Agents register themselves with the control plane automatically. When an agent starts, it sends a heartbeat containing its node ID, version, and the full list of reasoners and skills it exposes. The control plane updates the registry, and other agents can immediately discover the new capabilities.

af server          # Terminal 1 -- control plane at http://localhost:8080
python app.py      # Terminal 2 -- agent registers on startup

The agent exposes a /discover endpoint that the control plane polls. No manual registration step is required.

Dynamic Tool Calling

Use discovery to build tool definitions for LLM calls at runtime. When agents come and go, the tool list updates automatically.

@app.reasoner()
async def smart_router(question: str) -> dict:
    # Discover available capabilities
    caps = app.discover(
        tags=["public"],
        include_input_schema=True,
        health_status="active",
    )

    # Feed discovered tools into an LLM call
    result = await app.ai(
        system="Route the question to the best available agent.",
        user=question,
        tools="discover",  # built-in shorthand
    )
    return result

Health-Gated Failover

Before calling a specific agent, verify it is active. If not, discover an alternative with the same tags.

async def call_with_failover(target: str, tags: list[str], **kwargs) -> dict:
    try:
        return await app.call(target, **kwargs)
    except Exception:
        # Find an active alternative
        fallback = app.discover(tags=tags, health_status="active")
        if not fallback.json.capabilities:
            raise RuntimeError(f"No active agents with tags {tags}")

        alt_cap = fallback.json.capabilities[0]
        alt_target = f"{alt_cap.agent_id}.{alt_cap.reasoners[0].id}"
        return await app.call(alt_target, **kwargs)

Use ARD when a selected reasoner or skill should be discoverable outside the deployment.

1. Enable ARD deployment guardrails in agentfield.yaml or environment variables.
2. Open Discovery -> Overview and confirm the catalog URL and DID/trust status.
3. Open Discovery -> Public Catalog or expand an agent in Agent nodes.
4. Turn on Expose through ARD for one reasoner or skill.
5. Add a display name, description, tags, representative queries, and artifact type.

Published entries are served at:

curl https://control-plane.example.com/.well-known/ai-catalog.json

See Expose agents to external discovery for the full external search, import, and callability workflow.

Python -- app.discover()

Returns: DiscoveryResult with .json, .compact, .xml, .raw, and .format fields.

TypeScript -- agent.discover(options?)

Returns: Promise<DiscoveryResult> with json?, compact?, xml?, raw, and format fields.

Go -- agent.Discover(ctx, ...DiscoveryOption)

Returns: (*types.DiscoveryResult, error) with JSON, Compact, XML, Raw, and Format fields.