agentic-ai-framework 1.0.0

package/src/team/AgentTeam.js

@@ -0,0 +1,308 @@
+import { Tool } from '../tool/Tool.js';
+import { TeamResult } from './TeamResult.js';
+import { createLogger } from '../utils/logger.js';
+
+/**
+ * Coordinates multiple Agent instances in a team.
+ *
+ * Two modes:
+ *
+ *   'router' (default) — The coordinator agent has all member agents registered
+ *   as tools. It receives the user input and decides which member(s) to delegate
+ *   to. The coordinator synthesizes member results into a final answer.
+ *   This maps directly to the existing MasterAgent pattern.
+ *
+ *   'parallel' — All member agents are run simultaneously on the same user input
+ *   via Promise.all(). The coordinator receives all results and synthesizes them.
+ *   Useful when a question needs multiple specialists (e.g., SQL data + RAG docs).
+ *
+ * Usage:
+ *   const team = new AgentTeam({ coordinator, members: [sqlAgent, ragAgent], mode: 'router' });
+ *   const result = await team.run('How many tickets last month?');
+ *   console.log(result.final);
+ *
+ * Concurrency note:
+ *   Same as Agent — create a fresh AgentTeam per request (cheap, no shared state).
+ */
+export class AgentTeam {
+    /**
+     * @param {Object} options
+     * @param {import('../agent/Agent.js').Agent} options.coordinator - Orchestrating agent
+     * @param {import('../agent/Agent.js').Agent[]} [options.members=[]] - Specialist agents
+     * @param {'router' | 'parallel'} [options.mode='router']
+     */
+    constructor({ coordinator, members = [], mode = 'router' }) {
+        if (!coordinator) throw new Error('AgentTeam: coordinator is required');
+        if (!['router', 'parallel'].includes(mode)) {
+            throw new Error(`AgentTeam: mode must be 'router' or 'parallel', got "${mode}"`);
+        }
+
+        this._coordinator = coordinator;
+        this._members = new Map(); // agentName → Agent
+        this._mode = mode;
+        this._log = createLogger('AgentTeam', { coordinator: coordinator.name, mode });
+
+        for (const member of members) {
+            this.addMember(member);
+        }
+    }
+
+    // ── Member management ─────────────────────────────────────────────────────
+
+    /**
+     * Add a member agent to the team.
+     * In router mode, also registers the member as a tool on the coordinator.
+     * @param {import('../agent/Agent.js').Agent} agent
+     */
+    addMember(agent) {
+        this._members.set(agent.name, agent);
+        if (this._mode === 'router') {
+            this._registerMemberTool(agent);
+        }
+        this._log.debug({ member: agent.name }, 'member added');
+    }
+
+    /**
+     * Remove a member agent from the team.
+     * @param {string} agentName
+     */
+    removeMember(agentName) {
+        this._members.delete(agentName);
+        if (this._mode === 'router') {
+            this._coordinator.getToolRegistry().unregister(`delegate_to_${agentName}`);
+        }
+    }
+
+    /**
+     * Get all member names.
+     * @returns {string[]}
+     */
+    getMembers() {
+        return [...this._members.keys()];
+    }
+
+    // ── Tool registration (router mode) ───────────────────────────────────────
+
+    _registerMembersAsTools() {
+        for (const agent of this._members.values()) {
+            this._registerMemberTool(agent);
+        }
+    }
+
+    _registerMemberTool(agent) {
+        const toolName = `delegate_to_${agent.name}`;
+
+        // Don't register twice
+        if (this._coordinator.getToolRegistry().has(toolName)) {
+            this._coordinator.getToolRegistry().unregister(toolName);
+        }
+
+        this._coordinator.getToolRegistry().registerOrReplace(new Tool({
+            name: toolName,
+            description: agent.description
+                ? `Delegate to ${agent.name}: ${agent.description}`
+                : `Delegate this question to the ${agent.name} specialist agent`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    question: {
+                        type: 'string',
+                        description: 'The question or task to delegate to this agent',
+                    },
+                    context: {
+                        type: 'string',
+                        description: 'Optional additional context to include',
+                    },
+                },
+                required: ['question'],
+            },
+            handler: async ({ question, context }) => {
+                const input = context ? `${question}\n\nAdditional context: ${context}` : question;
+                const result = await agent.run(input, { appendToHistory: false });
+                if (!result.success) {
+                    return JSON.stringify({ _delegateError: true, error: result.error, agent: agent.name });
+                }
+                return result.text || result.content || 'No response';
+            },
+        }));
+    }
+
+    // ── Main execution ────────────────────────────────────────────────────────
+
+    /**
+     * Run the team on a user input.
+     *
+     * @param {string} userInput
+     * @param {Object} [opts={}]
+     * @param {Record<string, string>} [opts.templateVars={}] - Passed to coordinator
+     * @param {boolean} [opts.appendToHistory=false] - Whether to update coordinator history
+     * @returns {Promise<TeamResult>}
+     */
+    async run(userInput, opts = {}) {
+        const { templateVars = {}, appendToHistory = false } = opts;
+
+        this._log.info({ mode: this._mode, input: userInput.slice(0, 100) }, 'team.run()');
+
+        if (this._mode === 'router') {
+            return this._runRouter(userInput, { templateVars, appendToHistory });
+        } else {
+            return this._runParallel(userInput, { templateVars, appendToHistory });
+        }
+    }
+
+    // ── Router mode ───────────────────────────────────────────────────────────
+
+    /**
+     * Router mode: coordinator decides which member(s) to call via tool-calling.
+     * Members are already registered as tools — this is just a normal agent.run().
+     */
+    async _runRouter(userInput, { templateVars, appendToHistory }) {
+        try {
+            // Inject member list into coordinator's context for awareness
+            const memberList = [...this._members.values()]
+                .map(a => `- ${a.name}: ${a.description || 'specialist agent'}`)
+                .join('\n');
+
+            const coordinatorResult = await this._coordinator.run(userInput, {
+                templateVars: { ...templateVars, teamMembers: memberList },
+                appendToHistory,
+            });
+
+            if (!coordinatorResult.success) {
+                return TeamResult.failure(coordinatorResult.error, 'router');
+            }
+
+            // Extract per-member results from tool call history
+            const memberResults = this._extractMemberResultsFromHistory(coordinatorResult.toolCallHistory);
+
+            return new TeamResult({
+                success: true,
+                final: coordinatorResult.text || coordinatorResult.content || '',
+                memberResults,
+                coordinatorResult,
+                mode: 'router',
+            });
+
+        } catch (err) {
+            this._log.error({ err: err.message }, 'router mode failed');
+            return TeamResult.failure(err.message, 'router');
+        }
+    }
+
+    /**
+     * Extract member results keyed by agent name from the coordinator's tool call history.
+     */
+    _extractMemberResultsFromHistory(toolCallHistory = []) {
+        const memberResults = {};
+        for (const call of toolCallHistory) {
+            const match = call.name.match(/^delegate_to_(.+)$/);
+            if (match) {
+                const agentName = match[1];
+                // Detect structured error marker from the handler
+                let isError = false;
+                let resultText = typeof call.result === 'string' ? call.result : String(call.result ?? '');
+                try {
+                    const parsed = JSON.parse(resultText);
+                    if (parsed?._delegateError) {
+                        isError = true;
+                        resultText = parsed.error || resultText;
+                    }
+                } catch { /* not JSON — treat as success text */ }
+                memberResults[agentName] = {
+                    success: !isError,
+                    text: resultText,
+                    content: resultText,
+                    toolCallHistory: [],
+                };
+            }
+        }
+        return memberResults;
+    }
+
+    // ── Parallel mode ─────────────────────────────────────────────────────────
+
+    /**
+     * Parallel mode: all members run simultaneously, coordinator synthesizes.
+     */
+    async _runParallel(userInput, { templateVars, appendToHistory }) {
+        const members = [...this._members.values()];
+
+        if (members.length === 0) {
+            return TeamResult.failure('AgentTeam: no members registered', 'parallel');
+        }
+
+        // Run all members in parallel
+        const memberEntries = await Promise.all(
+            members.map(async agent => {
+                try {
+                    const result = await agent.run(userInput, { appendToHistory: false });
+                    return [agent.name, result];
+                } catch (err) {
+                    return [agent.name, {
+                        success: false,
+                        error: err.message,
+                        text: `Error: ${err.message}`,
+                        toolCallHistory: [],
+                        iterations: 0,
+                    }];
+                }
+            })
+        );
+
+        const memberResults = Object.fromEntries(memberEntries);
+
+        // Build a synthesis prompt for the coordinator
+        const memberSummaries = memberEntries.map(([name, result]) => {
+            return `### ${name}\n${result.success ? result.text : `Error: ${result.error}`}`;
+        }).join('\n\n');
+
+        const synthesisInput = `The following specialist agents have answered the user's question. Synthesize their responses into a single, comprehensive answer.
+
+User question: ${userInput}
+
+Specialist responses:
+${memberSummaries}
+
+Provide a unified answer that incorporates the most relevant information from each specialist.`;
+
+        try {
+            const coordinatorResult = await this._coordinator.run(synthesisInput, {
+                templateVars,
+                appendToHistory,
+            });
+
+            return new TeamResult({
+                success: coordinatorResult.success,
+                final: coordinatorResult.text || coordinatorResult.content || '',
+                memberResults,
+                coordinatorResult,
+                mode: 'parallel',
+                error: coordinatorResult.success ? undefined : coordinatorResult.error,
+            });
+
+        } catch (err) {
+            this._log.error({ err: err.message }, 'parallel synthesis failed');
+            // Return partial success with member results even if coordinator failed
+            return new TeamResult({
+                success: false,
+                final: '',
+                memberResults,
+                coordinatorResult: null,
+                mode: 'parallel',
+                error: `Coordinator synthesis failed: ${err.message}`,
+            });
+        }
+    }
+
+    /**
+     * Get team info.
+     * @returns {Object}
+     */
+    getInfo() {
+        return {
+            coordinator: this._coordinator.getInfo(),
+            members: [...this._members.values()].map(a => a.getInfo()),
+            mode: this._mode,
+        };
+    }
+}

package/src/team/TeamResult.js

@@ -0,0 +1,60 @@
+/**
+ * Structured result returned by AgentTeam.run().
+ *
+ * @typedef {Object} TeamResult
+ * @property {boolean} success
+ * @property {string}  final           - Final synthesized answer from coordinator
+ * @property {Object}  memberResults   - Map of agentName → AgentResult for each member
+ * @property {import('../agent/AgentRunner.js').AgentResult} coordinatorResult - Coordinator's result
+ * @property {string}  mode            - 'router' | 'parallel'
+ * @property {string}  [error]         - Present when success=false
+ */
+
+export class TeamResult {
+    /**
+     * @param {Object} data
+     * @param {boolean} data.success
+     * @param {string}  data.final
+     * @param {Record<string, Object>} data.memberResults
+     * @param {Object}  data.coordinatorResult
+     * @param {string}  data.mode
+     * @param {string}  [data.error]
+     */
+    constructor({ success, final, memberResults, coordinatorResult, mode, error }) {
+        this.success = success;
+        this.final = final ?? '';
+        this.memberResults = memberResults ?? {};
+        this.coordinatorResult = coordinatorResult ?? null;
+        this.mode = mode;
+        this.error = error ?? null;
+    }
+
+    /**
+     * Get the result for a specific team member.
+     * @param {string} agentName
+     * @returns {Object | null}
+     */
+    getMemberResult(agentName) {
+        return this.memberResults[agentName] ?? null;
+    }
+
+    /**
+     * List the names of members that successfully returned results.
+     * @returns {string[]}
+     */
+    getSuccessfulMembers() {
+        return Object.entries(this.memberResults)
+            .filter(([, result]) => result.success)
+            .map(([name]) => name);
+    }
+
+    /**
+     * Create a failure TeamResult.
+     * @param {string} error
+     * @param {string} mode
+     * @returns {TeamResult}
+     */
+    static failure(error, mode) {
+        return new TeamResult({ success: false, final: '', memberResults: {}, coordinatorResult: null, mode, error });
+    }
+}

package/src/tool/Tool.js

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { ToolError } from '../utils/errors.js';
+
+/**
+ * Wraps a tool definition (name, description, parameters) and its handler.
+ *
+ * The parameters field accepts either:
+ *   - A plain JSON Schema object: { type: 'object', properties: {...}, required: [...] }
+ *   - A Zod schema (z.object(...)): automatically converted to JSON Schema for the LLM
+ *
+ * Handler contract:
+ *   async (args: Record<string, any>) => string | object
+ *   - Receives the parsed arguments from the LLM
+ *   - Returns a string or any JSON-serializable value
+ *   - Throwing an error causes AgentRunner to report the error to the LLM as the tool result
+ */
+export class Tool {
+    /**
+     * @param {Object} definition
+     * @param {string} definition.name         - Unique tool name (snake_case recommended)
+     * @param {string} definition.description  - Description shown to the LLM
+     * @param {Object | import('zod').ZodObject<any>} [definition.parameters] - Parameter schema
+     * @param {Function} definition.handler    - async (args) => string | object
+     */
+    constructor({ name, description, parameters, handler }) {
+        if (!name || typeof name !== 'string') {
+            throw new ToolError('Tool: name must be a non-empty string');
+        }
+        if (typeof handler !== 'function') {
+            throw new ToolError(`Tool "${name}": handler must be a function`);
+        }
+
+        this.name = name;
+        this.description = description ?? '';
+        this._handler = handler;
+
+        // Normalize parameters to plain JSON Schema
+        if (parameters && typeof parameters._def !== 'undefined') {
+            // Zod schema detected — convert to JSON Schema
+            this.parameters = zodToJsonSchema(parameters);
+        } else {
+            this.parameters = parameters ?? { type: 'object', properties: {} };
+        }
+    }
+
+    /**
+     * Returns the tool definition object sent to the LLM (without the handler).
+     * @returns {{ name: string, description: string, parameters: Object }}
+     */
+    toDefinition() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: this.parameters,
+        };
+    }
+
+    /**
+     * Execute the tool with the given arguments.
+     * @param {Record<string, any>} args
+     * @returns {Promise<string | object>}
+     */
+    async execute(args) {
+        try {
+            return await this._handler(args);
+        } catch (err) {
+            throw new ToolError(`Tool "${this.name}" execution failed: ${err.message}`, {
+                cause: err,
+                toolName: this.name,
+            });
+        }
+    }
+}
+
+/**
+ * Minimal Zod → JSON Schema conversion for common types.
+ * Handles z.object(), z.string(), z.number(), z.boolean(), z.array(), z.enum().
+ * For complex schemas, pass a plain JSON Schema object instead.
+ *
+ * @param {import('zod').ZodTypeAny} zodSchema
+ * @returns {Object} JSON Schema
+ */
+function zodToJsonSchema(zodSchema) {
+    const def = zodSchema._def;
+
+    switch (def.typeName) {
+        case z.ZodFirstPartyTypeKind.ZodObject: {
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(def.shape())) {
+                properties[key] = zodToJsonSchema(value);
+                if (!(value._def.typeName === z.ZodFirstPartyTypeKind.ZodOptional)) {
+                    required.push(key);
+                }
+            }
+            const schema = { type: 'object', properties };
+            if (required.length > 0) schema.required = required;
+            if (def.description) schema.description = def.description;
+            return schema;
+        }
+        case z.ZodFirstPartyTypeKind.ZodOptional:
+            return zodToJsonSchema(def.innerType);
+        case z.ZodFirstPartyTypeKind.ZodString: {
+            const s = { type: 'string' };
+            if (def.description) s.description = def.description;
+            return s;
+        }
+        case z.ZodFirstPartyTypeKind.ZodNumber: {
+            const s = { type: 'number' };
+            if (def.description) s.description = def.description;
+            return s;
+        }
+        case z.ZodFirstPartyTypeKind.ZodBoolean: {
+            const s = { type: 'boolean' };
+            if (def.description) s.description = def.description;
+            return s;
+        }
+        case z.ZodFirstPartyTypeKind.ZodArray: {
+            const s = { type: 'array', items: zodToJsonSchema(def.type) };
+            if (def.description) s.description = def.description;
+            return s;
+        }
+        case z.ZodFirstPartyTypeKind.ZodEnum: {
+            const s = { type: 'string', enum: def.values };
+            if (def.description) s.description = def.description;
+            return s;
+        }
+        case z.ZodFirstPartyTypeKind.ZodNullable:
+            return zodToJsonSchema(def.innerType);
+        case z.ZodFirstPartyTypeKind.ZodDefault:
+            return zodToJsonSchema(def.innerType);
+        default:
+            throw new ToolError(
+                `zodToJsonSchema: unsupported Zod type "${def.typeName}". ` +
+                'Use a plain JSON Schema object for complex types.'
+            );
+    }
+}

package/src/tool/ToolRegistry.js

@@ -0,0 +1,81 @@
+import { ToolError } from '../utils/errors.js';
+
+/**
+ * Manages a collection of Tool instances.
+ * Provides registration, lookup, definition export, and execution.
+ */
+export class ToolRegistry {
+    constructor() {
+        this._tools = new Map(); // name → Tool
+    }
+
+    /**
+     * Register a tool. Throws if a tool with the same name already exists.
+     * @param {import('./Tool.js').Tool} tool
+     */
+    register(tool) {
+        if (this._tools.has(tool.name)) {
+            throw new ToolError(`Tool "${tool.name}" is already registered`);
+        }
+        this._tools.set(tool.name, tool);
+    }
+
+    /**
+     * Register or replace a tool by name.
+     * @param {import('./Tool.js').Tool} tool
+     */
+    registerOrReplace(tool) {
+        this._tools.set(tool.name, tool);
+    }
+
+    /**
+     * Remove a tool by name.
+     * @param {string} name
+     */
+    unregister(name) {
+        this._tools.delete(name);
+    }
+
+    /**
+     * Get tool definitions to send to the LLM (no handlers).
+     * Returns an empty array if no tools are registered.
+     * @returns {Array<{ name: string, description: string, parameters: Object }>}
+     */
+    getDefinitions() {
+        return [...this._tools.values()].map(t => t.toDefinition());
+    }
+
+    /**
+     * List registered tool names.
+     * @returns {string[]}
+     */
+    listNames() {
+        return [...this._tools.keys()];
+    }
+
+    /**
+     * Check if a tool is registered.
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name) {
+        return this._tools.has(name);
+    }
+
+    /**
+     * Execute a tool by name with the given arguments.
+     * Always returns a string (serializes objects to JSON).
+     *
+     * @param {string} name
+     * @param {Record<string, any>} args
+     * @returns {Promise<string>}
+     */
+    async execute(name, args) {
+        const tool = this._tools.get(name);
+        if (!tool) {
+            return `Error: Tool "${name}" is not registered. Available tools: ${this.listNames().join(', ') || 'none'}`;
+        }
+        const result = await tool.execute(args);
+        return typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+    }
+}

package/src/utils/errors.js

@@ -0,0 +1,46 @@
+// Framework-specific error types
+
+export class AgentError extends Error {
+    constructor(message, { cause, agentName } = {}) {
+        super(message);
+        this.name = 'AgentError';
+        this.agentName = agentName ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+export class ToolError extends Error {
+    constructor(message, { cause, toolName } = {}) {
+        super(message);
+        this.name = 'ToolError';
+        this.toolName = toolName ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+export class LLMError extends Error {
+    constructor(message, { cause, provider } = {}) {
+        super(message);
+        this.name = 'LLMError';
+        this.provider = provider ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+export class ConfigError extends Error {
+    constructor(message, { cause, field } = {}) {
+        super(message);
+        this.name = 'ConfigError';
+        this.field = field ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+export class MemoryError extends Error {
+    constructor(message, { cause, sessionId } = {}) {
+        super(message);
+        this.name = 'MemoryError';
+        this.sessionId = sessionId ?? null;
+        if (cause) this.cause = cause;
+    }
+}

package/src/utils/logger.js

@@ -0,0 +1,33 @@
+import pino from 'pino';
+
+// Check if pino-pretty is available (optional dev dependency)
+let prettyTransport;
+if (process.env.NODE_ENV !== 'production') {
+    try {
+        // Verify the module can be resolved before configuring it as a transport
+        await import('pino-pretty');
+        prettyTransport = { target: 'pino-pretty', options: { colorize: true, translateTime: 'HH:MM:ss' } };
+    } catch {
+        // pino-pretty not installed — fall back to default JSON output
+    }
+}
+
+// Single shared logger instance for the framework
+// Uses pino for structured JSON output with log levels
+const logger = pino({
+    name: 'agent-framework',
+    level: process.env.AGENT_LOG_LEVEL ?? 'info',
+    transport: prettyTransport,
+});
+
+/**
+ * Create a child logger scoped to a specific component (agent name, team name, etc.)
+ * @param {string} component
+ * @param {Object} [bindings] - Additional context to bind
+ * @returns {pino.Logger}
+ */
+export function createLogger(component, bindings = {}) {
+    return logger.child({ component, ...bindings });
+}
+
+export default logger;