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

# Calling Agents

> How to use AgentClient to call remote SAMVAD agents.

## Connect to an agent

```typescript theme={null}
import { AgentClient } from '@samvad-protocol/sdk'

// Fetches the remote agent card and builds a typed client
const client = await AgentClient.from('https://other-agent.com')
```

`from()` fetches `/.well-known/agent.json`, loads the public key, and generates a local Ed25519 keypair stored in `.samvad/client-keys/` (created if absent).

## Sync call

```typescript theme={null}
const result = await client.call('review-code', {
  code: 'function foo() {}',
  language: 'typescript',
})
// result is the skill's typed output
```

`call()` builds a signed envelope, sends it to `POST /agent/message`, and returns the parsed result. Throws `SamvadError` on protocol errors.

## Async task

```typescript theme={null}
// Fire-and-forget with webhook — agent POSTs result to your callback URL
const taskId = await client.task(
  'review-code',
  { code: '...' },
  'https://my-agent.com/agent/message'
)

// No webhook — SDK polls automatically with configurable interval/timeout
const result = await client.taskAndPoll('review-code', { code: '...' }, {
  intervalMs: 500,
  timeoutMs: 60_000,
})
```

## SSE streaming

```typescript theme={null}
for await (const chunk of client.stream('review-code', { code: '...' })) {
  process.stdout.write(String(chunk))
}
```

`stream()` sends to `POST /agent/stream` and returns an async generator over SSE chunks. The stream ends when the agent sends `"done": true`.

## Calling a trusted-peers skill

A `trusted-peers` skill only accepts callers whose `agent://` ID and public key are registered on the server. Use `AgentClient.prepare()` to generate the client keypair *before* connecting, so you can register it first:

```typescript theme={null}
// 1. Generate client identity without connecting
const client = await AgentClient.prepare()

// 2. Register the client's public key on the server
serverAgent.trustPeer(client.agentId, client.publicKey)

// 3. Now connect and call
await client.connect('https://server-agent.com')
const result = await client.call('internal-skill', { data: '...' })
```

## Error handling

```typescript theme={null}
import { SamvadError, ErrorCode } from '@samvad-protocol/sdk'

try {
  const result = await client.call('review-code', { code: '...' })
} catch (err) {
  if (err instanceof SamvadError) {
    switch (err.code) {
      case ErrorCode.RATE_LIMITED:
        // back off and retry
        break
      case ErrorCode.AUTH_FAILED:
        // signature verification failed or bearer token missing
        break
      case ErrorCode.SCHEMA_INVALID:
        // input didn't match the skill's schema
        break
    }
  }
}
```

See [Error Codes](/protocol/error-codes) for the full list.