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
  secrets: SecretsContext;     // Secure credentials → ctx.secrets
  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.secrets`

Read credentials from the vault — securely, with delegation-enforced access.

`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.call.human() 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 guide Patterns library