Skip to main content

AgentDiscovery

What it is

AgentDiscovery is a lightweight resolver for A2A agent cards. Every A2A agent publishes a card at /.well-known/agent-card.json describing its identity, skills, and parameter schemas. This class fetches and validates that card, with in-memory TTL-based caching so you don’t re-fetch on every check. It is strictly a discovery tool — it does not send messages or hold a connection. For that, use RemoteAgent (which discovers internally on connect()).

When to use it

  • Building a UI that lists agents and their skills (dashboards, capability pickers, admin views).
  • Validating an agent’s card in tests or CI.
  • Bulk-polling a set of agents to build a registry.
  • Inspecting an agent before deciding whether to connect.
If your goal is to call the agent, skip this and go straight to RemoteAgent.

Functional usage

When you need a fully-fresh card (cache bypass), pass force_refresh: true to discover().

Constructor

  • ttl_ms — cache TTL in milliseconds. Defaults to 60_000 (1 minute). Pass 0 to disable caching.

Methods

discover(base_url, force_refresh?)

Resolve a single agent card. Returns a fresh card on cache miss, or the cached card when fresh. Pass force_refresh: true to bypass the cache. Throws if the remote does not serve a valid agent card.

discover_all(base_urls)

Resolve multiple agents in parallel. Failed discoveries are silently dropped — only successful cards are returned.

invalidate(base_url)

Remove one URL from the cache. No-op when the URL is not cached (or falsy).

invalidate_all()

Clear the entire cache.

Properties

Example