@ariaflowagents/core 0.7.1 → 0.8.1

package/guides/AGENTS.md

@@ -0,0 +1,173 @@
+# Agents Guide
+
+Agent primitives in AriaFlow: LLMAgent, FlowAgent, TriageAgent, CompositeAgent.
+
+## Agent Types
+
+### LLMAgent
+Standard LLM-based agent with tools and system prompt. Good for free-form conversation.
+
+```ts
+const agent: LLMAgentConfig = {
+  id: 'my-agent',
+  type: 'llm',
+  systemPrompt: 'You are a helpful assistant.',
+  model: openai('gpt-4o'),
+  tools: { myTool },
+};
+```
+
+### FlowAgent
+Node-based agent with defined flow graph and state management. Good for structured, multi-step processes.
+
+```ts
+const agent: FlowAgentConfig = {
+  id: 'my-flow',
+  type: 'flow',
+  flow: {
+    nodes: [
+      { id: 'start', prompt: '...' },
+      { id: 'collect_info', prompt: '...' },
+    ],
+  },
+  initialNode: 'start',
+  model: openai('gpt-4o'),
+  tools: { myTool },
+};
+```
+
+### TriageAgent
+Routes user input to appropriate agent based on conditions or LLM classification.
+
+```ts
+const agent: TriageAgentConfig = {
+  id: 'triage',
+  type: 'triage',
+  routes: [
+    { agentId: 'sales', condition: 'sales-related' },
+    { agentId: 'support', condition: 'support-related' },
+  ],
+  model: openai('gpt-4o'),
+};
+```
+
+### CompositeAgent
+Orchestrates multiple agents in sequence or parallel with coordination logic.
+
+```ts
+const agent: CompositeAgentConfig = {
+  id: 'composite',
+  type: 'composite',
+  agents: ['agent1', 'agent2', 'agent3'],
+  orchestration: 'sequential', // or 'parallel'
+  model: openai('gpt-4o'),
+};
+```
+
+## Agent-to-Agent Consultation
+
+Use `runtime.runAgent()` to have one agent consult another directly, enabling **team collaboration**.
+
+### Pattern
+
+```ts
+// Specialist agents
+const weatherAgent = {
+  id: 'weather',
+  type: 'llm',
+  systemPrompt: 'You are a weather expert.',
+  model,
+};
+
+const newsAgent = {
+  id: 'news',
+  type: 'llm',
+  systemPrompt: 'You are a news expert.',
+  model,
+};
+
+// Lead agent with consultation tools
+const leadAgent = {
+  id: 'lead',
+  type: 'llm',
+  systemPrompt: 'You have access to weather and news specialists.',
+  model,
+  tools: {
+    consult_weather: createTool({
+      description: 'Consult Weather Specialist',
+      inputSchema: z.object({ query: z.string() }),
+      execute: async (input, options?: ToolExecutionOptions) => {
+        const { runtime } = options.experimental_context;
+        if (!runtime) throw new Error('Runtime required in tool context');
+        
+        let result = '';
+        for await (const part of runtime.runAgent('weather', input, options.sessionId)) {
+          if (part.type === 'text-delta') result += part.text;
+        }
+        
+        return result;
+      },
+    }),
+  },
+};
+
+// Runtime orchestrates everything
+const runtime = new Runtime({
+  agents: [leadAgent, weatherAgent, newsAgent],
+  defaultModel: model,
+  ctaConfig: { enabled: false }, // Disable CTA for direct agent control
+});
+```
+
+### How It Works
+
+1. **User talks to**: Lead agent
+2. **Lead calls**: `consult_weather` tool
+3. **Tool receives**: `runtime` via `experimental_context.runtime`
+4. **Tool executes**: `runtime.runAgent('weather', query, sessionId)`
+5. **Specialist responds**: Weather agent processes request
+6. **Result returned**: Tool result passed back to lead agent
+7. **Lead synthesizes**: Combines into ONE unified response
+
+### Benefits
+
+- ✅ **No wrappers** - Tools get runtime directly from context
+- ✅ **Type-safe** - Uses proper types (no `as any`)
+- ✅ **Session sharing** - Automatic sessionId injection
+- ✅ **Team model** - Lead orchestrates specialists as one team
+- ✅ **Single response** - Customer sees unified answer, not multiple agents
+
+### When to Use
+
+- **Team collaboration** (specialist pattern): One lead agent + multiple specialists
+- **Direct agent control**: Use `runtime.runAgent()` to run specific agents
+- **Bypass CTA**: Pass `agentId` to skip triage routing
+
+### Example
+
+See [Agent Consultation Example](../../examples/agents/agent-consultation.ts) for a full working demo.
+
+## Key Types
+
+- `ToolExecutionOptions` - Tool execution options including `experimental_context`
+- `ToolExecutionContext` - Context passed to tools (includes `runtime`)
+- `ToolExecutionContextWithRuntime` - Extended context with `runtime` field
+- `Runtime.runAgent()` - Direct method to run specific agent
+
+## Best Practices
+
+1. **Always check runtime existence**: `if (!context?.runtime) throw new Error(...)`
+2. **Use sessionId from options**: `options.sessionId` for consultation continuity
+3. **Type-safe access**: Use helper functions like `getRuntimeFromContext()`
+4. **Consultation tools should be lightweight**: Return string results, not complex objects
+5. **Lead agent combines results**: The orchestrator agent synthesizes specialist responses
+
+## Comparison to Other Patterns
+
+| Pattern | Description | CTA | Handoffs | Wrapper Functions |
+|---------|-------------|-----|-----------|------------------|
+| Agent Consultation | Tool calls runtime.runAgent() directly | Skip CTA | No handoffs | Direct runtime access |
+| Traditional Handoff | TriageAgent routes to agent | CTA | Handoffs | No runtime access to tools | N/A |
+| Wrapper Function | Custom function wraps runtime.runAgent() | May not use CTA | N/A | N/A | Boilerplate code |
+
+**Agent Consultation is the cleanest approach** - no wrappers, no handoffs, type-safe runtime access.

package/guides/README.md

@@ -9,6 +9,7 @@ Practical guides for the AriaFlow core runtime and agent primitives.
 - **[Flows](./FLOWS.md)** - Flow agents and structured conversations
 - **[Tools](./TOOLS.md)** - Tool design, execution, and AI SDK integration
 - **[Guardrails](./GUARDRAILS.md)** - Stop conditions, enforcement rules, processors, redaction
+- **[Agents](./AGENTS.md)** - Agent types, consultation patterns, and team collaboration
 - **[Example Verification](./EXAMPLE_VERIFICATION.md)** - Latest example sweep results and known prerequisites
 
 ## Examples
@@ -16,3 +17,14 @@ Practical guides for the AriaFlow core runtime and agent primitives.
 - `examples/` for runnable demos
 - `examples/flows/` for Pipecat flow parity examples
 - `examples/agents/` for Line example parity agents and integrations
+
+### New in This Version
+
+**Agent-to-Agent Consultation** (see AGENTS.md): Enables team collaboration where a lead agent can consult specialist agents directly using `runtime.runAgent()`. This pattern supports:
+
+- Lead agent orchestration
+- Direct specialist consultation
+- Type-safe runtime access
+- Single unified customer response
+
+See [agent-consultation](../examples/agents/agent-consultation.ts) for a complete example.

package/guides/TOOLS.md

@@ -32,41 +32,107 @@ const lookup = createToolWithFiller({
 });
 ```
 
-## Tool Execution Context
+## Agent-to-Agent Consultation
 
-AI SDK passes `ToolExecutionOptions` into `execute`:
-- `toolCallId`
-- `messages`
-- `abortSignal`
-- `experimental_context`
+Use `runtime.runAgent()` to have one agent consult another directly, without CTA routing or wrapper functions.
 
-AriaFlow preserves these options so advanced tools can use them directly.
-Runtime also injects:
-- `experimental_context.idempotencyKey` (stable per session/step/toolCall)
-- `experimental_context.sessionId`
-- `experimental_context.agentId`
+### Why This Matters
+
+- **Team Model**: Lead agent orchestrates, specialists provide domain expertise
+- **Single Response**: Customer sees ONE unified answer from lead agent
+- **Type-Safe**: No `as any` casts needed - uses proper types
+- **Automatic Context**: Session ID injected via `experimental_context`
+
+### Basic Example
 
 ```ts
-execute: async (input, { abortSignal, toolCallId, experimental_context }) => {
-  // Use abortSignal to cancel I/O
-  // Use idempotencyKey for external writes
-  const idempotencyKey = experimental_context?.idempotencyKey;
-  return fetch(url, { signal: abortSignal });
-}
+// Define specialist agents
+const weatherAgent = {
+  id: 'weather',
+  name: 'Weather Specialist',
+  type: 'llm' as const,
+  systemPrompt: 'You are a weather expert.',
+  model,
+};
+
+const newsAgent = {
+  id: 'news',
+  name: 'News Specialist',
+  type: 'llm' as const,
+  systemPrompt: 'You are a news expert.',
+  model,
+};
+
+// Create lead agent with consultation tools
+const leadAgent = {
+  id: 'lead',
+  name: 'Lead Agent',
+  type: 'llm' as const,
+  systemPrompt: 'You have access to weather and news specialists.',
+  model,
+  tools: {
+    consult_weather: createTool({
+      description: 'Consult Weather Specialist',
+      inputSchema: z.object({ query: z.string() }),
+      execute: async (input, options?: ToolExecutionOptions) => {
+        const { runtime } = options.experimental_context;
+        if (!runtime) throw new Error('Runtime required in tool context');
+        
+        let result = '';
+        for await (const part of runtime.runAgent('weather', input, options.sessionId)) {
+          if (part.type === 'text-delta') result += part.text;
+        }
+        
+        return result;
+      },
+    }),
+  },
+};
+
+// Runtime handles orchestration
+const runtime = new Runtime({
+  agents: [leadAgent, weatherAgent, newsAgent],
+  defaultModel: model,
+  ctaConfig: { enabled: false },
+});
+
+// Usage: Lead agent consults specialists
+const response = await runtime.stream({ input: 'What is the weather today?' });
+// Internally: consult_weather tool calls runtime.runAgent('weather', query)
+// Weather agent responds, result returned to lead
+// Lead combines into: "The weather is sunny, 72°F."
 ```
 
-## Tools in Flows
+### How It Works
 
-In flows, tools should return transitions:
+1. **User asks**: Lead agent
+2. **Tool executes**: `consult_weather` tool
+3. **Runtime available**: Tool receives `runtime` via `experimental_context.runtime`
+4. **Direct consultation**: Tool calls `runtime.runAgent('weather', input, sessionId)`
+5. **Session preserved**: Same session ID flows through consultation
+6. **Specialist responds**: Weather agent processes request
+7. **Result returned**: Tool result passed back to lead agent
+8. **Unified answer**: Lead agent synthesizes and delivers ONE response
 
-```ts
-import { createFlowTransition } from '@ariaflowagents/core';
+### Key Features
 
-execute: async ({ date }) => createFlowTransition('next_node', { date })
-```
+- ✅ **No wrapper functions** - Tools get runtime directly from context
+- ✅ **Type-safe** - Uses `ToolExecutionOptions` and `ToolExecutionContext`
+- ✅ **Session sharing** - Automatic sessionId injection
+- ✅ **Clean consultation** - Direct agent-to-agent execution path
+- ✅ **Team collaboration** - Multiple agents can work together
+
+### When to Use
+
+- When you need **one agent to consult another** (specialist pattern)
+- When you want **team collaboration** (lead agent + specialists)
+- When you need **direct agent control** (skip CTA entirely)
+
+### When NOT to Use
+
+- Simple tool-to-API calls (use `createTool()` directly)
+- Handoffs/CTA (use handoffs for routing instead)
+- Wrapper functions around tools
 
-## Security Notes
+See [Agent Consultation Example](../../examples/agents/agent-consultation.ts) for a full working demo.
 
-- Treat tool args/results as sensitive.
-- Avoid returning secrets in tool results.
-- If you forward tool events to a UI or webhook, filter them first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ariaflowagents/core",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -53,6 +53,14 @@
     "./types": {
       "types": "./dist/types/index.d.ts",
       "default": "./dist/types/index.js"
+    },
+    "./memory": {
+      "types": "./dist/memory/index.d.ts",
+      "default": "./dist/memory/index.js"
+    },
+    "./foundation": {
+      "types": "./dist/foundation/index.d.ts",
+      "default": "./dist/foundation/index.js"
     }
   },
   "peerDependencies": {
@@ -63,7 +71,6 @@
     "@ai-sdk/openai": "^3.0.0",
     "@types/node": "^20.11.0",
     "ai": "^6.0.0",
-    "chrono-node": "^2.6.0",
     "dotenv": "^16.4.0",
     "tsx": "^4.7.0",
     "typescript": "^5.3.0",
@@ -73,9 +80,10 @@
     "build": "tsc -p tsconfig.json",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run clean && npm run build",
-    "test": "npm run build && node --test test/*.test.js"
+    "test": "npm run build && node --test test/*.test.js test/**/*.test.js"
   },
   "dependencies": {
-    "@ariaflowagents/config": "^0.7.0"
+    "@ariaflowagents/config": "^0.8.0",
+    "chrono-node": "^2.6.0"
   }
 }

package/dist/agents/LLMAgent.d.ts

@@ -1,11 +0,0 @@
-import { type ToolSet } from 'ai';
-import { Agent } from './Agent.js';
-import type { AgentContext, AgentStreamPart, LLMAgentConfig } from '../types/index.js';
-export declare class LLMAgent extends Agent<LLMAgentConfig> {
-    private model;
-    private tools;
-    constructor(config: LLMAgentConfig);
-    process(_input: string, context: AgentContext): AsyncGenerator<AgentStreamPart>;
-    protected getToolsForContext(_context: AgentContext): ToolSet;
-}
-//# sourceMappingURL=LLMAgent.d.ts.map

package/dist/agents/LLMAgent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"LLMAgent.d.ts","sourceRoot":"","sources":["../../src/agents/LLMAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAIvF,qBAAa,QAAS,SAAQ,KAAK,CAAC,cAAc,CAAC;IACjD,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,KAAK,CAAU;gBAEX,MAAM,EAAE,cAAc;IAS3B,OAAO,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,YAAY,GACpB,cAAc,CAAC,eAAe,CAAC;IAgBlC,SAAS,CAAC,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO;CAG9D"}

package/dist/agents/LLMAgent.js

@@ -1,31 +0,0 @@
-import { streamText } from 'ai';
-import { Agent } from './Agent.js';
-import { processAIStream } from '../utils/aiStream.js';
-export class LLMAgent extends Agent {
-    model;
-    tools;
-    constructor(config) {
-        super(config);
-        if (!config.model) {
-            throw new Error(`LLMAgent "${config.id}" requires a model`);
-        }
-        this.model = config.model;
-        this.tools = config.tools ?? {};
-    }
-    async *process(_input, context) {
-        const systemPrompt = this.buildSystemPrompt(context);
-        const result = streamText({
-            model: this.model,
-            system: systemPrompt,
-            messages: context.messages,
-            tools: this.getToolsForContext(context),
-            abortSignal: context.abortSignal,
-        });
-        yield* processAIStream(result.fullStream);
-        yield { type: 'turn-end', metadata: { response: await result.response } };
-    }
-    getToolsForContext(_context) {
-        return this.tools;
-    }
-}
-//# sourceMappingURL=LLMAgent.js.map

package/dist/agents/LLMAgent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"LLMAgent.js","sourceRoot":"","sources":["../../src/agents/LLMAgent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAoC,MAAM,IAAI,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAGnC,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,MAAM,OAAO,QAAS,SAAQ,KAAqB;IACzC,KAAK,CAAgB;IACrB,KAAK,CAAU;IAEvB,YAAY,MAAsB;QAChC,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,aAAa,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,CAAC;IAED,KAAK,CAAC,CAAC,OAAO,CACZ,MAAc,EACd,OAAqB;QAErB,MAAM,YAAY,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAErD,MAAM,MAAM,GAAG,UAAU,CAAC;YACxB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,YAAY;YACpB,QAAQ,EAAE,OAAO,CAAC,QAAe;YACjC,KAAK,EAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAS;YAChD,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;QAEH,KAAK,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAE1C,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;IAC5E,CAAC;IAES,kBAAkB,CAAC,QAAsB;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;CACF"}