@hazeljs/agent 0.2.0-beta.8 → 0.2.0-beta.80

package/README.md

@@ -1,17 +1,26 @@
 # @hazeljs/agent
 
-**AI-native Agent Runtime for HazelJS** - Build stateful, long-running agents with tools, memory, and human-in-the-loop workflows.
+**Build AI agents that actually do things.**
+
+Stateful, tool-using, memory-enabled. Define tools with `@Tool`, delegate between agents with `@Delegate`, orchestrate multi-agent pipelines with `AgentGraph`, and route tasks automatically with `SupervisorAgent`. Production-grade agent infrastructure without the complexity.
+
+[![npm version](https://img.shields.io/npm/v/@hazeljs/agent.svg)](https://www.npmjs.com/package/@hazeljs/agent)
+[![npm downloads](https://img.shields.io/npm/dm/@hazeljs/agent)](https://www.npmjs.com/package/@hazeljs/agent)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 ## Overview
 
-The Agent Runtime is a core primitive in HazelJS designed for building production-grade AI agents. Unlike stateless request handlers, agents are:
+Unlike stateless request handlers, agents are:
+
+- **Stateful** — Maintain context across multiple steps and sessions
+- **Long-running** — Execute complex, multi-hop workflows over time
+- **Tool-using** — Call functions safely with timeout, retry, and approval workflows
+- **Multi-agent** — Orchestrate teams of specialised agents with `AgentGraph`, `SupervisorAgent`, and `@Delegate`
+- **Memory-enabled** — Integrate with persistent memory systems
+- **Observable** — Full event system for monitoring and debugging
+- **Resumable** — Support pause/resume and human-in-the-loop
 
-- **Stateful** - Maintain context across multiple steps
-- **Long-running** - Execute complex workflows over time
-- **Tool-using** - Call functions safely with approval workflows
-- **Memory-enabled** - Integrate with persistent memory systems
-- **Observable** - Full event system for monitoring and debugging
-- **Resumable** - Support pause/resume and human-in-the-loop
+---
 
 ## Installation
 
@@ -19,9 +28,11 @@ The Agent Runtime is a core primitive in HazelJS designed for building productio
 npm install @hazeljs/agent @hazeljs/core @hazeljs/rag
 ```
 
-## Quick Start
+---
 
-### 1. Define an Agent
+## Quick Start — Single Agent
+
+### 1. Define an agent
 
 ```typescript
 import { Agent, Tool } from '@hazeljs/agent';
@@ -36,242 +47,375 @@ import { Agent, Tool } from '@hazeljs/agent';
 export class SupportAgent {
   @Tool({
     description: 'Look up order information by order ID',
-    parameters: [
-      {
-        name: 'orderId',
-        type: 'string',
-        description: 'The order ID to lookup',
-        required: true,
-      },
-    ],
+    parameters: [{ name: 'orderId', type: 'string', description: 'The order ID', required: true }],
   })
   async lookupOrder(input: { orderId: string }) {
-    // Your implementation
-    return {
-      orderId: input.orderId,
-      status: 'shipped',
-      trackingNumber: 'TRACK123',
-    };
+    return { orderId: input.orderId, status: 'shipped', trackingNumber: 'TRACK123' };
   }
 
   @Tool({
     description: 'Process a refund for an order',
-    requiresApproval: true, // Requires human approval
+    requiresApproval: true,   // requires human approval before execution
     parameters: [
-      {
-        name: 'orderId',
-        type: 'string',
-        description: 'The order ID to refund',
-        required: true,
-      },
-      {
-        name: 'amount',
-        type: 'number',
-        description: 'Refund amount',
-        required: true,
-      },
+      { name: 'orderId', type: 'string', required: true },
+      { name: 'amount',  type: 'number', required: true },
     ],
   })
   async processRefund(input: { orderId: string; amount: number }) {
-    // Your implementation
-    return {
-      success: true,
-      refundId: 'REF123',
-      amount: input.amount,
-    };
+    return { success: true, refundId: 'REF123', amount: input.amount };
   }
 }
 ```
 
-### 2. Set Up the Runtime
+### 2. Set up the runtime
 
 ```typescript
 import { AgentRuntime } from '@hazeljs/agent';
 import { MemoryManager } from '@hazeljs/rag';
 import { AIService } from '@hazeljs/ai';
 
-// Initialize dependencies
-const memoryManager = new MemoryManager(/* ... */);
-const aiService = new AIService({ provider: 'openai' });
-
-// Create runtime
 const runtime = new AgentRuntime({
-  memoryManager,
-  llmProvider: aiService,
+  memoryManager: new MemoryManager(/* ... */),
+  llmProvider: new AIService({ provider: 'openai' }),
   defaultMaxSteps: 10,
   enableObservability: true,
 });
 
-// Register agent
-const supportAgent = new SupportAgent();
+const agent = new SupportAgent();
 runtime.registerAgent(SupportAgent);
-runtime.registerAgentInstance('support-agent', supportAgent);
+runtime.registerAgentInstance('support-agent', agent);
 ```
 
-### 3. Execute the Agent
+### 3. Execute
 
 ```typescript
-// Execute agent
 const result = await runtime.execute(
   'support-agent',
-  'I need to check my order status for order #12345',
-  {
-    sessionId: 'user-session-123',
-    userId: 'user-456',
-    enableMemory: true,
-    enableRAG: true,
-  }
+  'I need to check my order #12345',
+  { sessionId: 'user-session-123', userId: 'user-456', enableMemory: true },
 );
 
 console.log(result.response);
 console.log(`Completed in ${result.steps.length} steps`);
 ```
 
-### 4. Handle Human-in-the-Loop
+### 4. Handle human-in-the-loop
 
 ```typescript
-// Subscribe to approval requests
 runtime.on('tool.approval.requested', async (event) => {
   console.log('Approval needed:', event.data);
-  
-  // Approve or reject
   runtime.approveToolExecution(event.data.requestId, 'admin-user');
-  // or
-  // runtime.rejectToolExecution(event.data.requestId);
 });
 
-// Resume after approval
-const resumedResult = await runtime.resume(result.executionId);
+const resumed = await runtime.resume(result.executionId);
 ```
 
-## Core Concepts
+---
 
-### Agent State Machine
+## Multi-Agent Orchestration
 
-Every agent execution follows a deterministic state machine:
+`@hazeljs/agent` ships three complementary patterns for coordinating multiple agents. Use them individually or combine them.
+
+### Pattern 1 — `@Delegate`: peer-to-peer agent calls
+
+`@Delegate` marks a method on an agent as a delegation point to another agent. The method body is replaced at runtime with an actual `runtime.execute(targetAgent, input)` call — making agent-to-agent communication completely transparent to the LLM (it sees delegation targets as ordinary tools).
 
 ```
-idle → thinking → using_tool → thinking → ... → completed
-                    ↓
-              waiting_for_input
-                    ↓
-              waiting_for_approval
-                    ↓
-                 failed
+OrchestratorAgent
+   └── @Delegate → ResearchAgent
+   └── @Delegate → WriterAgent
 ```
 
-### Execution Loop
+```typescript
+import { Agent, Delegate } from '@hazeljs/agent';
 
-The agent runtime implements a controlled execution loop:
+@Agent({
+  name: 'OrchestratorAgent',
+  description: 'Plans and delegates research and writing tasks',
+  systemPrompt: 'You orchestrate research and writing. Use the available tools to complete tasks.',
+})
+export class OrchestratorAgent {
+  // The LLM sees this as a tool. At runtime it calls ResearchAgent.
+  @Delegate({
+    agent: 'ResearchAgent',
+    description: 'Research a topic thoroughly and return key findings',
+    inputField: 'query',
+  })
+  async researchTopic(query: string): Promise<string> {
+    return ''; // body replaced at runtime by AgentRuntime
+  }
 
-1. **Load State** - Restore agent context and memory
-2. **Load Memory** - Retrieve conversation history
-3. **Retrieve RAG** - Get relevant context (optional)
-4. **Ask LLM** - Decide next action
-5. **Execute Action** - Call tool, ask user, or respond
-6. **Persist State** - Save state and memory
-7. **Repeat or Finish** - Continue or complete
+  // The LLM sees this as a tool. At runtime it calls WriterAgent.
+  @Delegate({
+    agent: 'WriterAgent',
+    description: 'Write a polished article from the provided research notes',
+    inputField: 'content',
+  })
+  async writeArticle(content: string): Promise<string> {
+    return ''; // body replaced at runtime by AgentRuntime
+  }
+}
 
-### Tools
+@Agent({ name: 'ResearchAgent', systemPrompt: 'You are an expert researcher.' })
+export class ResearchAgent {
+  @Tool({ description: 'Search the web', parameters: [{ name: 'query', type: 'string', required: true }] })
+  async searchWeb(input: { query: string }) {
+    return `Research findings for: ${input.query}`;
+  }
+}
 
-Tools are explicit, auditable capabilities:
+@Agent({ name: 'WriterAgent', systemPrompt: 'You are a professional technical writer.' })
+export class WriterAgent {
+  @Tool({ description: 'Format content as Markdown', parameters: [{ name: 'raw', type: 'string', required: true }] })
+  async formatMarkdown(input: { raw: string }) {
+    return `## Article\n\n${input.raw}`;
+  }
+}
+```
+
+**Registration:**
 
 ```typescript
-@Tool({
-  description: 'Send an email',
-  requiresApproval: true,
-  timeout: 30000,
-  retries: 2,
-  parameters: [
-    { name: 'to', type: 'string', required: true },
-    { name: 'subject', type: 'string', required: true },
-    { name: 'body', type: 'string', required: true },
-  ],
-})
-async sendEmail(input: { to: string; subject: string; body: string }) {
-  // Implementation
-}
+const orchestrator = new OrchestratorAgent();
+const researcher  = new ResearchAgent();
+const writer      = new WriterAgent();
+
+[ResearchAgent, WriterAgent, OrchestratorAgent].forEach(A => runtime.registerAgent(A));
+[['OrchestratorAgent', orchestrator], ['ResearchAgent', researcher], ['WriterAgent', writer]]
+  .forEach(([name, inst]) => runtime.registerAgentInstance(name as string, inst));
+
+const result = await runtime.execute('OrchestratorAgent', 'Write a blog post about LLMs');
+console.log(result.response);
 ```
 
-**Tool Features:**
-- Automatic parameter validation
-- Timeout and retry logic
-- Approval workflows
-- Execution logging
-- Error handling
+> **Note:** `@Delegate` implicitly registers the method as `@Tool`. Do not add `@Tool` separately.
+
+---
 
-### Memory Integration
+### Pattern 2 — `AgentGraph`: DAG pipelines
 
-Agents automatically integrate with HazelJS Memory:
+`AgentGraph` lets you wire agents and functions into a directed acyclic graph with sequential edges, conditional routing, and parallel fan-out/fan-in. Think LangGraph but TypeScript-native and integrated with `AgentRuntime`.
+
+```
+Entry → NodeA → NodeB → END              (sequential)
+Entry → RouterNode → NodeA | NodeB → END (conditional)
+Entry → Splitter → [NodeA ‖ NodeB] → Combiner → END (parallel)
+```
 
 ```typescript
-// Memory is automatically persisted
-const result = await runtime.execute('agent-name', 'Hello', {
-  sessionId: 'session-123',
-  enableMemory: true,
-});
+import { END } from '@hazeljs/agent';
 
-// Conversation history is maintained
-const result2 = await runtime.execute('agent-name', 'What did I just say?', {
-  sessionId: 'session-123', // Same session
-  enableMemory: true,
-});
+// Create graph via the runtime
+const graph = runtime.createGraph('research-pipeline');
 ```
 
-### RAG Integration
+#### Sequential pipeline
 
-Agents can query RAG before reasoning:
+```typescript
+const pipeline = runtime
+  .createGraph('blog-pipeline')
+  .addNode('researcher', { type: 'agent', agentName: 'ResearchAgent' })
+  .addNode('writer',     { type: 'agent', agentName: 'WriterAgent' })
+  .addEdge('researcher', 'writer')
+  .addEdge('writer', END)
+  .setEntryPoint('researcher')
+  .compile();
+
+const result = await pipeline.execute('Write a blog post about TypeScript generics');
+console.log(result.output);
+```
+
+#### Conditional routing
 
 ```typescript
-@Agent({
-  name: 'docs-agent',
-  enableRAG: true,
-  ragTopK: 5,
-})
-export class DocsAgent {
-  // Agent automatically retrieves relevant docs
+const router = runtime
+  .createGraph('router')
+  .addNode('classifier', { type: 'agent', agentName: 'ClassifierAgent' })
+  .addNode('coder',      { type: 'agent', agentName: 'CoderAgent' })
+  .addNode('writer',     { type: 'agent', agentName: 'WriterAgent' })
+  .setEntryPoint('classifier')
+  .addConditionalEdge('classifier', (state) =>
+    state.data?.type === 'code' ? 'coder' : 'writer',
+  )
+  .addEdge('coder',  END)
+  .addEdge('writer', END)
+  .compile();
+
+const result = await router.execute('Write a sorting algorithm in TypeScript');
+```
+
+#### Parallel fan-out / fan-in
+
+```typescript
+async function splitTask(state: GraphState) {
+  return { ...state, data: { ...state.data, split: true } };
 }
+
+async function mergeResults(state: GraphState) {
+  const results = state.data?.branchResults as ParallelBranchResult[];
+  return { ...state, output: results.map(r => r.output).join('\n---\n') };
+}
+
+const parallel = runtime
+  .createGraph('parallel-research')
+  .addNode('splitter',    { type: 'function', fn: splitTask })
+  .addNode('parallel-1', { type: 'parallel', branches: ['tech-researcher', 'market-researcher'] })
+  .addNode('tech-researcher',   { type: 'agent', agentName: 'TechResearchAgent' })
+  .addNode('market-researcher', { type: 'agent', agentName: 'MarketResearchAgent' })
+  .addNode('combiner',   { type: 'function', fn: mergeResults })
+  .addEdge('splitter',   'parallel-1')
+  .addEdge('parallel-1', 'combiner')
+  .addEdge('combiner',    END)
+  .setEntryPoint('splitter')
+  .compile();
+
+const result = await parallel.execute('Analyse the AI framework market');
 ```
 
-## Event System
+#### Streaming execution
+
+```typescript
+for await (const chunk of pipeline.stream('Tell me about GraphRAG')) {
+  if (chunk.type === 'node_complete') {
+    console.log(`✓ ${chunk.nodeId}: ${chunk.output?.slice(0, 80)}...`);
+  }
+}
+```
 
-Subscribe to agent events for observability:
+#### `AgentGraph` API
 
 ```typescript
-import { AgentEventType } from '@hazeljs/agent';
+interface AgentGraph {
+  addNode(id: string, config: GraphNodeConfig): this;
+  addEdge(from: string, to: string): this;
+  addConditionalEdge(from: string, router: RouterFunction): this;
+  setEntryPoint(nodeId: string): this;
+  compile(): CompiledGraph;
+}
 
-// Execution events
-runtime.on(AgentEventType.EXECUTION_STARTED, (event) => {
-  console.log('Agent started:', event.data);
-});
+interface CompiledGraph {
+  execute(input: string, options?: GraphExecutionOptions): Promise<GraphExecutionResult>;
+  stream(input: string, options?: GraphExecutionOptions): AsyncIterable<GraphStreamChunk>;
+  visualize(): string;   // returns a Mermaid diagram string
+}
+```
 
-runtime.on(AgentEventType.EXECUTION_COMPLETED, (event) => {
-  console.log('Agent completed:', event.data);
-});
+---
 
-// Step events
-runtime.on(AgentEventType.STEP_STARTED, (event) => {
-  console.log('Step started:', event.data);
-});
+### Pattern 3 — `SupervisorAgent`: LLM-driven routing
+
+`SupervisorAgent` uses an LLM to decompose tasks into subtasks, route each subtask to the best worker agent, and accumulate results — continuing until the task is complete or `maxRounds` is reached.
 
-// Tool events
-runtime.on(AgentEventType.TOOL_EXECUTION_STARTED, (event) => {
-  console.log('Tool executing:', event.data);
+```
+User Task
+    │
+Supervisor  ←──────────────────────────┐
+    │                                   │
+┌───▼────────────────┐           Worker result
+│  Route to worker?  │                  │
+└───────────┬────────┘                  │
+            │                           │
+     ┌──────▼──────┐                    │
+     │ WorkerAgent │───────────────────┘
+     └─────────────┘
+```
+
+```typescript
+const supervisor = runtime.createSupervisor({
+  name: 'project-manager',
+  workers: ['ResearchAgent', 'CoderAgent', 'WriterAgent'],
+  maxRounds: 6,
+  llm: async (prompt) => {
+    const res = await openai.chat.completions.create({
+      model: 'gpt-4o-mini',
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return res.choices[0].message.content ?? '';
+  },
 });
 
-runtime.on(AgentEventType.TOOL_APPROVAL_REQUESTED, (event) => {
-  console.log('Approval needed:', event.data);
+const result = await supervisor.run(
+  'Build and document a REST API for a todo app',
+  { sessionId: 'proj-001' },
+);
+
+console.log(result.response);
+result.rounds.forEach((round, i) => {
+  console.log(`Round ${i + 1}: routed to ${round.worker} — ${round.workerResult.response.slice(0, 80)}`);
 });
+```
+
+**`SupervisorConfig`:**
 
-// Subscribe to all events
-runtime.onAny((event) => {
-  console.log('Event:', event.type, event.data);
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `name` | string | — | Supervisor instance name |
+| `workers` | string[] | — | Registered agent names available to the supervisor |
+| `maxRounds` | number | 5 | Maximum routing iterations |
+| `llm` | `(prompt: string) => Promise<string>` | — | LLM function for routing decisions |
+| `sessionId` | string | auto | Session for memory continuity across rounds |
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                        AgentRuntime                              │
+├──────────────┬───────────────┬───────────────┬───────────────────┤
+│   Registry   │  State Mgr    │   Executor    │  Tool Executor    │
+│  (agents,    │  (in-mem /    │  (step loop,  │  (timeout,        │
+│   tools)     │   Redis / DB) │   approval)   │   retry, audit)   │
+├──────────────┴───────────────┴───────────────┴───────────────────┤
+│                  Multi-Agent Layer                                │
+│  ┌──────────────┐  ┌───────────────────┐  ┌────────────────────┐ │
+│  │  AgentGraph  │  │  SupervisorAgent  │  │  @Delegate         │ │
+│  │  (DAG pipes) │  │  (LLM routing)    │  │  (peer-to-peer)    │ │
+│  └──────────────┘  └───────────────────┘  └────────────────────┘ │
+├────────────────────────────────────────────────────────────────── ┤
+│         Memory Module (@hazeljs/rag)  │  RAG Module               │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## State Machine
+
+Every agent execution follows a deterministic state machine:
+
+```
+idle → thinking → using_tool → thinking → ... → completed
+                     ↓
+               waiting_for_input
+                     ↓
+               waiting_for_approval
+                     ↓
+                  failed
+```
+
+---
+
+## Event System
+
+```typescript
+import { AgentEventType } from '@hazeljs/agent';
+
+runtime.on(AgentEventType.EXECUTION_STARTED,   e => console.log('started:',    e.data));
+runtime.on(AgentEventType.EXECUTION_COMPLETED, e => console.log('completed:',  e.data));
+runtime.on(AgentEventType.STEP_STARTED,        e => console.log('step:',       e.data));
+runtime.on(AgentEventType.TOOL_EXECUTION_STARTED,   e => console.log('tool:',  e.data));
+runtime.on(AgentEventType.TOOL_APPROVAL_REQUESTED,  e => {
+  console.log('approval needed:', e.data);
+  runtime.approveToolExecution(e.data.requestId, 'admin');
 });
+
+// Catch-all
+runtime.onAny(e => console.log(e.type, e.data));
 ```
 
-## HazelJS Module Integration
+---
 
-Use with HazelJS modules:
+## HazelJS Module Integration
 
 ```typescript
 import { HazelModule } from '@hazeljs/core';
@@ -282,146 +426,116 @@ import { RagModule } from '@hazeljs/rag';
   imports: [
     RagModule.forRoot({ /* ... */ }),
     AgentModule.forRoot({
-      runtime: {
-        defaultMaxSteps: 10,
-        enableObservability: true,
-      },
-      agents: [SupportAgent, SalesAgent],
+      runtime: { defaultMaxSteps: 10, enableObservability: true },
+      agents: [SupportAgent, ResearchAgent, WriterAgent, OrchestratorAgent],
     }),
   ],
 })
 export class AppModule {}
 ```
 
-## Advanced Usage
+---
 
-### Pause and Resume
+## Best Practices
 
-```typescript
-// Execute agent
-const result = await runtime.execute('agent', 'Start task');
+### Keep tools idempotent
 
-if (result.state === 'waiting_for_input') {
-  // Agent is waiting for user input
-  const resumed = await runtime.resume(result.executionId, 'User response');
+```typescript
+@Tool({ description: 'Create an order' })
+async createOrder(input: { orderId: string; items: Item[] }) {
+  const existing = await this.findOrder(input.orderId);
+  if (existing) return existing;            // safe to retry
+  return this.createNewOrder(input);
 }
 ```
 
-### Custom Context
+### Use `@Delegate` for domain specialisation
 
-```typescript
-const result = await runtime.execute('agent', 'Process order', {
-  initialContext: {
-    userId: '123',
-    orderData: { /* ... */ },
-  },
-});
-```
+Keep each agent focused on one domain. `@Delegate` lets the orchestrator combine specialists without any agent becoming a monolith.
 
-### Tool Policies
+### Choose the right multi-agent pattern
 
-```typescript
-@Tool({
-  description: 'Delete user data',
-  requiresApproval: true,
-  policy: 'admin-only', // Custom policy
-})
-async deleteUserData(input: { userId: string }) {
-  // Implementation
-}
-```
+| Pattern | Use when |
+|---------|----------|
+| `@Delegate` | Two or three agents with a clear orchestrator / worker split |
+| `AgentGraph` | Workflow is known at design time; conditional routing matters |
+| `SupervisorAgent` | Task decomposition is dynamic; you want LLM-driven routing |
 
-## Architecture
+### Require approval for destructive actions
 
+```typescript
+@Tool({ requiresApproval: true, description: 'Delete user account' })
+async deleteAccount(input: { userId: string }) { /* ... */ }
 ```
-┌─────────────────────────────────────────────────┐
-│              Agent Runtime                       │
-├─────────────────────────────────────────────────┤
-│  ┌──────────────┐  ┌──────────────┐            │
-│  │   Registry   │  │  State Mgr   │            │
-│  └──────────────┘  └──────────────┘            │
-│  ┌──────────────┐  ┌──────────────┐            │
-│  │   Executor   │  │ Tool Executor│            │
-│  └──────────────┘  └──────────────┘            │
-│  ┌──────────────┐  ┌──────────────┐            │
-│  │    Events    │  │   Context    │            │
-│  └──────────────┘  └──────────────┘            │
-├─────────────────────────────────────────────────┤
-│         Memory Module    │    RAG Module        │
-└─────────────────────────────────────────────────┘
-```
-
-## Best Practices
 
-### 1. Keep Agents Declarative
+### Handle errors in tools
 
 ```typescript
-// ✅ Good - Declarative
-@Agent({ name: 'support-agent' })
-export class SupportAgent {
-  @Tool()
-  async lookupOrder(input: { orderId: string }) {
-    return this.orderService.find(input.orderId);
+@Tool({ description: 'Call external API' })
+async callExternalAPI(input: { endpoint: string }) {
+  try {
+    return await this.api.call(input.endpoint);
+  } catch (error) {
+    return { success: false, error: (error as Error).message };
   }
 }
-
-// ❌ Bad - Business logic in decorator
-@Agent({ 
-  name: 'support-agent',
-  onExecute: async () => { /* complex logic */ }
-})
 ```
 
-### 2. Use Approval for Destructive Actions
+---
 
-```typescript
-@Tool({ requiresApproval: true })
-async deleteAccount(input: { userId: string }) {
-  // Destructive action
-}
-```
+## API Reference
 
-### 3. Design Idempotent Tools
+### `AgentRuntime`
 
 ```typescript
-@Tool()
-async createOrder(input: { orderId: string; items: any[] }) {
-  // Check if order exists first
-  const existing = await this.findOrder(input.orderId);
-  if (existing) return existing;
-  
-  return this.createNewOrder(input);
+class AgentRuntime {
+  execute(agentName: string, input: string, options?: ExecuteOptions): Promise<AgentExecutionResult>;
+  resume(executionId: string, input?: string): Promise<AgentExecutionResult>;
+  registerAgent(agentClass: new (...args: unknown[]) => unknown): void;
+  registerAgentInstance(name: string, instance: unknown): void;
+  createGraph(name: string): AgentGraph;
+  createSupervisor(config: SupervisorConfig): SupervisorAgent;
+  approveToolExecution(requestId: string, approvedBy: string): void;
+  rejectToolExecution(requestId: string, reason?: string): void;
+  on(event: string, handler: (e: AgentEvent) => void): void;
+  onAny(handler: (e: AgentEvent) => void): void;
 }
 ```
 
-### 4. Handle Errors Gracefully
+### Decorators
+
+| Decorator | Target | Description |
+|-----------|--------|-------------|
+| `@Agent(config)` | Class | Declares a class as an agent |
+| `@Tool(config)` | Method | Exposes a method as an LLM-callable tool |
+| `@Delegate(config)` | Method | Delegates a method to another agent (registers as `@Tool` automatically) |
+
+### `GraphNodeConfig` types
 
 ```typescript
-@Tool()
-async externalAPICall(input: any) {
-  try {
-    return await this.api.call(input);
-  } catch (error) {
-    // Return structured error
-    return {
-      success: false,
-      error: error.message,
-    };
-  }
-}
-```
+// Agent node — runs a registered agent
+{ type: 'agent', agentName: string }
 
-## API Reference
+// Function node — runs a custom function
+{ type: 'function', fn: (state: GraphState) => Promise<GraphState> }
 
-See [API Documentation](./docs/api.md) for complete API reference.
+// Parallel node — fans out to multiple branches simultaneously
+{ type: 'parallel', branches: string[] }
+```
+
+---
 
 ## Examples
 
-- [Customer Support Agent](./examples/support-agent.ts)
-- [Sales Agent with Approval](./examples/sales-agent.ts)
-- [Multi-Agent System](./examples/multi-agent.ts)
-- [RAG-Powered Agent](./examples/rag-agent.ts)
+- [hazeljs-ai-multiagent-starter](../../hazeljs-ai-multiagent-starter) — Full multi-agent REST API with `AgentGraph`, `SupervisorAgent`, and `@Delegate`
+- [hazeljs-rag-documents-starter](../../hazeljs-rag-documents-starter) — RAG + GraphRAG knowledge base API
+
+---
 
 ## License
 
-MIT
+Apache 2.0
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.