Skip to main content

​
AgentDiscovery

import { AgentDiscovery } from '@svantic/sdk';

​
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

import { AgentDiscovery } from '@svantic/sdk';

// 5-minute cache — cards rarely change, and no caller is checking per-request.
const discovery = new AgentDiscovery(5 * 60_000);

// Single lookup — served from cache on subsequent calls within the TTL.
const card = await discovery.discover('https://api.svantic.com/agents/invoice-agent');
console.log(card.name, '—', (card.skills ?? []).map((s) => s.name));

// Parallel lookups; failures are silently dropped.
const cards = await discovery.discover_all([
  'https://api.svantic.com/agents/invoice-agent',
  'https://api.svantic.com/agents/refund-agent',
  'https://api.svantic.com/agents/docs-agent',
]);

// Kick a specific agent out of the cache (e.g. after a deploy).
discovery.invalidate('https://api.svantic.com/agents/invoice-agent');
When you need a fully-fresh card (cache bypass), pass force_refresh: true to discover().

​
Constructor

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

​
Methods

​
discover(base_url, force_refresh?)

const card = await discovery.discover('https://invoice.example.com');
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)

const cards = await discovery.discover_all([url_a, url_b, url_c]);
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

PropertyTypeDescription
cache_sizenumberCount of cached entries.

​
Example

const discovery = new AgentDiscovery(5 * 60_000);

const cards = await discovery.discover_all([
  'https://invoice.example.com',
  'https://summarizer.example.com',
]);

for (const card of cards) {
  console.log(card.name, '—', card.skills?.length ?? 0, 'skills');
}