@nebutra/agents 1.0.0

package/src/orchestrator.ts

@@ -0,0 +1,147 @@
+/**
+ * AgentOrchestrator — multi-agent coordination engine.
+ *
+ * Supports three execution modes:
+ *   - chat(): route a single message to the best agent
+ *   - pipeline(): chain agents sequentially (output → next input)
+ *   - broadcast(): fan-out to all agents and collect results
+ */
+
+import { logger } from "@nebutra/logger";
+import { BaseAgent } from "./agent";
+import { AgentRouter } from "./router";
+import { checkAgentQuota } from "./tenant";
+import type {
+  AgentContext,
+  AgentMessage,
+  AgentResponse,
+  OrchestratorConfig,
+  PipelineStep,
+} from "./types";
+
+export class AgentOrchestrator {
+  private readonly agents: Map<string, BaseAgent>;
+  private readonly router: AgentRouter;
+  private readonly defaultAgentId: string | undefined;
+
+  constructor(config: OrchestratorConfig) {
+    this.agents = new Map();
+    this.defaultAgentId = config.defaultAgentId;
+
+    // Register agents — callers provide AgentConfig[], we wrap in BaseAgent
+    // In practice, callers will register concrete subclasses (VercelAIAgent, etc.)
+    for (const agentConfig of config.agents) {
+      this.agents.set(agentConfig.id, new BaseAgent(agentConfig));
+    }
+
+    // Set up router
+    this.router = new AgentRouter(config.router ?? { strategy: "keyword" });
+  }
+
+  /**
+   * Register a pre-built agent instance (e.g. VercelAIAgent).
+   * Overwrites any agent with the same ID.
+   */
+  registerAgent(agent: BaseAgent): void {
+    this.agents.set(agent.config.id, agent);
+  }
+
+  /**
+   * Get a registered agent by ID.
+   */
+  getAgent(agentId: string): BaseAgent | undefined {
+    return this.agents.get(agentId);
+  }
+
+  /**
+   * Route a message to the best agent and execute.
+   */
+  async chat(message: string, context: AgentContext): Promise<AgentResponse> {
+    await this.assertQuota(context.tenantId);
+
+    const agentConfigs = [...this.agents.values()].map((a) => a.config);
+    const agentId = await this.router.route(message, agentConfigs, context, this.defaultAgentId);
+
+    const agent = this.agents.get(agentId);
+    if (!agent) {
+      throw new Error(`Agent "${agentId}" not found in orchestrator`);
+    }
+
+    const messages: AgentMessage[] = [{ role: "user", content: message, timestamp: new Date() }];
+
+    return agent.run(messages, context);
+  }
+
+  /**
+   * Execute a multi-agent pipeline where each step's output feeds the next.
+   * @experimental — API may change. Use `chat()` for production workloads.
+   */
+  async pipeline(
+    steps: readonly PipelineStep[],
+    input: string,
+    context: AgentContext,
+  ): Promise<AgentResponse> {
+    await this.assertQuota(context.tenantId);
+
+    let currentInput = input;
+    let lastResponse: AgentResponse | undefined;
+
+    for (const step of steps) {
+      const agent = this.agents.get(step.agentId);
+      if (!agent) {
+        throw new Error(`Pipeline step references unknown agent "${step.agentId}"`);
+      }
+
+      const transformedInput = step.transformInput
+        ? step.transformInput(currentInput)
+        : currentInput;
+
+      const messages: AgentMessage[] = [
+        { role: "user", content: transformedInput, timestamp: new Date() },
+      ];
+
+      lastResponse = await agent.run(messages, context);
+
+      // Extract the last assistant message as input for the next step
+      const assistantMessages = lastResponse.messages.filter((m) => m.role === "assistant");
+      const lastAssistant = assistantMessages[assistantMessages.length - 1];
+      currentInput = lastAssistant?.content ?? "";
+
+      logger.info("Pipeline step completed", {
+        agentId: step.agentId,
+        tenantId: context.tenantId,
+      });
+    }
+
+    if (!lastResponse) {
+      throw new Error("Pipeline produced no response (empty steps?)");
+    }
+
+    return lastResponse;
+  }
+
+  /**
+   * Broadcast a message to ALL registered agents in parallel.
+   * Returns an array of responses (one per agent).
+   * @experimental — API may change. Use `chat()` for production workloads.
+   */
+  async broadcast(message: string, context: AgentContext): Promise<readonly AgentResponse[]> {
+    await this.assertQuota(context.tenantId);
+
+    const messages: AgentMessage[] = [{ role: "user", content: message, timestamp: new Date() }];
+
+    const promises = [...this.agents.values()].map((agent) => agent.run(messages, context));
+
+    return Promise.all(promises);
+  }
+
+  /**
+   * Check tenant quota before execution.
+   */
+  private async assertQuota(tenantId: string): Promise<void> {
+    const { allowed } = await checkAgentQuota(tenantId);
+    if (!allowed) {
+      throw new Error(`Tenant "${tenantId}" has exceeded agent execution quota`);
+    }
+  }
+}

package/src/providers/langchain.ts

@@ -0,0 +1,28 @@
+/**
+ * LangChain.js agent adapter — stub.
+ *
+ * This module intentionally throws at construction time to guide
+ * developers through the required dependency installation.
+ *
+ * Once the packages are installed, implement the `execute()` method
+ * using LangChain's AgentExecutor or the newer LangGraph approach.
+ */
+
+import { BaseAgent } from "../agent";
+import type { AgentConfig } from "../types";
+
+export class LangChainAgent extends BaseAgent {
+  constructor(config: AgentConfig) {
+    super(config);
+    throw new Error(
+      [
+        "LangChain agent requires additional packages. Install:",
+        "",
+        "  pnpm add langchain @langchain/core @langchain/openai",
+        "",
+        "Then implement the execute() method in this file using",
+        "LangChain's AgentExecutor or LangGraph.",
+      ].join("\n"),
+    );
+  }
+}

package/src/providers/vercel-ai.ts

@@ -0,0 +1,114 @@
+/**
+ * Vercel AI SDK agent adapter.
+ *
+ * Uses `streamText` from the `ai` package with tool-loop support.
+ * The `ai` peer dependency is dynamically imported so the package
+ * doesn't fail at require-time when the SDK is absent.
+ */
+
+import { BaseAgent } from "../agent";
+import { runWithFallback, withAnthropicCacheControl } from "../fallback";
+import { buildTelemetryConfig } from "../observability";
+import type { AgentContext, AgentMessage, AgentResponse } from "../types";
+
+export class VercelAIAgent extends BaseAgent {
+  protected override async execute(
+    messages: readonly AgentMessage[],
+    context: AgentContext,
+  ): Promise<AgentResponse> {
+    // Dynamic import — avoids hard dependency on `ai`
+    const { streamText, stepCountIs, dynamicTool } = await import("ai");
+
+    type StreamTextParams = Parameters<typeof streamText>[0];
+
+    // Build AI SDK tool definitions from our AgentTool interface.
+    // We use dynamicTool() because our AgentTool uses a loose JSON Schema
+    // record type rather than a typed Zod schema.
+    const toolSet: StreamTextParams["tools"] = this.config.tools
+      ? Object.fromEntries(
+          this.config.tools.map((t) => [
+            t.name,
+            dynamicTool({
+              description: t.description,
+              inputSchema: t.inputSchema as Parameters<typeof dynamicTool>[0]["inputSchema"],
+              execute: async (args) => t.execute(args, context),
+            }),
+          ]),
+        )
+      : undefined;
+
+    // Build streamText options, conditionally including tools to satisfy
+    // exactOptionalPropertyTypes (tools must not be `undefined`).
+    //
+    // Cost optimization: stable content (system prompt + tool defs) is placed
+    // FIRST and dynamic content (user messages) LAST. This ordering is required
+    // for both Anthropic explicit prompt caching (90% discount via `cacheControl`)
+    // and OpenAI automatic caching (≥1024 token stable prefix). Reordering or
+    // mutating the system prompt invalidates the cache on every call.
+    const telemetry = buildTelemetryConfig({
+      functionId: `agent.${this.config.id}`,
+      metadata: {
+        tenantId: context.tenantId,
+        userId: context.userId,
+        sessionId: context.conversationId,
+        agentId: this.config.id,
+      },
+    });
+
+    const baseOptionsWithoutModel = {
+      system: this.config.instructions,
+      messages: messages.map((m) => ({
+        role: m.role as "user" | "assistant" | "system",
+        content: m.content,
+      })),
+      stopWhen: stepCountIs(this.config.maxSteps ?? 20),
+      // Anthropic prompt cache control on the system message — 90% cost
+      // reduction on cached prefix tokens. No-op for non-Anthropic providers.
+      providerOptions: withAnthropicCacheControl(),
+      experimental_telemetry: telemetry,
+    };
+
+    // Run through the multi-provider fallback chain. The chain is filtered
+    // to providers with API keys present (so single-provider deploys are
+    // backward-compatible — only the configured provider is tried).
+    const { result } = await runWithFallback(
+      async (model) => {
+        const streamOptions = {
+          ...baseOptionsWithoutModel,
+          model,
+          ...(toolSet !== undefined ? { tools: toolSet } : {}),
+        } as StreamTextParams;
+        const r = streamText(streamOptions);
+        // Materialize the result so retryable errors surface inside the
+        // try/catch in runWithFallback() rather than escaping as unhandled
+        // rejections from the lazy stream.
+        const text = await r.text;
+        const usage = await r.usage;
+        return { text, usage };
+      },
+      { model: this.config.model },
+    );
+
+    const { text, usage } = result;
+
+    // AI SDK v6 uses inputTokens/outputTokens on LanguageModelUsage
+    const inputTokens = usage?.inputTokens ?? 0;
+    const outputTokens = usage?.outputTokens ?? 0;
+
+    const responseMessages: AgentMessage[] = [
+      ...messages,
+      { role: "assistant" as const, content: text, timestamp: new Date() },
+    ];
+
+    return {
+      messages: responseMessages,
+      usage: {
+        promptTokens: inputTokens,
+        completionTokens: outputTokens,
+        totalTokens: inputTokens + outputTokens,
+      },
+      finishReason: "stop",
+      agentId: this.config.id,
+    };
+  }
+}

package/src/router.ts

@@ -0,0 +1,158 @@
+/**
+ * AgentRouter — routes incoming messages to the appropriate agent.
+ *
+ * Strategies:
+ *   - keyword: fast, pattern-based matching against agent descriptions
+ *   - llm: uses a small model to classify intent (requires AI SDK)
+ *   - custom: user-supplied routing function
+ */
+
+import { logger } from "@nebutra/logger";
+import type { AgentConfig, AgentContext, RouterConfig } from "./types";
+
+export class AgentRouter {
+  private readonly config: RouterConfig;
+
+  constructor(config: RouterConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Route a message to the best-matching agent.
+   * Returns the agent ID.
+   */
+  async route(
+    message: string,
+    agents: readonly AgentConfig[],
+    context: AgentContext,
+    defaultAgentId?: string,
+  ): Promise<string> {
+    if (agents.length === 0) {
+      throw new Error("No agents configured in the orchestrator");
+    }
+
+    const fallback = defaultAgentId ?? agents[0]?.id;
+    if (!fallback) {
+      throw new Error("No agents configured in the orchestrator");
+    }
+    switch (this.config.strategy) {
+      case "keyword":
+        return this.routeByKeyword(message, agents, defaultAgentId) ?? fallback;
+      case "llm":
+        return (await this.routeByLLM(message, agents, defaultAgentId)) ?? fallback;
+      case "custom":
+        return this.routeByCustom(message, context, defaultAgentId);
+      default: {
+        const _exhaustive: never = this.config.strategy;
+        throw new Error(`Unknown routing strategy: ${String(_exhaustive)}`);
+      }
+    }
+  }
+
+  /**
+   * Keyword-based routing: score each agent by how many words from
+   * its name + description appear in the user message.
+   */
+  private routeByKeyword(
+    message: string,
+    agents: readonly AgentConfig[],
+    defaultAgentId?: string,
+  ): string | undefined {
+    const messageLower = message.toLowerCase();
+    let bestId = defaultAgentId ?? agents[0]?.id;
+    let bestScore = 0;
+
+    for (const agent of agents) {
+      const keywords = `${agent.name} ${agent.description}`.toLowerCase().split(/\s+/);
+
+      let score = 0;
+      for (const keyword of keywords) {
+        if (keyword.length > 2 && messageLower.includes(keyword)) {
+          score += 1;
+        }
+      }
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestId = agent.id;
+      }
+    }
+
+    logger.info("Router: keyword match", {
+      selectedAgentId: bestId,
+      score: bestScore,
+    });
+    return bestId;
+  }
+
+  /**
+   * LLM-based routing: uses a small model to classify the user's intent
+   * and select the best agent. Falls back to keyword if AI SDK unavailable.
+   */
+  private async routeByLLM(
+    message: string,
+    agents: readonly AgentConfig[],
+    defaultAgentId?: string,
+  ): Promise<string | undefined> {
+    try {
+      const { generateText } = await import("ai");
+
+      const agentList = agents.map((a) => `- ${a.id}: ${a.description}`).join("\n");
+
+      const result = await generateText({
+        model: agents[0]?.model as unknown as Parameters<typeof generateText>[0]["model"],
+        system: [
+          "You are a routing classifier. Given a user message and a list of agents,",
+          "respond with ONLY the agent ID that best matches the user's intent.",
+          "If no agent is a good match, respond with the default agent ID.",
+          "",
+          `Available agents:\n${agentList}`,
+          "",
+          defaultAgentId ? `Default agent: ${defaultAgentId}` : "",
+        ].join("\n"),
+        messages: [{ role: "user" as const, content: message }],
+      });
+
+      const selectedId = result.text.trim();
+      const validAgent = agents.find((a) => a.id === selectedId);
+
+      if (validAgent) {
+        logger.info("Router: LLM classification", {
+          selectedAgentId: validAgent.id,
+        });
+        return validAgent.id;
+      }
+
+      // LLM returned an invalid ID — fall back
+      return defaultAgentId ?? agents[0]?.id;
+    } catch (error) {
+      logger.warn("Router: LLM routing failed, falling back to keyword", {
+        error,
+      });
+      return this.routeByKeyword(message, agents, defaultAgentId);
+    }
+  }
+
+  /**
+   * Custom routing via user-supplied function.
+   */
+  private async routeByCustom(
+    message: string,
+    context: AgentContext,
+    defaultAgentId?: string,
+  ): Promise<string> {
+    if (!this.config.customRouter) {
+      throw new Error(
+        'RouterConfig strategy is "custom" but no customRouter function was provided',
+      );
+    }
+
+    try {
+      return await this.config.customRouter(message, context);
+    } catch (error) {
+      logger.warn("Router: custom router failed", { error });
+      if (defaultAgentId) return defaultAgentId;
+      throw error;
+    }
+  }
+}

package/src/sdk/config.ts

@@ -0,0 +1,73 @@
+/**
+ * Runtime configuration for the Vercel AI SDK-backed helpers
+ * (`generateText`, `streamText`, `embed`, `embedMany`).
+ *
+ * Previously lived in `@nebutra/ai-sdk/config`. Absorbed into
+ * `@nebutra/agents` during the AI package consolidation so there is
+ * a single AI runtime package.
+ */
+
+import { z } from "zod";
+
+/**
+ * Supported AI provider backends for the top-level helpers.
+ *
+ * - openrouter:   300+ models, automatic failover, pay-as-you-go (default)
+ * - openai:       Direct OpenAI API access
+ * - siliconflow:  SiliconFlow cloud — Qwen, DeepSeek, etc. (OpenAI-compatible, China-optimized)
+ * - gateway:      Vercel AI Gateway with OIDC auth (for Vercel-deployed apps)
+ */
+export const ProviderType = z.enum(["openrouter", "openai", "siliconflow", "gateway"]);
+export type ProviderType = z.infer<typeof ProviderType>;
+
+export const NebutraAIConfigSchema = z.object({
+  /** Which provider backend to use. Defaults to "openrouter". */
+  provider: ProviderType.default("openrouter"),
+
+  /** API key override. Falls back to env vars per provider. */
+  apiKey: z.string().optional(),
+
+  /** Default model identifier. Provider-specific format. */
+  defaultModel: z.string().default("anthropic/claude-sonnet-4"),
+
+  /** Default temperature for generations. */
+  temperature: z.number().min(0).max(2).default(0.7),
+
+  /** Default max tokens for output. */
+  maxTokens: z.number().int().positive().optional(),
+
+  /** Extra headers merged into every request (e.g. HTTP-Referer for OpenRouter). */
+  headers: z.record(z.string(), z.string()).optional(),
+
+  /** Extra body fields merged into every request. */
+  extraBody: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type NebutraAIConfig = z.input<typeof NebutraAIConfigSchema>;
+export type ResolvedNebutraAIConfig = z.output<typeof NebutraAIConfigSchema>;
+
+/**
+ * Resolves the API key from explicit config or environment variables.
+ */
+export function resolveApiKey(config: ResolvedNebutraAIConfig): string {
+  if (config.apiKey) return config.apiKey;
+
+  const envMap: Record<ProviderType, string> = {
+    openrouter: "OPENROUTER_API_KEY",
+    openai: "OPENAI_API_KEY",
+    siliconflow: "SILICONFLOW_API_KEY",
+    gateway: "VERCEL_OIDC_TOKEN",
+  };
+
+  const envVar = envMap[config.provider];
+
+  const value = globalThis.process?.env?.[envVar];
+
+  if (!value) {
+    throw new Error(
+      `[@nebutra/agents] Missing API key. Set "${envVar}" in environment or pass "apiKey" in config.`,
+    );
+  }
+
+  return value;
+}