Qwen-Agent 配置完全指南从 LLM 后端到工具系统的参数详解与实战【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-AgentQwen-Agent 是一个基于 Qwen 系列模型的 Agent 框架其灵活性与可扩展性很大程度上来自两套核心配置体系通过llm_cfg字典配置 LLM 后端涵盖 DashScope 云端 API、OpenAI 兼容接口以及本地 vLLM/SGLang 服务以及通过function_list参数以字符串、字典、MCP 配置或工具对象四种形态装配工具能力。本文以官方配置文档为主体结合仓库源码逐项解析每个参数的语义、默认值、底层实现与常见踩坑点帮助你在实际项目中正确、高效地完成 Agent 的初始化与调优。LLM 配置llm_cfg参数详解Qwen-Agent 中所有 Agent如Assistant都通过一个名为llm_cfg的字典来指定 LLM 后端。框架会将该字典交给get_chat_model()完成模型对象的实例化只要字典中包含model_type就会直接从注册表LLM_REGISTRY中取出对应的模型类若未提供model_type框架还会根据model与model_server自动推断详见下文自动推断小节。因此理解这个字典的每一项含义是搭建 Qwen-Agent 应用的第一步。参数总览参数类型必填说明modelstr✅ 是要使用的模型名称例如qwen3-max、qwen3-vl-plus、qwen3-omni-flash、qwen3-coder-plusmodel_typestr✅ 是指定模型服务提供商并与模型能力绑定。使用阿里云 DashScope API•qwen_dashscopeLLM支持文本 → 文本•qwenvl_dashscopeVLM支持文本/图像/视频 → 文本•qwenaudio_dashscopeOmni 全模态模型支持文本/图像/视频/音频 → 文本使用 OpenAI 兼容 API•oaiLLM支持文本 → 文本•qwenvl_oaiVLM支持文本/图像/视频 → 文本•qwenaudio_oaiOmni 全模态模型支持文本/图像/视频/音频 → 文本model_serverstr⚠️ 条件必填仅在使用 OpenAI 兼容 API 时需要提供例如•http://localhost:8000/v1本地服务vLLM / SGLang 等•https://dashscope.aliyuncs.com/compatible-mode/v1DashScope 的 OpenAI 兼容模式端点api_keystr❌ 否用于认证的 API Key。•DashScope可在此处提供也可通过环境变量DASHSCOPE_API_KEY提供•OpenAI 兼容 API可在此处提供也可通过环境变量OPENAI_API_KEY提供generate_cfgdict❌ 否控制生成行为与解析逻辑详见下方小节关键参数的源码级解读model_type与模型能力的绑定。从源码看每个model_type都对应LLM_REGISTRY中一个注册的类例如qwen_dashscope对应QwenChatAtDS调用dashscope.Generation.calloai对应TextChatAtOAI基于openaiSDK 的chat.completions。support_multimodal_input、support_multimodal_output等属性决定了多模态消息的预处理与后处理策略见 qwen_agent/llm/base.py因此model_type选错会导致多模态能力无法正确启用。model_server的两种特殊行为。其一在get_chat_model()中如果model_type为oai或qwenvl_oai且model_server填的是dashscope框架会自动改写为https://dashscope.aliyuncs.com/compatible-mode/v1其二在TextChatAtOAI中model_server会被当作api_base/base_url使用见 qwen_agent/llm/oai.py#L44-L47。api_key的读取优先级。在initialize_dashscope()中DashScope 的api_key按配置字典 →DASHSCOPE_API_KEY环境变量的顺序读取OpenAI 兼容侧则按配置字典 →OPENAI_API_KEY环境变量 → 默认EMPTY的顺序见 qwen_agent/llm/oai.py#L49-L51。此外 DashScope 还支持通过base_http_api_url/base_websocket_api_url或环境变量DASHSCOPE_HTTP_URL/DASHSCOPE_WEBSOCKET_URL覆盖服务地址这在私有化网关场景下很有用。未提供model_type时的自动推断。若llm_cfg中省略model_type框架会按以下顺序推断见 qwen_agent/llm/init.py#L70-L100配置含azure_endpoint视为azuremodel_server以http开头视为oai模型名含-vl视为qwenvl_dashscope含-audio视为qwenaudio_dashscope含qwen视为qwen_dashscope。尽管如此官方文档仍建议显式声明model_type以明确模型能力边界。generate_cfg生成与解析控制generate_cfg是llm_cfg中的嵌套字典控制生成行为以及函数调用Function Calling的解析逻辑。参数如下参数类型默认值说明max_input_tokensint90000Agent 的最大上下文长度当上下文超过该长度时会自动执行上下文管理。该值应低于模型支持的最大输入长度以保证 Agent 正常运行use_raw_apiboolFalse是否使用模型服务端原生的工具调用解析例如 vLLM 内置的 parser。官方建议 qwen3-coder、qwen3-max 及后续系列模型设置为True未来将改为默认Trueenable thinking——若模型支持则启用思考模式具体写法取决于模型服务端协议• DashScopeenable_thinkingTrue• DashScope 的 OpenAI 兼容 APIextra_body: {enable_thinking: True}• vLLM 的 OpenAI 兼容 APIextra_body: {chat_template_kwargs: {enable_thinking: True}}其他参数——直接透传给模型服务的参数如top_p、temperature、max_tokens等关于max_input_tokens的默认值需要注意官方文档记录的默认值为 90000而框架层在 qwen_agent/settings.py 中定义的兜底默认值DEFAULT_MAX_INPUT_TOKENS为 58000可通过环境变量QWEN_AGENT_DEFAULT_MAX_INPUT_TOKENS覆盖。在 qwen_agent/llm/base.py#L190-L195 中每次调用 LLM 时该值会从generate_cfg弹出并调用_truncate_input_messages_roughly()对超长输入做粗略截断源码注释也明确指出与函数调用及多模态项相关的 token 估算并不精确因此这是一个保守策略。实际部署中建议结合所选模型的最大上下文显式设置例如调小至 6500get_chat_model的 docstring 中就有此示例。关于use_raw_api的实现细节框架在 qwen_agent/llm/base.py#L89-L96 中先读取环境变量QWEN_AGENT_USE_RAW_API再用generate_cfg[use_raw_api]覆盖并且对qwen_dashscope类型如果模型是Qwen3-Max会自动强制开启。开启后走raw_chat()路径且仅支持完整流式输出要求streamTrue且delta_streamFalse见 qwen_agent/llm/base.py#L220-L223。其他常用透传参数top_p、temperature会原样传给模型服务parallel_function_calls、function_choice、thought_in_content则用于控制函数调用解析见 qwen_agent/llm/function_calling.py#L59-L80。当通过 OpenAI v1 SDK 调用时top_k、repetition_penalty等 OpenAI 协议不支持的参数会被自动移入extra_body透传见 qwen_agent/llm/oai.py#L67-L74。实战示例DashScope APIllm_cfg { model: qwen3-max-preview, model_type: qwen_dashscope, # api_key: your-key, # 若已设置 DASHSCOPE_API_KEY 环境变量此项可省略 generate_cfg: { enable_thinking: True, use_raw_api: True, top_p: 0.8, } }实战示例本地模型vLLM / SGLangllm_cfg { model: Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, generate_cfg: { top_p: 0.85, extra_body: {chat_template_kwargs: {enable_thinking: True}}, } }注意model_type在此省略后框架会因model_server以http开头而自动推断为oaiapi_key填EMPTY是本地服务不校验密钥时的常见写法。仓库中的 examples/assistant_qwen3.py 还额外展示了第三种形态——通过model_server: https://dashscope.aliyuncs.com/compatible-mode/v1使用 DashScope 的 OpenAI 兼容接口并给出了thought_in_content参数的适用说明当响应以think.../think内容拼接返回、而非通过reasoning_content与content分离时需要设置该参数以修正工具调用解析策略。注意事项默认支持并行工具调用框架的 Function Calling 流程对并行工具调用开箱即用parallel_function_calls相关逻辑可在 qwen_agent/llm/function_calling.py 中查看。FnCallAgent每轮运行最多允许MAX_LLM_CALL_PER_RUN次 LLM 调用默认 20可通过环境变量QWEN_AGENT_MAX_LLM_CALL_PER_RUN调整见 qwen_agent/settings.py#L24 与 qwen_agent/agents/fncall_agent.py#L75。完整可运行示例可参考仓库的 examples/ 目录。工具配置function_list的四种装配方式初始化Assistant或其他支持工具调用的 Agent时可以通过function_list参数指定可用的工具集合。在 qwen_agent/agents/assistant.py#L85 与 qwen_agent/agent.py#L63-L65 中可以确认该参数接收一个列表每个元素会被逐个交给_init_tool()完成注册最终汇入 Agent 的function_map。支持以下三种元素类型第四种即三种类型的自由组合框架会自动识别并加载对应工具。类型 1字符串str— 引用预注册的内置工具用途快速启用一个已在TOOL_REGISTRY中注册的工具。格式工具名的字符串。要求该工具必须已预先注册例如通过register_tool装饰器。示例code_interpreterTOOL_REGISTRY定义在 qwen_agent/tools/base.py#L24register_tool装饰器负责把工具类写入注册表并校验工具名唯一性qwen_agent/tools/base.py#L44-L59。仓库内置工具如CodeInterpreter、WebSearch、DocParser、Retrieval、ImageGen、Storage等均在 qwen_agent/tools/init.py 中完成注册。类型 2字典dict— 配置注册工具或 MCP 服务器字典格式有两种子类型(a) 标准工具配置字典用途向已注册工具传入自定义配置。格式{ name: tool_name, # 必填已注册工具的名称 other_config: ... # 可选附加配置参数 }要求name必须对应TOOL_REGISTRY中已注册的工具。示例{ name: weather, api_key: your_key }从 qwen_agent/agent.py#L226-L237 可以看到这类字典最终会以TOOL_REGISTRYtool_name的形式实例化字典中除name外的所有键如api_key都会作为cfg传入工具构造函数因此自定义配置的字段取决于目标工具本身的实现。(b) MCP 服务器配置字典特殊键mcpServers用途通过**模型上下文协议Model Context ProtocolMCP**动态加载一组工具。格式{ mcpServers: { server_alias_1: { command: executable, args: [arg1, arg2, ...] }, server_alias_2: { ... } } }行为系统调用MCPManager().initConfig(...)启动 MCP 服务并自动发现可用工具。mcpServers下的每个键如time、fetch代表一个独立的 MCP 工具服务器。示例{ mcpServers: { time: { command: uvx, args: [mcp-server-time, --local-timezoneAsia/Shanghai] }, fetch: { command: uvx, args: [mcp-server-fetch] } } }MCP 装配在 qwen_agent/agent.py#L218-L224 中实现命中mcpServers键后交给MCPManager().initConfig()完成异步初始化。MCPManager是单例实现qwen_agent/tools/mcp_manager.py#L31-L55并通过 monkey patch MCP 客户端保证进程随 Qwen-Agent 退出时被正确回收。校验逻辑qwen_agent/tools/mcp_manager.py#L94-L137支持commandargsstdio 传输以及urlheaders远程服务两种描述方式还允许env注入环境变量。从每个服务器发现的工具会被注册为server_name - tool.name的形式qwen_agent/tools/mcp_manager.py#L198并在inputSchema缺失required字段时自动补空列表以兼容 OpenAI Schemaqwen_agent/tools/mcp_manager.py#L181-L190。依赖提示使用 MCP 功能需要安装mcp包即pip install -U mcpqwen_agent/tools/mcp_manager.py#L42-L45。类型 3BaseTool实例 — 直接提供工具对象用途直接传入一个已完全实例化的工具对象适合高级定制场景。格式一个继承自BaseTool的类的实例。示例伪代码my_tool CustomSearchTool(config{...}) # 然后将 my_tool 直接放入 function_listBaseTool是全部工具的抽象基类qwen_agent/tools/base.py#L109-L138要求子类声明name、description、parameters并实现call()方法parameters若以字典形式提供必须是合法的 OpenAI 兼容 JSON Schema由is_tool_schema()校验。当传入实例时Agent 会直接将其写入function_mapqwen_agent/agent.py#L212-L217不再经过注册表因此这是注入自定义工具最彻底的方式。处理重名工具如果列表中有多个条目试图注册同名工具系统会用列表中最后一次出现的工具覆盖之前的同名工具。源码中每次覆盖都会打印警告Repeatedly adding tool {tool_name}, will use the newest tool in function list见 qwen_agent/agent.py#L215-L216。⚠️ 注意应避免使用重名工具完整使用示例tools [ # 类型 1字符串引用内置工具 code_interpreter, # 类型 2a以字典形式配置已注册工具 { name: weather, api_key: your_openweather_key }, # 类型 2bMCP 服务器配置 { mcpServers: { time: { command: uvx, args: [mcp-server-time, --local-timezoneAsia/Shanghai] }, file: { command: uvx, args: [mcp-server-filesystem] } } }, # 类型 3直接传入 BaseTool 实例可选 # MyCustomTool(config{...}) ] bot Assistant( llmllm_cfg, function_listtools )该示例与仓库中的 examples/assistant_qwen3.py#L64-L80 结构一致——后者同时混用了mcpServerstime、fetch与内置工具code_interpreter可作为真实可运行的参照。Assistant在运行时会把function_map中每个工具的function信息name/description/parameters注入给 LLM见 qwen_agent/agents/fncall_agent.py#L83-L85工具执行结果则以FUNCTION角色的消息回填对话qwen_agent/agents/fncall_agent.py#L97-L104从而形成完整的模型决策 → 工具执行 → 结果反馈闭环。常见错误排查错误原因解决方案ValueError: Tool xxx is not registered.尝试使用一个不在TOOL_REGISTRY中的工具名确保工具已注册如register_tool或改用 MCP /BaseTool方式提供MCP 服务器启动失败command/args配置错误或环境中缺少对应 MCP 服务器先在终端验证命令能否正常执行确保mcp-server-time等工具已安装例如通过uvx从源码看ValueError的确由_init_tool()中的注册表查表直接抛出错误信息与文档完全一致MCP 初始化失败则会由MCPManager.initConfig()抛出并携带日志qwen_agent/tools/mcp_manager.py#L148-L150。小结function_list参数的设计目标是灵活支持多种工具集成策略简单用字符串快速启用内置工具。可配置用字典定制已注册工具的参数。可扩展用mcpServers接入整个 MCP 生态。完全自定义传入BaseTool实例获得完全控制权。将这些方式组合使用你可以构建功能强大且易于扩展的工具调用型 Agent。与此同时llm_cfg的精细配置model_type能力绑定、generate_cfg的上下文与解析控制、思考模式的按服务端差异化写法为上层 Agent 行为提供了稳定可靠的大模型底座——两者结合即可系统性地掌握 Qwen-Agent 的核心配置方法论。【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Qwen-Agent 配置完全指南：从 LLM 后端到工具系统的参数详解与实战
Qwen-Agent 配置完全指南从 LLM 后端到工具系统的参数详解与实战【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-AgentQwen-Agent 是一个基于 Qwen 系列模型的 Agent 框架其灵活性与可扩展性很大程度上来自两套核心配置体系通过llm_cfg字典配置 LLM 后端涵盖 DashScope 云端 API、OpenAI 兼容接口以及本地 vLLM/SGLang 服务以及通过function_list参数以字符串、字典、MCP 配置或工具对象四种形态装配工具能力。本文以官方配置文档为主体结合仓库源码逐项解析每个参数的语义、默认值、底层实现与常见踩坑点帮助你在实际项目中正确、高效地完成 Agent 的初始化与调优。LLM 配置llm_cfg参数详解Qwen-Agent 中所有 Agent如Assistant都通过一个名为llm_cfg的字典来指定 LLM 后端。框架会将该字典交给get_chat_model()完成模型对象的实例化只要字典中包含model_type就会直接从注册表LLM_REGISTRY中取出对应的模型类若未提供model_type框架还会根据model与model_server自动推断详见下文自动推断小节。因此理解这个字典的每一项含义是搭建 Qwen-Agent 应用的第一步。参数总览参数类型必填说明modelstr✅ 是要使用的模型名称例如qwen3-max、qwen3-vl-plus、qwen3-omni-flash、qwen3-coder-plusmodel_typestr✅ 是指定模型服务提供商并与模型能力绑定。使用阿里云 DashScope API•qwen_dashscopeLLM支持文本 → 文本•qwenvl_dashscopeVLM支持文本/图像/视频 → 文本•qwenaudio_dashscopeOmni 全模态模型支持文本/图像/视频/音频 → 文本使用 OpenAI 兼容 API•oaiLLM支持文本 → 文本•qwenvl_oaiVLM支持文本/图像/视频 → 文本•qwenaudio_oaiOmni 全模态模型支持文本/图像/视频/音频 → 文本model_serverstr⚠️ 条件必填仅在使用 OpenAI 兼容 API 时需要提供例如•http://localhost:8000/v1本地服务vLLM / SGLang 等•https://dashscope.aliyuncs.com/compatible-mode/v1DashScope 的 OpenAI 兼容模式端点api_keystr❌ 否用于认证的 API Key。•DashScope可在此处提供也可通过环境变量DASHSCOPE_API_KEY提供•OpenAI 兼容 API可在此处提供也可通过环境变量OPENAI_API_KEY提供generate_cfgdict❌ 否控制生成行为与解析逻辑详见下方小节关键参数的源码级解读model_type与模型能力的绑定。从源码看每个model_type都对应LLM_REGISTRY中一个注册的类例如qwen_dashscope对应QwenChatAtDS调用dashscope.Generation.calloai对应TextChatAtOAI基于openaiSDK 的chat.completions。support_multimodal_input、support_multimodal_output等属性决定了多模态消息的预处理与后处理策略见 qwen_agent/llm/base.py因此model_type选错会导致多模态能力无法正确启用。model_server的两种特殊行为。其一在get_chat_model()中如果model_type为oai或qwenvl_oai且model_server填的是dashscope框架会自动改写为https://dashscope.aliyuncs.com/compatible-mode/v1其二在TextChatAtOAI中model_server会被当作api_base/base_url使用见 qwen_agent/llm/oai.py#L44-L47。api_key的读取优先级。在initialize_dashscope()中DashScope 的api_key按配置字典 →DASHSCOPE_API_KEY环境变量的顺序读取OpenAI 兼容侧则按配置字典 →OPENAI_API_KEY环境变量 → 默认EMPTY的顺序见 qwen_agent/llm/oai.py#L49-L51。此外 DashScope 还支持通过base_http_api_url/base_websocket_api_url或环境变量DASHSCOPE_HTTP_URL/DASHSCOPE_WEBSOCKET_URL覆盖服务地址这在私有化网关场景下很有用。未提供model_type时的自动推断。若llm_cfg中省略model_type框架会按以下顺序推断见 qwen_agent/llm/init.py#L70-L100配置含azure_endpoint视为azuremodel_server以http开头视为oai模型名含-vl视为qwenvl_dashscope含-audio视为qwenaudio_dashscope含qwen视为qwen_dashscope。尽管如此官方文档仍建议显式声明model_type以明确模型能力边界。generate_cfg生成与解析控制generate_cfg是llm_cfg中的嵌套字典控制生成行为以及函数调用Function Calling的解析逻辑。参数如下参数类型默认值说明max_input_tokensint90000Agent 的最大上下文长度当上下文超过该长度时会自动执行上下文管理。该值应低于模型支持的最大输入长度以保证 Agent 正常运行use_raw_apiboolFalse是否使用模型服务端原生的工具调用解析例如 vLLM 内置的 parser。官方建议 qwen3-coder、qwen3-max 及后续系列模型设置为True未来将改为默认Trueenable thinking——若模型支持则启用思考模式具体写法取决于模型服务端协议• DashScopeenable_thinkingTrue• DashScope 的 OpenAI 兼容 APIextra_body: {enable_thinking: True}• vLLM 的 OpenAI 兼容 APIextra_body: {chat_template_kwargs: {enable_thinking: True}}其他参数——直接透传给模型服务的参数如top_p、temperature、max_tokens等关于max_input_tokens的默认值需要注意官方文档记录的默认值为 90000而框架层在 qwen_agent/settings.py 中定义的兜底默认值DEFAULT_MAX_INPUT_TOKENS为 58000可通过环境变量QWEN_AGENT_DEFAULT_MAX_INPUT_TOKENS覆盖。在 qwen_agent/llm/base.py#L190-L195 中每次调用 LLM 时该值会从generate_cfg弹出并调用_truncate_input_messages_roughly()对超长输入做粗略截断源码注释也明确指出与函数调用及多模态项相关的 token 估算并不精确因此这是一个保守策略。实际部署中建议结合所选模型的最大上下文显式设置例如调小至 6500get_chat_model的 docstring 中就有此示例。关于use_raw_api的实现细节框架在 qwen_agent/llm/base.py#L89-L96 中先读取环境变量QWEN_AGENT_USE_RAW_API再用generate_cfg[use_raw_api]覆盖并且对qwen_dashscope类型如果模型是Qwen3-Max会自动强制开启。开启后走raw_chat()路径且仅支持完整流式输出要求streamTrue且delta_streamFalse见 qwen_agent/llm/base.py#L220-L223。其他常用透传参数top_p、temperature会原样传给模型服务parallel_function_calls、function_choice、thought_in_content则用于控制函数调用解析见 qwen_agent/llm/function_calling.py#L59-L80。当通过 OpenAI v1 SDK 调用时top_k、repetition_penalty等 OpenAI 协议不支持的参数会被自动移入extra_body透传见 qwen_agent/llm/oai.py#L67-L74。实战示例DashScope APIllm_cfg { model: qwen3-max-preview, model_type: qwen_dashscope, # api_key: your-key, # 若已设置 DASHSCOPE_API_KEY 环境变量此项可省略 generate_cfg: { enable_thinking: True, use_raw_api: True, top_p: 0.8, } }实战示例本地模型vLLM / SGLangllm_cfg { model: Qwen3-8B, model_server: http://localhost:8000/v1, api_key: EMPTY, generate_cfg: { top_p: 0.85, extra_body: {chat_template_kwargs: {enable_thinking: True}}, } }注意model_type在此省略后框架会因model_server以http开头而自动推断为oaiapi_key填EMPTY是本地服务不校验密钥时的常见写法。仓库中的 examples/assistant_qwen3.py 还额外展示了第三种形态——通过model_server: https://dashscope.aliyuncs.com/compatible-mode/v1使用 DashScope 的 OpenAI 兼容接口并给出了thought_in_content参数的适用说明当响应以think.../think内容拼接返回、而非通过reasoning_content与content分离时需要设置该参数以修正工具调用解析策略。注意事项默认支持并行工具调用框架的 Function Calling 流程对并行工具调用开箱即用parallel_function_calls相关逻辑可在 qwen_agent/llm/function_calling.py 中查看。FnCallAgent每轮运行最多允许MAX_LLM_CALL_PER_RUN次 LLM 调用默认 20可通过环境变量QWEN_AGENT_MAX_LLM_CALL_PER_RUN调整见 qwen_agent/settings.py#L24 与 qwen_agent/agents/fncall_agent.py#L75。完整可运行示例可参考仓库的 examples/ 目录。工具配置function_list的四种装配方式初始化Assistant或其他支持工具调用的 Agent时可以通过function_list参数指定可用的工具集合。在 qwen_agent/agents/assistant.py#L85 与 qwen_agent/agent.py#L63-L65 中可以确认该参数接收一个列表每个元素会被逐个交给_init_tool()完成注册最终汇入 Agent 的function_map。支持以下三种元素类型第四种即三种类型的自由组合框架会自动识别并加载对应工具。类型 1字符串str— 引用预注册的内置工具用途快速启用一个已在TOOL_REGISTRY中注册的工具。格式工具名的字符串。要求该工具必须已预先注册例如通过register_tool装饰器。示例code_interpreterTOOL_REGISTRY定义在 qwen_agent/tools/base.py#L24register_tool装饰器负责把工具类写入注册表并校验工具名唯一性qwen_agent/tools/base.py#L44-L59。仓库内置工具如CodeInterpreter、WebSearch、DocParser、Retrieval、ImageGen、Storage等均在 qwen_agent/tools/init.py 中完成注册。类型 2字典dict— 配置注册工具或 MCP 服务器字典格式有两种子类型(a) 标准工具配置字典用途向已注册工具传入自定义配置。格式{ name: tool_name, # 必填已注册工具的名称 other_config: ... # 可选附加配置参数 }要求name必须对应TOOL_REGISTRY中已注册的工具。示例{ name: weather, api_key: your_key }从 qwen_agent/agent.py#L226-L237 可以看到这类字典最终会以TOOL_REGISTRYtool_name的形式实例化字典中除name外的所有键如api_key都会作为cfg传入工具构造函数因此自定义配置的字段取决于目标工具本身的实现。(b) MCP 服务器配置字典特殊键mcpServers用途通过**模型上下文协议Model Context ProtocolMCP**动态加载一组工具。格式{ mcpServers: { server_alias_1: { command: executable, args: [arg1, arg2, ...] }, server_alias_2: { ... } } }行为系统调用MCPManager().initConfig(...)启动 MCP 服务并自动发现可用工具。mcpServers下的每个键如time、fetch代表一个独立的 MCP 工具服务器。示例{ mcpServers: { time: { command: uvx, args: [mcp-server-time, --local-timezoneAsia/Shanghai] }, fetch: { command: uvx, args: [mcp-server-fetch] } } }MCP 装配在 qwen_agent/agent.py#L218-L224 中实现命中mcpServers键后交给MCPManager().initConfig()完成异步初始化。MCPManager是单例实现qwen_agent/tools/mcp_manager.py#L31-L55并通过 monkey patch MCP 客户端保证进程随 Qwen-Agent 退出时被正确回收。校验逻辑qwen_agent/tools/mcp_manager.py#L94-L137支持commandargsstdio 传输以及urlheaders远程服务两种描述方式还允许env注入环境变量。从每个服务器发现的工具会被注册为server_name - tool.name的形式qwen_agent/tools/mcp_manager.py#L198并在inputSchema缺失required字段时自动补空列表以兼容 OpenAI Schemaqwen_agent/tools/mcp_manager.py#L181-L190。依赖提示使用 MCP 功能需要安装mcp包即pip install -U mcpqwen_agent/tools/mcp_manager.py#L42-L45。类型 3BaseTool实例 — 直接提供工具对象用途直接传入一个已完全实例化的工具对象适合高级定制场景。格式一个继承自BaseTool的类的实例。示例伪代码my_tool CustomSearchTool(config{...}) # 然后将 my_tool 直接放入 function_listBaseTool是全部工具的抽象基类qwen_agent/tools/base.py#L109-L138要求子类声明name、description、parameters并实现call()方法parameters若以字典形式提供必须是合法的 OpenAI 兼容 JSON Schema由is_tool_schema()校验。当传入实例时Agent 会直接将其写入function_mapqwen_agent/agent.py#L212-L217不再经过注册表因此这是注入自定义工具最彻底的方式。处理重名工具如果列表中有多个条目试图注册同名工具系统会用列表中最后一次出现的工具覆盖之前的同名工具。源码中每次覆盖都会打印警告Repeatedly adding tool {tool_name}, will use the newest tool in function list见 qwen_agent/agent.py#L215-L216。⚠️ 注意应避免使用重名工具完整使用示例tools [ # 类型 1字符串引用内置工具 code_interpreter, # 类型 2a以字典形式配置已注册工具 { name: weather, api_key: your_openweather_key }, # 类型 2bMCP 服务器配置 { mcpServers: { time: { command: uvx, args: [mcp-server-time, --local-timezoneAsia/Shanghai] }, file: { command: uvx, args: [mcp-server-filesystem] } } }, # 类型 3直接传入 BaseTool 实例可选 # MyCustomTool(config{...}) ] bot Assistant( llmllm_cfg, function_listtools )该示例与仓库中的 examples/assistant_qwen3.py#L64-L80 结构一致——后者同时混用了mcpServerstime、fetch与内置工具code_interpreter可作为真实可运行的参照。Assistant在运行时会把function_map中每个工具的function信息name/description/parameters注入给 LLM见 qwen_agent/agents/fncall_agent.py#L83-L85工具执行结果则以FUNCTION角色的消息回填对话qwen_agent/agents/fncall_agent.py#L97-L104从而形成完整的模型决策 → 工具执行 → 结果反馈闭环。常见错误排查错误原因解决方案ValueError: Tool xxx is not registered.尝试使用一个不在TOOL_REGISTRY中的工具名确保工具已注册如register_tool或改用 MCP /BaseTool方式提供MCP 服务器启动失败command/args配置错误或环境中缺少对应 MCP 服务器先在终端验证命令能否正常执行确保mcp-server-time等工具已安装例如通过uvx从源码看ValueError的确由_init_tool()中的注册表查表直接抛出错误信息与文档完全一致MCP 初始化失败则会由MCPManager.initConfig()抛出并携带日志qwen_agent/tools/mcp_manager.py#L148-L150。小结function_list参数的设计目标是灵活支持多种工具集成策略简单用字符串快速启用内置工具。可配置用字典定制已注册工具的参数。可扩展用mcpServers接入整个 MCP 生态。完全自定义传入BaseTool实例获得完全控制权。将这些方式组合使用你可以构建功能强大且易于扩展的工具调用型 Agent。与此同时llm_cfg的精细配置model_type能力绑定、generate_cfg的上下文与解析控制、思考模式的按服务端差异化写法为上层 Agent 行为提供了稳定可靠的大模型底座——两者结合即可系统性地掌握 Qwen-Agent 的核心配置方法论。【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考