### **快速入门：本地启动 LangGraph 服务器**

本指南将帮助您在本地快速启动并运行 LangGraph 应用。

---

#### **环境要求**
- **Python** >= 3.11
- **LangGraph CLI**：需要 `langchain-cli[inmem]` >= 0.1.58

---

#### **安装 LangGraph CLI**
```bash
pip install --upgrade "langgraph-cli[inmem]"
```

---

#### **创建 LangGraph 应用**
使用 `react-agent` 模板创建一个新应用。该模板是一个简单的代理，可以灵活扩展以支持多种工具。

```bash
langgraph new path/to/your/app --template react-agent-python
```

**其他模板**  
如果不指定模板，`langgraph new` 会显示交互式菜单，供您选择可用模板。

---

#### **安装依赖**
在应用根目录下，以编辑模式安装依赖，以便服务器使用本地更改：

```bash
pip install -e .
```

---

#### **创建 `.env` 文件**
在应用根目录下找到 `.env.example` 文件，创建 `.env` 文件并复制内容，填写必要的 API 密钥：

```env
LANGSMITH_API_KEY=lsv2...
TAVILY_API_KEY=tvly-...
ANTHROPIC_API_KEY=sk-
OPENAI_API_KEY=sk-...
```

---

#### **启动 LangGraph 服务器**
```bash
langgraph dev
```

如果成功启动，您将看到类似以下输出：

```
Ready!

API: http://localhost:2024

Docs: http://localhost:2024/docs

LangGraph Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
```

**内存模式**  
`langgraph dev` 以内存模式启动服务器，适合开发和测试。生产环境应使用持久化存储后端。

**持久化模式**  
使用 `langgraph up` 命令启动持久化模式（需要 Docker）。

---

#### **LangGraph Studio Web UI**
LangGraph Studio Web 是一个专用 UI，可连接到 LangGraph API 服务器，支持可视化、交互和调试。

访问 `langgraph dev` 输出中的 URL 即可使用。

**自定义主机/端口**  
如果服务器使用自定义主机/端口，可以通过修改 `baseUrl` 参数指向服务器。例如，端口为 `8000` 时：

```
https://smith.langchain.com/studio/baseUrl=http://127.0.0.1:8000
```

**Safari 兼容性**  
目前，LangGraph Studio Web 不支持 Safari。

---

#### **测试 API**
**安装 Python SDK**
```bash
pip install langgraph-sdk
```

**发送消息（无线程运行）**
```python
from langgraph_sdk import get_client

client = get_client(url="http://localhost:2024")

async for chunk in client.runs.stream(
    None,  # 无线程运行
    "agent", # 代理名称（在 langgraph.json 中定义）
    input={
        "messages": [{
            "role": "human",
            "content": "What is LangGraph?",
        }],
    },
    stream_mode="updates",
):
    print(f"Receiving new event of type: {chunk.event}...")
    print(chunk.data)
    print("\n\n")
```

**认证**  
连接远程服务器时，需要提供 LangSmith API 密钥。详见客户端 API 参考。

---

#### **下一步**
现在您已成功在本地运行 LangGraph 应用，接下来可以探索部署和高级功能：

- **🌐 部署到 LangGraph Cloud**  
  使用 LangGraph Cloud 快速部署您的应用。
- **📚 学习 LangGraph 平台**  
  通过以下资源扩展知识：
  - [LangGraph 平台概念](https://langgraph.ai/concepts)
  - [LangGraph 平台操作指南](https://langgraph.ai/guides)
- **🛠️ 开发者参考**  
  访问详细文档：
  - [LangGraph 服务器 API 参考](https://langgraph.ai/api)
  - [Python SDK 参考](https://langgraph.ai/sdk/python)
  - [JS/TS SDK 参考](https://langgraph.ai/sdk/js)

---

**开始构建您的智能系统吧！🚀**

快速入门：本地启动 LangGraph 服务器

### **工作流与代理：构建智能系统的核心模式**

在构建智能系统时，理解“工作流”和“代理”的区别至关重要。Anthropic 提供了一个清晰的解释：

- **工作流**：通过预定义的代码路径编排 LLM 和工具的系统。
- **代理**：LLM 动态指导自身过程和工具使用的系统，保持对任务完成方式的控制。

LangGraph 提供了构建这些系统的强大工具，支持持久化、流式处理、调试和部署。以下是详细指南：

---

#### **环境设置**
首先，安装依赖并配置 API 密钥：

```python
%%capture --no-stderr
%pip install -U langgraph langsmith langchain_anthropic

import os
import getpass

def _set_env(var: str):
    if not os.environ.get(var):
        os.environ[var] = getpass.getpass(f"{var}: ")

_set_env("ANTHROPIC_API_KEY")

from langchain_anthropic import ChatAnthropic
llm = ChatAnthropic(model="claude-3-5-sonnet-latest")
```

---

#### **构建块：增强的 LLM**
LLM 可以通过结构化输出和工具调用进行增强。以下是示例：

```python
from pydantic import BaseModel, Field

class SearchQuery(BaseModel):
    search_query: str = Field(None, description="优化网络搜索的查询。")
    justification: str = Field(None, description="为什么此查询与用户请求相关。")

# 增强 LLM 以支持结构化输出
structured_llm = llm.with_structured_output(SearchQuery)

# 调用增强的 LLM
output = structured_llm.invoke("钙 CT 评分与高胆固醇有何关系？")
print(output)
```

---

#### **提示链**
提示链将任务分解为一系列步骤，每个 LLM 调用处理前一个调用的输出：

```python
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict

# 定义状态
class State(TypedDict):
    topic: str
    joke: str
    improved_joke: str
    final_joke: str

# 节点函数
def generate_joke(state: State):
    msg = llm.invoke(f"写一个关于 {state['topic']} 的短笑话。")
    return {"joke": msg.content}

def check_punchline(state: State):
    if "?" in state["joke"] or "!" in state["joke"]:
        return "Fail"
    return "Pass"

def improve_joke(state: State):
    msg = llm.invoke(f"通过添加文字游戏使这个笑话更有趣：{state['joke']}")
    return {"improved_joke": msg.content}

def polish_joke(state: State):
    msg = llm.invoke(f"为这个笑话添加一个意想不到的转折：{state['improved_joke']}")
    return {"final_joke": msg.content}

# 构建工作流
workflow = StateGraph(State)
workflow.add_node("generate_joke", generate_joke)
workflow.add_node("improve_joke", improve_joke)
workflow.add_node("polish_joke", polish_joke)
workflow.add_edge(START, "generate_joke")
workflow.add_conditional_edges("generate_joke", check_punchline, {"Fail": "improve_joke", "Pass": END})
workflow.add_edge("improve_joke", "polish_joke")
workflow.add_edge("polish_joke", END)
chain = workflow.compile()

# 调用
state = chain.invoke({"topic": "猫"})
print(state["final_joke"])
```

---

#### **并行化**
并行化允许 LLM 同时处理任务，并将输出聚合：

```python
# 定义状态
class State(TypedDict):
    topic: str
    joke: str
    story: str
    poem: str
    combined_output: str

# 节点函数
def call_llm_1(state: State):
    msg = llm.invoke(f"写一个关于 {state['topic']} 的笑话。")
    return {"joke": msg.content}

def call_llm_2(state: State):
    msg = llm.invoke(f"写一个关于 {state['topic']} 的故事。")
    return {"story": msg.content}

def call_llm_3(state: State):
    msg = llm.invoke(f"写一首关于 {state['topic']} 的诗。")
    return {"poem": msg.content}

def aggregator(state: State):
    combined = f"这是关于 {state['topic']} 的故事、笑话和诗！\n\n"
    combined += f"故事：\n{state['story']}\n\n"
    combined += f"笑话：\n{state['joke']}\n\n"
    combined += f"诗：\n{state['poem']}"
    return {"combined_output": combined}

# 构建工作流
parallel_builder = StateGraph(State)
parallel_builder.add_node("call_llm_1", call_llm_1)
parallel_builder.add_node("call_llm_2", call_llm_2)
parallel_builder.add_node("call_llm_3", call_llm_3)
parallel_builder.add_node("aggregator", aggregator)
parallel_builder.add_edge(START, "call_llm_1")
parallel_builder.add_edge(START, "call_llm_2")
parallel_builder.add_edge(START, "call_llm_3")
parallel_builder.add_edge("call_llm_1", "aggregator")
parallel_builder.add_edge("call_llm_2", "aggregator")
parallel_builder.add_edge("call_llm_3", "aggregator")
parallel_builder.add_edge("aggregator", END)
parallel_workflow = parallel_builder.compile()

# 调用
state = parallel_workflow.invoke({"topic": "狗"})
print(state["combined_output"])
```

---

#### **代理**
代理通过工具调用和环境反馈在循环中执行任务：

```python
from langgraph.graph import MessagesState
from langchain_core.messages import SystemMessage, HumanMessage, ToolMessage
from langchain_core.tools import tool

# 定义工具
@tool
def multiply(a: int, b: int) -> int:
    return a * b

@tool
def add(a: int, b: int) -> int:
    return a + b

@tool
def divide(a: int, b: int) -> float:
    return a / b

# 增强 LLM 以支持工具调用
tools = [add, multiply, divide]
tools_by_name = {tool.name: tool for tool in tools}
llm_with_tools = llm.bind_tools(tools)

# 节点函数
def llm_call(state: MessagesState):
    return {
        "messages": [
            llm_with_tools.invoke(
                [
                    SystemMessage(content="你是一个帮助执行算术运算的助手。")
                ]
                + state["messages"]
            )
        ]
    }

def tool_node(state: dict):
    result = []
    for tool_call in state["messages"][-1].tool_calls:
        tool = tools_by_name[tool_call["name"]]
        observation = tool.invoke(tool_call["args"])
        result.append(ToolMessage(content=observation, tool_call_id=tool_call["id"]))
    return {"messages": result}

def should_continue(state: MessagesState) -> Literal["environment", END]:
    if state["messages"][-1].tool_calls:
        return "Action"
    return END

# 构建代理
agent_builder = StateGraph(MessagesState)
agent_builder.add_node("llm_call", llm_call)
agent_builder.add_node("environment", tool_node)
agent_builder.add_edge(START, "llm_call")
agent_builder.add_conditional_edges("llm_call", should_continue, {"Action": "environment", END: END})
agent_builder.add_edge("environment", "llm_call")
agent = agent_builder.compile()

# 调用
messages = [HumanMessage(content="3 加 4 等于多少？")]
messages = agent.invoke({"messages": messages})
for m in messages["messages"]:
    m.pretty_print()
```

---

#### **LangGraph 的优势**
- **持久化**：支持人类干预和动作批准。
- **流式处理**：支持流式输出和中间状态。
- **部署**：提供简单的部署、可观察性和评估。

---

**下一步**  
- 探索 [LangGraph 文档](https://langgraph.ai/concepts)。
- 学习 [LangChain Academy](https://langchain.academy) 的课程。
- 构建更复杂的智能系统！ 🚀

工作流与代理：构建智能系统的核心模式

### **构建支持聊天机器人：从基础到高级功能**

---

#### **概述**
在本教程中，我们将使用 LangGraph 构建一个支持聊天机器人，具备以下功能：
- ✅ 通过搜索网络回答常见问题
- ✅ 在多次调用中维护对话状态
- ✅ 将复杂查询路由给人工审核
- ✅ 使用自定义状态控制行为
- ✅ 回滚并探索替代对话路径

我们将从一个基础聊天机器人开始，逐步添加更复杂的功能，并在此过程中介绍 LangGraph 的核心概念。让我们开始吧！ 🌟

---

#### **环境设置**
首先，安装所需的包并配置环境：

```python
%%capture --no-stderr
%pip install -U langgraph langsmith langchain_anthropic

import getpass
import os

def _set_env(var: str):
    if not os.environ.get(var):
        os.environ[var] = getpass.getpass(f"{var}: ")

_set_env("ANTHROPIC_API_KEY")
```

**设置 LangSmith**  
注册 [LangSmith](https://langsmith.com/) 以快速发现问题并优化 LangGraph 项目的性能。LangSmith 允许你使用跟踪数据调试、测试和监控基于 LangGraph 构建的 LLM 应用。

---

#### **第一部分：构建基础聊天机器人**
我们将首先使用 LangGraph 创建一个简单的聊天机器人。这个机器人将直接响应用户消息。虽然简单，但它将展示使用 LangGraph 构建应用的核心概念。

**步骤 1：创建 StateGraph**  
`StateGraph` 对象定义了聊天机器人作为“状态机”的结构。我们将添加节点来表示 LLM 和机器人可以调用的函数，并添加边来指定机器人如何在函数之间转换。

```python
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

graph_builder = StateGraph(State)
```

**步骤 2：添加聊天机器人节点**  
节点代表工作单元，通常是普通的 Python 函数。

```python
from langchain_anthropic import ChatAnthropic

llm = ChatAnthropic(model="claude-3-5-sonnet-20240620")

def chatbot(state: State):
    return {"messages": [llm.invoke(state["messages"])]}

graph_builder.add_node("chatbot", chatbot)
```

**步骤 3：添加入口点和结束点**  
入口点告诉图每次运行时从哪里开始，结束点指示图何时可以退出。

```python
graph_builder.add_edge(START, "chatbot")
graph_builder.add_edge("chatbot", END)
```

**步骤 4：编译并运行图**  
调用 `compile()` 方法创建 `CompiledGraph`，然后使用 `invoke` 运行。

```python
graph = graph_builder.compile()
```

**步骤 5：可视化图**  
使用 `get_graph` 方法可视化图。

```python
from IPython.display import Image, display

try:
    display(Image(graph.get_graph().draw_mermaid_png()))
except Exception:
    pass
```

**步骤 6：运行聊天机器人**  
通过循环与用户交互，运行聊天机器人。

```python
def stream_graph_updates(user_input: str):
    for event in graph.stream({"messages": [{"role": "user", "content": user_input}]}):
        for value in event.values():
            print("Assistant:", value["messages"][-1].content)

while True:
    try:
        user_input = input("User: ")
        if user_input.lower() in ["quit", "exit", "q"]:
            print("Goodbye!")
            break
        stream_graph_updates(user_input)
    except:
        user_input = "What do you know about LangGraph?"
        print("User: " + user_input)
        stream_graph_updates(user_input)
        break
```

**恭喜！** 你已经使用 LangGraph 构建了第一个聊天机器人。这个机器人可以通过 LLM 生成响应与用户进行基本对话。

---

#### **第二部分：增强聊天机器人功能**
为了让机器人回答更多问题，我们将集成一个网络搜索工具。

**步骤 1：安装依赖并设置 API 密钥**

```python
%%capture --no-stderr
%pip install -U tavily-python langchain_community
_set_env("TAVILY_API_KEY")
```

**步骤 2：定义搜索工具**

```python
from langchain_community.tools.tavily_search import TavilySearchResults

tool = TavilySearchResults(max_results=2)
tools = [tool]
tool.invoke("What's a 'node' in LangGraph?")
```

**步骤 3：更新图定义**  
在 LLM 上绑定工具，让 LLM 知道如何使用搜索工具。

```python
llm_with_tools = llm.bind_tools(tools)

def chatbot(state: State):
    return {"messages": [llm_with_tools.invoke(state["messages"])]}

graph_builder.add_node("chatbot", chatbot)
```

**步骤 4：运行增强版聊天机器人**  
现在，机器人可以使用搜索工具回答更多问题。

---

#### **第三部分：添加高级功能**
我们将进一步扩展聊天机器人的功能，包括：
- **维护对话状态**：在多次调用中保留上下文。
- **路由复杂查询**：将复杂问题路由给人工审核。
- **自定义状态控制**：使用自定义状态控制机器人行为。
- **回滚和探索**：支持回滚并探索替代对话路径。

---

#### **总结**
通过本教程，你学会了如何使用 LangGraph 构建一个支持聊天机器人，并逐步添加高级功能。LangGraph 的强大功能使得构建复杂的 AI 应用变得更加简单和灵活。继续探索 LangGraph 的更多功能，构建更强大的应用吧！

---

**下一步**  
- 探索 [LangGraph 服务器快速入门](https://langgraph.ai/server-quickstart)。
- 部署你的 LangGraph 应用到 [LangGraph Cloud](https://langgraph.ai/cloud-quickstart)。
- 深入学习 [LangGraph 概念](https://langgraph.ai/concepts) 和 [操作指南](https://langgraph.ai/how-to-guides)。



langgraph快速开始

### **LangGraph 概念指南：从入门到精通**

---

#### **概述**
LangGraph 是一个强大的框架，用于构建基于图的 AI 应用。它通过将应用分解为节点和边，帮助开发者设计复杂的控制流和代理系统。本指南将带你了解 LangGraph 的核心概念、常见模式以及如何在实际项目中应用。

---

#### **快速开始**
在深入概念之前，建议先完成 [快速开始](https://langgraph.ai/quick-start) 教程。这将为你提供实践背景，帮助你更好地理解后续内容。

---

#### **核心概念**

##### **1. LangGraph 是什么？**
LangGraph 是一个基于图的框架，用于设计和执行 AI 应用。它的核心思想是将应用分解为节点（组件）和边（信息流），从而实现灵活的控制流和复杂的逻辑。

##### **2. LangGraph 术语**
- **节点（Node）**：表示应用中的一个组件，例如调用 LLM 或执行特定任务。
- **边（Edge）**：定义节点之间的信息流，决定应用的执行顺序。
- **图（Graph）**：由节点和边组成的结构，描述应用的整体逻辑。

##### **3. 常见代理模式**
代理（Agent）是 LangGraph 的核心组件，它使用 LLM 自主决定控制流，以解决复杂问题。常见的代理模式包括：
- **单代理系统**：一个代理负责整个任务。
- **多代理系统**：多个代理协作，每个代理负责不同的子任务。

##### **4. 断点（Breakpoints）**
断点允许在图的特定位置暂停执行，便于调试和检查中间状态。

##### **5. 人在回路（Human-in-the-Loop）**
通过集成人类反馈，提升应用的准确性和适应性。例如，在关键决策点请求用户确认。

##### **6. 时间旅行（Time Travel）**
时间旅行允许回放过去的操作，探索不同的执行路径，帮助调试和优化应用。

##### **7. 持久化（Persistence）**
LangGraph 内置持久化层，通过检查点（Checkpointers）实现。支持故障恢复、记忆和时间旅行等功能。

##### **8. 记忆（Memory）**
记忆使代理能够存储和回忆过去的信息，从而适应用户偏好和上下文。

##### **9. 流式处理（Streaming）**
流式处理逐步显示输出，提升用户体验，特别是在处理高延迟的 LLM 时。

##### **10. 功能 API（Functional API）**
功能 API 是 StateGraph 的替代方案，提供更灵活的开发方式。

---

#### **LangGraph 平台**

##### **1. 为什么选择 LangGraph 平台？**
LangGraph 平台是一个商业解决方案，用于在生产环境中部署代理应用。它基于开源的 LangGraph 框架，提供额外的功能和管理工具。

##### **2. 部署选项**
LangGraph 平台提供四种部署方式：
- **自托管精简版（Self-Hosted Lite）**：免费，适合小规模应用。
- **云 SaaS**：由 LangSmith 托管，适合快速部署。
- **自带云（BYOC）**：我们管理基础设施，但运行在你的云环境中。
- **自托管企业版（Self-Hosted Enterprise）**：完全由你管理，适合大规模企业。

##### **3. 计划**
LangGraph 平台提供三种计划：
- **开发者计划**：适合个人开发者和小团队。
- **Plus 计划**：适合中型团队。
- **企业计划**：适合大型企业。

---

#### **组件**

##### **1. LangGraph 服务器**
LangGraph 服务器支持多种代理应用场景，从后台处理到实时交互。

##### **2. LangGraph Studio**
LangGraph Studio 是一个专用 IDE，用于可视化、交互和调试本地应用。

##### **3. LangGraph CLI**
LangGraph CLI 是一个命令行工具，用于与本地应用交互。

##### **4. Python/JS SDK**
Python/JS SDK 提供编程接口，用于与部署的应用交互。

##### **5. 远程图（RemoteGraph）**
远程图允许你像本地应用一样与部署的应用交互。

---

#### **LangGraph 服务器**

##### **1. 应用结构**
LangGraph 应用由以下部分组成：
- 一个或多个图。
- LangGraph API 配置文件（`langgraph.json`）。
- 依赖文件。
- 环境变量。

##### **2. 助手（Assistants）**
助手用于保存和管理应用的不同配置。

##### **3. Webhooks**
Webhooks 允许应用在特定事件发生时向外部服务发送数据。

##### **4. Cron 任务**
Cron 任务用于在特定时间调度任务。

##### **5. 双重文本（Double Texting）**
双重文本是 LLM 应用中的常见问题，用户可能在图完成运行前发送多条消息。本指南解释了如何处理这一问题。

##### **6. 认证与访问控制**
了解 LangGraph 平台的认证和访问控制选项。

---

#### **部署选项**

##### **1. 自托管精简版**
免费版本，适合小规模应用，每年最多执行 100 万个节点。

##### **2. 云 SaaS**
由 LangSmith 托管，适合快速部署。

##### **3. 自带云（BYOC）**
我们管理基础设施，但运行在你的云环境中。

##### **4. 自托管企业版**
完全由你管理，适合大规模企业。

---

#### **模板应用**
LangGraph 平台提供参考应用模板，帮助你快速上手。

---

#### **FAQ**
- **LangGraph 是开源的吗？**  
  是的，LangGraph 是一个 MIT 许可的开源库。
- **我可以自己部署 LangGraph 应用吗？**  
  可以，你可以使用开源版本在自己的基础设施上部署应用。

---

#### **总结**
LangGraph 是一个强大的工具，适用于构建复杂的 AI 应用。通过理解其核心概念和平台功能，你可以更高效地设计和部署代理应用。如果需要进一步帮助，请参考 [官方文档](https://langgraph.ai/docs) 或联系支持团队。


langgraph翻译

# Agent - 让大模型拥有双手

## Agent 是什么

Agent（智能代理）是一个能够感知环境并采取行动以实现特定目标的系统。在 AI 应用中，Agent 结合了大语言模型的理解能力和预定义工具的执行能力，可以自主地完成复杂的任务。它是未来 AI 应用在生活和生产中主要的形态。

## Agent 的核心组成

在 Eino 框架中，实现 Agent 主要需要两个核心部分：**ChatModel** 和 **Tool**。

### ChatModel

ChatModel 是 Agent 的“大脑”，它通过强大的语言理解能力来处理用户的自然语言输入。当用户提出请求时，ChatModel 会深入理解用户的意图，分析任务需求，并决定是否需要调用特定的工具来完成任务。在需要使用工具时，它能够准确选择合适的工具并生成正确的参数。此外，ChatModel 还能将工具执行的结果转化为用户易于理解的自然语言回应，实现流畅的人机对话。

更详细的 ChatModel 信息可以参考：[Eino: ChatModel 使用说明](#)。

### Tool

Tool 是 Agent 的“执行器”，提供具体的功能实现。每个 Tool 都有明确的功能定义和参数规范，使 ChatModel 能够准确地调用它们。Tool 可以实现各种功能，从简单的数据操作到复杂的外部服务调用都可以封装成 Tool。

更详细关于 Tool 和 ToolsNode 的信息可参考：[Eino: ToolsNode 使用说明](#)。

## Tool 的实现方式

在 Eino 中，我们提供了多种方式来实现 Tool。下面通过一个待办事项（Todo）管理系统的例子来说明。

### 方式一：使用 NewTool 构建

这种方式适合简单的工具实现，通过定义工具信息和处理函数来创建 Tool：

```go
import (
    "context"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/components/tool/utils"
    "github.com/cloudwego/eino/schema"
)

// 处理函数
func AddTodoFunc(_ context.Context, params *TodoAddParams) (string, error) {
    // Mock处理逻辑
    return `{"msg": "add todo success"}`, nil
}

func getAddTodoTool() tool.InvokableTool {
    // 工具信息
    info := &schema.ToolInfo{
        Name: "add_todo",
        Desc: "Add a todo item",
        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
            "content": {
                Desc:     "The content of the todo item",
                Type:     schema.String,
                Required: true,
            },
            "started_at": {
                Desc: "The started time of the todo item, in unix timestamp",
                Type: schema.Integer,
            },
            "deadline": {
                Desc: "The deadline of the todo item, in unix timestamp",
                Type: schema.Integer,
            },
        }),
    }

    // 使用 NewTool 创建工具
    return utils.NewTool(info, AddTodoFunc)
}
```

这种方式虽然直观，但存在一个明显的缺点：需要在 ToolInfo 中手动定义参数信息（ParamsOneOf），和实际的参数结构（TodoAddParams）是分开定义的。这不仅造成了代码的冗余，而且在参数发生变化时需要同时修改两处地方，容易导致不一致，维护起来也比较麻烦。

### 方式二：使用 InferTool 构建

这种方式更加简洁，通过结构体的 tag 来定义参数信息，就能实现参数结构体和描述信息同源，无需维护两份信息：

```go
import (
    "context"
    "github.com/cloudwego/eino/components/tool/utils"
)

// 参数结构体
type TodoUpdateParams struct {
    ID        string  `json:"id" jsonschema:"description=id of the todo"`
    Content   *string `json:"content,omitempty" jsonschema:"description=content of the todo"`
    StartedAt *int64  `json:"started_at,omitempty" jsonschema:"description=start time in unix timestamp"`
    Deadline  *int64  `json:"deadline,omitempty" jsonschema:"description=deadline of the todo in unix timestamp"`
    Done      *bool   `json:"done,omitempty" jsonschema:"description=done status"`
}

// 处理函数
func UpdateTodoFunc(_ context.Context, params *TodoUpdateParams) (string, error) {
    // Mock处理逻辑
    return `{"msg": "update todo success"}`, nil
}

// 使用 InferTool 创建工具
updateTool, err := utils.InferTool(
    "update_todo", // tool name 
    "Update a todo item, eg: content, deadline...", // tool description
    UpdateTodoFunc)
```

### 方式三：实现 Tool 接口

对于需要更多自定义逻辑的场景，可以通过实现 Tool 接口来创建：

```go
import (
    "context"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/schema"
)

type ListTodoTool struct {}

func (lt *ListTodoTool) Info(ctx context.Context) (*schema.ToolInfo, error) {
    return &schema.ToolInfo{
        Name: "list_todo",
        Desc: "List all todo items",
        ParamsOneOf: schema.NewParamsOneOfByParams(map[string]*schema.ParameterInfo{
            "finished": {
                Desc:     "filter todo items if finished",
                Type:     schema.Boolean,
                Required: false,
            },
        }),
    }, nil
}

func (lt *ListTodoTool) InvokableRun(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
    // Mock调用逻辑
    return `{"todos": [{"id": "1", "content": "在2024年12月10日之前完成Eino项目演示文稿的准备工作", "started_at": 1717401600, "deadline": 1717488000, "done": false}]}`, nil
}
```

### 方式四：使用官方封装的工具

除了自己实现工具，我们还提供了许多开箱即用的工具。这些工具经过充分测试和优化，可以直接集成到你的 Agent 中。以 DuckDuckGo Search 工具为例：

```go
import (
    "github.com/cloudwego/eino-ext/components/tool/duckduckgo"
)

// 创建 DuckDuckGo Search 工具
searchTool, err := duckduckgo.NewTool(ctx, &duckduckgo.Config{})
```

使用 `eino-ext` 提供的工具不仅能避免重复开发的工作量，还能确保工具的稳定性和可靠性。这些工具都经过充分测试和持续维护，可以直接集成到项目中使用。

## 用 Chain 构建 Agent

在构建 Agent 时，`ToolsNode` 是一个核心组件，它负责管理和执行工具调用。`ToolsNode` 可以集成多个工具，并提供统一的调用接口。它支持同步调用（Invoke）和流式调用（Stream）两种方式，能够灵活地处理不同类型的工具执行需求。

要创建一个 `ToolsNode`，你需要提供一个工具列表配置：

```go
import (
    "context"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/compose"
)

conf := &compose.ToolsNodeConfig{
    Tools: []tool.BaseTool{tool1, tool2},  // 工具可以是 InvokableTool 或 StreamableTool
}
toolsNode, err := compose.NewToolNode(context.Background(), conf)
```

下面是一个完整的 Agent 示例，它使用 OpenAI 的 ChatModel 并结合了上述的 Todo 工具：

```go
import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/cloudwego/eino-ext/components/model/openai"
    "github.com/cloudwego/eino/components/tool"
    "github.com/cloudwego/eino/compose"
    "github.com/cloudwego/eino/schema"
)

func main() {
    // 初始化 tools
    todoTools := []tool.BaseTool{
        getAddTodoTool(),                               // NewTool 构建
        updateTool,                                     // InferTool 构建
        &ListTodoTool{},                                // 实现 Tool 接口
        searchTool,                                     // 官方封装的工具
    }

    // 创建并配置 ChatModel
    chatModel, err := openai.NewChatModel(context.Background(), &openai.ChatModelConfig{
        Model:       "gpt-4",
        APIKey:      os.Getenv("OPENAI_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 获取工具信息并绑定到 ChatModel
    toolInfos := make([]*schema.ToolInfo, 0, len(todoTools))
    for _, tool := range todoTools {
        info, err := tool.Info(ctx)
        if err != nil {
            log.Fatal(err)
        }
        toolInfos = append(toolInfos, info)
    }
    err = chatModel.BindTools(toolInfos)
    if err != nil {
        log.Fatal(err)
    }

    // 创建 tools 节点
    todoToolsNode, err := compose.NewToolNode(context.Background(), &compose.ToolsNodeConfig{
        Tools: todoTools,
    })
    if err != nil {
        log.Fatal(err)
    }

    // 构建完整的处理链
    chain := compose.NewChain[[]*schema.Message, []*schema.Message]()
    chain.
        AppendChatModel(chatModel, compose.WithNodeName("chat_model")).
        AppendToolsNode(todoToolsNode, compose.WithNodeName("tools"))

    // 编译并运行 chain
    agent, err := chain.Compile(ctx)
    if err != nil {
        log.Fatal(err)
    }

    // 运行示例
    resp, err := agent.Invoke(ctx, []*schema.Message{
        {
           Role:    schema.User,
           Content: "添加一个学习 Eino 的 TODO，同时搜索一下 cloudwego/eino 的仓库地址",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // 输出结果
    for _, msg := range resp {
        fmt.Println(msg.Content)
    }
}
```

这个示例假设 ChatModel 一定会做出工具调用的决策。

## 使用其他方式构建 Agent

除了上述使用 Chain/Graph 构建的 Agent 之外，Eino 还提供了常用的 Agent 模式的封装。

### ReAct Agent

ReAct（Reasoning + Acting）Agent 结合了推理和行动能力，通过思考-行动-观察的循环来解决复杂问题。它能够在执行任务时进行深入的推理，并根据观察结果调整策略，特别适合需要多步推理的复杂场景。

更详细的 ReAct Agent 可以参考：[Eino: React Agent 使用手册](https://www.cloudwego.io/zh/docs/eino/core_modules/flow_integration_components/react_agent_manual)。

### Multi Agent

Multi Agent 系统由多个协同工作的 Agent 组成，每个 Agent 都有其特定的职责和专长。通过 Agent 间的交互与协作，可以处理更复杂的任务，实现分工协作。这种方式特别适合需要多个专业领域知识结合的场景。

更详细的 Multi Agent 可以参考：[Eino Tutorial: Host Multi-Agent](https://www.cloudwego.io/zh/docs/eino/core_modules/flow_integration_components/multi_agent_hosting)。

## 总结

本文介绍了使用 Eino 框架构建 Agent 的基本方法。通过 Chain、Tool Calling 和 ReAct 等不同方式，我们可以根据实际需求灵活地构建 AI Agent。

Agent 是 AI 技术发展的重要方向。它不仅能够理解用户意图，还能主动采取行动，通过调用各种工具来完成复杂任务。随着大语言模型能力的不断提升，Agent 将在未来扮演越来越重要的角色，成为连接 AI 与现实世界的重要桥梁。我们期待 Eino 能为用户带来更强大、易用的 Agent 构建方案，推动更多基于 Agent 的应用创新。

## 关联阅读


- [实现一个最简 LLM 应用 - ChatModel](https://www.cloudwego.io/zh/docs/eino/quick_start/simple_llm_application)

希望这篇文章对你理解 Eino 框架中的 Agent 概念和实现方式有所帮助！