# @cognipeer/agent-sdk 中文文档

规范地址：https://npmcn.com/package/%40cognipeer/agent-sdk/

版本：0\.22\.2
npm 元数据更新时间：2026-11-03T09:40:25.144Z
中文译文更新时间：2026-11-10T12:31:58.200Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cognipeer/agent-sdk
原文对照：https://npmcn.com/package/%40cognipeer/agent-sdk/?lang=original
项目主页：https://docs.cognipeer.com/agent-sdk/
源码仓库：https://github.com/Cognipeer/agent-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.2 MB，18 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.17
- 运行依赖：4 个
- peer 依赖：langchain ^0\.3\.0 \|\| ^1\.0\.0，@langchain/aws ^0\.3\.0 \|\| ^1\.0\.0，@langchain/core ^0\.3\.0 \|\| ^1\.0\.0，@langchain/ollama ^0\.3\.0 \|\| ^1\.0\.0，@langchain/openai ^0\.3\.0 \|\| ^1\.0\.0，@langchain/anthropic ^0\.3\.0 \|\| ^1\.0\.0，@langchain/community ^0\.3\.0 \|\| ^1\.0\.0，@langchain/langgraph-sdk ^0\.3\.0 \|\| ^1\.0\.0，@langchain/google-vertexai ^0\.3\.0 \|\| ^1\.0\.0
- 首次发布：2025-09-26T13:34:47.322Z
- 最新版本发布：2026-11-03T09:40:24.602Z
- 近 30 天下载量：2665（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：80（近 12 个月 78 个）

## 中文简介

由可插件型号适配器所构成的轻量级智能代理核心(无LangGraph).

## 安装

```sh
npm install @cognipeer/agent-sdk
```

也可以使用：`pnpm add @cognipeer/agent-sdk`、`yarn add @cognipeer/agent-sdk`、`bun add @cognipeer/agent-sdk`

## README

# @ cognicepeer/ 代理服务器

**轻量级,信息首发TypeScript代理运行时间,适用于想要透明工具调用,规划和追踪的开发者.**

[![npm version](https://img.shields.io/npm/v/@cognipeer/agent-sdk)](https://www.npmjs.com/package/@cognipeer/agent-sdk) [![npm downloads](https://img.shields.io/npm/dm/@cognipeer/agent-sdk)](https://www.npmjs.com/package/@cognipeer/agent-sdk) [![license](https://img.shields.io/github/license/Cognipeer/agent-sdk)](https://npmcn.com/package/%40cognipeer/agent-sdk/LICENSE) [![docs](https://img.shields.io/badge/docs-docs.cognipeer.com-0A7CFF)](https://docs.cognipeer.com/agent-sdk/) [![GitHub stars](https://img.shields.io/github/stars/Cognipeer/agent-sdk?style=social)](https://github.com/Cognipeer/agent-sdk)

[文档](https://docs.cognipeer.com/agent-sdk/) • 妇女 [快开始](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-quick-start) • 妇女 [实例](https://npmcn.com/package/%40cognipeer/agent-sdk/examples/) • 妇女 [更改日志](https://npmcn.com/package/%40cognipeer/agent-sdk/CHANGELOG.md) • 妇女 [联系人](mailto:developer@cognipeer.com)

**通过:** cognipeer作为企业客户支持的近20家公司正在积极使用。 开源用户不在此计数中.

轻量级,信息第一代理运行时间,保持工具调用透明,支持提供者-内设推理外加工具后反射,自动总结出长历史,并有规划,多代理交接,结构化追踪的船舶.

-   SDK 来源 : `src/`
-   实例: `examples/`
-   Docs (视频): `docs/`
-   需要节点.js **18.17+ (中文(简体) )**

## 目录

-   [概览](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-overview)
-   [里面的东西](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-whats-inside)
-   [安装](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-install)
-   [快开始](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-quick-start)
    -   [智能代理(规划+汇总)](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-smart-agent-planning--summarization)
    -   [理由思考( R)](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-reasoning--reflection)
    -   [基干剂(最小环)](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-base-agent-minimal-loop)
-   [关键能力](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-key-capabilities)
-   [实例](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-examples)
-   [建筑快照](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-architecture-snapshot)
-   [API 表面](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-api-surface)
-   [追踪和可观察性](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-tracing--observability)
-   [发展](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-development)
-   [解决问题](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-troubleshooting)
-   [文档](https://npmcn.com/package/%40cognipeer/agent-sdk/#readme-documentation)

## 概览

`@cognipeer/agent-sdk` 是一个零图, TypeScript- first 代理环路。 工具调用持续作为消息,符号压力触发自动总和,可选规划模式强制TODO卫生与捆绑 `manage_todo_list` 工具。 多剂成分,结构化输出,分批追踪都是内置的.

要点 :

-   **信件首发设计** – 助理工具呼叫和工具响应留在笔录中.
-   **触觉总和** - 块块重写档案,显示工具输出过大 `get_tool_response` 用于无损失检索.
-   **规划模式** –适应系统即时+TODO工具支持完整的计划书写和版本安全的部分更新.
-   **统一推理表面** - 一个 `reasoning` 配置控制提供者-内在推理和后工具平文本反射.
-   **结构化产出** – 提供Zod schema,代理商会注入一个最终工具来决定性地捕获JSON.
-   **技能/逐步披露** - 先暴露廉价的能力头,然后按要求将技能工具与 `open_skill` 财务报告和审定财务报表 `bind_skill_tools`。 。 。 .
-   **多剂和分红** - 包装代理作为工具或转移控制 `asTool` 编号 : `asHandoff`。 。 。 .
-   **副代理人/动态代表团** - 让管弦乐师解析问题 `delegate_to` (登记), `spawn_subagent` 页:1 `spawn_subagents_parallel` (fan-out); 儿童为模型不可知和继承事件及取消接线(儿童文本流通过 `subagentPolicy.streamChildren`) (中文(简体) ). **选入 :** 产卵工具+ `<available_subagents>` 目录仅在您通过时才会出现 `subagents` 和(或) `subagentPolicy`。 。 。 .
-   **快速覆盖** - 拦截其他静态提示 `promptHooks` (单位:千美元)`transformSystemPrompt`, (中文(简体) ), `toolDescriptions`, (中文(简体) ), `subagentCatalog`) (中文(简体) ).
-   **人类的跳动** – 说吧 – `needsApproval` 用于审查的工具暂停; `humanInTheLoop.askUser` 启用内置 `ask_user_question` 工具以结构化多选择提示并恢复用户的回答.
-   **用法加活动** - 供应商正常使用,表面 `tool_call`, (中文(简体) ), `tool_approval`, (中文(简体) ), `user_question`, (中文(简体) ), `plan`, (中文(简体) ), `summarization`, (中文(简体) ), `reflection`, (中文(简体) ), `metadata`, (中文(简体) ), `handoff`,以及 `subagent` 事件.
-   **结构化追踪** – 可选的每个输入 JSON 有元数据、有效载荷捕获和可插接汇(文件、HTTP、Cognicepeer、自定义)的痕迹.

## 里面的东西

| 路径 | 说明 |
| --- | --- |
| `src/` | 已发布包的来源(TypeScript,通过tsup捆绑). |
| `examples/` | 端到端脚本显示工具,规划,归纳,多代理,MCP,结构化输出,和视觉输入. |
| `docs/` | VitePress 文件网站 [docs.cognitpeer.com/代理服务器 - sdk](https://docs.cognipeer.com/agent-sdk/)。 。 。 . |
| `dist/` | 构建输出( 生成) 。 包含无害环境管理、通用JS和类型脚本定义. |
| `logs/` | 生成跟踪会话当 `tracing.enabled: true`。安全删除. |

## 安装

安装 SDK 。 每个 `@langchain/*` 软件包(和 `langchain`是一个 _选项_ 依赖对等关系,除非您使用 LangChain 适配器,否则不会导入 LangChain :

```sh
npm install @cognipeer/agent-sdk zod
# Optional: LangChain bindings (if you want to use fromLangchainModel)
npm install @langchain/core @langchain/openai
```

SDK包括一个内置的本土供应商层,直接与OpenAI,Anthropic,Azure,Bedrock,Vertex,以及任何OpenAI相容的API对话——不需要LangChain.

你也可以带自己的模型适配器 只要它暴露 `invoke(messages[])` 和(可选) `bindTools()`。 。 。 .

## 快开始

### 本地供应商( 无 LangChain)

```ts
import { createSmartAgent, createTool, createProvider, fromNativeProvider } from "@cognipeer/agent-sdk";
import { z } from "zod";

const echo = createTool({
  name: "echo",
  description: "Echo back user text",
  schema: z.object({ text: z.string() }),
  func: async ({ text }) => ({ echoed: text }),
});

// Pick any provider – OpenAI, Anthropic, Azure, Bedrock, Vertex, or OpenAI-compatible
const model = fromNativeProvider(
  createProvider({ provider: "openai", apiKey: process.env.OPENAI_API_KEY! }),
  { model: "gpt-4o" },
);

const agent = createSmartAgent({ model, tools: [echo], runtimeProfile: "balanced" });
const result = await agent.invoke({ messages: [{ role: "user", content: "say hi" }] });
console.log(result.content);
```

通过更改单个配置行切换提供者 :

```ts
// Anthropic
createProvider({ provider: "anthropic", apiKey: process.env.ANTHROPIC_API_KEY! })

// Azure OpenAI
createProvider({ provider: "azure", apiKey: "...", endpoint: "https://my-resource.openai.azure.com", deploymentName: "gpt-4o" })

// AWS Bedrock
createProvider({ provider: "bedrock", region: "us-east-1", accessKeyId: "...", secretAccessKey: "..." })  // streams via ConverseStream

// Google Vertex AI
createProvider({ provider: "vertex", projectId: "my-project", accessToken: process.env.VERTEX_TOKEN })  // retry on 429/5xx, thoughtSignature round-trip; reasoning.thinkingLevel for Gemini 3

// Any OpenAI-compatible endpoint (Ollama, Groq, Together, vLLM, …)
createProvider({ provider: "openai-compatible", apiKey: "...", baseURL: "https://custom.endpoint/v1" })
```

### 嵌入层

每个有嵌入点的提供者都会暴露 `embed()`。它返回每个输入一个向量,顺序,加上符号使用:

```ts
const provider = createProvider({ provider: "openai", apiKey: process.env.OPENAI_API_KEY! });
const { vectors, usage } = await provider.embed({
  model: "text-embedding-3-small",
  input: ["first text", "second text"],
  dimensions: 256,          // models that support shortening
  inputType: "search_query" // Cohere on Bedrock, task type on Vertex
});
```

| 提供者 | 终点 | 页:1 |
| --- | --- | --- |
| `openai`, (中文(简体) ), `openai-compatible` | `POST /embeddings` | 已分批(2048年), `encodingFormat: "base64"` 已解码 |
| `azure` | `/openai/deployments/{model}/embeddings` | `model` 是部署名称 |
| `bedrock` | `InvokeModel` | 土卫一文字嵌入 v1/v2, Cohere 嵌入 v3/v4 |
| `vertex` | `:predict` | 文本集成,多语种, `gemini-embedding` |

### 网关使用

对于用自己的网关在供应商前面的主机: `ChatCompletionRequest` 带 `streamUsage`, (中文(简体) ), `seed`, (中文(简体) ), `n`, (中文(简体) ), `parallelToolCalls`, (中文(简体) ), `logprobs` 财务报告和审定财务报表 `topLogprobs`; 响应和流块保持提供者的 `rawFinishReason` 财务报告和审定财务报表 `providerFields` (单位:千美元)`system_fingerprint`, (中文(简体) ), `service_tier`, (中文(简体) ), `annotations`, (中文(简体) ), `refusal`, (中文(简体) ), `logprobs`);流出工具调用三角洲带入一个 `index`在贝德洛克, `extra` 非逆向请求字段的密钥 `additionalModelRequestFields`。 。 。 .

### 智能代理(规划+汇总)

```ts
import { createSmartAgent, createTool, fromLangchainModel } from "@cognipeer/agent-sdk";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

const echo = createTool({
  name: "echo",
  description: "Echo back user text",
  schema: z.object({ text: z.string().min(1) }),
  func: async ({ text }) => ({ echoed: text }),
  maxExecutionsPerRun: null,
});

const model = fromLangchainModel(new ChatOpenAI({
  model: "gpt-4o-mini",
  apiKey: process.env.OPENAI_API_KEY,
}));

const agent = createSmartAgent({
  name: "ResearchHelper",
  model,
  tools: [echo],
  runtimeProfile: "balanced",
  planning: { mode: "todo", replanPolicy: "on_failure" },
  memory: { provider: "inMemory", scope: "session", writePolicy: "auto_important" },
  summarization: { summaryTriggerTokens: 8000, summaryMode: "incremental" },
  context: { policy: "hybrid", lastTurnsToKeep: 8 },
  toolResponses: {
    defaultPolicy: "summarize_archive",
    toolResponseRetentionByTool: { read_skills: "keep_full" },
    maxToolResponseChars: 4000,
    maxToolResponseTokens: 1200,
  },
  limits: { maxToolCalls: 5, maxContextTokens: 12000 },
  tracing: { enabled: true },
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "plan a greeting and send it via the echo tool" }],
  toolHistory: [],
});

console.log(result.content);
```

工具响应保留是懒惰和总结驱动的:

-   工具输出以完全忠诚的方式存储在 `state.toolHistory` 绝不减少.
-   当摘要运行( 已到达文本限制) 时, 按照 `defaultPolicy` (默认 : `summarize_archive`) (中文(简体) ). 整个有效载荷仍可通过 `get_tool_response` 使用嵌入在占位符中的执行id.
-   `toolResponseRetentionByTool` 让您选择特定工具退出还原(例如). `read_skills: "keep_full"`) (中文(简体) ).
-   `criticalTools` 永远不会减少。 内置列表涵盖 `response`, (中文(简体) ), `manage_todo_list`,以及 `get_tool_response`。 。 。 .
-   `maxToolResponseChars` 编号 : `maxToolResponseTokens` 只有在一个工具输出足够大 足以炸掉下一个模型调用时 才能驱动急切的硬盖截取器 短发头总是指向 `get_tool_response` 为了康复.

智能包装器现在支持运行时间预设( S)`fast`, (中文(简体) ), `balanced`, (中文(简体) ), `deep`, (中文(简体) ), `research`),自定义剖面图分层于一个基础预设、结构化归纳、混合上下文收缩、基于技能的渐进披露、可配置工具-响应保留、记忆事实存储、授权限制和通过 `runSmartAgentEvalHarness(...)`。 。 。 .

大型或可选工具目录, 可通过 `skills` 而不是直接绑定每个工具 :

```ts
import { createSmartAgent, type Skill } from "@cognipeer/agent-sdk";

const pdfSkill: Skill = {
  key: "builtin:pdf",
  title: "PDF",
  header: "read and summarize PDF files when the user references a PDF",
  prompt: "Use pdf_read before pdf_summarize and preserve file ids in the answer.",
  listToolIndex: () => [
    { name: "pdf_read", description: "Extract PDF text by file id" },
    { name: "pdf_summarize", description: "Summarize extracted PDF text" },
  ],
  bindTools: (names) => bindPdfTools(names),
};

const agent = createSmartAgent({
  model,
  skills: [pdfSkill],
  skillPolicy: { maxOpenSkills: 2, maxBoundToolsPerSkill: 8, maxBoundToolsTotal: 24 },
});
```

模特儿先看技能头. 它召唤 `open_skill` 并立即绑定小技能, 或者获得工具索引 `bind_skill_tools`。 。 。 .

您也可以通过扩展一个内置的预设并仅覆盖您需要的接头来定义自定义配置 :

```ts
const agent = createSmartAgent({
  name: "CustomPlanner",
  model,
  runtimeProfile: "custom",
  customProfile: {
    extends: "balanced",
    limits: { maxToolCalls: 10, maxContextTokens: 18000 },
    planning: { mode: "todo" },
    context: { lastTurnsToKeep: 10 },
    memory: { writePolicy: "manual" },
  },
});
```

### 理由思考( R)

两者 `createAgent(...)` 财务报告和审定财务报表 `createSmartAgent(...)` 接受统一的 `reasoning` 配置 :

```ts
const agent = createSmartAgent({
  model: fromNativeProvider(
    createProvider({ provider: "openai", apiKey: process.env.OPENAI_API_KEY! }),
    { model: "gpt-5" },
  ),
  tools: [echo],
  reasoning: {
    enabled: true,
    level: "high",
    native: { effort: "high" },
    reflection: {
      cadence: "after_tool",
      mode: "piggyback",
      maxTokens: 450,
      keepLast: 4,
      summarize: false,
    },
  },
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Research the repo and propose the next implementation step." }],
}, {
  onEvent(event) {
    if (event.type === "reflection") {
      console.log("reflection:", event.text);
    }
  },
});

console.log(result.state?.reflections?.at(-1)?.text);
```

这有什么作用:

-   `reasoning.native` 通过本地提供者层, 传递特定提供者的推理键 .
-   `reasoning.reflection` 在限定转会后增加一个简短的倒影,而不将该音符作为普通的助理信息.
-   反省笔记持续存在 `result.state.reflections`; 只有最后一个 `keepLast` 作为合成系统上下文重注入下一个提示.

仅使用实际支持提供者-内在推理的模型/端点. 不支持的模型通常返回一个提供者错误,而不是默默地贬低.

### 基干剂(最小环)

偏好一个没有系统即时或总结的微小核? 使用 `createAgent`数字 :

```ts
import { createAgent, createTool, fromLangchainModel } from "@cognipeer/agent-sdk";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";

const echo = createTool({
  name: "echo",
  description: "Echo back",
  schema: z.object({ text: z.string().min(1) }),
  func: async ({ text }) => ({ echoed: text }),
});

const model = fromLangchainModel(new ChatOpenAI({ model: "gpt-4o-mini", apiKey: process.env.OPENAI_API_KEY }));

const agent = createAgent({
  model,
  tools: [echo],
  limits: { maxToolCalls: 3, maxParallelTools: 2 },
});

const res = await agent.invoke({ messages: [{ role: "user", content: "say hi via echo" }] });
console.log(res.content);
```

## 关键能力

-   **原生提供者层** – 直接呼叫OpenAI,Anthropic,Azure,Bedrock,Vertex,以及任何OpenAI相容的API. 不需要兰钱 统一 `ChatCompletionRequest` 编号 : `ChatCompletionResponse` 每条线格式转换的图案.
-   **全信追踪** - 每个反应都浮出水面 `inputTokens`, (中文(简体) ), `outputTokens`, (中文(简体) ), `cachedInputTokens`, (中文(简体) ), `cachedWriteTokens`,以及 `reasoningTokens` 供六供养.
-   **统一推理控制** - 允许提供者-本土推理(`reasoning.native`)和后工具反思(`reasoning.reflection`)从一个相貌表面.
-   **汇总管道** - 自动分块将工具调用历史保存在内部 `contextTokenLimit` 编号 : `summaryTokenLimit`原始文件存档 `get_tool_response` 晚点再去取.
-   **保留管制** – 工具输出可以保持完整,被缩小为结构化预览,归档,或者根据大小级,关键工具倒置,每个工具的覆盖,以及最近的反应平接来降.
-   **规划纪律** – 当规划被启用时,系统即时区分完整计划写作与增量计划更新并发布 `plan` 更改待办事宜的事件.
-   **结构化产出** - 供应 `outputSchema` 和框架添加隐藏 `response` 定稿工具;解析的 JSON 返回为 `result.output`。 。 。 .
-   **多剂管弦乐** - 通过再利用剂 `agent.asTool({ toolName })` 或执行交割 交换运行时间中执行.
-   **副代理人** -通过 `subagents` 编号 : `subagentPolicy` 给管弦乐手 `delegate_to`, (中文(简体) ), `spawn_subagent`,以及 `spawn_subagents_parallel`;孩子继承了父母模式+可观察性,表面人-在-在-在-在-为透明恢复而暂停. 见 [子代理指南](https://npmcn.com/package/%40cognipeer/agent-sdk/docs/guide/sub-agents.md)。 。 。 .
-   **询问用户** - 选择与 `humanInTheLoop: { askUser: true }` 给模型一个 `ask_user_question` 暂停运行的工具;通过调用恢复 `agent.resolveUserQuestion(state, { id, answers })`全球 `allowFreeText` 旗帜控制是否允许“ 其他” / 输入答案 .
-   **MCP + LangChain 工具** - 任何满足最小工具界面的物件都有效;LangChain的 `Tool` 直接插入执行.
-   **远景投入** – 消息部分接受基数64或URL图像用于多模式请求.
-   **观测钩** – 说吧 – `config.onEvent` surfaces 工具生命周期, 汇总, 反射, 元数据, 以及流式 UI 或 CLI 的最终解答事件 .

## 实例

实例 `examples/` 与每个文件夹的 README 。 首先构建软件包( E)`npm run build` 或者说 `npm run preexample:<name>`) (中文(简体) ).

| 文件夹 | 焦点 |
| --- | --- |
| `basic/` | 最小工具呼叫与真正的模型运行. |
| `tools/` | 多工具,Tavily搜索集成, `onEvent` 用途. |
| `tool-limit/` | 启动全球工具呼叫封顶并敲定行为. |
| `todo-planning/` | 智能规划工作流程与已执行的 TODO 更新. |
| `summarization/` | 托肯-门槛总合走过. |
| `summarize-context/` | 总结+ `get_tool_response` 原始检索. |
| `structured-output/` | Zod schema 最后确定工具并解析输出. |
| `rewrite-summary/` | 插入摘要后继续对话 . |
| `ask-user/` | 内建 `ask_user_question` 工具,结构化多选择即时,随用户的回答而恢复. |
| `multi-agent/` | 代理人之间通过 `asTool`。 。 。 . |
| `sub-agents/` | 动态分解 : `delegate_to`, (中文(简体) ), `spawn_subagent`, (中文(简体) ), `spawn_subagents_parallel`。 。 。 . |
| `handoff/` | 明确时间交接. |
| `mcp-tavily/` | MCP远程工具发现. |
| `vision/` | 文字+图像输入使用 LangChain 的 OpenAI 绑定. |

举例来说:

```bash
# Install root dependencies
npm install

# Install example dependencies
cd examples
npm install

# Run an example from the examples directory
npm run example:basic
npm run example:tools
npm run example:multi-agent
```

或者用 tsx 直接运行 :

```bash
# From examples directory
OPENAI_API_KEY=... npx tsx basic/basic.ts
```

## 建筑快照

代理是一个决定性的while-loop – 没有外部图运行时间. 每一回合通过:

1.  **解析器** - 正常状态(消息、计数器、限制).
2.  **上下文** (可选) – 当符号估计值超过活动总和阈值时,归档重工具输出.
3.  **代理人** - 引用模型(支持时具有约束力的工具).
4.  **工具** - 执行具有可配置平行性的拟议工具呼叫.
5.  **反映** (可选) – 在工具转换后附加纯文本反射 `reasoning.reflection` 已启用.
6.  **工具Limit 定稿** – 如果被打出工具调用盖,请注入系统通知,所以下一位助手必须直接回答.

当助手在没有工具调用的情况下生成消息,观察到结构化的输出完成信号,或者进行交接转移控制时,循环停止. 见 `docs/architecture/README.md` 用于图和高压.

## API 表面

导出助手( E)`agent-sdk/src/index.ts`:

**代理工厂:**

-   `createSmartAgent(options)`
-   `createAgent(options)`
-   `createTool({ name, description?, schema, func, needsApproval?, approvalPrompt?, approvalDefaults?, maxExecutionsPerRun?, cache?, retry? })`

**本地供应商( 无 LangChain ):**

-   `createProvider(config)` - 所有六个供应商的工厂
-   `fromNativeProvider(provider, options?)` - 包装一个提供者作为一个 `BaseChatModel`
-   `OpenAIProvider`, (中文(简体) ), `AnthropicProvider`, (中文(简体) ), `AzureProvider`, (中文(简体) ), `OpenAICompatibleProvider`, (中文(简体) ), `BedrockProvider`, (中文(简体) ), `VertexProvider`
-   类型 : `ChatCompletionRequest`, (中文(简体) ), `ChatCompletionResponse`, (中文(简体) ), `TokenUsage`, (中文(简体) ), `ProviderConfig`, (中文(简体) ), `ReasoningConfig`, (中文(简体) ), `ReflectionRecord`, (中文(简体) ), `ReflectionEvent`

**LangChain 适配器( 可选) :**

-   `fromLangchainModel(model)`
-   `withTools(model, tools)`
-   `fromLangchainTools(tools)`

**公用事业:**

-   `buildSystemPrompt(extra?, planning?, name?)`
-   `setTokenCounter`, (中文(简体) ), `getTokenCounter`, (中文(简体) ), `defaultTokenCounter` – 在全球或每台中换取真实的代币(tiktoken等)
-   `resolveToolApprovalState`, (中文(简体) ), `resolveUserQuestionState` - 后面的纯粹的助手 `agent.resolveToolApproval` 编号 : `agent.resolveUserQuestion` 对于想在代理厂外应用解决方案的呼叫者.
-   `createAskUserQuestionTool(stateRef, { allowFreeText, promptOverride })` - 供高级用户使用,这些用户希望手动附加人行工具而不是通过 `humanInTheLoop.askUser`。 。 。 .
-   节点工厂`nodes/*`),上下文帮助器,符号工具,以及全类型脚本类型(`SmartAgentOptions`, (中文(简体) ), `SmartState`, (中文(简体) ), `AgentInvokeResult`, (中文(简体) ), `PendingUserQuestion`, (中文(简体) ), `UserQuestionResolution`(见a/c.5/49/70,附件).

`SmartAgentOptions` 接受通常的嫌疑人(`model`, (中文(简体) ), `tools`, (中文(简体) ), `limits`, (中文(简体) ), `runtimeProfile`, (中文(简体) ), `customProfile`, (中文(简体) ), `useTodoList`, (中文(简体) ), `summarization`, (中文(简体) ), `reasoning`, (中文(简体) ), `usageConverter`, (中文(简体) ), `tracing`, (中文(简体) ), `tokenCounter`, (中文(简体) ), `costEstimator`) (中文(简体) ). 见 `docs/api/` 详细类型参考.

**预算表面** (单位:千美元)`limits`:

-   `maxToolCalls`, (中文(简体) ), `maxParallelTools`, (中文(简体) ), `maxContextTokens` - 经典循环预算
-   `maxTotalOutputTokens` - 累计完成令牌上限
-   `maxCostUsd` - 累计美元费用(要求) `costEstimator`(中文(简体) )
-   `maxWallClockMs` - 全面时钟预算(另见 `InvokeConfig.timeoutMs`(中文(简体) )

**工具级控制** (单位:千美元)`createTool`:

-   `maxExecutionsPerRun` - 将这一工具的顺利执行限制在一跑内
-   `cache` – 选入每输入结果缓存(`true` 或者说 `{ keyFn?, ttlMs? }`(中文(简体) )
-   `retry` - 每工具重试政策 `{ maxRetries?, backoffMs?, shouldRetry?, circuitBreakerThreshold? }`

**供应商一级的控制** (单位:千美元)`createProvider`:

-   `retry` - 自动429 / 5xx 重试,以指数回放和 `Retry-After` 支助
-   `prompt_caching: { enabled: true, strategy?, ttl? }` - 人类 `cache_control` 和贝德洛克 `cachePoint` 系统即时和工具上的断点;默认 `strategy: "auto"` 还缓存不断增长的对话(Anthropic自动缓存、滚动的Bedrock检查站), `"static"` 仅保留固定前缀; `ttl: "1h"` 在电话之间长时间暂停。 缓存读取长工具重跑的输入价格的一小部分

## 追踪和可观察性

以通过方式启用追踪 `tracing: { enabled: true }`每次引用都写着 `trace.session.json` 输入 `logs/<SESSION_ID>/` 详细说明:

-   模型/提供者、代理名称/版本、限制和计时元数据
-   模拟呼叫、工具处决、摘要、反思和错误的结构化事件
-   何时可选择的有效载荷捕获(请求/响应/工具机构) `logData` 实值 `true`
-   仪表板的汇总符号使用、字节计数和错误摘要

您可以禁用有效载荷捕获 `logData: false` 或配置汇,例如 `httpSink(url, headers?)`, (中文(简体) ), `cognipeerSink(apiKey, url?)`, (中文(简体) ), `otlpSink(endpoint, headers?)`,或 `customSink({ onEvent, onSession })` 在每次运行后转发痕迹。 敏感的信头/召回信头仍为记忆中,从未被写在痕迹上.

每个会话/活动还载有与OTel兼容的关联识别符(`traceId`, (中文(简体) ), `rootSpanId`, (中文(简体) ), `spanId`, (中文(简体) ), `parentSpanId`) (中文(简体) ). `otlpSink` 编辑 `otelTracing` 插件导出为 OpenTeleometry GenAI 跨度(`invoke_agent`, (中文(简体) ), `chat`, (中文(简体) ), `execute_tool`超过OTLP/HTTP JSON或原生出,并带有标准 `OTEL_*` 变量、可选即时/应答捕获和W3C `traceparent` 传播。 见 [打开几何指南](https://npmcn.com/package/%40cognipeer/agent-sdk/docs/guide/opentelemetry.md)。 。 。 .

过 `tracing: { metadata: { ... } }` 以附加任意键值标记(例如). `{ complexity: "complex" }`送入水槽的每一有效载荷。 SDK并不解释这些标记本身——它们被转发为-是使下游消费者(如Console)可以把它们用作报告/分配维度.

## 发展

安装依赖关系并构建软件包 :

```sh
cd agent-sdk
npm install
npm run build
```

从 repo 根可以运行 `npm run build` (包的代表)或使用 `npm run example:<name>` 脚本定义于 `package.json`。 。 。 .

### 测试

```sh
npm test               # all mock-based tests (no API key)
npm run test:coverage  # v8 coverage + enforced thresholds
npm run test:critical  # critical-feature integration suite
npm run test:real      # real OpenAI  (OPENAI_API_KEY)
npm run test:matrix    # real-provider matrix (per-provider keys; skips without)
```

模拟套房是决定性的,无密钥. 选入 **提供者矩阵** (单位:千美元)`tests/integration/providerMatrix.integration.test.ts`)对有证书的任何供应商执行同样的合同——工具调用、结构化产出、流出(`OPENAI_API_KEY`, (中文(简体) ), `ANTHROPIC_API_KEY`, Azure/Bedrock/Vertex vars)并跳过其余. 公众 **电子控制仪** (单位:千美元)`runSmartAgentEvalHarness`在所有运行时间配置中评分行为质量。 见 [测试和评价指南](https://npmcn.com/package/%40cognipeer/agent-sdk/docs/guide/testing.md) 财务报告和审定财务报表 [`tests/README.md`](https://npmcn.com/package/%40cognipeer/agent-sdk/tests/README.md)。 。 。 .

### 出版

只发布 `agent-sdk/`数字 :

```sh
cd agent-sdk
npm version <patch|minor|major>
npm publish --access public
```

`prepublishOnly` 确保在发布前有新的构建.

## 解决问题

-   **缺少工具调用** - 确保您的模型支持 `bindTools`如果没有,请用 `withTools(model, tools)` 提供最好的行为.
-   **总结太过分了** - 调整 `limits.maxToken`, (中文(简体) ), `contextTokenLimit`,以及 `summaryTokenLimit`,或以 `summarization: false`。 。 。 .
-   **大工具响应** - 返回结构化有效载荷并依赖 `get_tool_response` 用于原始数据,而不是向内倾出兆字节.
-   **用法缺失** - 一些提供者不报告使用情况;自定义 `usageConverter` 使专有形状正常化.

## 文档

-   现场: [https://docs.cognippeer.com/agent-sdk/ 页面存档备份,存于互联网档案馆](https://docs.cognipeer.com/agent-sdk/)
-   此重置范围内的关键指南 :
    -   `docs/getting-started/`
    -   `docs/core-concepts/`
    -   `docs/architecture/`
    -   `docs/api/`
    -   `docs/tools/`
    -   `docs/examples/`
    -   `docs/debugging/`
    -   `docs/limits-tokens/`
    -   `docs/tool-development/`
    -   `docs/faq/`

欢迎捐款! 公开发行或公关反对 `main` 包含报告错误时的复制细节.

## 认知开源项目

| 项目 | 它会做什么 |
| --- | --- |
| [认知控制台](https://github.com/Cognipeer/console) | 自办AI网关和控制平面:与OpenAI兼容的路由、RAG、MCP枢纽、护栏和代理追踪 |
| [控制台 sdk](https://github.com/Cognipeer/console-sdk) | 用于 Cognpeer 控制台的 SDK 类型脚本 SDK API |
| [代理服务器](https://github.com/Cognipeer/agent-server) | AI 代理的 REST API 层 |
| [闲聊](https://github.com/Cognipeer/chat-ui) | AI 代理机的回放聊天 UI 组件 |
| [标记](https://github.com/Cognipeer/to-markdown) | 将 PDF 、 Office 、 HTML 等转换为 LLM 管道的 Markdown |
| [图形构建器](https://github.com/Cognipeer/graph-builder) | 将文本源变成可查询的图表 |
| [可识别性](https://github.com/Cognipeer/cognipeer-observability) | LangChain、LangGraph、OpenAI 代理和OpenTeleometry的投放代理追踪 |

如果此工程对您有用, GitHub 上的 QQ 会帮助其他开发者找到它 .

问题或企业支助: [开发者@ cognippeer.com](mailto:developer@cognipeer.com)。 。 。 .

## 常见问题

### @cognipeer/agent-sdk 是什么？

由可插件型号适配器所构成的轻量级智能代理核心\(无LangGraph\)\.

### 如何安装 @cognipeer/agent-sdk？

在项目目录运行 npm install @cognipeer/agent-sdk，或使用 pnpm add / yarn add / bun add。

### @cognipeer/agent-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cognipeer/agent-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @cognipeer/agent-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.17。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cognipeer/agent-sdk 可以商用吗？

@cognipeer/agent-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cognipeer/agent-sdk 的下载量有多少？

根据 npm 官方下载统计，@cognipeer/agent-sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,665 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cognipeer/agent-sdk 还在维护吗？

最新版本 0\.22\.2 发布于 2026/11/03（7 天前）；至今共发布 80 个版本，其中过去 12 个月发布了 78 个；首次发布于 2025/09/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。