@amitdeshmukh/ax-crew 8.6.0 → 8.7.0

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

@@ -0,0 +1,168 @@
+---
+name: ax-crew-state
+version: __VERSION__
+description: "State management: shared state, StateInstance, set, get, getAll, reset, accessing state from class-based functions"
+---
+
+# State
+
+Every `AxCrew` instance has a shared `StateInstance` at `crew.state`. All agents and class-based functions in the crew can access the same state.
+
+## StateInstance API
+
+```ts
+interface StateInstance {
+  set(key: string, value: any): void;   // Set a value
+  get(key: string): any;                // Get a value
+  getAll(): Record<string, any>;        // Get all key-value pairs (shallow copy)
+  reset(): void;                        // Clear all state
+}
+```
+
+## Core Behavior
+
+- `crew.state` is created automatically when `new AxCrew(config)` is called.
+- State is keyed by `crewId` (auto-generated UUID). Each crew instance has its own isolated state.
+- State persists for the lifetime of the crew. Calling `crew.destroy()` calls `state.reset()`.
+- Values can be any type: strings, objects, arrays, etc.
+
+## Canonical Pattern
+
+```ts
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig, FunctionRegistryType } from '@amitdeshmukh/ax-crew';
+import type { AxFunction } from '@ax-llm/ax';
+import dotenv from 'dotenv';
+dotenv.config();
+
+// Class-based function that reads from shared state
+class SendEmail {
+  private state: Record<string, any>;
+  constructor(state: Record<string, any>) { this.state = state; }
+  toFunction(): AxFunction {
+    return {
+      name: 'SendEmail',
+      description: 'Send an email using configured SMTP credentials',
+      parameters: {
+        type: 'object',
+        properties: {
+          to: { type: 'string', description: 'Recipient email' },
+          subject: { type: 'string', description: 'Email subject' },
+          body: { type: 'string', description: 'Email body' },
+        },
+        required: ['to', 'subject', 'body']
+      },
+      func: async ({ to, subject, body }: { to: string; subject: string; body: string }) => {
+        // Access env credentials set via crew.state.set("env", {...})
+        const env = this.state.env || {};
+        const smtpHost = env.SMTP_HOST;
+        const smtpUser = env.SMTP_USER;
+        const smtpPass = env.SMTP_PASS;
+        // ... send email using credentials
+        return { sent: true, to };
+      }
+    };
+  }
+}
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "notifier",
+      description: "An agent that sends email notifications",
+      signature: "task:string -> result:string",
+      provider: "openai",
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o-mini", temperature: 0 },
+      functions: ["SendEmail"],
+    }
+  ]
+};
+
+async function main() {
+  const functions: FunctionRegistryType = { SendEmail };
+  const crew = new AxCrew(config, functions);
+
+  // Set environment variables in shared state BEFORE adding agents
+  crew.state.set("env", {
+    SMTP_HOST: "smtp.example.com",
+    SMTP_USER: "user@example.com",
+    SMTP_PASS: "secret",
+  });
+
+  // You can also set arbitrary data
+  crew.state.set("company", "Acme Corp");
+  crew.state.set("maxRetries", 3);
+
+  await crew.addAllAgents();
+  const notifier = crew.agents?.get("notifier");
+
+  const result = await notifier?.forward({ task: "Notify user about order shipped" });
+  console.log(result?.result);
+
+  // Read state back
+  console.log("All state:", crew.state.getAll());
+  console.log("Company:", crew.state.get("company"));
+
+  // Reset state (clear all)
+  crew.state.reset();
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Setting Environment Credentials
+
+The common pattern for passing credentials to class-based functions:
+
+```ts
+crew.state.set("env", {
+  WORDPRESS_URL: "http://my-wordpress-site.com",
+  WORDPRESS_USERNAME: "my-username",
+  WORDPRESS_PASSWORD: "my-password",
+});
+```
+
+Inside the class-based function, access via `this.state.env`:
+
+```ts
+class MyFunction {
+  private state: Record<string, any>;
+  constructor(state: Record<string, any>) { this.state = state; }
+  toFunction(): AxFunction {
+    return {
+      name: 'MyFunction',
+      description: 'Does something',
+      parameters: { type: 'object', properties: {} },
+      func: () => {
+        const url = this.state.env?.WORDPRESS_URL;  // reads from shared state
+        return url;
+      }
+    };
+  }
+}
+```
+
+## Accessing State from Agents
+
+Each `StatefulAxAgent` has a `state` property that references the crew's shared state:
+
+```ts
+const agent = crew.agents?.get("myAgent");
+// agent.state is the same StateInstance as crew.state
+```
+
+## Do Not Generate
+
+- Do NOT assume state values exist without checking; always use optional chaining (e.g. `this.state.env?.KEY`).
+- Do NOT call `crew.state.set("env", ...)` after `addAllAgents()` if class-based functions read state during construction -- set state first.
+- Do NOT confuse `crew.state` (StateInstance with `set`/`get`/`getAll`/`reset`) with plain objects. The state object passed to class-based function constructors is a plain record, not the `StateInstance` interface.
+- Do NOT store sensitive credentials in state if the state object might be logged or serialized. The `getAll()` method returns all stored values.
+
+## References
+
+- [write-post-and-publish-to-wordpress.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/write-post-and-publish-to-wordpress.ts)
+- [src/state/index.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/state/index.ts)
+- [src/types.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/types.ts)

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

@@ -0,0 +1,143 @@
+---
+name: ax-crew-streaming
+version: "__VERSION__"
+description: "ax-crew streaming patterns: streaming, streamingForward, stream, delta, real-time, chunks, async generator consumption"
+argument-hint: [topic]
+allowed-tools: Read, Grep, Glob
+---
+
+# ax-crew Streaming
+
+## streamingForward() vs forward()
+
+`forward()` returns `Promise<Record<string, any>>` -- waits for full response.
+`streamingForward()` returns `AxGenStreamingOut<any>` -- an async generator yielding chunks as they arrive.
+
+Both accept the same input values object. Both work with `axgen` and `axagent` execution modes.
+
+```typescript
+// Blocking
+const result = await agent.forward({ question: "What is AI?" });
+console.log(result.answer);
+
+// Streaming
+const stream = agent.streamingForward({ question: "What is AI?" });
+for await (const chunk of stream) {
+  if (chunk.delta && 'answer' in chunk.delta) {
+    process.stdout.write(chunk.delta.answer);
+  }
+}
+```
+
+## chunk.delta Structure
+
+Each yielded chunk has a `delta` property containing partial values keyed by output field names from the agent's signature.
+
+```typescript
+// For signature: 'question:string -> answer:string'
+// chunk.delta = { answer: "partial text..." }
+
+// For signature: 'query:string -> title:string, summary:string'
+// chunk.delta may contain { title: "..." } or { summary: "..." }
+```
+
+Always check for the field's existence before accessing:
+```typescript
+if (chunk.delta && typeof chunk.delta === 'object' && 'answer' in chunk.delta) {
+  process.stdout.write(chunk.delta.answer);
+}
+```
+
+## Stream Config in Agent Config
+
+Enable streaming at the provider level via `ai.stream` or `options.stream`:
+
+```typescript
+{
+  name: "StreamAgent",
+  ai: { model: "gemini-2.5-flash", stream: true },   // provider-level
+  options: { stream: true },                           // forward options level
+}
+```
+
+## Overload Signatures
+
+```typescript
+// Without explicit AI instance (uses agent's configured AI)
+agent.streamingForward(values: Record<string, any>, options?: AxProgramStreamingForwardOptions): AxGenStreamingOut<any>;
+
+// With explicit AI instance
+agent.streamingForward(ai: AxAI, values: Record<string, any>, options?: AxProgramStreamingForwardOptions): AxGenStreamingOut<any>;
+```
+
+## Canonical Pattern
+
+```typescript
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "ManagerAgent",
+      description: "Completes a user specified task",
+      signature:
+        'question:string "a question to be answered" -> answer:string "the answer to the question"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash", maxTokens: 1000, temperature: 0 },
+      options: { debug: true, stream: true },
+      agents: ["MathAgent"],
+    },
+    {
+      name: "MathAgent",
+      description: "Solves math problems",
+      signature:
+        'mathProblem:string "a math problem" -> solution:string "the answer"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", temperature: 0 },
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const agent = crew.agents?.get("ManagerAgent");
+  if (!agent) throw new Error("Agent not found");
+
+  const stream = agent.streamingForward({
+    question: "Get me the first 5 fibonacci numbers divided by 2",
+  });
+
+  for await (const chunk of stream) {
+    if (chunk.delta && typeof chunk.delta === 'object' && 'answer' in chunk.delta) {
+      process.stdout.write(chunk.delta.answer);
+    }
+  }
+  console.log('\n');
+
+  // Metrics still available after streaming
+  console.log("Agent Metrics:", JSON.stringify(agent.getMetrics?.(), null, 2));
+  console.log("Crew Metrics:", JSON.stringify(crew.getCrewMetrics(), null, 2));
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT `await` the return of `streamingForward()` -- it returns the async generator directly, not a promise.
+- Do NOT assume `chunk.delta` is always a string -- it is an object keyed by output field names.
+- Do NOT forget to check field existence in `chunk.delta` before accessing (`'fieldName' in chunk.delta`).
+- Do NOT use `forward()` with the expectation of receiving streaming chunks -- use `streamingForward()`.
+- Do NOT skip `crew.destroy()` -- it cleans up MCP servers and resources.
+
+## References
+
+- [streaming.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/streaming.ts)
+- [Source: StatefulAxAgent.streamingForward](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/index.ts)

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/)