如何使用 pyproject.toml 设置应用

必须为应用配置配置文件，才能将其部署到 LangSmith（或自托管）。本操作指南介绍使用 pyproject.toml 定义包依赖来设置应用以进行部署的基本步骤。

本示例基于此仓库，它使用 LangGraph 框架。

最终仓库结构大致如下：

my-app/
├── my_agent # all project code lies within here
│   ├── utils # utilities for your graph
│   │   ├── __init__.py
│   │   ├── tools.py # tools for your graph
│   │   ├── nodes.py # node functions for your graph
│   │   └── state.py # state definition of your graph
│   ├── __init__.py
│   └── agent.py # code for constructing your graph
├── .env # environment variables
├── langgraph.json  # configuration file for LangGraph
└── pyproject.toml # dependencies for your project

TIP

LangSmith Deployment 支持部署 LangGraph 图。不过，图的节点实现可以包含任意代码。这意味着可以在节点内实现任何框架，并将其部署到 LangSmith Deployment。这样，你就可以在不使用额外 LangGraph OSS API 的情况下实现核心应用逻辑，同时仍然使用 LangSmith 进行部署、扩缩容和可观测性。更多详情请参阅将任何框架与 LangSmith Deployment 配合使用。

你也可以使用以下方式设置：

• requirements.txt：如需依赖管理，请查看本操作指南，了解如何为 LangSmith 使用 requirements.txt。
• monorepo：要部署位于 monorepo 中的图，请参阅此仓库，其中提供了示例。

每个步骤之后都会提供一个示例文件目录，演示代码的组织方式。

指定依赖

可以选择在以下文件之一中指定依赖：pyproject.toml、setup.py 或 requirements.txt。如果未创建这些文件，则可以在稍后的配置文件中指定依赖。

以下依赖将包含在镜像中，你也可以在代码中使用它们，只要版本范围兼容：

langgraph>=0.4.10,<2
langgraph-sdk>=0.3.5
langgraph-checkpoint>=3.0.1,<5
langchain-core>=0.3.66
langsmith>=0.7.31
orjson>=3.9.7
httpx>=0.25.0
tenacity>=8.0.0
uvicorn>=0.26.0
sse-starlette>=2.1.3,<3.4.0
uvloop>=0.18.0
httptools>=0.5.0
jsonschema-rs>=0.20.0
structlog>=24.1.0
cloudpickle>=3.0.0
truststore>=0.1
protobuf>=6.32.1,<7.0.0
grpcio>=1.81.0,<1.82.0
grpcio-tools>=1.81.0,<1.82.0
grpcio-health-checking>=1.81.0,<1.82.0
opentelemetry-api>=0.0.1
opentelemetry-sdk>=0.0.1
opentelemetry-exporter-otlp-proto-http>=0.0.1

示例 pyproject.toml 文件：

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-agent"
version = "0.0.1"
description = "An excellent agent build for LangSmith."
authors = [
    {name = "Assistant", email = "1223+assistant@users.noreply.github.com"}
]
license = {text = "MIT"}
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "langgraph>=0.6.0",
    "langchain-fireworks>=0.1.3"
]

[tool.hatch.build.targets.wheel]
packages = ["my_agent"]

示例文件目录：

my-app/
└── pyproject.toml   # Python packages required for your graph

指定环境变量

可以选择在文件中（例如 .env）指定环境变量。有关为部署配置其他变量，请参阅环境变量参考。

示例 .env 文件：

MY_ENV_VAR_1=foo
MY_ENV_VAR_2=bar
FIREWORKS_API_KEY=key

示例文件目录：

my-app/
├── .env # file with environment variables
└── pyproject.toml

TIP

默认情况下，LangSmith 遵循 uv/pip 的行为，不会安装预发布版本，除非明确允许。如果你想使用预发布版本，有以下选项：

• 使用 pyproject.toml：在 [tool.uv] 部分添加 allow-prereleases = true。
• 使用 requirements.txt 或 setup.py：必须显式指定每个预发布依赖，包括传递依赖。例如，如果你声明 a==0.0.1a1，而 a 依赖 b==0.0.1a1，那么你还必须在依赖中显式包含 b==0.0.1a1。

定义图

实现你的图。图可以在单个文件或多个文件中定义。请记下要包含在应用中的每个 CompiledStateGraph 的变量名。稍后创建配置文件时会用到这些变量名。

示例 agent.py 文件，展示了如何从你定义的其他模块导入（此处未显示模块代码，请参阅此仓库了解其实现）：

# my_agent/agent.py
from typing import Literal
from typing_extensions import TypedDict

from langgraph.graph import StateGraph, END, START
from my_agent.utils.nodes import call_model, should_continue, tool_node # import nodes
from my_agent.utils.state import AgentState # import state

# Define the runtime context
class GraphContext(TypedDict):
    model_name: Literal["anthropic", "openai"]

workflow = StateGraph(AgentState, context_schema=GraphContext)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)
workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

graph = workflow.compile()

示例文件目录：

my-app/
├── my_agent # all project code lies within here
│   ├── utils # utilities for your graph
│   │   ├── __init__.py
│   │   ├── tools.py # tools for your graph
│   │   ├── nodes.py # node functions for your graph
│   │   └── state.py # state definition of your graph
│   ├── __init__.py
│   └── agent.py # code for constructing your graph
├── .env
└── pyproject.toml

创建配置文件

创建一个名为 langgraph.json 的配置文件。有关配置文件中 JSON 对象各键的详细说明，请参阅配置文件参考。

示例 langgraph.json 文件：

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./my_agent/agent.py:graph"
  },
  "env": ".env"
}

请注意，CompiledGraph 的变量名会出现在顶层 graphs 键中每个子键值的末尾（即 :<variable_name>）。

WARNING

配置文件位置 配置文件必须放在与包含已编译图及相关依赖的 Python 文件同级或更高级别的目录中。

示例文件目录：

my-app/
├── my_agent # all project code lies within here
│   ├── utils # utilities for your graph
│   │   ├── __init__.py
│   │   ├── tools.py # tools for your graph
│   │   ├── nodes.py # node functions for your graph
│   │   └── state.py # state definition of your graph
│   ├── __init__.py
│   └── agent.py # code for constructing your graph
├── .env # environment variables
├── langgraph.json  # configuration file for LangGraph
└── pyproject.toml # dependencies for your project

下一步

设置项目并将其放入 GitHub 仓库后，就可以部署应用了。

---