@auth/agent

Client SDK for the Agent Auth Protocol — agent identity, registration, and capability-based authorization.

Installation

npm install @auth/agent

Quick Start

import { AgentAuthClient } from "@auth/agent";

const client = new AgentAuthClient({
  directoryUrl: "https://directory.example.com",
});

// Discover a provider
const config = await client.discoverProvider("https://api.example.com");

// Connect an agent with constrained capabilities
const agent = await client.connectAgent({
  provider: "https://api.example.com",
  capabilities: ["read_data", { name: "transfer_money", constraints: { amount: { max: 1000 } } }],
  name: "my-assistant",
});

// Execute a capability
const result = await client.executeCapability({
  agentId: agent.agentId,
  capability: "read_data",
  arguments: { id: "user-123" },
});

AI Framework Integration

Vercel AI SDK

toAISDKTools auto-imports jsonSchema from the ai package. Pass it explicitly if preferred:

import { generateText } from "ai";
import { AgentAuthClient, getAgentAuthTools, toAISDKTools } from "@auth/agent";

const client = new AgentAuthClient();
const tools = await toAISDKTools(getAgentAuthTools(client));

const { text } = await generateText({
  model: openai("gpt-4o"),
  tools,
  prompt: "Transfer $50 to Alice",
});

To pass jsonSchema explicitly (avoids the dynamic import):

import { generateText, jsonSchema } from "ai";
import { AgentAuthClient, getAgentAuthTools, toAISDKTools } from "@auth/agent";

const client = new AgentAuthClient();
const tools = await toAISDKTools(getAgentAuthTools(client), { jsonSchema });

OpenAI Function Calling

import { AgentAuthClient, getAgentAuthTools, toOpenAITools } from "@auth/agent";

const client = new AgentAuthClient();
const { definitions, execute } = toOpenAITools(getAgentAuthTools(client), {
  strict: true, // structured outputs — prevents hallucinated arguments
});

const res = await openai.chat.completions.create({
  model: "gpt-4o",
  tools: definitions,
  messages,
});

for (const call of res.choices[0].message.tool_calls ?? []) {
  const result = await execute(call.function.name, JSON.parse(call.function.arguments));
}

Anthropic Claude

import { AgentAuthClient, getAgentAuthTools, toAnthropicTools } from "@auth/agent";

const client = new AgentAuthClient();
const { definitions, processToolUse } = toAnthropicTools(getAgentAuthTools(client));

const res = await anthropic.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  tools: definitions,
  messages,
});

const toolUseBlocks = res.content.filter((b) => b.type === "tool_use");
if (toolUseBlocks.length > 0) {
  const results = await processToolUse(toolUseBlocks);
  messages.push({ role: "assistant", content: res.content }, { role: "user", content: results });
}

Error Handling

All adapters wrap tool execution errors as structured { error, code } objects instead of throwing. This lets models recover gracefully:

{ "error": "Capability not granted", "code": "capability_not_granted" }

SDK Tools

The SDK exposes protocol tools that map to the agent lifecycle:

| Tool | Description | | --------------------- | --------------------------------------------- | | list_providers | List discovered/configured providers | | search_providers | Search registry by intent | | discover_provider | Look up a provider by URL | | list_capabilities | List provider capabilities | | describe_capability | Get full capability definition | | connect_agent | Register an agent (with optional constraints) | | execute_capability | Execute a granted capability | | request_capability | Request additional capabilities | | agent_status | Check agent status and grants | | sign_jwt | Sign an agent JWT manually | | disconnect_agent | Revoke an agent | | reactivate_agent | Reactivate an expired agent | | rotate_agent_key | Rotate agent keypair | | rotate_host_key | Rotate host keypair | | enroll_host | Enroll host with enrollment token |

Filtering Tools

Use filterTools to expose only the tools your agent needs:

import { getAgentAuthTools, filterTools } from "@auth/agent";

const allTools = getAgentAuthTools(client);

const minimal = filterTools(allTools, { only: ["execute_capability", "agent_status"] });
const safe = filterTools(allTools, { exclude: ["sign_jwt", "rotate_host_key"] });

Subpath Import

For lighter imports when you only need tools + adapters (no client, crypto, or storage):

import { getAgentAuthTools, toOpenAITools, filterTools } from "@auth/agent/tools";

Constraints (Section 2.13)

Pass constraints when connecting or requesting capabilities to restrict argument values:

await client.connectAgent({
  provider: "https://api.example.com",
  capabilities: [
    "read_data",
    {
      name: "transfer_money",
      constraints: {
        amount: { max: 1000, min: 1 },
        currency: { in: ["USD", "EUR"] },
      },
    },
  ],
});

Constraint grants are returned in capabilityGrants[].constraints.

Storage

The SDK uses pluggable storage for persisting host identity and agent connections:

import { AgentAuthClient } from "@auth/agent";

const client = new AgentAuthClient({
  storage: myCustomStorage, // implements Storage interface
});

Built-in: MemoryStorage (default, non-persistent). For long-running apps, implement the Storage interface with your preferred backend (database, filesystem, KV store, etc.):

| Method group | Description | | --------------------------------------------------------------------- | ------------------------------ | | getHostIdentity / setHostIdentity / deleteHostIdentity | Host keypair and identity | | getAgentConnection / setAgentConnection / deleteAgentConnection | Per-agent connection state | | getProviderConfig / setProviderConfig / listProviderConfigs | Cached provider discovery docs |

The CLI package (@auth/agent-cli) includes a file-based FileStorage implementation with optional encryption at rest — see packages/cli/src/storage.ts for a reference implementation.

License

MIT