The TypeScript SDK is the reference implementation for OpenAgent application developers. Use it in Node services, Next.js routes, edge workers, CLI tools, and browser clients that need verifiable agent identity. See the SDK Hub for the full feature parity matrix and the TypeScript SDK narrative page on the main site.

​
Install

npm install @openagent/sdk

​
Initialize

import { OpenAgent } from '@openagent/sdk';

export const openagent = new OpenAgent({
  parentDid: process.env.OPENAGENT_PARENT_DID!,
  brokerUrl: process.env.OPENAGENT_BROKER_URL!,
  signingKey: process.env.OPENAGENT_SIGNING_KEY!,
});

​
Create an agent

const agent = await openagent.agents.create({
  name: 'calendar-planner',
  scopes: [
    'google-calendar:events:read',
    'google-calendar:events:write',
  ],
  metadata: {
    owner: 'did:oas:l1fe:hmr:alice',
    environment: 'production',
  },
});

console.log(agent.did);

​
Start a client handshake

const session = await openagent.client.handshake({
  audience: 'https://api.example.com',
  agentDid: agent.did,
  capabilities: ['tickets:read', 'tickets:triage'],
});

await fetch('https://api.example.com/oaap/session', {
  method: 'POST',
  headers: session.headers(),
  body: JSON.stringify(session.proof()),
});

​
Verify on the server

import { createOpenAgentMiddleware } from '@openagent/sdk/server';

export const verifyOpenAgent = createOpenAgentMiddleware({
  audience: 'https://api.example.com',
  requireLineage: true,
  policies: [
    { type: 'scope', value: 'tickets:triage' },
    { type: 'maxSessionAge', seconds: 300 },
  ],
});

​
Broker credentials

const response = await agent.fetch('https://api.openai.com/v1/chat/completions', {
  method: 'POST',
  body: JSON.stringify({
    model: 'gpt-4.1-mini',
    messages: [{ role: 'user', content: 'Classify this lead.' }],
  }),
});

const result = await response.json();
The raw provider key stays in Arsenal. The SDK sends the agent DID, lineage proof, requested capability, and short-lived ACT; Arsenal injects the provider credential only after policy evaluation.

​
Errors

CodeMeaningAction
OAS_INVALID_LINEAGEThe DID proof chain is invalid or expired.Recreate the agent or rotate the parent proof.
OAAP_HANDSHAKE_REJECTEDThe peer rejected the handshake challenge.Confirm audience, nonce, and clock skew.
ACT_SCOPE_DENIEDRequested capability is not allowed by policy.Ask for a narrower scope or update Arsenal policy.
BROKER_CREDENTIAL_UNAVAILABLEArsenal cannot resolve a provider credential.Check provider binding and broker health.

​
Testing

import { createOpenAgentTestHarness } from '@openagent/sdk/testing';

const harness = await createOpenAgentTestHarness();
const agent = await harness.agents.create({ scopes: ['tickets:triage'] });

expect(await harness.verify(agent.did)).toEqual({ verified: true });

Quickstart

Build the first working agent flow.

Server middleware

Add OpenAgent verification to an existing API.