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

Property	Type	Description
`cache_size`	`number`	Count 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');
}

Overview

Guides

Reference

Agent discovery

AgentDiscovery

What it is

When to use it

Functional usage

Constructor

Methods

`discover(base_url, force_refresh?)`

`discover_all(base_urls)`

`invalidate(base_url)`

`invalidate_all()`

Properties

Example

​AgentDiscovery

​What it is

​When to use it

​Functional usage

​Constructor

​Methods

​discover(base_url, force_refresh?)

​discover_all(base_urls)

​invalidate(base_url)

​invalidate_all()

​Properties

​Example

AgentDiscovery

What it is

When to use it

Functional usage

Constructor

Methods

`discover(base_url, force_refresh?)`

`discover_all(base_urls)`

`invalidate(base_url)`

`invalidate_all()`

Properties

Example