bootstrapping-deepagents-env

能力目标

把一台干净机器变成可用的 DeepAgents 开发环境：解释器版本达标、依赖隔离在虚拟环境里、主包与模型提供方包装齐并核验、凭证从环境变量注入不落进源码，最后跑通一个最小示例，在终端看到一条完整的工具调用闭环。

前置

• DeepAgents 是纯 Python 编排层，算力都在远端模型 API 上，本机不需要 GPU 或大内存。
• 需要一个支持工具调用的模型凭证。下面用 DeepSeek 的 OpenAI 兼容端点，环境变量名 DEEPSEEK_API_KEY。
• 概念（智能体装具、工具调用循环）见知识库，本流程只做落地操作。

实操流程

1. 核对本机解释器与包管理器版本。整条依赖链要求 Python >=3.11,<4.0，这是包元数据里唯一的硬约束（该下限会随依赖链演进上移，以安装时的报错信息为准）：

   python3 --version
   uv --version
   

   macOS 系统自带的 python3 常年停在 3.9.x，直接 pip install deepagents 会因解释器版本不达标失败，且报错往往指向某个依赖包、不直说版本问题。看到低于 3.11 就走第 2 步用 uv 置备解释器。

2. 用 uv 置备一个达标解释器并建虚拟环境。uv 既装包也能直接提供指定版本的解释器，这正是官方推荐 uv add deepagents 而不是裸 pip 的原因：

   curl -LsSf https://astral.sh/uv/install.sh | sh   # 未装 uv 时先装（Windows 用 winget install astral-sh.uv）
   uv python list | grep -E "3.1[12]"                # 看 uv 手里有哪些可用解释器
   uv venv --python 3.12 .venv
   source .venv/bin/activate                         # Windows 为 .venv\Scripts\activate
   .venv/bin/python --version                        # 应为 3.12.x
   

3. 装主包与模型提供方包。提供方包按你要接的模型选一个，DeepSeek 走 OpenAI 兼容端点、用 langchain-openai 一个包就够：

   uv pip install -qU deepagents langchain-openai
   # 换别的提供方时的等价命令：
   # pip install -qU deepagents langchain-anthropic      # Anthropic
   # pip install -qU deepagents langchain-google-genai   # Google
   

4. 核验真实安装版本并实跑一次导入，不要只看安装日志：

   .venv/bin/python -c "from importlib.metadata import version; \
   print('deepagents ', version('deepagents')); \
   print('langchain  ', version('langchain')); \
   print('langgraph  ', version('langgraph')); \
   print('langchain-openai', version('langchain-openai')); \
   import deepagents; print('import deepagents OK')"
   

   统一用标准库 importlib.metadata.version，它从安装元数据读版本、对任意已装包通用。

5. 注入模型凭证。凭证是机密，只进环境变量、不进源码也不进截图：

   export DEEPSEEK_API_KEY=sk-...   # 真值从本地 .env 或凭证文件注入
   

6. 写最小示例 hello_agent.py——一个工具 + 一个系统提示 + 一次 invoke：

   import os
   from langchain_openai import ChatOpenAI
   from deepagents import create_deep_agent
   
   def get_weather(city: str) -> str:
       """Get weather for a given city."""
       return f"It's always sunny in {city}!"
   
   model = ChatOpenAI(
       model="deepseek-chat",
       base_url="https://api.deepseek.com",
       api_key=os.environ["DEEPSEEK_API_KEY"],
   )
   
   agent = create_deep_agent(
       model=model,
       tools=[get_weather],
       system_prompt="You are a helpful assistant",
   )
   
   result = agent.invoke(
       {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
   )
   print(result["messages"][-1].content)
   print(f"消息总数: {len(result['messages'])}")
   

   三处不能省：工具函数的文档字符串会作为工具说明喂给模型、模型靠它判断何时调用；base_url 不写请求就发去 OpenAI；api_key 从环境变量读。

7. 运行：

   .venv/bin/python hello_agent.py
   

校验回路

• 激活后 .venv/bin/python --version 显示 ≥3.11 的版本。
• 版本核验命令四个包全部打印版本号，末尾出现 import deepagents OK，无 ImportError。
• 示例运行输出消息总数 4：用户提问、模型发起 get_weather 调用、工具返回、模型整理成自然语言答复。最终回复复用了工具返回的措辞（如 It's always sunny in San Francisco!）而不是模型自己编的天气。看到这条四段闭环即环境可用。

常见陷阱

• 直接用系统 python3 装包：低于 3.11 时报错指向某个依赖包、不会直说版本太老。装包前先核对版本，不达标就用 uv 置备一个。
• 用 langgraph.__version__ 取版本：该包没有导出这个属性，会抛 AttributeError。一律改用 importlib.metadata.version("langgraph")。
• 照抄官方的提供方字符串写法却没装对应包：create_deep_agent(model="deepseek:deepseek-chat", ...) 会去找 langchain-deepseek 这个专属提供方包，没装就抛 ImportError: Initializing ChatDeepSeek requires the langchain-deepseek package。两条解法都成立、二选一即可：装上 langchain-deepseek 继续用字符串写法；或改用 ChatOpenAI(model="deepseek-chat", base_url="https://api.deepseek.com", ...) 预配置实例写法。只装了 langchain-openai 就走后者。
• 给 OpenAI 兼容端点写错提供方前缀：把 DeepSeek 写成 "openai:deepseek-chat" 会让请求走 OpenAI 的 Responses API，而该端点不支持，返回 404 NotFoundError。接兼容端点用预配置实例写法最稳。
• 把凭证写进脚本再提交：一律 os.environ[...] 读取，仓库里只放占位符模板。