@axlsdk/axl 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,8 @@
-# axl
+# @axlsdk/axl
 
-Core SDK for orchestrating agentic systems in TypeScript.
+[![npm version](https://img.shields.io/npm/v/@axlsdk/axl)](https://www.npmjs.com/package/@axlsdk/axl)
+
+Core SDK for orchestrating agentic systems in TypeScript. Part of the [Axl](https://github.com/axl-sdk/axl) monorepo.
 
 ## Installation
 
@@ -26,11 +28,23 @@ const calculator = tool({
     const result = new Function(`return (${expression})`)();
     return { result };
   },
+  // handler also accepts (input, ctx) for nested agent invocations — see below
   retry: { attempts: 3, backoff: 'exponential' },
   sensitive: false,
 });
 ```
 
+Tool handlers receive a second parameter `ctx: WorkflowContext` (a child context), enabling the "agent-as-tool" composition pattern:
+
+```typescript
+const researchTool = tool({
+  name: 'research',
+  description: 'Delegate to a specialist',
+  input: z.object({ question: z.string() }),
+  handler: async (input, ctx) => ctx.ask(researcher, input.question),
+});
+```
+
 ### `agent(config)`
 
 Define an agent with model, system prompt, tools, and handoffs:
@@ -40,9 +54,10 @@ import { agent } from '@axlsdk/axl';
 
 const researcher = agent({
   name: 'researcher',
-  model: 'openai:gpt-4o',
+  model: 'openai-responses:gpt-5.4',
   system: 'You are a research assistant.',
   tools: [calculator],
+  effort: 'high',
   maxTurns: 10,
   timeout: '30s',
   temperature: 0.7,
@@ -55,12 +70,71 @@ Dynamic model and system prompt selection:
 ```typescript
 const dynamicAgent = agent({
   model: (ctx) => ctx.metadata?.tier === 'premium'
-    ? 'openai:gpt-4o'
-    : 'openai:gpt-4.1-nano',
+    ? 'openai-responses:gpt-5.4'
+    : 'openai-responses:gpt-5-nano',
   system: (ctx) => `You are a ${ctx.metadata?.role ?? 'general'} assistant.`,
 });
 ```
 
+#### Dynamic Handoffs
+
+`handoffs` accepts a static array or a function for runtime-conditional routing:
+
+```typescript
+const router = agent({
+  model: 'openai-responses:gpt-5-mini',
+  system: 'Route to the right specialist.',
+  handoffs: (ctx) => {
+    const base = [
+      { agent: billingAgent, description: 'Billing issues' },
+      { agent: shippingAgent, description: 'Shipping questions' },
+    ];
+    if (ctx.metadata?.tier === 'enterprise') {
+      base.push({ agent: priorityAgent, description: 'Priority support' });
+    }
+    return base;
+  },
+});
+```
+
+#### Workflow-Level Routing with `ctx.delegate()`
+
+When your workflow (not an agent's LLM) needs to pick the best agent:
+
+```typescript
+const result = await ctx.delegate(
+  [billingAgent, shippingAgent, returnsAgent],
+  customerMessage,
+);
+```
+
+`ctx.delegate()` creates a temporary router agent that uses handoffs to select the best candidate. For a single agent, it calls `ctx.ask()` directly with no routing overhead.
+
+#### Effort (cross-provider reasoning control)
+
+The `effort` parameter provides a unified way to control reasoning depth across all providers:
+
+```typescript
+// Simple levels — works on any provider
+const reasoner = agent({
+  model: 'anthropic:claude-opus-4-6',
+  system: 'You are a careful analyst.',
+  effort: 'high',  // 'none' | 'low' | 'medium' | 'high' | 'max'
+});
+
+// Explicit thinking budget (in tokens)
+const budgetReasoner = agent({
+  model: 'google:gemini-2.5-flash',
+  system: 'Think step by step.',
+  thinkingBudget: 5000,
+});
+
+// Per-call override
+const result = await reasoner.ask('Analyze this data', { effort: 'low' });
+```
+
+Each provider maps `effort` to its native API: `reasoning_effort` (OpenAI), adaptive thinking + `output_config.effort` (Anthropic 4.6), `thinkingLevel` (Gemini 3.x), `thinkingBudget` (Gemini 2.x). See [docs/providers.md](../../docs/providers.md) for the full mapping table.
+
 ### `workflow(config)`
 
 Define a named workflow with typed input/output:
@@ -240,7 +314,7 @@ const containsPII = (text: string) => /\b\d{3}-\d{2}-\d{4}\b/.test(text);
 const isOffTopic = (text: string) => !text.toLowerCase().includes('support');
 
 const safe = agent({
-  model: 'openai:gpt-4o',
+  model: 'openai-responses:gpt-5.4',
   system: 'You are a helpful assistant.',
   guardrails: {
     input: async (prompt, ctx) => {
@@ -266,7 +340,7 @@ const session = runtime.session('user-123', {
   history: {
     maxMessages: 100,          // Trim oldest messages when exceeded
     summarize: true,           // Auto-summarize trimmed messages
-    summaryModel: 'openai:gpt-4o-mini',  // Model for summarization
+    summaryModel: 'openai-responses:gpt-5-mini',  // Model for summarization
   },
   persist: true,               // Save to StateStore (default: true)
 });
@@ -321,9 +395,9 @@ const runtime = new AxlRuntime({
 Four built-in providers using the `provider:model` URI scheme:
 
 ```
-openai:gpt-4o                          # OpenAI Chat Completions
-openai-responses:gpt-4o                # OpenAI Responses API
-anthropic:claude-sonnet-4-5            # Anthropic
+openai-responses:gpt-5.4               # OpenAI Responses API (recommended)
+openai:gpt-5.4                         # OpenAI Chat Completions
+anthropic:claude-sonnet-4-6            # Anthropic
 google:gemini-2.5-pro                  # Google Gemini
 ```