Skip to navigation
SDK

SDK — Agent Operations

View as Markdown

Source: packages/sdk/src/agents.ts.

SDK methodEndpoint
registerAgent(params)POST /api/v1/agents
getAgent(did)GET /api/v1/agents/{did}
updateAgent(did, updates)PUT /api/v1/agents/{did}
decommissionAgent(did)DELETE /api/v1/agents/{did}
getAgentCard(did)GET /.well-known/agent.json?did=…
issueAgentDelegation(params)POST /api/v1/agents/{delegatorDid}/delegate
verifyDelegationChain(chain)POST /api/v1/delegations/verify-chain
discoverAgents(query)GET /api/v1/agents/discover?…
getAuditLog(did, limit?, offset?)GET /api/v1/agents/{did}/audit-log?…

RegisterAgentParams (mapping note)

autonomyLevel accepts a string (Intern, Junior, Senior, Principal); the SDK maps to the integer expected by the API (Intern→0, Junior→2, Senior→3, Principal→4; see agents.ts:157-165). If you pass an unknown level, it falls through to 0 (Intern).

⚠️ Known SDK gap (v1.x): the helper enum skips autonomy level 1. If you need level 1 (“Apprentice”), pass the integer literal 1 directly. Tracked as an SDK issue.

const agent = await client.registerAgent({
  operator: 'did:adi:human…',
  name: 'Shopping Assistant',
  modelInfo: { provider: 'OpenAI', name: 'gpt-4o', version: '2026-03-01' },
  capabilities: ['shopping', 'price-comparison'],
  autonomyLevel: 'Junior',
  services: [{ id: '#a2a-1', type: 'A2AEndpoint', serviceEndpoint: 'https://agent.example.com/a2a' }],
});

Issuing a delegation (IBCT)

const delegation = await operatorClient.issueAgentDelegation({
  delegatorDid: 'did:adi:human…',
  agentDid: agent.did,
  scope: {
    actions: ['shopping.search', 'shopping.purchase'],
    resources: ['catalog:eu-grocery/*'],
    constraints: { region: 'EU' },
    budget: { maxAmount: 50, currency: 'GBP', period: '7D' },
    expiry: '2026-12-31T23:59:59Z',
  },
});

The SDK serialises actions joined by comma into the API’s capability field (see agents.ts:97-98) — the API normalises back to an array on the server side.

Verifying a chain

const chain = await client.discoverAgents({ capability: 'shopping.purchase', limit: 1 });
// fetch the chain via /agents/{did}/delegation-chain or build manually
const result = await client.verifyDelegationChain({
  rootDelegator: 'did:adi:human…',
  leafAgent: agent.did,
  hops: [/* … */],
  effectiveScope: {/* … */},
  depth: 2,
});
console.log('Chain valid?', result.valid);