代理

AI 无魔法特工

一个综合性的TypeScript工具包,用于用RAG来构建LLM动力的代理,以及多代理工作流程. 没有隐藏的状态机器,没有强制抽象——只是打字的代理,可相容的图表,和一个完整的工具包中的完全控制.

文档 二. 支助 实例 二. 支助 吉特拉布语Name 二. 支助 无

快速启动

1. 安装

仅安装您需要的选择性导入 :

# Install core library + Claude SDK
npm install @agentionai/agents @anthropic-ai/sdk

2. 获取 API 密钥

从选中的提供者获取 API 密钥 :

• 克劳德数字 : control.harmanic.com (中文(简体) )
• 开放AI数字 : 互联网档案馆的存檔,存档日期2013-12-02. openai.com
• 双子座数字 : aistudio.google.com (中文(中国大陆) )
• 迷雾数字 : 控制台. mistral.ai
• 打开路透社数字 : 开口/钥匙 - 一个钥匙,几十个上游供应商
• 奥拉玛 编号 : 拉玛.cpp: 不需要 API 密钥——在当地运行模型(参见 代理指南(中文(简体) )

设定为环境变量:

export ANTHROPIC_API_KEY=your-key-here

3. 创建您的第一代理

// Import only Claude - no other agent SDKs required!
import { ClaudeAgent } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'assistant',
  name: 'Assistant',
  description: 'You are a helpful assistant.',
  model: 'claude-sonnet-4-5',
});

const response = await agent.execute('What can you help me with?');
console.log(response);

选择性导入

只导入所需的代理 :

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 { OpenRouterAgent } from '@agentionai/agents/openrouter'; // Requires @openrouter/sdk
import { OllamaAgent } from '@agentionai/agents/ollama';     // Requires ollama (local, no API key)
import { LlamaCppAgent } from '@agentionai/agents/llamacpp'; // Requires openai (local, no API key)

或导入一切( 需要全部 SDK ):

import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';

特征

• 多服务, 无锁定 - Claude、OpenAI、双子座、Mistral、OpenRouter(一个钥匙,几十个上游供应商),加上通过Ollama和lama.cpp的本地模型-相同的接口。 用一行切换模型. listModels() 问任何提供者它目前提供什么, 一个共享的形状.
• 可编译上下文管理 - 工具结果遮掩(无损失、免费)+滚动总和(自动起火)+副代理授权(按结构进行隔离).
• 流线 - 说吧 executeStream() 克劳德,OpenAI,OpenRouter, 和所有OpenAI兼容的代理。 也门 { type: "text" | "reasoning" } 块; 工具呼叫处理透明 .
• 内建工具 - 使用自定义的服务器侧工具(例如Anthropic的网页搜索、bash、文本编辑器),同时使用自己的工具.
• 可编曲的,非魔法 - 特工就是目标 管道为阵列. 没有隐藏的状态 没有惊喜.
• 多式联运/愿景 - 以统一文本同时发送图像 MessageContent[] 所有供应商的API.
• 完全可观察性 ——逐个计票,执行时间,管线结构可视化.
• 类型脚本- Native - 严格打字、接口和通用软件.
• RAG 准备 - LanceDB向量商店, 信号意识分解, 摄取管道出盒子.

有工具的代理

import { GeminiAgent, Tool } from '@agentionai/agents/gemini';

const weatherTool = new Tool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'City name' },
    },
    required: ['location'],
  },
  execute: async ({ location }) => {
    // In production, call a weather API
    return JSON.stringify({
      location,
      temperature: 22,
      conditions: 'Sunny',
    });
  },
});

const agent = new GeminiAgent({
  apiKey: process.env.GEMINI_API_KEY,
  id: 'weather-agent',
  name: 'Weather Agent',
  description: 'You are a weather assistant.',
  model: 'gemini-flash-lite-latest',
  tools: [weatherTool],
});

const response = await agent.execute("What's the weather in Paris?");

内容管理

每一次代理谈话都不断增长——工具结果堆积而成,转弯而成堆积而成活物复合. Agention的历史插件使上下文窗口自动倾斜,不进行人工记账.

import { toolResultMaskingPlugin, compressionPlugin } from '@agentionai/agents/history/plugins';
import { History } from '@agentionai/agents/history';

// Mask old tool results at read time — sync, free, lossless
const maskingPlugin = toolResultMaskingPlugin({ keepRecentResults: 2 });

// Compress old turns into a rolling summary — auto-fires past a token budget
const history = new History([], { maxTokens: 50000 })
  .use(maskingPlugin)
  .use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 8000 } }));

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'Research topics thoroughly.',
  model: 'claude-sonnet-4-6',
  tools: [searchTool, maskingPlugin.retrieveTool],
}, history);

内容管理指南 • 妇女 API 历史 ~

本地模型( Ollama / lama.cpp / OpenAI 兼容服务器)

在自己的机器上运行模型——不需要API密钥. 与其他提供者相同的代理接口 :

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();

自定义 OpenAI 兼容服务器 (vLLM, LM Studio, College AI, Groq,.):扩展 OpenAICompatibleAgent 直接 :

import { OpenAICompatibleAgent, OpenAICompatibleConfig } from '@agentionai/agents/llamacpp';

class VLLMAgent extends OpenAICompatibleAgent {
  constructor(config: Omit<OpenAICompatibleConfig, 'vendor'>) {
    super({ ...config, vendor: 'llamacpp', baseURL: config.baseURL ?? 'http://localhost:8000/v1' });
  }
  protected getVendorName() { return 'vLLM'; }
}

完整指南 –

内建工具

使用服务商自己的服务器侧工具( 由服务商执行, 而非本地) 与您的自定义工具 :

import { ClaudeAgent, 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?');

流线

所有三个主要供应商都通过下列途径支持流动: executeStream()返回一个 AsyncGenerator<StreamChunk>每个块是 { type: "text" | "reasoning"; content: string } ——可见输出的文本,内部思维符号的推理(DeepSeek R1,克洛德扩展思维,OpenAI o-series).

import { ClaudeAgent } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'assistant',
  name: 'Assistant',
  description: 'You are a helpful assistant.',
});

for await (const chunk of agent.executeStream('Tell me a story')) {
  if (chunk.type === 'text') process.stdout.write(chunk.content);
}

工具呼叫以透明方式处理——每次往返后发电机继续流出. 同样的API工作跨越 ClaudeAgent, (中文(简体) ), OpenAiAgent,以及 LlamaCppAgent / 任意 OpenAICompatibleAgent 子类.

多剂管道

链剂与不同的供应商和模型:

import { ClaudeAgent } from '@agentionai/agents/claude';
import { OpenAiAgent } from '@agentionai/agents/openai';
import { Pipeline } from '@agentionai/agents/core';

const researcher = new OpenAiAgent({
  apiKey: process.env.OPENAI_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'Research the given topic and provide key facts.',
  model: 'gpt-4o',
  tools: [searchTool],
});

const writer = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'writer',
  name: 'Writer',
  description: 'Write a blog post based on the research provided.',
  model: 'claude-sonnet-4-5',
});

const pipeline = new Pipeline([researcher, writer]);
const result = await pipeline.execute('Renewable energy trends in 2024');

代理代表团

使用代理作为分级工作流程的工具:

import { ClaudeAgent } from '@agentionai/agents/claude';
import { OpenAiAgent } from '@agentionai/agents/openai';

// Research assistant (cheaper model for data gathering)
const researchAssistant = new OpenAiAgent({
  apiKey: process.env.OPENAI_API_KEY,
  id: 'research-assistant',
  name: 'Research Assistant',
  description: 'Search and summarize information on topics.',
  model: 'gpt-4o-mini',
  tools: [searchTool],
});

// Lead researcher delegates to assistant, synthesizes findings
const researcher = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Lead Researcher',
  description: 'Research topics thoroughly using your assistant.',
  model: 'claude-sonnet-4-5',
  agents: [researchAssistant],  // Assistant available as a tool
});

const result = await researcher.execute('Latest developments in quantum computing');

多式联运/愿景

使用文本同时发送图像 imageUrl() 或者说 imageBase64()。同样的 MessageContent[] 接口在所有提供者之间工作 :

import { ClaudeAgent } from '@agentionai/agents/claude';
import { imageUrl, imageBase64 } from '@agentionai/agents/core';
import * as fs from 'fs';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'vision-agent',
  name: 'VisionAgent',
  description: 'You analyze images.',
  model: 'claude-opus-4-6',
});

// Remote image by URL
const response = await agent.execute([
  imageUrl('https://example.com/chart.png'),
  { type: 'text', text: 'Summarize this chart in one sentence.' },
]);

// Local image as base64
const data = fs.readFileSync('./photo.jpg').toString('base64');
const response2 = await agent.execute([
  imageBase64(data, 'image/jpeg'),
  { type: 'text', text: 'What plant is this?' },
]);

核心概念

探员

Claude,OpenAI,双子座,Mistral通过Ollama和lama.cpp实现统一接口,并实现本地模式. 工具、历史和信使追踪系统.

学习更多

工具

JSON Schema + 处理器图案. 独特的能力:将任何代理人包起来作为代表团等级的工具。 同时支持运行服务器侧面的自定义内置工具(例如Anthropic的网页搜索,bash,文本编辑器).

学习更多

内容管理

工具结果遮掩(无损失,免费)+滚动相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相 可编译插件使上下文窗口自动倾斜.

学习更多 • 妇女 API 历史 ~

多式联运/愿景

统一 MessageContent[] 用于所有提供者图像的界面。 URL和 Base64 图像,将文本和图像自由混合在一个呼叫中.

学习更多

图表管道

编成相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相相接相接相接相 混合模型和提供者自由.

学习更多

RAG 矢量存储器

LanceDB 向量存储, 信号意识分解, 摄取管道, 以及取出工具.

学习更多

观察性

随叫随到和按节点计数、期限指标、全面执行的能见度.

学习更多

文档

• 开始 - 安装和第一代理
• 内容管理 - 预算、蒙面和压缩
• 探员 - 代理配置和提供者
• 工具 - 增加能力和代理授权
• 多式联运/愿景 - 向所有提供者发送图像
• 历史 - 对话持续和插件
• 图表管道 - 多代理人工作流程
• 矢量存储器 - RAG和语义搜索
• 实例 - 现实世界的执行情况
• API 参考 - 全面的API文档

为什么是特工?

• 飞快一点 停止为每个项目重建代理基础设施
• 保持灵活 ——交换提供者,混合模型,自定义一切
• 继续控制 - 看清楚每一步都发生了什么
• 自信地缩放 - 内置的计量标准、信使跟踪和可观察性

实例

看看这个 实例 完整工作示例目录 :

• 有不同提供者的基本代理人
• 定制工具和代理人授权
• 顺序、平行和表决管道
• 带有向量搜索的 RAG 应用程序
• 文档摄取和分解

由代理设计

• 马歇尔 开口重量的编码代理。 运行一个完全通过ella.cpp或Ollama在本地硬件上的规划员/编码员/审查员环路,不需要API密钥,账户,或云——有批准权的文件写作和 shell命令,并支持将本地模式和付费模式混合到角色之间.

捐款

欢迎捐款! 请打开一个问题或提交拉动请求.

链接

• 文档
• 吉特拉布语Name
• 无
• 问题