agent-ts-example

本仓库是对 https://github.com/Annyfee/agent-craft 的 TypeScript 复刻：

• 目标：深度梳理其 Agent 实现模式（从最小 LLM 调用、工具调用、ReAct、RAG、到 LangGraph 的白盒工作流/多智能体/MCP），并用 LangChain.js + LangGraph（@langchain/langgraph） 在 TS 中实现“机制等价”的范例。
• 原则：每个模式一个 src/*.ts 文件，尽量做到“可读/可运行/可扩展”，并用大量中文注释解释与原版的映射关系。

运行前准备

1) 安装依赖

npm install

2) 环境变量

多数示例需要 LLM：

• OPENAI_API_KEY：必需
• OPENAI_MODEL：可选，默认 gpt-4o-mini
• OPENAI_BASE_URL：可选，用于对齐 agent-craft 中 “DeepSeek base_url” 这类兼容 OpenAI 协议的网关

示例：

export OPENAI_API_KEY=... 
export OPENAI_MODEL=gpt-4o-mini

模式清单（与 agent-craft 的映射）

说明：agent-craft 中并没有发现明确命名的 Reflection / Plan-and-Execute 范式实现。 其“规划-执行/反思修正”的能力更多通过：LangGraph 多节点工作流、Supervisor 多智能体调度、Human-in-the-Loop 审批、Graph-as-a-Tool 子图封装等组合实现。

A. 基础形态

• src/01_minimal_llm.ts：最小 LLM 调用（对应 m01_agent_introduction/agent-demo.py）
• src/02_conversation_loop.ts：手写 messages 的多轮对话循环（对应 m02_llm_fundamentals/s02_conversational_agent.py）

B. Function/Tool Calling（两段式）

• src/03_function_calling_two_step.ts：先 tool_call → 执行工具 → 再总结（对应 m03_function_calling_tools/s01_*.py / s02_*.py）

C. LangChain AgentExecutor（ReAct 黑盒）

• src/04_langchain_react_agent.ts：Tool-Calling Agent + AgentExecutor（对应 m05_langchain_advanced/s02_general_agent.py）
• src/05_langchain_react_with_memory.ts：ReAct + RunnableWithMessageHistory 会话记忆（对应 m05_langchain_advanced/s04_memory_general_agent.py）

D. SQL Agent（自然语言 → SQL → 执行）

• src/06_sql_agent.ts：用 node:sqlite + 工具调用复刻 SQL Agent 机制（对应 m05_langchain_advanced/s03_sql_agent.py）

E. RAG as Tool + Agent

• src/07_rag_tool_agent.ts：RAG chain 工具化 + ReAct + 记忆（对应 m07_rag_advanced/s05_memory_rag_agent.py）

F. LangGraph（白盒 ReAct / 记忆 / HITL / 子图工具化）

• src/08_langgraph_conditional_router.ts：ReAct 白盒循环（agent→tools→agent，条件边控制）（对应 m08_langgraph_basics/s03_conditional_router.py）
• src/09_langgraph_agent_with_memory.ts：MemorySaver + thread_id 的可恢复对话线程（对应 m08_langgraph_basics/s04_agent_with_memory.py）
• src/10_langgraph_human_approval.ts：interruptBefore=["tools"] 的人工审批（对应 m09_langgraph_advanced/s01_human_approval.py）
• src/11_langgraph_graph_as_tool.ts：子图实现重试/容错，再封装为 tool（对应 m09_langgraph_advanced/s02_graph_as_a_tool.py）
• src/12_langgraph_multi_agent_supervisor.ts：Supervisor 调度多个专家（对应 m09_langgraph_advanced/s03_multi_agent_orchestration.py）
• src/13_langgraph_ops_system.ts：综合样例（子图工具化 + 审批拦截）（对应 m09_langgraph_advanced/s04_supervisor_agent_ops_system.py）

G. MCP（server / client / 注入 LangGraph）

• src/14_mcp_stdio_server.ts：MCP stdio server（对应 m10_mcp_basics/s01_stdio_server.py）
• src/15_mcp_stdio_client.ts：spawn server 并调用 tool（概念等价 m11_mcp_advanced）
• src/16_mcp_tools_to_langgraph.ts：MCP tools → LangChain tools → LangGraph ReAct（对应 m11_mcp_advanced/mcp_main.py / s02_final_mcp_main.py）
• src/17_mcp_streamable_http_server.ts：MCP Streamable HTTP server（对应 m10_mcp_basics/s02_streamable_http_server.py）

本地运行示例

下面命令都在仓库根目录运行。

只做类型检查

npm run typecheck

运行某个示例

npx tsx src/04_langchain_react_agent.ts 
npm run 04

MCP stdio：客户端调用服务端工具

npx tsx src/15_mcp_stdio_client.ts

MCP HTTP server

npx tsx src/17_mcp_streamable_http_server.ts

工程结构

• src/_shared/env.ts：加载 .env、并提供必需 env 校验
• src/_shared/model.ts：统一创建 ChatOpenAI，支持 ARK_BASE_URL 对齐网关
• src/_shared/stdio.ts：最小 readline 封装，复刻 agent-craft 中大量 input() 交互