{"id":31877796,"url":"https://github.com/reuac/reagentbuilder","last_synced_at":"2025-10-12T23:25:54.229Z","repository":{"id":314029497,"uuid":"1053857275","full_name":"reuAC/reAgentBuilder","owner":"reuAC","description":"An enterprise-grade AI agent framework based on LangChain and LangGraph, featuring dynamic tools, interceptors, breakpoints, and performance monitoring.","archived":false,"fork":false,"pushed_at":"2025-09-10T04:31:12.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-12T14:59:09.758Z","etag":null,"topics":["agent-framework","agent-framework-javascript","ai-agents","ai-agents-framework","debugging-tools","interceptor","langchain","langchain-js","langgraph","langgraph-js","llm","multi-agent-systems","nodejs","observability","tool-calling","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/reuAC.png","metadata":{"files":{"readme":"README-CN.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-10T03:15:26.000Z","updated_at":"2025-09-10T05:41:17.000Z","dependencies_parsed_at":"2025-09-10T07:20:35.068Z","dependency_job_id":null,"html_url":"https://github.com/reuAC/reAgentBuilder","commit_stats":null,"previous_names":["reuac/reagentbuilder"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/reuAC/reAgentBuilder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reuAC%2FreAgentBuilder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reuAC%2FreAgentBuilder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reuAC%2FreAgentBuilder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reuAC%2FreAgentBuilder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/reuAC","download_url":"https://codeload.github.com/reuAC/reAgentBuilder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/reuAC%2FreAgentBuilder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013465,"owners_count":26085274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agent-framework-javascript","ai-agents","ai-agents-framework","debugging-tools","interceptor","langchain","langchain-js","langgraph","langgraph-js","llm","multi-agent-systems","nodejs","observability","tool-calling","typescript"],"created_at":"2025-10-12T23:25:48.985Z","updated_at":"2025-10-12T23:25:54.223Z","avatar_url":"https://github.com/reuAC.png","language":"TypeScript","readme":"# ReAgentBuilder\n\nReAgentBuilder 是一个基于 LangChain 和 LangGraph 构建的智能体框架，旨在为需要高度可控性、可观测性和扩展性的企业级 AI 应用提供坚实的基础。它集成了完整的生命周期管理、动态工具系统、拦截器与断点调试、并发控制、错误处理以及性能监控能力。\n\n[English](./README.md)\n\n## 核心特性\n\n*   **动态工具管理**: 支持在运行时动态添加、查询、替换工具集，并能将一个完整的智能体封装为另一个智能体的工具，实现复杂工作流的组合。\n*   **拦截器系统**: 提供在智能体执行生命周期的关键节点（如模型调用前、工具执行前后、任务完成时）注入自定义逻辑的能力，以修改数据流或执行附加操作。\n*   **断点调试系统**: 允许在执行过程中的任何关键点设置断点，用于观察实时状态、调试逻辑，且支持异步处理以避免阻塞主流程。\n*   **性能与资源管理**: 内置全面的性能监控模块，提供计时器、计数器和内存快照功能。通过并发控制、智能缓存和显式的资源清理机制，确保应用的稳定性和效率。\n*   **状态管理与持久化**: 利用 LangGraph 的检查点（Checkpointer）机制，支持多轮对话的上下文记忆和线程安全的状态隔离。默认使用内存存储，并可扩展至持久化后端。\n*   **健壮的错误处理**: 集成了统一的错误处理系统，能够对错误进行分类、记录详细上下文，并支持自动重试策略，增强了系统的可靠性。\n\n## 技术架构\n\n### 核心依赖\n\n*   **@langchain/core**: 提供核心抽象、消息类型和工具定义。\n*   **@langchain/langgraph**: 负责状态图的构建和工作流管理。\n*   **@langchain/openai, @langchain/anthropic**: 支持主流大型语言模型。\n*   **zod**: 用于工具输入模式的定义和验证。\n\n### 模块结构\n\n```\nreagentbuilder/\n├── types/              # 类型定义模块 (Agent, LLM, Interceptor, Breakpoint)\n├── core/               # 核心工具模块 (Logger, LLMFactory, Performance, ErrorHandler)\n├── agent/              # Agent 功能模块 (ReAgentBuilder, InterceptorManager, BreakpointManager)\n└── utils/              # 公共工具函数 (当前为空)\n```\n\n## 安装\n\n### 环境要求\n*   Node.js \u003e= 16.0.0\n\n### 安装依赖\n```bash\n# 使用 npm\nnpm install reagentbuilder\n\n# 使用 pnpm\npnpm add reagentbuilder\n\n# 使用 yarn\nyarn add reagentbuilder\n```\n\n## 快速开始\n\n### 导入方式\n\n#### 完整导入 (推荐)\n```typescript\nimport { ReAgentBuilder } from 'reagentbuilder';\nimport { LLMFactory, Logger, ErrorHandler } from 'reagentbuilder';\nimport type { AgentConfig, LLMConfig, InterceptorConfig, BreakpointConfig } from 'reagentbuilder';\n```\n\n#### 模块化导入 (高级)\n要使用模块化路径导入，请确保项目构建配置（如 `package.json` 中的 `exports` 字段）能够正确解析这些子路径。\n```typescript\nimport { ReAgentBuilder } from 'reagentbuilder/agent';\nimport { Logger } from 'reagentbuilder/core';\nimport type { AgentConfig } from 'reagentbuilder/types';\n```\n\n### 默认配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `memory` | `true` | 是否启用对话记忆。 |\n| `systemPrompt` | `undefined` | 系统提示词。如果未设置，则不向模型传递任何系统级指令。 |\n| `tools` | `[]` | 工具列表，默认为空数组。 |\n| `interceptors.enabled` | `false` | 拦截器系统默认关闭。 |\n| `breakpoints.enabled` | `false` | 断点系统默认关闭。 |\n| `llm.*` | (依赖模型) | `temperature`、`maxTokens`等参数的默认值由底层LangChain模型提供。 |\n| `concurrency.*`| `interceptors: 10`, `breakpoints: 5` | 拦截器和断点的最大并发数。 |\n\n### TypeScript 使用示例\n\n```typescript\nimport { ReAgentBuilder } from 'reagentbuilder';\nimport { tool } from '@langchain/core/tools';\nimport { z } from 'zod';\n\n// 1. 定义工具\nconst calculatorTool = tool(\n  async (input: { a: number; b: number; operation: 'add' | 'multiply' }) =\u003e {\n    const { a, b, operation } = input;\n    switch (operation) {\n      case 'add': return `${a} + ${b} = ${a + b}`;\n      case 'multiply': return `${a} * ${b} = ${a * b}`;\n      default: return 'Unsupported operation';\n    }\n  },\n  {\n    name: 'calculator',\n    schema: z.object({\n      a: z.number().describe('第一个数字'),\n      b: z.number().describe('第二个数字'),\n      operation: z.enum(['add', 'multiply']).describe('运算类型'),\n    }),\n    description: '执行基本的数学运算',\n  }\n);\n\n// 2. 配置并创建智能体\nconst agent = new ReAgentBuilder({\n  name: 'math-agent',\n  systemPrompt: '你是一个数学计算助手。',\n  llm: {\n    provider: 'openai',\n    model: 'gpt-4',\n    apiKey: process.env.OPENAI_API_KEY,\n  },\n  tools: [calculatorTool],\n  memory: true // 显式启用记忆\n});\n\n// 3. 执行智能体\nasync function main() {\n  const result = await agent.run('请计算 15 乘以 8 的结果', 'thread-1');\n  if (result) {\n    const lastMessage = result.messages[result.messages.length - 1];\n    console.log('Final Result:', lastMessage.content);\n  }\n}\n\nmain();\n```\n\n### JavaScript (ES Module) 使用示例\n\n```javascript\n// main.js\n// 确保 package.json 中已设置 \"type\": \"module\"\nimport { ReAgentBuilder } from 'reagentbuilder';\nimport { tool } from '@langchain/core/tools';\nimport { z } from 'zod';\n\n// 1. 定义工具\nconst weatherTool = tool(\n  async (input) =\u003e {\n    const weatherData = { '北京': '晴天', '上海': '多云' };\n    return weatherData[input.city] || `无法获取${input.city}的天气`;\n  },\n  {\n    name: 'weather',\n    schema: z.object({ city: z.string().describe('城市名称') }),\n    description: '查询指定城市的天气信息',\n  }\n);\n\n// 2. 配置并创建智能体\nconst agent = new ReAgentBuilder({\n  name: 'js-demo-agent',\n  systemPrompt: '你是一个智能助手。',\n  llm: {\n    provider: 'openai',\n    model: 'gpt-4',\n    apiKey: process.env.OPENAI_API_KEY,\n  },\n  tools: [weatherTool],\n});\n\n// 3. 执行智能体\nasync function main() {\n  const result = await agent.run('查询北京的天气', 'thread-js-1');\n  if (result) {\n    const lastMessage = result.messages[result.messages.length - 1];\n    console.log('Final Result:', lastMessage.content);\n  }\n}\n\nmain();\n```\n\n## 高级配置\n\n### 拦截器与断点配置\n\n```typescript\nimport { ReAgentBuilder } from 'reagentbuilder';\nimport type { InterceptorConfig, BreakpointConfig } from 'reagentbuilder';\n\n// 配置拦截器系统\nconst interceptorConfig: InterceptorConfig = {\n  enabled: true,\n  core: {\n    beforeModelInvoke: async (messages, state) =\u003e {\n      console.log('Interceptor: Modifying model input.');\n      return messages;\n    },\n  },\n  global: {\n    beforeToolCall: async (toolCall, state) =\u003e {\n      console.log(`Interceptor: Before calling tool: ${toolCall.name}`);\n      return { shortCircuit: false, modifiedInput: toolCall };\n    },\n  },\n};\n\n// 配置断点系统\nconst breakpointConfig: BreakpointConfig = {\n  enabled: true,\n  core: {\n    beforeModelInvoke: async (messages, state) =\u003e {\n      console.log('Breakpoint: Observing model input.');\n      // 可以在此处执行异步调试操作\n    },\n  },\n};\n\n// 创建具有高级配置的智能体\nconst advancedAgent = new ReAgentBuilder({\n  name: 'advanced-agent',\n  llm: {\n    provider: 'openai',\n    model: 'gpt-4',\n    apiKey: process.env.OPENAI_API_KEY,\n  },\n  interceptors: interceptorConfig,\n  breakpoints: breakpointConfig,\n  concurrency: { // 自定义并发限制\n    interceptors: 5,\n    breakpoints: 2,\n  },\n});\n```\n\n## 工具管理\n\n### 动态添加与设置工具\n```typescript\n// 动态添加一个工具\nagent.addTool(weatherTool);\n\n// 批量设置工具，这将覆盖所有现有工具\nagent.setTool([calculatorTool, weatherTool]);\n```\n\n### 查询工具\n```typescript\n// 获取所有工具\nconst allTools = agent.getTool(); // 返回 StructuredTool[]\n\n// 获取指定名称的工具\nconst specificTool = agent.getTool('calculator'); // 返回 StructuredTool | undefined\n```\n\n### 将智能体转换为工具\n此功能允许创建分层的智能体架构。\n```typescript\n// 1. 创建一个子智能体\nconst translatorAgent = new ReAgentBuilder({\n  name: 'translator',\n  systemPrompt: '你是一个专业的翻译引擎。',\n  llm: { provider: 'openai', model: 'gpt-4', apiKey: '...' },\n});\n\n// 2. 将子智能体转换为一个工具\nconst translatorTool = translatorAgent.toTool(\n  'translator',\n  '一个可以将文本在中文和英文之间互译的工具。'\n);\n\n// 3. 将此工具添加到主智能体\nconst mainAgent = new ReAgentBuilder(/* ... */);\nmainAgent.addTool(translatorTool);\n\n// 现在 mainAgent 可以调用 translator 工具来执行翻译任务\nawait mainAgent.run(\"使用 translator 工具将 'hello world' 翻译成中文。\");\n```\n\n## 支持的 LLM 提供商\n\n框架通过 `LLMConfig` 接口支持多种 LLM 提供商。\n\n### OpenAI (及兼容 API)\n适用于 OpenAI 官方 API、Ollama、vLLM、阿里云通义千问等兼容服务。\n\n```typescript\nconst openAIConfig = {\n  provider: 'openai',\n  model: 'gpt-4-turbo',\n  apiKey: 'sk-...',\n  baseURL: 'https://api.openai.com/v1', // 可选，用于指向兼容 API\n};\n```\n\n### Anthropic\n```typescript\nconst anthropicConfig = {\n  provider: 'anthropic',\n  model: 'claude-3-5-sonnet-20240620',\n  apiKey: '...',\n};\n```\n\n### Azure OpenAI\n```typescript\nconst azureConfig = {\n  provider: 'azure',\n  model: 'gpt-4',\n  apiKey: '...',\n  azureEndpoint: 'https://your-resource.openai.azure.com',\n  apiVersion: '2024-02-01',\n  deploymentName: 'your-deployment-name',\n};\n```\n\n### 自定义模型实例\n您可以传入任何 `BaseChatModel` 的实例。\n```typescript\nimport { ChatOpenAI } from '@langchain/openai';\n\nconst customModel = new ChatOpenAI({\n  model: 'gpt-4',\n  apiKey: '...',\n});\n\nconst customConfig = {\n  provider: 'custom',\n  model: 'custom-model-identifier',\n  instance: customModel,\n};\n```\n\n## API 参考\n\n### `ReAgentBuilder` 类\n\n#### `constructor(config: AgentConfig)`\n\n#### 主要方法\n\n| 方法 | 描述 | 返回值 |\n|------|------|--------|\n| `run(input, threadId?)` | 异步执行智能体。 | `Promise\u003cAgentStateType | null\u003e` |\n| `addTool(tool)` | 向智能体添加一个工具。 | `void` |\n| `getTool(name?)` | 获取一个或所有工具。 | `StructuredTool \\| StructuredTool[] \\| undefined` |\n| `setTool(tools)` | 批量设置工具，覆盖现有列表。 | `void` |\n| `toTool(name, desc)` | 将智能体实例转换为一个 `StructuredTool`。 | `StructuredTool` |\n| `getLLMInfo()` | 获取当前使用的模型信息。 | `string` |\n| `getPerformanceReport()` | 获取详细的性能指标报告。 | `object` |\n| `getConcurrencyStatus()` | 获取当前的并发任务状态。 | `object` |\n| `cleanup()` | 清理所有内部资源，如缓存和定时器。 | `Promise\u003cvoid\u003e` |\n\n---\n\n### 核心接口\n\n#### `AgentConfig`\n```typescript\ninterface AgentConfig {\n  name: string;\n  systemPrompt?: string;\n  tools?: StructuredTool[];\n  llm: LLMConfig | BaseChatModel;\n  interceptors?: InterceptorConfig;\n  breakpoints?: BreakpointConfig;\n  memory?: boolean; // 默认: true\n  concurrency?: {\n    interceptors?: number; // 默认: 10\n    breakpoints?: number;  // 默认: 5\n  };\n}\n```\n\n#### `InterceptorConfig`\n```typescript\nimport { BaseMessage } from \"@langchain/core/messages\";\nimport type { ToolCall } from \"@langchain/core/messages/tool\";\nimport type { AgentStateType, InterceptorResult, InterceptorOutput } from \"./types\";\n\ninterface InterceptorConfig {\n  enabled: boolean;\n  core?: {\n    beforeModelInvoke?: (messages: BaseMessage[], state: AgentStateType) =\u003e Promise\u003cBaseMessage[]\u003e;\n    afterAgentComplete?: (finalState: AgentStateType) =\u003e Promise\u003cAgentStateType\u003e;\n  };\n  global?: {\n    beforeToolCall?: (toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cInterceptorResult\u003e;\n    afterToolCall?: (result: InterceptorOutput, toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cInterceptorOutput\u003e;\n  };\n  toolSpecific?: Map\u003cstring, {\n    beforeToolCall?: (toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cInterceptorResult\u003e;\n    afterToolCall?: (result: InterceptorOutput, toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cInterceptorOutput\u003e;\n  }\u003e;\n}\n```\n\n#### `BreakpointConfig`\n```typescript\ninterface BreakpointConfig {\n  enabled: boolean;\n  core?: {\n    beforeModelInvoke?: (messages: BaseMessage[], state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n    afterAgentComplete?: (finalState: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n  };\n  global?: {\n    beforeToolCall?: (toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n    afterToolCall?: (result: InterceptorOutput, toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n  };\n  toolSpecific?: Map\u003cstring, {\n    beforeToolCall?: (toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n    afterToolCall?: (result: InterceptorOutput, toolCall: ToolCall, state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n  }\u003e;\n  model?: {\n    beforeCall?: (state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n    afterCall?: (response: BaseMessage, state: AgentStateType) =\u003e Promise\u003cvoid\u003e;\n  };\n}\n```\n\n## 性能与监控\n\n### 获取性能报告\n```javascript\nconst report = agent.getPerformanceReport();\nconsole.log('Performance Report:', JSON.stringify(report, null, 2));\n\n/*\n{\n  \"timestamp\": \"...\",\n  \"uptime\": 10.123,\n  \"timers\": {\n    \"agent.run\": { \"count\": 1, \"total\": 1500.25, \"average\": 1500.25, ... }\n  },\n  \"counters\": {\n    \"agent.runs\": 1,\n    \"tool.executions\": 2\n  },\n  // ... 省略\n}\n*/\n```\n\n### 获取并发状态\n```javascript\nconst status = agent.getConcurrencyStatus();\nconsole.log('Concurrency Status:', status);\n\n/*\n{\n  \"activeInterceptors\": 0,\n  \"activeBreakpoints\": 0,\n  \"toolMapSize\": 2\n}\n*/\n```\n\n## 错误处理\n框架内置了统一的 `ErrorHandler`，可自动捕获、分类和记录在智能体执行期间发生的错误。它提供了丰富的上下文信息，并能防止重复的错误日志刷屏，以帮助快速定位问题。\n\n## 贡献\n欢迎社区贡献。请在提交 Pull Request 前，确保遵循现有的代码风格，添加相应的测试，并更新相关文档。","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freuac%2Freagentbuilder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Freuac%2Freagentbuilder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Freuac%2Freagentbuilder/lists"}