@amitdeshmukh/ax-crew 4.0.1 → 4.1.2

package/CHANGELOG.md

@@ -1,4 +1,23 @@
 # Changelog
+## [4.1.2] - 2025-10-14
+
+### Added
+- Azure OpenAI provider key support via `AZURE_OPENAI_API_KEY`.
+- Documentation: README Environment now lists Azure and includes a minimal Azure config example (`provider: "azure-openai"` + `apiURL`).
+
+### Changed
+- TypeScript config now includes Node types (`types: ["node"]`) to resolve `process` usage in `src/config/index.ts`.
+
+## [4.1.0] - 2025-08-25
+
+### Added
+- Agent persona support via `definition` with validation (>= 100 chars).
+- `prompt` alias for persona; `definition` takes precedence when both provided.
+
+### Changed
+- README updated to document `definition`/`prompt` usage with example.
+- Example `examples/mcp-agent.ts` demonstrates `prompt` in agent config.
+
 ## [4.0.1] - 2025-08-24
 
 ### Added

package/README.md

@@ -1,20 +1,18 @@
 ![image](axcrew.png)
 
-# AxCrew - A Crew of AI Agents (built with AxLLM)
+### AxCrew — build a crew of AI agents with shared state (powered by AxLLM)
 
-This repo simplifies development of [AxLLM](https://axllm.dev) AI Agents by using config to instantiate agents. This means you can write a library of functions, and quickly invoke AI agents to use them using a simple configuration file.
+AxCrew lets you define a team of AI agents in config and run them together with shared state, tools, streaming, MCP, and built‑in metrics/cost tracking. Bring your own functions or use the provided registry.
 
-## Features
-- **Crew Configuration**: Define a crew of agents in a JSON file. (see [agentConfig.json](agentConfig.json) as an example)
-- **State Management**: Share state across agents in a crew, as well as with functions used by those agents.
-- **Task Execution**: Plan and execute tasks using agents in the crew.
-- **Streaming Support**: Stream agent responses in real-time for better user experience and faster feedback.
-- **Model Context Protocol (MCP)**: Support for MCP to allow agents to use MCP servers.
-- **Metrics and Cost Tracking**: Built-in per-agent and per-crew metrics, including token usage and estimated USD costs (5-decimal rounding).
+### Why AxCrew
+- **Config-first crews**: Declare agents once; instantiate on demand.
+- **Shared state**: Simple key/value state all agents can read/write.
+- **Sub‑agents and tools**: Compose agents and functions cleanly.
+- **Streaming**: Real‑time token streaming for responsive UX.
+- **MCP**: Connect agents to MCP servers (STDIO, HTTP SSE, Streamable HTTP).
+- **Metrics & costs**: Per‑agent and crew snapshots, with estimated USD.
 
-## Getting Started
-
-### Installation
+### Install
 Install this package:
 ```bash
 npm install @amitdeshmukh/ax-crew
@@ -22,11 +20,41 @@ npm install @amitdeshmukh/ax-crew
 AxLLM is a peer dependency, so you will need to install it separately. 
 
 ```bash
-npm install @ax-llm/ax
+npm install @ax-llm/ax @ax-llm/ax-tools
+```
+
+Requirements: Node.js >= 21.
+
+### Environment
+Set provider keys in your environment. Example `.env`:
+```bash
+GEMINI_API_KEY=...
+ANTHROPIC_API_KEY=...
+OPENAI_API_KEY=...
+AZURE_OPENAI_API_KEY=...
+```
+In each agent config, set `providerKeyName` to the env var name.
+
+#### Azure OpenAI
+- Use provider `azure-openai`.
+- Set `providerKeyName` to `AZURE_OPENAI_API_KEY`.
+- Set `apiURL` to your Azure endpoint (e.g., `https://your-resource.openai.azure.com`).
+
+Minimal example agent config:
+```json
+{
+  "name": "Writer",
+  "description": "Writes concise summaries",
+  "signature": "topic:string -> summary:string",
+  "provider": "azure-openai",
+  "providerKeyName": "AZURE_OPENAI_API_KEY",
+  "ai": { "model": "gpt-4o-mini", "temperature": 0 },
+  "apiURL": "https://your-resource.openai.azure.com"
+}
 ```
 
-### TypeScript Support
-This package includes TypeScript declarations and provides full type safety. Here's how to use it with TypeScript:
+### Quickstart
+This package includes TypeScript declarations and provides type safety.
 
 ```typescript
 import { AxCrew, AxCrewFunctions, FunctionRegistryType, StateInstance } from '@amitdeshmukh/ax-crew';
@@ -82,12 +110,10 @@ crew.state.set('key', 'value');
 const value: string = crew.state.get('key');
 
 // Add agents to the crew
-const agents = crew.addAgentsToCrew(['Planner']);
-const planner = agents?.get('Planner');
+await crew.addAgentsToCrew(['Planner']);
+const planner = crew.agents?.get('Planner');
 
 if (planner) {
-  // Agent usage with function overloads
-  // Direct usage - AI config from agent construction is used
   const response = await planner.forward({ task: "Plan something" });
   
   // Sub-agent usage - when used by another agent (AI is ignored and agent's own config is used)
@@ -109,8 +135,14 @@ Key TypeScript features:
 - Comprehensive type safety for agent operations and responses
 - Usage cost tracking with proper types
 
-### Environment Setup
-Refer to the [.env.example](.env.example) file for the required environment variables. These will need to be set in the environment where the agents are run.
+### Concepts at a glance
+- **Agent**: An LLM program with a `signature`, `provider`, `ai` model config, optional `examples`, and optional `mcpServers`.
+- **Sub‑agents**: List other agent names in `agents` to compose behaviors.
+- **Functions (tools)**: Register callable functions via a registry and reference by name in agent `functions`.
+- **State**: `crew.state.set/get/getAll()` shared across all agents.
+- **Persona**: Use `definition` (preferred) or `prompt` to set the system program. If both are present, `definition` wins.
+- **Streaming**: Use `streamingForward()` for token streams.
+- **Metrics**: Per‑agent `getMetrics()` + crew‑level `getCrewMetrics()` snapshots.
 
 ## Usage
 
@@ -174,6 +206,25 @@ Both methods support the same configuration structure and options. Choose the on
   - Modify configurations at runtime
   - Keep everything in one file for simpler projects
 
+### Agent Persona: definition and prompt
+
+- **definition**: Detailed persona/program description used as the system prompt. Recommended for precise control. Must be at least 100 characters.
+- **prompt**: An alias for `definition`. If both are provided, **definition** takes precedence.
+
+Add either field to any agent config. The chosen value becomes the Ax agent's underlying program description (system prompt).
+
+```json
+{
+  "name": "Planner",
+  "description": "Creates a plan to complete a task",
+  "prompt": "You are a meticulous planning assistant. Produce concise, executable step-by-step plans with clear justifications, constraints, and assumptions. Prefer brevity, avoid fluff, and ask for missing critical details before proceeding when necessary.",
+  "signature": "task:string -> plan:string",
+  "provider": "google-gemini",
+  "providerKeyName": "GEMINI_API_KEY",
+  "ai": { "model": "gemini-1.5-flash", "temperature": 0 }
+}
+```
+
 ### Agent Examples
 You can provide examples to guide the behavior of your agents using the `examples` field in the agent configuration. Examples help the agent understand the expected input/output format and improve its responses.
 

package/dist/agents/agentConfig.d.ts

@@ -29,6 +29,7 @@ declare const parseAgentConfig: (agentName: string, crewConfig: CrewConfigInput,
     ai: import("@ax-llm/ax").AxAI<string>;
     name: string;
     description: string;
+    definition: any;
     signature: string | import("@ax-llm/ax").AxSignature<Record<string, any>, Record<string, any>>;
     functions: AxFunction[];
     subAgentNames: string[];

package/dist/agents/agentConfig.js

@@ -192,7 +192,7 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
             throw new Error(`Provider key name is missing in the agent configuration`);
         }
         // Create a cost tracker instance and pass to ai()
-        const costTracker = new AxDefaultCostTracker();
+        const costTracker = new AxDefaultCostTracker((agentConfigData.options?.costTracking) || undefined);
         // Create an instance of the AI agent via factory
         const aiArgs = {
             name: provider,
@@ -238,6 +238,7 @@ const parseAgentConfig = async (agentName, crewConfig, functions, state) => {
             ai: aiInstance,
             name: agentName,
             description: agentConfigData.description,
+            definition: agentConfigData.definition ?? agentConfigData.prompt,
             signature: agentConfigData.signature,
             functions: agentFunctions,
             subAgentNames: agentConfigData.agents || [],

package/dist/agents/index.d.ts

@@ -12,6 +12,7 @@ declare class StatefulAxAgent extends AxAgent<any, any> {
     constructor(ai: AxAI, options: Readonly<{
         name: string;
         description: string;
+        definition?: string;
         signature: string | AxSignature;
         agents?: AxAgentic<any, any>[] | undefined;
         functions?: (AxFunction | (() => AxFunction))[] | undefined;

package/dist/agents/index.js

@@ -244,6 +244,7 @@ class AxCrew {
             const agent = new StatefulAxAgent(ai, {
                 name,
                 description,
+                definition: agentConfig.definition,
                 signature,
                 functions: uniqueFunctions,
                 agents: uniqueSubAgents,

package/dist/config/index.js

@@ -3,6 +3,7 @@ dotenv.config();
 // AI API keys
 const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+const AZURE_OPENAI_API_KEY = process.env.AZURE_OPENAI_API_KEY;
 const COHERE_API_KEY = process.env.COHERE_API_KEY;
 const DEEPSEEK_API_KEY = process.env.DEEPSEEK_API_KEY;
 const GEMINI_API_KEY = process.env.GEMINI_API_KEY;
@@ -16,6 +17,7 @@ const PROVIDER_API_KEYS = {
     COHERE_API_KEY,
     GEMINI_API_KEY,
     OPENAI_API_KEY,
+    AZURE_OPENAI_API_KEY,
     ANTHROPIC_API_KEY,
     DEEPSEEK_API_KEY,
     GROQ_API_KEY,

package/dist/types.d.ts

@@ -147,6 +147,16 @@ type MCPTransportConfig = MCPStdioTransportConfig | MCPHTTPSSETransportConfig |
 interface AgentConfig {
     name: string;
     description: string;
+    /**
+     * Optional detailed persona/program definition. If provided, becomes the system prompt.
+     * Must be at least 100 characters per Ax semantics.
+     */
+    definition?: string;
+    /**
+     * Optional alias for definition for clarity. If provided and definition is omitted,
+     * this will be used as the program definition/system prompt.
+     */
+    prompt?: string;
     signature: string | AxSignature;
     provider: Provider;
     providerKeyName?: string;

package/examples/mcp-agent.ts

@@ -1,15 +1,15 @@
-import { AxCrew } from "../dist/index.js";
-import type { AxCrewConfig } from "../dist/index.js";
+import { AxCrew, AxCrewConfig } from "../dist/index.js";
 
 import dotenv from "dotenv";
 dotenv.config();
 
 // Define the crew configuration
-const config: AxCrewConfig = {
+const config = {
   crew: [
     {
       name: "MapsAgent",
       description: "A specialized agent with access to Google Maps APIs that can: geocode addresses to coordinates and vice versa, search for and get details about places, calculate travel distances and times between multiple locations, provide elevation data, and generate navigation directions between points.",
+      prompt: "You are a precise geospatial assistant with expert knowledge of Google Maps APIs. Answer user queries by combining place search, geocoding, distance matrix, elevation, and directions. Provide concise, actionable answers, include travel mode assumptions, and cite uncertainties. When location is ambiguous, ask a brief clarifying question before proceeding.",
       signature: 'userQuery:string "a question to be answered" -> answer:string "the answer to the question"',
       provider: "anthropic",
       providerKeyName: "ANTHROPIC_API_KEY",
@@ -38,6 +38,7 @@ const config: AxCrewConfig = {
     {
       name: "ManagerAgent",
       description: "Completes a user specified task",
+      prompt: "You are a manager agent that orchestrates tools and sub-agents. Read the user's objective, optionally produce a short plan, then call the MapsAgent when geospatial knowledge is needed. Keep answers direct and avoid extraneous commentary.",
       signature:
         'question:string "a question to be answered" -> answer:string "the answer to the question"',
       provider: "openai", 
@@ -73,7 +74,7 @@ const config: AxCrewConfig = {
 };
 
 // Create a new instance of AxCrew with the config
-const crew = new AxCrew(config);
+const crew = new AxCrew(config as AxCrewConfig);
 
 // Add the agents to the crew
 await crew.addAllAgents();

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@amitdeshmukh/ax-crew",
-  "version": "4.0.1",
+  "version": "4.1.2",
   "description": "Build and launch a crew of AI agents with shared state. Built with axllm.dev",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -30,7 +30,7 @@
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
     "@types/big.js": "^6.2.2",
-    "@types/node": "^20.14.9",
+    "@types/node": "^20.19.21",
     "@types/uuid": "^10.0.0",
     "@vitest/coverage-v8": "^3.0.9",
     "@vitest/ui": "^3.0.9",

package/src/agents/agentConfig.ts

@@ -224,7 +224,7 @@ const parseAgentConfig = async (
     }
 
     // Create a cost tracker instance and pass to ai()
-    const costTracker = new AxDefaultCostTracker();
+    const costTracker = new AxDefaultCostTracker(((agentConfigData as any).options?.costTracking) || undefined);
 
     // Create an instance of the AI agent via factory
     const aiArgs: any = {
@@ -273,6 +273,7 @@ const parseAgentConfig = async (
       ai: aiInstance,
       name: agentName,
       description: agentConfigData.description,
+      definition: (agentConfigData as any).definition ?? (agentConfigData as any).prompt,
       signature: agentConfigData.signature,
       functions: agentFunctions,
       subAgentNames: agentConfigData.agents || [],

package/src/agents/index.ts

@@ -27,6 +27,7 @@ interface ParsedAgentConfig {
   ai: AxAI;
   name: string;
   description: string;
+  definition?: string;
   signature: string | AxSignature;
   functions: (
     | AxFunction
@@ -58,6 +59,7 @@ class StatefulAxAgent extends AxAgent<any, any> {
     options: Readonly<{
       name: string;
       description: string;
+      definition?: string;
       signature: string | AxSignature;
       agents?: AxAgentic<any, any>[] | undefined;
       functions?: (AxFunction | (() => AxFunction))[] | undefined;
@@ -347,6 +349,7 @@ class AxCrew {
         {
           name,
           description,
+          definition: (agentConfig as any).definition,
           signature,
           functions: uniqueFunctions,
           agents: uniqueSubAgents,

package/src/config/index.ts

@@ -4,6 +4,7 @@ dotenv.config();
 // AI API keys
 const ANTHROPIC_API_KEY: string | undefined = process.env.ANTHROPIC_API_KEY;
 const OPENAI_API_KEY: string | undefined = process.env.OPENAI_API_KEY;
+const AZURE_OPENAI_API_KEY: string | undefined = process.env.AZURE_OPENAI_API_KEY;
 const COHERE_API_KEY: string | undefined = process.env.COHERE_API_KEY;
 const DEEPSEEK_API_KEY: string | undefined = process.env.DEEPSEEK_API_KEY;
 const GEMINI_API_KEY: string | undefined = process.env.GEMINI_API_KEY;
@@ -23,6 +24,7 @@ const PROVIDER_API_KEYS: ProviderApiKeys = {
   COHERE_API_KEY,
   GEMINI_API_KEY,
   OPENAI_API_KEY,
+  AZURE_OPENAI_API_KEY,
   ANTHROPIC_API_KEY,
   DEEPSEEK_API_KEY,
   GROQ_API_KEY,

package/src/types.ts

@@ -180,6 +180,16 @@ type MCPTransportConfig = MCPStdioTransportConfig | MCPHTTPSSETransportConfig |
 interface AgentConfig {
   name: string;
   description: string;
+  /**
+   * Optional detailed persona/program definition. If provided, becomes the system prompt.
+   * Must be at least 100 characters per Ax semantics.
+   */
+  definition?: string;
+  /**
+   * Optional alias for definition for clarity. If provided and definition is omitted,
+   * this will be used as the program definition/system prompt.
+   */
+  prompt?: string;
   signature: string | AxSignature;
   provider: Provider;
   providerKeyName?: string;

package/tsconfig.json

@@ -13,7 +13,8 @@
     "rootDir": "./src",
     "allowJs": true,
     "resolveJsonModule": true,
-    "typeRoots": ["./node_modules/@types", "./types"]
+    "typeRoots": ["./node_modules/@types", "./types"],
+    "types": ["node"]
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "**/*.spec.ts"]