DocsBuildAPI ReferenceSDK Reference

Build Agents

@human/agent-sdk — the SDK for building production-ready agents on HUMΛN.

Infrastructure is invisible. You write business logic. HUMΛN owns everything else.

Every LLM call is cost-tracked. Every action is audited. Every delegation is enforced. You get all of this automatically — the only code you write is what makes your agent unique.

Install

bash
pnpm add @human/agent-sdk

Quick Start

Every agent is a handler() call. Declare what your agent does, provide an execute function, and HUMΛN handles identity, cost tracking, provenance, and routing.

typescript
import { handler } from '@human/agent-sdk';


export default handler({
  name: 'my-first-agent',
  description: 'Answers questions with full provenance tracking',
  capabilities: ['question-answering'],
  version: '1.0.0',


  execute: async (ctx, input: { question: string }) => {
    ctx.log.info('Processing question', { question: input.question });


    const response = await ctx.llm.complete({
      prompt: input.question,
      temperature: 0.7,
    });


    await ctx.provenance.log({
      action: 'question.answered',
      executionId: ctx.executionId,
      agentId: ctx.agentId,
      timestamp: Date.now(),
      input: { question: input.question },
      output: { answer: response.content },
      cost: response.cost,
    });


    return {
      answer: response.content,
      cost: response.cost,
      provenanceId: response.provenanceId,
    };
  },
});

The ExecutionContext

Your execute function receives an ExecutionContext (ctx) that provides every capability your agent needs. All capabilities are:

Delegation-gated

Only capabilities granted in the delegation scope are accessible.

Cost-tracked

Every call returns a Cost object. ctx.llm.getTotalCost() at any time.

Automatically audited

Every operation creates a provenance record. No extra code needed.

typescript
// The ExecutionContext — everything your agent needs
export interface ExecutionContext {
  // Identity
  executionId: string;          // Unique ID for this execution
  agentId: string;              // Your agent's cryptographic DID
  orgId: string;                // Organization context
  delegation: Delegation;       // Authority granted to this agent


  // Logging
  log: Logger;                  // Structured logging with correlation


  // Capabilities (all delegation-gated, cost-tracked, audited)
  llm: LLMContext;             // Language models → ctx.llm
  call: CallContext;           // Agent orchestration → ctx.call
  memory: MemoryContext;       // Key-value + vector storage → ctx.memory
  prompts: PromptContext;      // Prompt registry → ctx.prompt
  provenance: ProvenanceContext; // Audit trail → ctx.provenance
  config: ConfigContext;       // Cascading preferences → ctx.config
  credentials: SecretsContext;   // API keys & tokens → ctx.credentials
  db: DBContext;               // Database operations
  cache: CacheContext;         // Distributed cache
  queue: QueueContext;         // Background jobs
  files: FilesContext;         // File storage
}

SDK Reference

handler()

The entry point for every agent. Declare name, capabilities, version, and execute.

ctx.llm

Language model completions, embeddings, and streaming — with automatic cost tracking.

ctx.call

Call other agents, route by capability, or escalate to a human for approval.

ctx.memory

Scoped key-value and vector stores — execution, session, persistent, and suite scopes.

ctx.prompt

Load prompts from the registry, compose layers, and track telemetry.

ctx.provenance

Log events, attest actions, query history, and export audit trails.

ctx.config & ctx.credentials

Cascading config vs scoped credentials from the vault — delegation-enforced.

Testing

createMockExecutionContext and mock suite for unit testing agents without infrastructure.

Error Reference

SDKError, AccessDeniedError, BudgetExceededError, and all typed error classes.

What you get automatically

Cryptographic identity — Every agent execution carries a signed delegation chain back to the human who authorized it.
Cost transparency — Every LLM call, embedding, and storage operation is cost-tracked. No surprise bills.
Audit trail — Every ctx.* call creates a provenance record. Queryable, exportable, cryptographically verifiable.
Human oversight — ctx.escalate() escalates to a human for approval. The Fourth Law: AI defers to humans on high-stakes decisions.
Capability enforcement — If the delegation doesn't include a scope, the ctx.* call throws AccessDeniedError. No workarounds.
Budget enforcement — Agents respect budget limits from their delegation. BudgetExceededError if exceeded.

Next Steps

handler() reference →Build Your First Agent guidePatterns library