Agno 与 DeepSeek V4 集成实战指南Thinking 模式、推理控制与工具调用【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno本篇技术指南以 cookbook/90_models/deepseek/README.md 为核心骨架深入讲解如何在 Agno 框架中使用 DeepSeek 官方 OpenAI 兼容 API覆盖 V4 系列模型deepseek-v4-flash与deepseek-v4-pro的选型、Thinking 模式默认开启机制、reasoning_effort推理力度控制、结构化输出、工具调用与失败重试等完整能力。读完本文你将能够在 Agno 中快速搭建基于 DeepSeek 的 Agent、按场景开关思考模式、并把思维链输出到终端用于调试。一、DeepSeek 模型在 Agno 中的定位DeepSeek 提供 OpenAI 兼容的 APIhttps://api.deepseek.com因此在 Agno 中由agno.models.deepseek.DeepSeek类承载该类继承自OpenAILike见 libs/agno/agno/models/deepseek/deepseek.py这意味着 DeepSeek 可以被当作一个换端点的 OpenAI 兼容模型直接使用无需额外的适配层。从源码可以确认DeepSeek类的默认配置为id默认deepseek-v4-flashname默认DeepSeekprovider默认DeepSeekbase_url默认https://api.deepseek.comapi_key默认从环境变量DEEPSEEK_API_KEY读取见 deepseek.py若未设置 API Key构造客户端时会立即抛出ModelAuthenticationError并提示设置DEEPSEEK_API_KEY见 deepseek.py。二、可用模型与 deprecated 模型 id 迁移2.1 V4 系列模型原文档给出的模型清单如下Model idDescriptiondeepseek-v4-flashFast V4 model (default)1M context。Hybridthinking non-thinking。deepseek-v4-proFlagship V4 model1M context。Hybridthinking non-thinking。两者均支持 1M 上下文且属于混合模型——同一个 id 既可开启 Thinking返回reasoning_content也可关闭 Thinking直接返回内容。flash定位为快速版默认pro为旗舰版适合高难度推理任务。2.2 Deprecated 模型 idLegacy idMaps todeepseek-chatdeepseek-v4-flash的 non-thinking 模式deepseek-reasonerdeepseek-v4-flash的 thinking 模式这些旧 id 仍然可用服务端会路由到 V4 对应模式但官方建议迁移到新 id。在 Agno 源码中也有对应的实现印证_non_thinking_model_ids集合包含deepseek-chat即该旧 id 默认不开启 thinking见 deepseek.py而deepseek-reasoner本身即 thinking 模型无需特殊处理。三、环境准备与安装1. 创建并激活虚拟环境python3 -m venv ~/.venvs/aienv source ~/.venvs/aienv/bin/activate2. 导出DEEPSEEK_API_KEYexport DEEPSEEK_API_KEY***需要先到 DeepSeek 开放平台申请 API Key。Agno 源码会在构造客户端时读取该环境变量未设置则直接抛错见 deepseek.py。3. 安装依赖库uv pip install -U openai ddgs duckdb yfinance agno其中openai是底层 OpenAI 兼容客户端ddgsDuckDuckGo 搜索与yfinance金融数据分别是 tool_use.py、thinking_tool_calls.py 等工具调用示例的可选依赖agno为本框架本体。根据 cookbook/90_models/deepseek/TEST_LOG.md 的记录工具类示例需要在安装了这些可选依赖的 venv 中运行。四、Thinking 模式默认开启的推理机制4.1 默认行为DeepSeek V4 模型的 Thinking 模式默认开启因此模型开箱即返回reasoning_content思维链内容这与旧版deepseek-chat的行为不同。Agno 源码中的_thinking_enabled()方法完整描述了这一决策逻辑见 deepseek.pyuse_thinking显式设置时以显式值为准未设置时thinking-capable 模型V4 系列默认开启legacy 非思考模型deepseek-chat默认关闭。开启时get_request_params()会向请求注入extra_body{thinking: {type: enabled}}显式关闭时则注入{type: disabled}见 deepseek.py。4.2 用use_thinking开关DeepSeek(iddeepseek-v4-flash, use_thinkingFalse)关闭思考响应更快、更便宜且不再返回reasoning_contentuse_thinkingTrue强制开启思考。完整的对照示例见 thinking_mode.py它同时构造了一个默认开启思考的thinking_agent和一个use_thinkingFalse的non_thinking_agent用同一个问题Why is the sky blue?分别流式调用验证reasoning_content是否存在。from agno.agent import Agent from agno.models.deepseek import DeepSeek # Thinking enabled (default) - returns reasoning_content thinking_agent Agent(modelDeepSeek(iddeepseek-v4-flash), markdownTrue) # Thinking disabled - faster, no reasoning_content non_thinking_agent Agent( modelDeepSeek(iddeepseek-v4-flash, use_thinkingFalse), markdownTrue, ) if __name__ __main__: thinking_agent.print_response(Why is the sky blue?, streamTrue) non_thinking_agent.print_response(Why is the sky blue?, streamTrue)4.3 思考模式的参数约束当 Thinking 模式处于激活状态时temperature、top_p、presence_penalty、frequency_penalty会被 API 静默忽略。这是 DeepSeek V4 的硬性行为源码类注释中亦明确说明见 deepseek.py。因此追求确定性的任务如结构化抽取可考虑use_thinkingFalse以便自由调节采样参数需要深度推理的任务放弃上述采样参数专注于reasoning_effort。五、控制推理力度reasoning_effort对于高要求的 Agent 任务DeepSeek 建议将reasoning_effort设为max。合法取值为high与maxlow、medium会在服务端被映射为high。默认不设置None此时 API 使用其自身默认值high。从源码看reasoning_effort仅在 thinking 开启时有效当关闭 thinking 时get_request_params()会将其从请求参数中移除避免无效参数见 deepseek.py。from agno.agent import Agent from agno.models.deepseek import DeepSeek agent Agent( modelDeepSeek(iddeepseek-v4-pro, reasoning_effortmax), markdownTrue, ) task ( A farmer needs to cross a river with a fox, a chicken and a sack of grain. The boat only fits the farmer and one item. The fox cannot be left alone with the chicken, and the chicken cannot be left alone with the grain. Provide a step-by-step solution. ) if __name__ __main__: agent.print_response(task, streamTrue, show_full_reasoningTrue)要点show_full_reasoningTrue会在终端完整打印思维链reasoning_content适合调试与验证推理过程。完整示例见 reasoning_effort.py。六、搭建 Agent 的四种运行模式basi.py 演示了同一个 Agent 的四种调用方式这是 Agno 中最基础的用法from agno.agent import Agent, RunOutput from agno.models.deepseek import DeepSeek import asyncio agent Agent(modelDeepSeek(iddeepseek-v4-flash), markdownTrue) if __name__ __main__: # --- Sync --- agent.print_response(Share a 2 sentence horror story) # --- Sync Streaming --- agent.print_response(Share a 2 sentence horror story, streamTrue) # --- Async --- asyncio.run(agent.aprint_response(Share a 2 sentence horror story)) # --- Async Streaming --- asyncio.run(agent.aprint_response(Share a 2 sentence horror story, streamTrue))如需把响应存入变量而不是打印可使用run: RunOutput agent.run(...)然后访问run.content示例中以注释形式给出。提示由于 Thinking 默认开启流式场景下响应会先产出reasoning_content增量、再产出正文增量。测试日志 TEST_LOG.md 提到集成测试已按此thinking-aware行为更新意味着你的流式处理逻辑需要兼容这一顺序。七、推理 Agent用思维链解复杂谜题reasoning_agent.py 展示了一个推理型 Agent使用旗舰模型deepseek-v4-pro求解传教士与食人族过河问题并要求给出分步解答与 ASCII 示意图。from agno.agent import Agent from agno.models.deepseek import DeepSeek task ( Three missionaries and three cannibals need to cross a river. They have a boat that can carry up to two people at a time. If, at any time, the cannibals outnumber the missionaries on either side of the river, the cannibals will eat the missionaries. How can all six people get across the river safely? Provide a step-by-step solution and show the solutions as an ascii diagram ) agent Agent( modelDeepSeek( iddeepseek-v4-pro, ), markdownTrue, ) agent.print_response(task, streamTrue)这类场景正是deepseek-v4-pro Thinking 模式的典型用例复杂约束类问题需要模型先展开推理再给出结构化解答markdownTrue让输出保持可读的排版。八、结构化输出JSON 模式是可靠路径DeepSeek 官方支持 JSON 模式response_format{type: json_object}但不支持原生的 json_schema 结构化输出。因此在 Agno 中使用output_schema时推荐显式设置use_json_modeTrue。这一结论在源码中也有直接体现DeepSeek类的supports_native_structured_outputs False见 deepseek.py。structured_output.py 演示了两种写法from typing import List from agno.agent import Agent, RunOutput from agno.models.deepseek import DeepSeek from pydantic import BaseModel, Field class MovieScript(BaseModel): setting: str Field(..., descriptionProvide a nice setting for a blockbuster movie.) ending: str Field(..., descriptionEnding of the movie. If not available, provide a happy ending.) genre: str Field(..., descriptionGenre of the movie. If not available, select action, thriller or romantic comedy.) name: str Field(..., descriptionGive a name to this movie) characters: List[str] Field(..., descriptionName of characters for this movie.) storyline: str Field(..., description3 sentence storyline for the movie. Make it exciting!) # Agent that uses JSON mode (recommended for DeepSeek) json_mode_agent Agent( modelDeepSeek(iddeepseek-v4-flash), descriptionYou help people write movie scripts., output_schemaMovieScript, use_json_modeTrue, ) # Agent that uses native structured outputs (output_schema without JSON mode) structured_output_agent Agent( modelDeepSeek(iddeepseek-v4-flash), descriptionYou help people write movie scripts., output_schemaMovieScript, ) if __name__ __main__: json_mode_agent.print_response(New York) structured_output_agent.print_response(New York)根据 TEST_LOG.md 的验证结果两种方式最终都能产出合法 JSONuse_json_modeTrue走官方 JSON 模式仅传output_schema时Agno 会退回到基于提示词的 JSON 兜底方案。实战建议优先use_json_modeTrue它更稳定可靠。九、工具调用Thinking 与工具协作DeepSeek V4 模型在 Thinking 与非 Thinking 模式下均支持工具调用且 Thinking 模式下的工具调用能力进一步增强——模型在输出最终答案前可以进行多轮推理 → 工具调用 → 推理的循环从而提升回答质量。tool_use.py使用deepseek-v4-flashWebSearchTools同步与异步流式两种方式询问法国正在发生什么import asyncio from agno.agent import Agent from agno.models.deepseek import DeepSeek from agno.tools.websearch import WebSearchTools agent Agent( modelDeepSeek(iddeepseek-v4-flash), tools[WebSearchTools()], markdownTrue, ) if __name__ __main__: agent.print_response(Whats happening in France?) asyncio.run(agent.aprint_response(Whats happening in France?, streamTrue))thinking_tool_calls.py使用deepseek-v4-proWebSearchTools流式输出并以show_full_reasoningTrue展示思考与工具调用交织的过程from agno.agent import Agent from agno.models.deepseek import DeepSeek from agno.tools.websearch import WebSearchTools agent Agent( modelDeepSeek(iddeepseek-v4-pro), tools[WebSearchTools()], markdownTrue, streamTrue, ) agent.print_response(Whats happening in France?, show_full_reasoningTrue)运行工具类示例前需安装ddgsuv pip install ddgs。工具调用参数会在reasoning_content中体现结合show_full_reasoningTrue可以完整观察模型先想后做的决策链路。十、失败重试机制当 API 请求失败网络抖动、限流、无效模型 id 等时可以通过retries、delay_between_retries、exponential_backoff三个参数配置重试行为。retry.py 用一个故意写错的模型 iddeepseek-wrong-id来触发重试from agno.agent import Agent from agno.models.deepseek import DeepSeek wrong_model_id deepseek-wrong-id agent Agent( modelDeepSeek( idwrong_model_id, retries3, # 请求重试次数 delay_between_retries1, # 重试间隔秒 exponential_backoffTrue, # 若为 True每次重试间隔翻倍 ), ) agent.print_response(What is the capital of France?)参数说明retries最大重试次数delay_between_retries两次重试之间的基础间隔秒exponential_backoff开启后间隔按 2 的幂次递增1s → 2s → 4s…适合应对限流类错误。十一、示例清单与运行方式原文档给出的全部示例及运行命令如下在仓库根目录执行# Basic agent (sync, async, streaming) python cookbook/90_models/deepseek/basic.py # Tool use python cookbook/90_models/deepseek/tool_use.py # Structured output python cookbook/90_models/deepseek/structured_output.py # Reasoning agent (thinking mode) python cookbook/90_models/deepseek/reasoning_agent.py # Thinking tool calls python cookbook/90_models/deepseek/thinking_tool_calls.py # Controlling reasoning effort python cookbook/90_models/deepseek/reasoning_effort.py # Toggling thinking mode on/off python cookbook/90_models/deepseek/thinking_mode.py # Retry behavior python cookbook/90_models/deepseek/retry.py各示例均需提前设置DEEPSEEK_API_KEY环境变量。按 TEST_LOG.md 的实测记录2026-05-29针对 DeepSeek V4 APIbasic.py、thinking_mode.py、reasoning_effort.py、structured_output.py全部 PASS相关单元测试libs/agno/tests/unit/reasoning/test_reasoning_checkers.py与libs/agno/tests/unit/models/deepseek/test_deepseek.py共79 passed无需网络集成测试libs/agno/tests/integration/models/deepseek/test_basic.py共9 passed流式测试已适配先 reasoning_content 后 content的顺序tool_use.py、structured_output.py、reasoning_agent.py、thinking_tool_calls.py依赖可选 cookbook 依赖ddgs/yfinance需在安装了这些依赖的演示 venv 中运行。十二、选型建议速查场景推荐配置默认通用 AgentDeepSeek(iddeepseek-v4-flash)thinking 默认开启追求速度/成本不需要思维链DeepSeek(iddeepseek-v4-flash, use_thinkingFalse)高难度推理数学、谜题、复杂规划DeepSeek(iddeepseek-v4-pro, reasoning_effortmax)配合show_full_reasoningTrue观察思维链结构化输出output_schemaYourModeluse_json_modeTrue需要实时信息tools[WebSearchTools()]配合thinking_tool_calls.py体验多轮推理工具调用请求不稳定环境retries3, delay_between_retries1, exponential_backoffTrue注意事项汇总Thinking 开启时temperature/top_p/presence_penalty/frequency_penalty被 API 忽略reasoning_effort合法值为high与max关闭 thinking 后该参数自动失效旧 iddeepseek-chat/deepseek-reasoner仍可用但建议迁移到 V4 系列DeepSeek 无原生 json_schema 结构化输出use_json_modeTrue是可靠路径。通过以上配置与源码级原理你已可以在 Agno 中完整驾驭 DeepSeek V4 的混合思考能力构建从简单问答到复杂推理、从工具调用到结构化输出的各类 Agent 应用。【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考