@amitdeshmukh/ax-crew 8.6.0 → 8.7.0

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

@@ -0,0 +1,218 @@
+---
+name: ax-crew-functions
+version: __VERSION__
+description: "Functions and tools: FunctionRegistryType, AxFunction, toFunction, custom functions, AxCrewFunctions, class-based functions with state"
+---
+
+# Functions
+
+Agents call tools via a `FunctionRegistryType` -- a map of function names to either plain `AxFunction` objects or class-based constructors that receive shared state.
+
+## Two Patterns
+
+### Object-based (plain AxFunction)
+
+```ts
+import type { AxFunction } from '@ax-llm/ax';
+
+const MyTool: AxFunction = {
+  name: 'MyTool',
+  description: 'Does something useful',
+  parameters: {
+    type: 'object',
+    properties: {
+      input: { type: 'string', description: 'The input value' }
+    },
+    required: ['input']
+  },
+  func: ({ input }: { input: string }) => {
+    return `Processed: ${input}`;
+  }
+};
+```
+
+### Class-based (with state access)
+
+Constructor receives shared state. Must implement `toFunction()` returning an `AxFunction`.
+
+```ts
+import type { AxFunction } from '@ax-llm/ax';
+
+class WordPressPost {
+  private state: Record<string, any>;
+
+  constructor(state: Record<string, any>) {
+    this.state = state;
+  }
+
+  toFunction(): AxFunction {
+    return {
+      name: 'WordPressPost',
+      description: 'Creates a post on WordPress',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: { type: 'string', description: 'Post title' },
+          content: { type: 'string', description: 'Post content' },
+          status: { type: 'string', description: 'Post status (draft, publish, private)' }
+        },
+        required: ['title', 'content', 'status']
+      },
+      func: async ({ title, content, status }: { title: string; content: string; status: string }) => {
+        const env = this.state.env || {};
+        const url = env.WORDPRESS_URL;
+        const username = env.WORDPRESS_USERNAME;
+        const password = env.WORDPRESS_PASSWORD;
+        // ... make API call using credentials from state
+        return { id: 123, link: `${url}/?p=123` };
+      }
+    };
+  }
+}
+```
+
+## FunctionRegistryType
+
+```ts
+type FunctionRegistryType = {
+  [key: string]: AxFunction | { new(state: Record<string, any>): { toFunction: () => AxFunction } };
+};
+```
+
+The registry key must match the name used in `AgentConfig.functions[]`.
+
+## Built-in AxCrewFunctions
+
+```ts
+import { AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+// Contains: { CurrentDateTime, DaysBetweenDates }
+```
+
+**CurrentDateTime** -- returns current date/time in `iso`, `datetime`, or `date` format.
+
+**DaysBetweenDates** -- calculates days between two ISO date strings. Parameters: `startDate`, `endDate`.
+
+## Merging Registries
+
+```ts
+import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+import type { FunctionRegistryType } from '@amitdeshmukh/ax-crew';
+
+const myFunctions: FunctionRegistryType = {
+  MyTool: MyTool,
+  WordPressPost: WordPressPost,  // class-based
+};
+
+// Merge built-in + custom
+const crew = new AxCrew(config, { ...AxCrewFunctions, ...myFunctions });
+```
+
+Then reference by name in agent config:
+
+```ts
+{
+  name: "poster",
+  functions: ["CurrentDateTime", "WordPressPost"],
+  // ...
+}
+```
+
+## Canonical Pattern
+
+Full runnable example adapted from the WordPress example:
+
+```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();
+
+// Plain AxFunction
+const Summarize: AxFunction = {
+  name: 'Summarize',
+  description: 'Summarize text to a given length',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Text to summarize' },
+      maxWords: { type: 'number', description: 'Maximum words' }
+    },
+    required: ['text']
+  },
+  func: ({ text, maxWords }: { text: string; maxWords?: number }) => {
+    const limit = maxWords ?? 50;
+    return text.split(' ').slice(0, limit).join(' ') + '...';
+  }
+};
+
+// Class-based function with state access
+class FetchFromAPI {
+  private state: Record<string, any>;
+  constructor(state: Record<string, any>) { this.state = state; }
+  toFunction(): AxFunction {
+    return {
+      name: 'FetchFromAPI',
+      description: 'Fetch data from a configured API endpoint',
+      parameters: {
+        type: 'object',
+        properties: {
+          endpoint: { type: 'string', description: 'API endpoint path' }
+        },
+        required: ['endpoint']
+      },
+      func: async ({ endpoint }: { endpoint: string }) => {
+        const baseUrl = this.state.env?.API_BASE_URL || 'https://api.example.com';
+        const resp = await fetch(`${baseUrl}${endpoint}`);
+        return await resp.json();
+      }
+    };
+  }
+}
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "assistant",
+      description: "An assistant that can summarize text and fetch data",
+      signature: "request:string -> response:string",
+      provider: "openai",
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o-mini", temperature: 0.5 },
+      functions: ["Summarize", "FetchFromAPI"],
+    }
+  ]
+};
+
+async function main() {
+  const customFunctions: FunctionRegistryType = {
+    Summarize,
+    FetchFromAPI,
+  };
+  const crew = new AxCrew(config, customFunctions);
+
+  // Set state for class-based functions
+  crew.state.set("env", { API_BASE_URL: "https://api.example.com" });
+
+  await crew.addAllAgents();
+  const assistant = crew.agents?.get("assistant");
+  const result = await assistant?.forward({ request: "Summarize the latest news" });
+  console.log(result?.response);
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT define functions inline in AgentConfig; always use a `FunctionRegistryType` registry passed to the `AxCrew` constructor.
+- Do NOT forget that class-based function constructors receive `state: Record<string, any>`, not `StateInstance`. Access values directly (e.g. `this.state.env`), since the state object is a plain record populated via `crew.state.set()`.
+- Do NOT use a registry key that differs from the function name used in `AgentConfig.functions[]` -- they must match.
+- Do NOT import `AxCrewFunctions` from `@ax-llm/ax`; import from `@amitdeshmukh/ax-crew`.
+
+## 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/functions/dateTime.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/functions/dateTime.ts)
+- [src/functions/index.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/src/functions/index.ts)

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

@@ -0,0 +1,221 @@
+---
+name: ax-crew-mcp
+version: "__VERSION__"
+description: "ax-crew MCP integration: MCP, Model Context Protocol, STDIO, HTTP SSE, Streamable HTTP, mcpServers, tools, tool filtering, multiple servers"
+argument-hint: [topic]
+allowed-tools: Read, Grep, Glob
+---
+
+# ax-crew MCP (Model Context Protocol)
+
+MCP servers expose external tools to agents. Configured per-agent via `mcpServers` in the agent config. Transport type is auto-detected by config shape.
+
+## Three Transport Types
+
+### STDIO (local process)
+
+```typescript
+mcpServers: {
+  "context7": {
+    command: "npx",                              // required
+    args: ["-y", "@upstash/context7-mcp"],       // optional
+    env: { API_KEY: "..." },                     // optional
+    tools: ["resolve-library-id", "query-docs"], // optional allowlist
+  }
+}
+```
+
+Type: `MCPStdioTransportConfig = { command: string; args?: string[]; env?: NodeJS.ProcessEnv; tools?: string[] }`
+
+### HTTP SSE (remote, server-sent events)
+
+```typescript
+mcpServers: {
+  "api-server": {
+    sseUrl: "https://api.example.com/mcp/sse",   // required
+    tools: ["search", "fetch"],                    // optional allowlist
+  }
+}
+```
+
+Type: `MCPHTTPSSETransportConfig = { sseUrl: string; tools?: string[] }`
+
+### Streamable HTTP (bidirectional)
+
+```typescript
+mcpServers: {
+  "graphjin": {
+    mcpEndpoint: "http://localhost:8080/api/v1/mcp",  // required
+    options: { timeout: 30000 },                       // optional AxMCPStreamableHTTPTransportOptions
+    tools: ["list_workflows", "execute_workflow"],      // optional allowlist
+  }
+}
+```
+
+Type: `MCPStreamableHTTPTransportConfig = { mcpEndpoint: string; options?: AxMCPStreamableHTTPTransportOptions; tools?: string[] }`
+
+## tools[] Allowlist
+
+When `tools` is specified, only those MCP tool names are exposed to the agent. This reduces token usage and prevents the agent from calling unwanted tools.
+
+```typescript
+mcpServers: {
+  "big-server": {
+    command: "npx",
+    args: ["-y", "some-mcp-server"],
+    tools: ["only_this_tool", "and_this_one"],  // filter from all available
+  }
+}
+```
+
+If `tools` is omitted or empty, all tools from the MCP server are exposed.
+
+## Multiple MCP Servers Per Agent
+
+An agent can connect to multiple MCP servers simultaneously. All tools are merged:
+
+```typescript
+{
+  name: "MultiToolAgent",
+  description: "Agent with multiple MCP servers",
+  signature: 'query:string -> answer:string',
+  provider: "google-gemini",
+  providerKeyName: "GEMINI_API_KEY",
+  ai: { model: "gemini-2.5-pro", temperature: 0 },
+  mcpServers: {
+    "filesystem": {
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+    },
+    "database": {
+      mcpEndpoint: "http://localhost:8080/api/v1/mcp",
+      tools: ["query", "describe_table"],
+    }
+  }
+}
+```
+
+## Canonical Pattern
+
+### STDIO transport (from mcp-agent.ts)
+
+```typescript
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Context7DocsAgent",
+      description: "Agent with access to Context7 Docs APIs",
+      signature: 'apiDocQuery:string "a question" -> apiDocAnswer:string "the answer"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", temperature: 0 },
+      options: { debug: true },
+      mcpServers: {
+        "context7": {
+          command: "npx",
+          args: ["-y", "@upstash/context7-mcp", "--api-key", process.env.CONTEXT7_API_KEY!],
+        },
+      },
+    },
+    {
+      name: "ManagerAgent",
+      description: "Orchestrates sub-agents",
+      signature: 'question:string -> answer:string',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", maxTokens: 1000, temperature: 0 },
+      agents: ["Context7DocsAgent"],
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  try {
+    await crew.addAllAgents();
+
+    const manager = crew.agents?.get("ManagerAgent");
+    if (!manager) throw new Error("Agent not found");
+
+    const result = await manager.forward({
+      question: "How do I configure MCP servers in ax-crew?",
+    });
+    console.log("Answer:", result.answer);
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+### Streamable HTTP transport (from graphjin-database-agent.ts)
+
+```typescript
+import { AxCrew } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/ax-crew';
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "DatabaseAgent",
+      description: "Agent with direct database access via GraphJin",
+      signature: 'dbQuery:string "a database question" -> dbResult:string "the result"',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", temperature: 0 },
+      mcpServers: {
+        "graphjin": {
+          command: "graphjin",
+          args: ["mcp", "--server", "http://localhost:8080"],
+        },
+      },
+    },
+    {
+      name: "ManagerAgent",
+      description: "Orchestrates database queries",
+      signature: 'question:string -> answer:string',
+      provider: "google-gemini",
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-pro", maxTokens: 2000, temperature: 0 },
+      agents: ["DatabaseAgent"],
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  try {
+    await crew.addAllAgents();
+    const manager = crew.agents?.get("ManagerAgent");
+    if (!manager) throw new Error("Agent not found");
+
+    const result = await manager.forward({
+      question: "What tables are available in the database?",
+    });
+    console.log("Answer:", result.answer);
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Do Not Generate
+
+- Do NOT mix transport config keys -- use exactly one of `command`, `sseUrl`, or `mcpEndpoint` per server entry.
+- Do NOT forget `crew.destroy()` -- MCP STDIO processes must be cleaned up.
+- Do NOT put `mcpServers` at the crew level -- it is per-agent only.
+- Do NOT assume MCP tools have `parameters` -- some zero-arg tools omit it; ax-crew normalizes this automatically.
+- Do NOT use `AxMCPStdioTransport` directly -- ax-crew handles transport creation internally from config.
+
+## References
+
+- [mcp-agent.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/mcp-agent.ts)
+- [graphjin-database-agent.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/graphjin-database-agent.ts)
+- [Source: agentConfig.ts (initializeMCPServers)](https://github.com/amitdeshmukh/ax-crew/blob/main/src/agents/agentConfig.ts)
+- [Types: MCPStdioTransportConfig, MCPHTTPSSETransportConfig, MCPStreamableHTTPTransportConfig](https://github.com/amitdeshmukh/ax-crew/blob/main/src/types.ts)

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

@@ -0,0 +1,170 @@
+---
+name: ax-crew-metrics
+version: "__VERSION__"
+description: "ax-crew metrics and cost tracking: metrics, cost, tracking, getMetrics, getCrewMetrics, MetricsSnapshot, usage, tokens, estimatedCostUSD, resetCosts, resetCrewMetrics"
+argument-hint: [topic]
+allowed-tools: Read, Grep, Glob
+---
+
+# ax-crew Metrics & Cost Tracking
+
+## Per-Agent: agent.getMetrics()
+
+Returns a `MetricsSnapshot` scoped to this agent within its crew.
+
+```typescript
+const agent = crew.agents?.get("MyAgent");
+const metrics = agent.getMetrics();
+```
+
+## Crew-Level: crew.getCrewMetrics()
+
+Returns a `MetricsSnapshot` aggregated across all agents in the crew.
+
+```typescript
+const crewMetrics = crew.getCrewMetrics();
+```
+
+## MetricsSnapshot Shape
+
+```typescript
+interface MetricsSnapshot {
+  provider?: string;
+  model?: string;
+  requests: {
+    totalRequests: number;
+    totalErrors: number;
+    errorRate: number;               // errors / requests
+    totalStreamingRequests: number;
+    durationMsSum: number;
+    durationCount: number;
+  };
+  tokens: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens?: number;
+  };
+  estimatedCostUSD: number;          // rounded to 5 decimal places
+  functions: {
+    totalFunctionCalls: number;
+    totalFunctionLatencyMs: number;
+    details?: Array<{                // per-function breakdown
+      name: string;
+      calls: number;
+      totalLatencyMs: number;
+    }>;
+  };
+}
+```
+
+## Reset Methods
+
+```typescript
+// Reset all cost/usage tracking for the entire crew (resets agent usage + metrics)
+crew.resetCosts();
+
+// Reset only the metrics registry for the crew
+crew.resetCrewMetrics();
+```
+
+`resetCosts()` calls `resetUsage()` and `resetMetrics()` on each agent, then clears crew-level metrics.
+`resetCrewMetrics()` only clears the MetricsRegistry entries for this crew.
+
+## Canonical Pattern
+
+```typescript
+import { AxCrew, AxCrewFunctions } from '@amitdeshmukh/ax-crew';
+import type { AxCrewConfig } from '@amitdeshmukh/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, stream: 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 },
+      agents: ["researcher"],
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config, AxCrewFunctions);
+  await crew.addAgentsToCrew(["researcher"]);
+  await crew.addAgentsToCrew(["writer"]);
+
+  const writer = crew.agents?.get("writer");
+  const researcher = crew.agents?.get("researcher");
+  if (!writer || !researcher) throw new Error("Failed to initialize agents");
+
+  try {
+    const { article } = await writer.forward({
+      topic: "Quantum Computing Benefits",
+    });
+    console.log("Article:", article);
+
+    // Per-agent metrics
+    console.log("Writer Metrics:", JSON.stringify(writer.getMetrics?.(), null, 2));
+    console.log("Researcher Metrics:", JSON.stringify(researcher.getMetrics?.(), null, 2));
+
+    // Crew-wide aggregate
+    console.log("Crew Metrics:", JSON.stringify(crew.getCrewMetrics(), null, 2));
+
+    // Reset for next measurement period
+    crew.resetCosts();
+  } finally {
+    crew.destroy();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Accessing Specific Fields
+
+```typescript
+const m = agent.getMetrics();
+
+// Cost
+console.log(`Estimated USD: ${m?.estimatedCostUSD ?? 0}`);
+
+// Tokens
+console.log(`Prompt: ${m?.tokens?.promptTokens}, Completion: ${m?.tokens?.completionTokens}, Total: ${m?.tokens?.totalTokens}`);
+
+// Request stats
+console.log(`Requests: ${m?.requests?.totalRequests}, Errors: ${m?.requests?.totalErrors}`);
+
+// Function calls
+console.log(`Function calls: ${m?.functions?.totalFunctionCalls}`);
+if (m?.functions?.details) {
+  for (const fn of m.functions.details) {
+    console.log(`  ${fn.name}: ${fn.calls} calls, ${fn.totalLatencyMs}ms`);
+  }
+}
+```
+
+## Do Not Generate
+
+- Do NOT call `getMetrics()` on the crew object -- use `crew.getCrewMetrics()` for crew-level and `agent.getMetrics()` for per-agent.
+- Do NOT confuse `resetCosts()` with `resetCrewMetrics()` -- `resetCosts()` is broader (resets agent usage too).
+- Do NOT expect `getMetrics()` to return cost data from the legacy `getUsage()` / `getCosts()` API -- those are separate.
+- Do NOT assume `functions.details` is always present -- it is `undefined` when no function calls have been made.
+- Do NOT forget that `estimatedCostUSD` is an estimate based on tracked token counts and model pricing.
+
+## References
+
+- [basic-researcher-writer.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/basic-researcher-writer.ts)
+- [rlm-long-task.ts example](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/rlm-long-task.ts)
+- [Source: MetricsSnapshot type](https://github.com/amitdeshmukh/ax-crew/blob/main/src/metrics/types.ts)
+- [Source: MetricsRegistry](https://github.com/amitdeshmukh/ax-crew/blob/main/src/metrics/registry.ts)