> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent discovery

# AgentDiscovery

```typescript theme={null}
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`](./remote-agent) (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

```typescript theme={null}
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

```typescript theme={null}
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?)`

```typescript theme={null}
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)`

```typescript theme={null}
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

```typescript theme={null}
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');
}
```