@amitdeshmukh/ax-crew 8.5.0 → 8.7.0

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)

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

@@ -0,0 +1,286 @@
+---
+name: ax-crew-patterns
+version: __VERSION__
+description: "AxCrew multi-agent patterns: pipeline, delegation, fan-out, orchestrator, sequential workflows, and agent coordination."
+tags: [patterns, workflow, pipeline, multi-agent, orchestrator, delegation, sequential, fan-out]
+---
+
+# Multi-Agent Patterns
+
+## Pipeline Pattern (A -> B -> C)
+
+Sequential agent calls where each agent's output feeds the next. Each agent is independent -- the orchestration happens in your code.
+
+```ts
+import { AxCrew } from "ax-crew";
+import type { AxCrewConfig, Provider } from "ax-crew";
+
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "Planner",
+      description: "Generates search queries for a topic",
+      signature: 'topic:string, guidance:string -> queries:string[]',
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 1 },
+    },
+    {
+      name: "Searcher",
+      description: "Searches the web for a query",
+      signature: 'query:string -> searchResult:string',
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-1.5-pro", temperature: 0.5 },
+      options: {
+        googleSearchRetrieval: { mode: "MODE_UNSPECIFIED" },
+      },
+    },
+    {
+      name: "Writer",
+      description: "Writes a blog post from research",
+      signature: 'topic:string, guidance:string, searchResults:string[] -> title:string, content:string',
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 1 },
+    },
+    {
+      name: "Publisher",
+      description: "Publishes a post to WordPress",
+      signature: 'title:string, content:string, status:string -> postResponse:string',
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 0 },
+      functions: ["WordPressPost"],
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config, customFunctions);
+  const agents = await crew.addAgentsToCrew([
+    "Planner", "Searcher", "Writer", "Publisher",
+  ]);
+
+  const planner = agents!.get("Planner")!;
+  const searcher = agents!.get("Searcher")!;
+  const writer = agents!.get("Writer")!;
+  const publisher = agents!.get("Publisher")!;
+
+  const topic = "How to tell what your dog is thinking";
+  const guidance = "Fun, engaging, under 500 words.";
+
+  // Step 1: Plan
+  const { queries } = await planner.forward({ topic, guidance });
+
+  // Step 2: Research (sequential to avoid rate limits)
+  const searchResults: string[] = [];
+  for (const query of queries) {
+    const { searchResult } = await searcher.forward({ query });
+    searchResults.push(searchResult);
+  }
+
+  // Step 3: Write
+  const { title, content } = await writer.forward({ topic, guidance, searchResults });
+
+  // Step 4: Publish
+  const { postResponse } = await publisher.forward({ title, content, status: "draft" });
+  console.log(postResponse);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## Delegation Pattern (Sub-Agents)
+
+Use `agents[]` in config to give one agent access to other agents as tools. The parent agent decides when to delegate. Sub-agents must be added to the crew **before** the parent.
+
+```ts
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "MathAgent",
+      description: "Solves math problems using Python code execution",
+      signature: 'mathProblem:string -> solution:string',
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", temperature: 0 },
+      options: { codeExecution: true },
+    },
+    {
+      name: "ManagerAgent",
+      description: "Answers questions, delegating math to MathAgent",
+      signature: 'question:string -> answer:string',
+      provider: "google-gemini" as Provider,
+      providerKeyName: "GEMINI_API_KEY",
+      ai: { model: "gemini-2.5-flash-lite", maxTokens: 1000, temperature: 0 },
+      agents: ["MathAgent"],  // <-- delegation
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+
+  // Order matters: sub-agents first, then parent
+  await crew.addAgentsToCrew(["MathAgent"]);
+  await crew.addAgentsToCrew(["ManagerAgent"]);
+
+  const manager = crew.agents!.get("ManagerAgent")!;
+  const result = await manager.forward({
+    question: "What is the 7th root of 1955?",
+  });
+  console.log(result.answer);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+Note: `addAgentsToCrew(["MathAgent", "ManagerAgent"])` also works -- it resolves dependencies automatically.
+
+## Fan-Out Pattern (Parallel Agents)
+
+Run multiple agents concurrently with `Promise.all`:
+
+```ts
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAllAgents();
+
+  const analyst = crew.agents!.get("Analyst")!;
+  const reviewer = crew.agents!.get("Reviewer")!;
+  const factChecker = crew.agents!.get("FactChecker")!;
+
+  const input = { document: "..." };
+
+  // Fan-out: run all three in parallel
+  const [analysis, review, facts] = await Promise.all([
+    analyst.forward(input),
+    reviewer.forward(input),
+    factChecker.forward(input),
+  ]);
+
+  // Merge results downstream
+  const synthesizer = crew.agents!.get("Synthesizer")!;
+  const final = await synthesizer.forward({
+    analysis: analysis.result,
+    review: review.result,
+    facts: facts.result,
+  });
+
+  crew.destroy();
+}
+```
+
+## Orchestrator Pattern
+
+A manager agent with multiple specialist sub-agents. The manager decides which specialist(s) to invoke based on the query.
+
+```ts
+const config: AxCrewConfig = {
+  crew: [
+    {
+      name: "CodeAgent",
+      description: "Writes and reviews code",
+      signature: "task:string -> code:string",
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 0 },
+    },
+    {
+      name: "ResearchAgent",
+      description: "Researches technical topics",
+      signature: "topic:string -> findings:string",
+      provider: "openai" as Provider,
+      providerKeyName: "OPENAI_API_KEY",
+      ai: { model: "gpt-4o", temperature: 0.5 },
+    },
+    {
+      name: "Orchestrator",
+      description: "Routes tasks to the right specialist and synthesizes results",
+      signature: "request:string -> response:string",
+      provider: "anthropic" as Provider,
+      providerKeyName: "ANTHROPIC_API_KEY",
+      ai: { model: "claude-3-5-sonnet-20240620", temperature: 0.3 },
+      agents: ["CodeAgent", "ResearchAgent"],  // can delegate to either
+    },
+  ],
+};
+
+async function main() {
+  const crew = new AxCrew(config);
+  await crew.addAgentsToCrew(["CodeAgent", "ResearchAgent", "Orchestrator"]);
+
+  const orchestrator = crew.agents!.get("Orchestrator")!;
+  const result = await orchestrator.forward({
+    request: "Research WebSocket best practices and write a TypeScript echo server",
+  });
+  console.log(result.response);
+
+  crew.destroy();
+}
+
+main().catch(console.error);
+```
+
+## definition / prompt for System Prompts
+
+Use `definition` (or its alias `prompt`) to provide a detailed system prompt. Must be at least 100 characters. If both are set, `definition` takes precedence.
+
+```ts
+{
+  name: "Writer",
+  description: "Short description (used as tool description for sub-agent delegation)",
+  definition: `You are a senior technical writer specializing in developer documentation.
+Follow the Divio documentation framework: tutorials, how-to guides, reference, explanation.
+Always include code examples. Use active voice. Keep paragraphs under 4 sentences.
+Target audience: intermediate developers familiar with TypeScript.`,
+  signature: "topic:string -> documentation:string",
+  provider: "anthropic" as Provider,
+  providerKeyName: "ANTHROPIC_API_KEY",
+  ai: { model: "claude-3-5-sonnet-20240620", temperature: 0.7 },
+}
+```
+
+## Shared State Across Agents
+
+All agents in a crew share a mutable `state` object for out-of-band data passing:
+
+```ts
+crew.state.set("env", { WORDPRESS_URL: "http://...", WORDPRESS_USERNAME: "..." });
+crew.state.set("context", { userId: "abc-123" });
+
+// Inside a custom function, state is accessible via the constructor:
+class MyTool {
+  constructor(private state: Record<string, any>) {}
+  toFunction() {
+    return {
+      name: "myTool",
+      description: "...",
+      parameters: { ... },
+      func: async () => {
+        const env = this.state.env;  // access shared state
+        // ...
+      },
+    };
+  }
+}
+```
+
+## Do Not Generate
+
+- Do NOT add a parent agent before its sub-agents -- `addAgentsToCrew` resolves dependencies but `addAgent` does not.
+- Do NOT use `agents: ["SelfName"]` -- an agent cannot be its own sub-agent (circular dependency error).
+- Do NOT assume agents share conversation context -- they share `state` but each `forward()` call is independent. Pass data explicitly via signatures.
+- Do NOT use `definition` shorter than 100 characters -- Ax requires minimum length for program definitions.
+- Do NOT confuse `description` (used as the tool description when this agent is a sub-agent) with `definition` (the system prompt).
+
+## References
+
+- [write-post-and-publish-to-wordpress.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/write-post-and-publish-to-wordpress.ts) (4-agent pipeline)
+- [solve-math-problem.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/solve-math-problem.ts) (delegation)
+- [search-tweets.ts](https://github.com/amitdeshmukh/ax-crew/blob/main/examples/search-tweets.ts) (streaming)