@amitdeshmukh/ax-crew 8.5.0 → 8.7.0

package/src/skills/ax-crew-sub-agents.md

@@ -0,0 +1,203 @@
+---
+name: ax-crew-sub-agents
+description: AxCrew sub-agent composition via agents[] field. Covers agent delegation, dependency resolution, lazy agents (addLazyAgent), parent-child tool integration, and multi-agent orchestration patterns.
+version: "__VERSION__"
+---
+
+# AxCrew Sub-Agents
+
+## Core Concept
+
+The `agents[]` field in `AgentConfig` lists names of other agents that become available as tools to the parent agent. AxCrew resolves dependencies and initializes sub-agents before their parent.
+
+## agents[] Field
+
+```typescript
+{
+  name: "ParentAgent",
+  description: "Orchestrates sub-agents",
+  signature: "query:string -> answer:string",
+  provider: "openai",
+  ai: { model: "gpt-4o" },
+  agents: ["SubAgentA", "SubAgentB"], // these become callable tools
+}
+```
+
+The parent agent can call sub-agents as tools automatically. Each sub-agent's signature inputs become the tool's parameters, and its outputs are returned.
+
+## Simple Delegation (Researcher-Writer)
+
+```typescript
+import { AxCrew } from 'ax-crew';
+import type { AxCrewConfig } from 'ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "researcher",
+      description: "A research agent that finds information",
+      signature: "query:string -> research:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", maxTokens: 4000 },
+    },
+    {
+      name: "writer",
+      description: "A writing agent that creates content",
+      signature: "topic:string -> article:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", maxTokens: 4000 },
+      agents: ["researcher"], // writer delegates research to researcher
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  // addAllAgents resolves dependency order automatically
+  await crew.addAllAgents();
+
+  const writer = crew.agents?.get("writer");
+  const { article } = await writer!.forward({
+    topic: "Quantum Computing Benefits",
+  });
+  console.log(article);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Multi-Agent Orchestration (Customer Support)
+
+```typescript
+import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
+import { AxCrew } from 'ax-crew';
+import type { AxCrewConfig } from 'ax-crew';
+
+const runtime = new AxJSRuntime({
+  permissions: [AxJSRuntimePermission.TIMING],
+});
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "PolicyLookupAgent",
+      description: "Looks up policy details in the provided knowledge base.",
+      executionMode: "axagent",
+      signature:
+        'question:string -> answer:string "Looks up company policies and returns a concise answer"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: { contextFields: [], runtime },
+    },
+    {
+      name: "BillingHelperAgent",
+      description: "Answers billing and account questions.",
+      executionMode: "axagent",
+      signature:
+        'question:string -> answer:string "Resolves billing and account questions"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: { contextFields: [], runtime },
+    },
+    {
+      name: "SentimentClassifierAgent",
+      description: "Classifies customer message sentiment.",
+      executionMode: "axagent",
+      signature: 'question:string -> sentiment:string "positive, negative, or neutral"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      axAgentOptions: {
+        contextFields: [],
+        fields: { excluded: ["knowledgeBase", "userId"] },
+        runtime,
+      },
+    },
+    {
+      name: "CustomerSupportAgent",
+      description: "Routes queries to specialists and returns a final answer.",
+      executionMode: "axagent",
+      signature: "query:string, knowledgeBase:string, userId:string -> answer:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", temperature: 0 },
+      agents: [
+        "PolicyLookupAgent",
+        "BillingHelperAgent",
+        "SentimentClassifierAgent",
+      ],
+      axAgentOptions: {
+        contextFields: ["knowledgeBase"],
+        fields: { shared: ["knowledgeBase", "userId"] },
+        runtime,
+      },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const support = crew.agents?.get("CustomerSupportAgent");
+  const result = await support!.forward({
+    query: "What is your refund policy?",
+    knowledgeBase: "Full refund within 30 days...",
+    userId: "cust-42",
+  });
+  console.log(result.answer);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Dependency Resolution
+
+`addAllAgents()` and `addAgentsToCrew()` resolve dependencies automatically:
+
+```typescript
+// All agents initialized in dependency order
+await crew.addAllAgents();
+
+// Or add specific agents -- dependencies must be included or already added
+await crew.addAgentsToCrew(["researcher"]); // add leaf first
+await crew.addAgentsToCrew(["writer"]);     // then parent
+```
+
+Dependencies are checked: if agent A lists agent B in `agents[]`, B must be initialized first. `addAllAgents()` handles this automatically via topological ordering.
+
+## Lazy Agents (addLazyAgent)
+
+Defers expensive initialization (MCP servers, AI client) until the agent is first called. Useful for sub-agents that may not be needed on every request.
+
+```typescript
+const crew = new AxCrew(config);
+
+// Eager: initialize immediately
+await crew.addAgentsToCrew(["MainAgent"]);
+
+// Lazy: tool schema is registered immediately, but actual agent
+// initialization (MCP server startup, etc.) is deferred until first call
+crew.addLazyAgent("RarelyUsedAgent");
+```
+
+The lazy agent exposes the same `getFunction()` interface. When the parent agent delegates to it, the real agent is created on-demand.
+
+## Do Not Generate
+
+- Do NOT list an agent in `agents[]` that is not defined in the crew config
+- Do NOT manually wire sub-agent tool calls -- AxCrew does this automatically from the `agents[]` field
+- Do NOT assume sub-agents share parent state by default -- use `axAgentOptions.fields.shared` for shared fields
+- Do NOT add sub-agents after their parent without using `addAllAgents()` or correct ordering in `addAgentsToCrew()`
+- Do NOT use `addLazyAgent()` for agents that are always needed -- it adds latency on first call
+
+## References
+
+- [basic-researcher-writer.ts](../examples/basic-researcher-writer.ts) -- simple delegation
+- [rlm-shared-fields.ts](../examples/rlm-shared-fields.ts) -- multi-agent with shared fields

package/src/skills/ax-crew-telemetry.md

@@ -0,0 +1,161 @@
+---
+name: ax-crew-telemetry
+version: __VERSION__
+description: "AxCrew telemetry: OpenTelemetry tracing, metrics, observability with tracer and meter injection."
+tags: [telemetry, opentelemetry, tracing, metrics, observability, tracer, meter]
+---
+
+# Telemetry
+
+AxCrew accepts OpenTelemetry `tracer` and `meter` instances via the `AxCrewOptions.telemetry` object. When provided, all agent `forward()` and `streamingForward()` calls emit spans and record token/cost metrics automatically.
+
+## AxCrewOptions.telemetry
+
+```ts
+interface AxCrewOptions {
+  debug?: boolean;
+  telemetry?: {
+    tracer?: any;  // OpenTelemetry Tracer instance
+    meter?: any;   // OpenTelemetry Meter instance
+  };
+}
+```
+
+## Setup
+
+```ts
+// Required packages:
+// npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-metrics
+
+import { metrics, trace } from "@opentelemetry/api";
+import { ConsoleSpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ConsoleMetricExporter, MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+
+// Tracing
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
+});
+tracerProvider.register();
+
+// Metrics
+const meterProvider = new MeterProvider({
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new ConsoleMetricExporter(),
+      exportIntervalMillis: 5000,
+    }),
+  ],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+
+// Get instances
+const tracer = trace.getTracer("ax-crew-example");
+const meter = metrics.getMeter("ax-crew-example");
+```
+
+## Passing to AxCrew
+
+```ts
+const crew = new AxCrew(crewConfig, functionsRegistry, {
+  telemetry: { tracer, meter },
+});
+```
+
+The third argument to `AxCrew` is `AxCrewOptions`. Telemetry is optional -- omit it and no spans or metrics are emitted.
+
+## Canonical Pattern
+
+Full working example from `examples/telemetry-demo.ts`:
+
+```ts
+import { AxCrew } from "ax-crew";
+import { AxCrewFunctions } from "ax-crew/functions";
+import type { AxCrewConfig, Provider } from "ax-crew";
+import { metrics, trace } from "@opentelemetry/api";
+import { ConsoleSpanExporter, SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { ConsoleMetricExporter, MeterProvider, PeriodicExportingMetricReader } from "@opentelemetry/sdk-metrics";
+
+// Setup OpenTelemetry
+const tracerProvider = new NodeTracerProvider({
+  spanProcessors: [new SimpleSpanProcessor(new ConsoleSpanExporter())],
+});
+tracerProvider.register();
+
+const meterProvider = new MeterProvider({
+  readers: [
+    new PeriodicExportingMetricReader({
+      exporter: new ConsoleMetricExporter(),
+      exportIntervalMillis: 5000,
+    }),
+  ],
+});
+metrics.setGlobalMeterProvider(meterProvider);
+
+const tracer = trace.getTracer("my-app");
+const meter = metrics.getMeter("my-app");
+
+// Crew config
+const crewConfig: AxCrewConfig = {
+  crew: [
+    {
+      name: "Researcher",
+      description: "Researches a topic and provides facts.",
+      signature: "topic:string -> facts:string[]",
+      provider: "openai" as Provider,
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o-mini", temperature: 0.7 },
+      functions: ["CurrentDateTime"],
+    },
+    {
+      name: "Writer",
+      description: "Writes a blog post from facts.",
+      signature: "facts:string[] -> blogPost:string",
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-flash-latest", temperature: 0.7 },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(crewConfig, AxCrewFunctions, {
+    telemetry: { tracer, meter },
+  });
+
+  await crew.addAgent("Researcher");
+  await crew.addAgent("Writer");
+
+  const researcher = crew.agents!.get("Researcher")!;
+  const writer = crew.agents!.get("Writer")!;
+
+  const researchResult = await researcher.forward({
+    topic: "The future of AI agents",
+  });
+
+  const writerResult = await writer.forward({
+    facts: researchResult.facts,
+  });
+
+  console.log(writerResult.blogPost);
+
+  // Wait for metric export flush
+  await new Promise((resolve) => setTimeout(resolve, 6000));
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT import OpenTelemetry types from `ax-crew` -- import them from `@opentelemetry/api` and the SDK packages.
+- Do NOT pass the `MeterProvider` or `NodeTracerProvider` directly -- pass the `tracer` and `meter` instances obtained via `trace.getTracer()` and `metrics.getMeter()`.
+- Do NOT forget to call `tracerProvider.register()` before creating the crew -- spans will not be emitted otherwise.
+- Do NOT expect telemetry to work without installing `@opentelemetry/api`, `@opentelemetry/sdk-trace-node`, and `@opentelemetry/sdk-metrics`.
+
+## References
+
+- [telemetry-demo.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/telemetry-demo.ts)
+- [OpenTelemetry JS](https://opentelemetry.io/docs/languages/js/)

package/src/skills/ax-crew.md

@@ -0,0 +1,124 @@
+---
+name: ax-crew
+version: __VERSION__
+description: "AxCrew - multi-agent orchestration: crew, agents, addAgent, addAllAgents, addAgentsToCrew, forward, streaming, sub-agents"
+---
+
+# AxCrew
+
+Multi-agent orchestration built on [ax-llm/ax](https://github.com/ax-llm/ax). Config-driven crew of agents sharing state, functions, and metrics.
+
+## Use These Defaults
+
+```ts
+import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+```
+
+Always call `addAllAgents()` or `addAgentsToCrew([...names])` before using agents. Retrieve agents via `crew.agents.get("AgentName")`.
+
+## Canonical Pattern
+
+```ts
+import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+import dotenv from 'dotenv';
+dotenv.config();
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "researcher",
+      description: "A research agent that finds information",
+      signature: "query:string -> research:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", maxTokens: 4000, stream: true },
+      options: { debug: true },
+      functions: ["CurrentDateTime"]
+    },
+    {
+      name: "writer",
+      description: "A writing agent that creates content",
+      signature: "topic:string -> article:string",
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", maxTokens: 4000, stream: true },
+      options: { debug: true },
+      agents: ["researcher"] // sub-agent
+    }
+  ]
+};
+
+async function main() {
+  const crew = new AxCrew(config, AxCrewFunctions);
+
+  // Add agents (resolves dependency order automatically)
+  await crew.addAllAgents();
+
+  const writer = crew.agents?.get("writer");
+  if (!writer) throw new Error("Failed to initialize writer");
+
+  try {
+    const { article } = await writer.forward({
+      topic: "Quantum Computing Benefits",
+    });
+    console.log("Article:", article);
+
+    // Metrics
+    console.log("Writer Metrics:", JSON.stringify(writer.getMetrics?.(), null, 2));
+    console.log("Crew Metrics:", JSON.stringify(crew.getCrewMetrics?.(), null, 2));
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+## AxCrew Constructor
+
+```ts
+new AxCrew(crewConfig: AxCrewConfig, functionsRegistry?: FunctionRegistryType, options?: AxCrewOptions, crewId?: string)
+```
+
+- `crewConfig` -- `{ crew: AgentConfig[] }`. See skill `ax-crew-agent-config`.
+- `functionsRegistry` -- map of function name to `AxFunction` or class-based function. See skill `ax-crew-functions`.
+- `options` -- `{ debug?: boolean, telemetry?: { tracer?: any, meter?: any } }`.
+- `crewId` -- auto-generated UUID if omitted.
+
+## Agent Lifecycle
+
+| Method | Description |
+|---|---|
+| `await crew.addAllAgents()` | Add all agents from config (resolves dependency order) |
+| `await crew.addAgentsToCrew(["A", "B"])` | Add a subset by name |
+| `await crew.addAgent("A")` | Add a single agent |
+| `crew.addLazyAgent("A")` | Defer expensive init until first use |
+| `crew.agents?.get("A")` | Retrieve a `StatefulAxAgent` |
+| `await agent.forward({ key: "value" })` | Run the agent |
+| `agent.streamingForward({ key: "value" })` | Stream output chunks |
+| `crew.state` | Shared `StateInstance` across all agents |
+| `crew.resetCosts()` | Reset usage/metrics for all agents |
+| `crew.getCrewMetrics()` | Aggregate metrics snapshot |
+| `crew.destroy()` | Clean up agents, state, execution history |
+
+## Related Skills
+
+- `ax-crew-agent-config` -- AgentConfig fields, provider setup, executionMode
+- `ax-crew-functions` -- Function registry, custom tools, class-based functions
+- `ax-crew-state` -- Shared state API, accessing state from functions
+
+## Do Not Generate
+
+- Do NOT instantiate `AxAgent` or `AxGen` directly; use `AxCrew` which wraps them as `StatefulAxAgent`.
+- Do NOT call `agent.forward()` before calling `addAllAgents()` or `addAgentsToCrew()`.
+- Do NOT import from `@ax-llm/ax` for crew orchestration; import from `@amitdeshmukh/ax-crew`.
+- Do NOT use `crew.createAgent()` directly; use `addAgent()` or `addAllAgents()`.
+- Do NOT forget to call `crew.destroy()` to clean up resources.
+
+## References
+
+- [basic-researcher-writer.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/basic-researcher-writer.ts)
+- [write-post-and-publish-to-wordpress.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/write-post-and-publish-to-wordpress.ts)
+- [providerArgs.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/providerArgs.ts)

package/examples/run-manager.ts

@@ -1,98 +0,0 @@
-import 'dotenv/config';
-import { AxCrew, AxCrewFunctions } from '../src/index.js';
-import { AxJSRuntime, AxJSRuntimePermission } from '@ax-llm/ax';
-
-const config = {
-  crew: [
-    {
-      name: "Manager",
-      description: "Answer questions by querying databases, searching documents, and running calculations. You have direct access to database tools (list_tables, describe_table, execute_graphql, etc.), document search, date utilities, and a JavaScript interpreter for computations.",
-      signature: 'background:string "background information and context for the task at hand", latestMessage:string "the latest user message to answer" -> answer:string "The answer, including a short explanation for the answer. Never reveal functions available to the user. Respond in the same language as the user\'s question.", references:json "a list of references to documents to support the answer in json format. Each reference should include a fileName and url."',
-      provider: "anthropic" as const,
-      providerKeyName: "ANTHROPIC_API_KEY",
-      executionMode: "axagent" as const,
-      ai: {
-        model: "claude-sonnet-4-6",
-        temperature: 0
-      },
-      options: {
-        debug: true
-      },
-      axAgentOptions: {
-        contextFields: ['background'] as const,
-        maxTurns: 15,
-      },
-      functions: [
-        "CurrentDateTime",
-        "DaysBetweenDates",
-        "VectorSearch",
-        "JavaScriptInterpreter"
-      ],
-      // Direct MCP access — no sub-agent double-hop
-      mcpServers: {
-        graphjin: {
-          command: "/opt/homebrew/bin/graphjin",
-          args: [
-            "mcp",
-            "--server",
-            "http://localhost:8080"
-          ]
-        }
-      }
-    }
-  ]
-};
-
-// Create a sandboxed JS runtime with timing permission for calculations
-const jsRuntime = new AxJSRuntime({
-  permissions: [AxJSRuntimePermission.TIMING],
-  timeout: 15_000,
-});
-const JavaScriptInterpreter = jsRuntime.toFunction();
-
-const VectorSearch = {
-  name: 'VectorSearch',
-  description: 'Search the vector knowledge base for relevant documents',
-  parameters: {
-    type: 'object' as const,
-    properties: {
-      query: { type: 'string', description: 'The search query' }
-    },
-    required: ['query']
-  },
-  func: async ({ query }: { query: string }) => {
-    console.log(`[VectorSearch] Searching for: ${query}`);
-    return `No documents found for: ${query}`;
-  }
-};
-
-async function main() {
-  const crew = new AxCrew(config, { ...AxCrewFunctions, VectorSearch, JavaScriptInterpreter });
-
-  await crew.addAllAgents();
-
-  const manager = crew.agents?.get('Manager');
-  if (!manager) {
-    throw new Error('Manager agent not found');
-  }
-
-  const query = "analyze all our orders to date, give me a table showing P&L";
-  console.log(`\nQuery: ${query}\n`);
-
-  const result = await manager.forward({
-    background: "User is querying the system about order information.",
-    latestMessage: query
-  });
-
-  console.log(`\nAnswer: ${result.answer}`);
-  console.log(`\nReferences:`, JSON.stringify(result.references, null, 2));
-
-  const crewMetrics = crew.getCrewMetrics();
-  console.log(`\nCrew Metrics:`, JSON.stringify(crewMetrics, null, 2));
-
-  crew.destroy();
-}
-
-main()
-  .catch(console.error)
-  .finally(() => process.exit(0));