hello-agents-ts

HelloAgents 的 TypeScript 版本：一个轻量级多智能体框架，提供统一 LLM 客户端、常见 Agent 范式、工具调用、上下文工程、会话持久化和执行追踪能力。

本包移植自 Python 项目 HelloAgents。当前版本优先提供一个可安装、可导入、可验证的 Node.js CommonJS SDK。

English documentation: README.en.md

当前状态

已经实现并验证：

• CommonJS 包入口：import { ... } from "hello-agents-ts"
• OpenAI 兼容 LLM 适配器
• 四种 Agent 范式：SimpleAgent、ReActAgent、ReflectionAgent、PlanSolveAgent
• 工具系统：Tool、ToolRegistry、ToolResponse、熔断器和工具过滤器
• 内置工具：计算器、文件工具、子任务委托、todo、devlog、技能加载
• 上下文组件：历史管理、Token 计数、工具输出截断、上下文构建
• 会话持久化和执行追踪
• 构建、smoke tests、示例类型检查、打包后消费验证

已知限制：

• 当前可用的运行路径是 OpenAI-compatible 接口；AnthropicAdapter 和 GeminiAdapter 仍是占位实现，调用时会明确报错。
• 自动化测试覆盖还没有 Python 版本系统化。
• 当前 SDK 以 CommonJS 为主，尚未启用 ESM 双格式发布。

安装

npm install hello-agents-ts

如果是在本仓库内本地开发：

cd hello-agents-ts
npm install
npm run build

环境变量

创建 .env 文件，或在 shell 中设置以下环境变量：

LLM_API_KEY=your-api-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL_ID=gpt-4o
LLM_TIMEOUT=60

LLM_BASE_URL 可以指向任意 OpenAI 兼容接口，例如 OpenAI、DeepSeek、Qwen 兼容网关、Kimi 兼容网关，或本地 OpenAI 兼容服务。

SDK 默认不输出内部运行日志。如需查看 Agent、工具注册、追踪保存等内部日志，可在构造配置时设置 verbose: true：

const config = new Config({ verbose: true });

当向 Agent 传入 ToolRegistry 时，默认会按配置自动注册启用的内置工具：Task、TodoWrite、DevLog 和 Skill。如需关闭，可设置 subagentEnabled、todowriteEnabled、devlogEnabled、skillsEnabled 或 skillsAutoRegister 为 false。

快速开始

import { HelloAgentsLLM, SimpleAgent } from "hello-agents-ts";

async function main() {
  const llm = new HelloAgentsLLM();
  const agent = new SimpleAgent(
    "assistant",
    llm,
    "你是一个回答简洁、可靠的 AI 助手。"
  );

  const reply = await agent.run("用一句话解释 TypeScript。");
  console.log(reply);
}

main().catch(console.error);

自定义工具

import {
  HelloAgentsLLM,
  SimpleAgent,
  Tool,
  ToolParameter,
  ToolRegistry,
  ToolResponse,
} from "hello-agents-ts";

class WeatherTool extends Tool {
  name = "get_weather";
  description = "查询指定城市的天气。";

  getParameters(): ToolParameter[] {
    return [
      {
        name: "city",
        type: "string",
        description: "城市名称",
        required: true,
      },
    ];
  }

  run(params: Record<string, any>): ToolResponse {
    return ToolResponse.success(`${params.city}: 晴天，25C`);
  }
}

async function main() {
  const llm = new HelloAgentsLLM();
  const tools = new ToolRegistry();
  tools.registerTool(new WeatherTool());

  const agent = new SimpleAgent(
    "tool-agent",
    llm,
    "在有帮助时使用工具。",
    null,
    tools,
    true
  );

  const reply = await agent.run("北京天气怎么样？");
  console.log(reply);
}

main().catch(console.error);

Agent 范式

| Agent | 模式 | 适用场景 | |---|---|---| | SimpleAgent | 单轮响应，可选工具调用 | 对话、简单助手、直接工具使用 | | ReActAgent | Thought -> Action -> Observation 循环 | 多步推理和工具工作流 | | ReflectionAgent | 生成 -> 反思 -> 优化 | 写作、分析、需要质量提升的生成任务 | | PlanSolveAgent | 先规划，再逐步执行 | 复杂任务拆解 |

示例：

import { HelloAgentsLLM, ReActAgent, ToolRegistry } from "hello-agents-ts";

const llm = new HelloAgentsLLM();
const tools = new ToolRegistry();
const agent = new ReActAgent("react", llm, tools, null, null, 10);

const result = await agent.run("请一步步分析这个问题。");
console.log(result);

核心导出

包根入口就是公开 API：

import {
  HelloAgentsLLM,
  Config,
  Message,
  SimpleAgent,
  ReActAgent,
  ReflectionAgent,
  PlanSolveAgent,
  Tool,
  ToolRegistry,
  ToolResponse,
  HistoryManager,
  TokenCounter,
  ObservationTruncator,
  SessionStore,
  TraceLogger,
  SkillLoader,
} from "hello-agents-ts";

应用代码不要从内部 src/ 或 dist/ 路径导入。

示例

仓库内提供了可运行的 TypeScript 示例：

npx ts-node examples/01-quickstart.ts
npx ts-node examples/02-custom-tools.ts
npx ts-node examples/03-react-agent.ts
npx ts-node examples/04-all-agents.ts
npx ts-node examples/05-context-engineering.ts

这些示例使用包名导入：hello-agents-ts。本地类型检查通过 tsconfig.examples.json 将包名映射到 src/index.ts。

验证

npm run build
npm test
npm run typecheck:examples
npm run test:package
npm run pack:dry-run

这些命令分别验证：

• npm run build：将 TypeScript 编译到 dist/
• npm test：构建并针对 dist/ 运行 smoke tests
• npm run typecheck:examples：使用包名导入对所有示例做类型检查
• npm run test:package：打包 SDK，并验证 require("hello-agents-ts")
• npm run pack:dry-run：检查最终 npm 包内容

当前发布包只包含：

• dist/
• README.md
• LICENSE
• npm 打包时生成的 package.json

发布

发布前检查：

npm whoami
npm view hello-agents-ts name version
npm run prepack
npm run pack:dry-run

发布：

npm publish --access public

发布后确认：

npm view hello-agents-ts name version

Python 到 TypeScript 映射

| Python | TypeScript | |---|---| | from hello_agents import ReActAgent | import { ReActAgent } from "hello-agents-ts" | | agent.run("问题") | await agent.run("问题") | | for chunk in agent.stream_run(...) | for await (const chunk of agent.streamRun(...)) | | Pydantic 模型 | TypeScript class / interface | | dict | Record<string, any> | | Iterator / AsyncIterator | Generator / AsyncGenerator |

开发说明

• 源码位于 src/。
• 编译产物生成到 dist/。
• 根导出文件是 src/index.ts。
• 包使用者应只使用根包导入。
• 需要真实 LLM 的示例必须提供有效的 LLM_API_KEY、LLM_BASE_URL 和 LLM_MODEL_ID。

License

CC-BY-NC-SA-4.0