当使用 LangChain 在本地构建智能体时,可视化智能体内部的运行情况、实时与之交互并在问题发生时进行调试会很有帮助。LangSmith Studio 是一个免费的可视化界面,用于在本地机器上开发和测试你的 LangChain 智能体。 Studio 连接到你本地运行的智能体,向你展示智能体采取的每一个步骤:发送给模型的提示词、工具调用及其结果,以及最终输出。你可以测试不同的输入,检查中间状态,并迭代优化智能体的行为,无需额外代码或部署。 本页面描述了如何将 Studio 与你的本地 LangChain 智能体进行设置。

前提条件

开始之前,请确保你已具备以下条件:
  • 一个 LangSmith 账户:在 smith.langchain.com 免费注册或登录。
  • 一个 LangSmith API 密钥:按照创建 API 密钥指南操作。
  • 如果你不想将数据追踪到 LangSmith,请在你的应用程序 .env 文件中设置 LANGSMITH_TRACING=false。禁用追踪后,任何数据都不会离开你的本地服务器。

设置本地智能体服务器

1. 安装 LangGraph CLI

LangGraph CLI 提供了一个本地开发服务器(也称为智能体服务器),用于将你的智能体连接到 Studio。

2. 准备你的智能体

如果你已经有一个 LangChain 智能体,可以直接使用。此示例使用一个简单的电子邮件智能体:
agent.py

3. 环境变量

Studio 需要一个 LangSmith API 密钥来连接你的本地智能体。在你的项目根目录下创建一个 .env 文件,并添加你从 LangSmith 获取的 API 密钥。
确保你的 .env 文件没有被提交到版本控制系统(如 Git)。
.env

4. 创建 LangGraph 配置文件

LangGraph CLI 使用一个配置文件来定位你的智能体并管理依赖项。在你的应用程序目录中创建一个 langgraph.json 文件:
langgraph.json
create_agent 函数会自动返回一个编译好的 LangGraph 图,这正是配置文件中 graphs 键所期望的。
关于配置文件 JSON 对象中每个键的详细解释,请参阅 LangGraph 配置文件参考。
此时,项目结构将如下所示:

5. 安装依赖项

从根目录安装你的项目依赖项:

6. 在 Studio 中查看你的智能体

启动开发服务器,将你的智能体连接到 Studio:
Safari 会阻止到 Studio 的 localhost 连接。要解决此问题,请使用 --tunnel 参数运行上述命令,通过安全隧道访问 Studio。你需要通过在 Studio UI 中单击 连接到本地服务器 手动将隧道 URL 添加到允许的源中。具体步骤请参阅故障排除指南。
服务器运行后,你的智能体可以通过 API 地址 http://127.0.0.1:2024 访问,也可以通过 Studio UI 地址 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 访问:
在 Studio UI 中查看智能体
Studio 连接到本地智能体后,你可以快速迭代优化智能体的行为。运行一个测试输入,在 LangSmith 中检查完整的执行跟踪,包括提示词、工具参数、返回值以及令牌/延迟指标。当出现问题时,Studio 会捕获异常及其周围状态,帮助你理解发生了什么。 开发服务器支持热重载——在代码中修改提示词或工具签名,Studio 会立即反映这些更改。你可以从任意步骤重新运行会话线程来测试更改,而无需从头开始。这种工作流程适用于从简单的单工具智能体到复杂的多节点图。 有关如何运行 Studio 的更多信息,请参阅 LangSmith 文档中的以下指南:

视频指南