@agentionai/agents 0.12.0-beta → 0.13.0

package/README.md

@@ -27,6 +27,7 @@ Get an API key from your chosen provider:
 - **OpenAI**: [platform.openai.com](https://platform.openai.com/api-keys)
 - **Gemini**: [aistudio.google.com](https://aistudio.google.com/app/apikey)
 - **Mistral**: [console.mistral.ai](https://console.mistral.ai/)
+- **Ollama** / **llama.cpp**: no API key needed — run models locally (see [Agents guide](https://docs.agention.ai/guide/agents))
 
 Set it as an environment variable:
 
@@ -56,10 +57,12 @@ console.log(response);
 Import only the agents you need:
 
 ```typescript
-import { ClaudeAgent } from '@agentionai/agents/claude';    // Requires @anthropic-ai/sdk
-import { OpenAiAgent } from '@agentionai/agents/openai';    // Requires openai
-import { GeminiAgent } from '@agentionai/agents/gemini';    // Requires @google/generative-ai
-import { MistralAgent } from '@agentionai/agents/mistral';  // Requires @mistralai/mistralai
+import { ClaudeAgent } from '@agentionai/agents/claude';     // Requires @anthropic-ai/sdk
+import { OpenAiAgent } from '@agentionai/agents/openai';     // Requires openai
+import { GeminiAgent } from '@agentionai/agents/gemini';     // Requires @google/generative-ai
+import { MistralAgent } from '@agentionai/agents/mistral';   // Requires @mistralai/mistralai
+import { OllamaAgent } from '@agentionai/agents/ollama';     // Requires ollama (local, no API key)
+import { LlamaCppAgent } from '@agentionai/agents/llamacpp'; // Requires openai (local, no API key)
 ```
 
 Or import everything (requires all SDKs):
@@ -71,7 +74,8 @@ import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';
 
 ## Features
 
-- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral—same interface. Switch models with one line.
+- **Multi-Provider, No Lock-in** - Claude, OpenAI, Gemini, Mistral, plus local models via Ollama and llama.cpp—same interface. Switch models with one line.
+- **Built-In Tools** - Use provider-defined server-side tools (e.g. Anthropic's web search, bash, text editor) alongside your own.
 - **Composable, Not Magical** - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
 - **Multimodal / Vision** - Send images alongside text with a unified `MessageContent[]` API across all providers.
 - **Full Observability** - Per-call token counts, execution timing, pipeline structure visualization.
@@ -115,6 +119,58 @@ const agent = new GeminiAgent({
 const response = await agent.execute("What's the weather in Paris?");
 ```
 
+### Local Models (Ollama / llama.cpp)
+
+Run models on your own machine — no API key required. Same agent interface as every other provider:
+
+```typescript
+import { OllamaAgent } from '@agentionai/agents/ollama';
+import { LlamaCppAgent } from '@agentionai/agents/llamacpp';
+
+// Ollama (https://ollama.com) — pull a model first: `ollama pull qwen2.5`
+const ollama = new OllamaAgent({
+  id: 'local-ollama',
+  name: 'Local Assistant',
+  description: 'You are a helpful assistant.',
+  model: 'qwen2.5',
+  apiKey: '',
+});
+
+// llama.cpp server (`llama-server -m model.gguf`) — OpenAI-compatible API
+const llamaCpp = new LlamaCppAgent({
+  id: 'local-llamacpp',
+  name: 'Local Assistant',
+  description: 'You are a helpful assistant.',
+  apiKey: '',
+  baseURL: 'http://localhost:8080/v1',
+});
+
+const response = await ollama.execute('What can you run locally?');
+
+// Discover which models are available on the server
+const models = await ollama.listModels();
+```
+
+### Built-In Tools
+
+Use a provider's own server-side tools (executed by the provider, not locally) alongside your custom tools:
+
+```typescript
+import { ClaudeAgent } from '@agentionai/agents/claude';
+import { webSearchTool } from '@agentionai/agents/claude';
+
+const agent = new ClaudeAgent({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  id: 'researcher',
+  name: 'Researcher',
+  description: 'You are a helpful research assistant with web access.',
+  model: 'claude-sonnet-4-6',
+  builtInTools: [webSearchTool({ maxUses: 5 })],
+});
+
+const response = await agent.execute('What happened in the news today?');
+```
+
 ### Multi-Agent Pipeline
 
 Chain agents together with different providers and models:
@@ -216,12 +272,12 @@ const response2 = await agent.execute([
 ## Core Concepts
 
 ### Agents
-Unified interface across Claude, OpenAI, Gemini, and Mistral. Tools, history, and token tracking built-in.
+Unified interface across Claude, OpenAI, Gemini, Mistral, and local models via Ollama and llama.cpp. Tools, history, and token tracking built-in.
 
 [Learn more →](https://docs.agention.ai/guide/agents)
 
 ### Tools
-JSON Schema + handler pattern. Unique capability: wrap any agent as a tool for delegation hierarchies.
+JSON Schema + handler pattern. Unique capability: wrap any agent as a tool for delegation hierarchies. Also supports provider-defined built-in tools (e.g. Anthropic's web search, bash, text editor) that run server-side.
 
 [Learn more →](https://docs.agention.ai/guide/tools)
 

package/dist/agents/Agent.d.ts

@@ -4,7 +4,9 @@ import { BaseAgentConfig } from "./BaseAgent";
 import { OpenAiAgent } from "./openai/OpenAiAgent";
 import { GeminiAgent } from "./google/GeminiAgent";
 import { MistralAgent } from "./mistral/MistralAgent";
-import { ClaudeModel, OpenAIModel, GeminiModel, MistralModel } from "./model-types";
+import { OllamaAgent } from "./ollama/OllamaAgent";
+import { LlamaCppAgent } from "./llamacpp/LlamaCppAgent";
+import { ClaudeModel, OpenAIModel, GeminiModel, MistralModel, OllamaModel, LlamaCppModel } from "./model-types";
 type ClaudeAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
     vendor: "anthropic";
     model?: ClaudeModel;
@@ -21,9 +23,19 @@ type MistralAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
     vendor: "mistral";
     model?: MistralModel;
 };
-type AgentConfig = ClaudeAgentConfig | OpenAIAgentConfig | GeminiAgentConfig | MistralAgentConfig;
+type OllamaAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
+    vendor: "ollama";
+    model?: OllamaModel;
+    host?: string;
+};
+type LlamaCppAgentConfig = Omit<BaseAgentConfig, "vendor" | "model"> & {
+    vendor: "llamacpp";
+    model?: LlamaCppModel;
+    baseURL?: string;
+};
+type AgentConfig = ClaudeAgentConfig | OpenAIAgentConfig | GeminiAgentConfig | MistralAgentConfig | OllamaAgentConfig | LlamaCppAgentConfig;
 export declare class Agent {
-    static create(config: AgentConfig, history?: History): ClaudeAgent | GeminiAgent | OpenAiAgent | MistralAgent;
+    static create(config: AgentConfig, history?: History): ClaudeAgent | GeminiAgent | OpenAiAgent | MistralAgent | OllamaAgent | LlamaCppAgent;
 }
 export {};
 //# sourceMappingURL=Agent.d.ts.map

package/dist/agents/Agent.js

@@ -5,6 +5,8 @@ const ClaudeAgent_1 = require("./anthropic/ClaudeAgent");
 const OpenAiAgent_1 = require("./openai/OpenAiAgent");
 const GeminiAgent_1 = require("./google/GeminiAgent");
 const MistralAgent_1 = require("./mistral/MistralAgent");
+const OllamaAgent_1 = require("./ollama/OllamaAgent");
+const LlamaCppAgent_1 = require("./llamacpp/LlamaCppAgent");
 class Agent {
     static create(config, history) {
         if (config.vendor === "anthropic") {
@@ -19,6 +21,12 @@ class Agent {
         else if (config.vendor === "mistral") {
             return new MistralAgent_1.MistralAgent(config, history);
         }
+        else if (config.vendor === "ollama") {
+            return new OllamaAgent_1.OllamaAgent(config, history);
+        }
+        else if (config.vendor === "llamacpp") {
+            return new LlamaCppAgent_1.LlamaCppAgent(config, history);
+        }
         else {
             throw new Error("No vendor defined");
         }

package/dist/agents/AgentConfig.d.ts

@@ -1,7 +1,8 @@
 import { Tool } from "../tools/Tool";
+import { BuiltInTool } from "../tools/BuiltInTool";
 import { BaseAgent } from "./BaseAgent";
 /** Supported LLM vendors */
-export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini";
+export type AgentVendor = "openai" | "anthropic" | "mistral" | "gemini" | "ollama" | "llamacpp";
 /**
  * Common configuration shared by all agents
  */
@@ -57,6 +58,21 @@ export interface CommonAgentConfig {
 export interface ClaudeSpecificConfig {
     disableParallelToolUse?: boolean;
     metadata?: Record<string, string>;
+    /**
+     * Provider-defined / server-side tools (e.g. web search, bash, text editor).
+     * These are executed by Anthropic rather than locally — see `lib/tools/BuiltInTool.ts`.
+     */
+    builtInTools?: BuiltInTool[];
+    /**
+     * How `apiKey` should be presented to the Anthropic SDK.
+     * - `"apiKey"` (default): sent as the `x-api-key` header — for standard Anthropic API keys.
+     * - `"oauth"`: sent as a bearer `authToken` — for OAuth access tokens (e.g. Claude Code /
+     *   Claude.ai tokens, which look like `sk-ant-oat...`).
+     *
+     * Set this explicitly rather than relying on the token's prefix, since prefixes are an
+     * implementation detail that can change.
+     */
+    authType?: "apiKey" | "oauth";
 }
 /**
  * Vendor-specific configuration for OpenAI
@@ -86,6 +102,20 @@ export interface GeminiSpecificConfig {
     responseMimeType?: string;
     responseSchema?: any;
 }
+/**
+ * Vendor-specific configuration for Ollama (local)
+ */
+export interface OllamaSpecificConfig {
+    /** Ollama server URL (default: `http://localhost:11434`) */
+    host?: string;
+}
+/**
+ * Vendor-specific configuration for llama.cpp server (local)
+ */
+export interface LlamaCppSpecificConfig {
+    /** Base URL of the llama.cpp server's OpenAI-compatible API (default: `http://localhost:8080/v1`) */
+    baseURL?: string;
+}
 /**
  * Generic vendor-specific configuration container
  * This allows any vendor to add custom config without modifying base types
@@ -95,6 +125,8 @@ export interface VendorSpecificConfig {
     openai?: OpenAISpecificConfig;
     mistral?: MistralSpecificConfig;
     gemini?: GeminiSpecificConfig;
+    ollama?: OllamaSpecificConfig;
+    llamacpp?: LlamaCppSpecificConfig;
 }
 /**
  * Complete agent configuration with vendor-specific extensions
@@ -134,10 +166,14 @@ export type TypedAgentConfig<V extends AgentVendor> = CommonAgentConfig & {
         mistral?: MistralSpecificConfig;
     } : V extends "gemini" ? {
         gemini?: GeminiSpecificConfig;
+    } : V extends "ollama" ? {
+        ollama?: OllamaSpecificConfig;
+    } : V extends "llamacpp" ? {
+        llamacpp?: LlamaCppSpecificConfig;
     } : never;
 };
 /**
  * Helper type to extract vendor-specific config for a given vendor
  */
-export type VendorConfigFor<V extends AgentVendor> = V extends "anthropic" ? ClaudeSpecificConfig : V extends "openai" ? OpenAISpecificConfig : V extends "mistral" ? MistralSpecificConfig : V extends "gemini" ? GeminiSpecificConfig : never;
+export type VendorConfigFor<V extends AgentVendor> = V extends "anthropic" ? ClaudeSpecificConfig : V extends "openai" ? OpenAISpecificConfig : V extends "mistral" ? MistralSpecificConfig : V extends "gemini" ? GeminiSpecificConfig : V extends "ollama" ? OllamaSpecificConfig : V extends "llamacpp" ? LlamaCppSpecificConfig : never;
 //# sourceMappingURL=AgentConfig.d.ts.map

package/dist/agents/anthropic/ClaudeAgent.d.ts

@@ -1,5 +1,6 @@
-import { Message, Usage } from "@anthropic-ai/sdk/resources";
+import { Message, ToolUnion, Usage } from "@anthropic-ai/sdk/resources";
 import { type ToolDefinition } from "../../tools/Tool";
+import { type BuiltInTool } from "../../tools/BuiltInTool";
 import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
 import { History, MessageContent } from "../../history/History";
 import { ClaudeModel } from "../model-types";
@@ -9,6 +10,18 @@ type AgentConfig = BaseAgentConfig & {
     maxTokens?: number;
     disableParallelToolUse?: boolean;
     metadata?: Record<string, string>;
+    /**
+     * How `apiKey` should be presented to the Anthropic SDK — `"apiKey"` (default, `x-api-key`
+     * header) or `"oauth"` (bearer `authToken`, for OAuth access tokens like Claude Code's
+     * `sk-ant-oat...` tokens). Set explicitly; do not infer it from the token's prefix.
+     */
+    authType?: "apiKey" | "oauth";
+    /**
+     * Provider-defined / server-side tools (e.g. web search, bash, text editor).
+     * These run on Anthropic's infrastructure rather than locally.
+     * @see lib/tools/BuiltInTool.ts
+     */
+    builtInTools?: BuiltInTool[];
 };
 /**
  * Agent for Anthropic models.
@@ -36,6 +49,11 @@ export declare class ClaudeAgent extends BaseAgent {
     private currentToolCallCount;
     constructor(config: Omit<AgentConfig, "vendor">, history?: History);
     protected getToolDefinitions(): ToolDefinition[];
+    /**
+     * Combine locally-executed tool definitions with provider-defined
+     * (server-side) built-in tools, in the shape Anthropic's API expects.
+     */
+    protected getAllToolDefinitions(): ToolUnion[];
     protected process(_input: string): Promise<string>;
     execute(input: string | MessageContent[]): Promise<string>;
     protected handleResponse(response: Message): Promise<string>;

package/dist/agents/anthropic/ClaudeAgent.js

@@ -29,9 +29,6 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
         super({ ...config, vendor: "anthropic" }, history);
         /** Count of tool calls in current execution */
         this.currentToolCallCount = 0;
-        this.client = new sdk_1.Anthropic({
-            apiKey: config.apiKey,
-        });
         // Merge flat config (deprecated) with nested vendorConfig
         // Flat config takes precedence for backward compatibility
         const vendorConfig = config.vendorConfig?.anthropic || {};
@@ -39,11 +36,18 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             vendorConfig.disableParallelToolUse ??
             false;
         const metadata = config.metadata ?? vendorConfig.metadata;
+        const builtInTools = config.builtInTools ?? vendorConfig.builtInTools;
+        const authType = config.authType ?? vendorConfig.authType ?? "apiKey";
+        this.client = new sdk_1.Anthropic(authType === "oauth"
+            ? { authToken: config.apiKey }
+            : { apiKey: config.apiKey });
         this.config = {
             model: config.model || "claude-3-5-haiku-latest",
             maxTokens: config.maxTokens || 1024,
             disableParallelToolUse,
             metadata,
+            builtInTools,
+            authType,
             apiKey: config.apiKey,
             temperature: config.temperature,
             topP: config.topP,
@@ -56,6 +60,16 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
     getToolDefinitions() {
         return Array.from(this.tools.values()).map((tool) => tool.getPrompt());
     }
+    /**
+     * Combine locally-executed tool definitions with provider-defined
+     * (server-side) built-in tools, in the shape Anthropic's API expects.
+     */
+    getAllToolDefinitions() {
+        return [
+            ...this.getToolDefinitions(),
+            ...(this.config.builtInTools ?? []),
+        ];
+    }
     async process(_input) {
         return "";
     }
@@ -95,7 +109,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                 system: systemMessage,
                 max_tokens: this.config.maxTokens,
                 messages,
-                tools: this.getToolDefinitions(),
+                tools: this.getAllToolDefinitions(),
                 temperature: this.config.temperature,
                 top_p: this.config.topP,
                 top_k: this.config.topK,
@@ -155,7 +169,12 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
             throw error;
         }
         if (response.stop_reason !== "tool_use") {
-            if (response.content && response.content[0]?.type === "text") {
+            // Server-side tools (web search, bash, etc.) add their own content blocks
+            // (server_tool_use / web_search_tool_result / ...) ahead of the final
+            // text — collect every text block rather than assuming content[0] is text.
+            const textBlocks = response.content?.filter((block) => block.type === "text");
+            if (response.content && textBlocks && textBlocks.length > 0) {
+                const textContent = textBlocks.map((block) => block.text).join("\n");
                 this.emit(AgentEvent_1.AgentEvent.DONE, response, usage);
                 // Convert response to normalized format and add to history
                 const entry = transformers_1.anthropicTransformer.fromProviderContent("assistant", response.content);
@@ -166,10 +185,10 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                         input: this.lastTokenUsage?.input_tokens || 0,
                         output: this.lastTokenUsage?.output_tokens || 0,
                         total: this.lastTokenUsage?.total_tokens || 0,
-                    }, "end_turn", this.currentToolCallCount > 0, this.currentToolCallCount, response.content[0].text);
+                    }, "end_turn", this.currentToolCallCount > 0, this.currentToolCallCount, textContent);
                     this.vizEventId = undefined;
                 }
-                return response.content[0].text;
+                return textContent;
             }
             else {
                 const error = new AgentError_1.ExecutionError(`Unexpected response format: ${JSON.stringify(response.content)}`);
@@ -199,7 +218,7 @@ class ClaudeAgent extends BaseAgent_1.BaseAgent {
                         system: this.history.getSystemMessage(),
                         max_tokens: this.config.maxTokens,
                         messages,
-                        tools: this.getToolDefinitions(),
+                        tools: this.getAllToolDefinitions(),
                         temperature: this.config.temperature,
                         top_p: this.config.topP,
                         top_k: this.config.topK,

package/dist/agents/llamacpp/LlamaCppAgent.d.ts

@@ -0,0 +1,60 @@
+import { ChatCompletion, ChatCompletionTool } from "openai/resources/chat/completions";
+import { Model } from "openai/resources/models";
+import { BaseAgent, BaseAgentConfig, TokenUsage } from "../BaseAgent";
+import { History, MessageContent } from "../../history/History";
+import { LlamaCppModel } from "../model-types";
+type AgentConfig = BaseAgentConfig & {
+    /** Base URL of the llama.cpp server's OpenAI-compatible API (default: `http://localhost:8080/v1`) */
+    baseURL?: string;
+    model?: LlamaCppModel;
+    maxTokens?: number;
+};
+/**
+ * Agent for locally-hosted models served by a llama.cpp server (`llama-server`),
+ * which exposes an OpenAI-compatible `/v1/chat/completions` API.
+ *
+ * Requires the `openai` package as a peer dependency and a running llama.cpp server.
+ *
+ * @example
+ * ```typescript
+ * const agent = new LlamaCppAgent({
+ *   id: "1",
+ *   name: "Assistant",
+ *   description: "A helpful assistant",
+ *   apiKey: "",
+ *   baseURL: "http://localhost:8080/v1",
+ * });
+ *
+ * const response = await agent.execute("Hello!");
+ * ```
+ *
+ * @example List available models
+ * ```typescript
+ * const models = await agent.listModels();
+ * ```
+ */
+export declare class LlamaCppAgent extends BaseAgent {
+    private client;
+    protected config: Partial<AgentConfig>;
+    /** Token usage from the last execution (for metrics tracking) */
+    lastTokenUsage?: TokenUsage;
+    /** Current visualization event ID */
+    private vizEventId?;
+    /** Count of tool calls in current execution */
+    private currentToolCallCount;
+    constructor(config: Omit<AgentConfig, "vendor">, history?: History);
+    /**
+     * List the models currently available on the llama.cpp server (via its
+     * OpenAI-compatible `/v1/models` endpoint).
+     */
+    listModels(): Promise<Model[]>;
+    protected getToolDefinitions(): ChatCompletionTool[];
+    protected process(_input: string): Promise<string>;
+    execute(input: string | MessageContent[]): Promise<string>;
+    private callLlamaCpp;
+    protected handleResponse(response: ChatCompletion): Promise<string>;
+    private handleToolCalls;
+    protected parseUsage(response: ChatCompletion): TokenUsage;
+}
+export {};
+//# sourceMappingURL=LlamaCppAgent.d.ts.map