AI Agent 模型要求：工具调用、上下文与 API 兼容性
这是什么
xAgent 依赖模型完成理解、推理、规划、工具调用和结果生成。部署完成后，管理员需要在模型配置页面接入至少一个可用模型，普通用户才能稳定创建会话并执行任务。
当前版本仍处于测试版阶段，模型选择和参数建议会继续根据实际测试结果调整。下面内容用于帮助管理员先选到可用、相对稳定的模型配置。
基本要求
建议优先选择满足下面条件的模型：
| 要求 | 说明 |
|---|---|
| 支持工具调用 | xAgent 会通过工具读取文件、调用 MCP、执行连接器动作、创建任务产物，因此模型需要具备稳定的工具调用能力 |
| 上下文足够长 | 建议至少 64k 上下文，长期任务、复杂文件和多工具场景建议 100k 以上 |
| 推理能力稳定 | 创建 Skill、拆解长任务、处理复杂材料时，建议使用智力更强、推理更稳定的模型 |
| 流式输出稳定 | 长任务执行过程中需要持续看到过程和结果，模型服务应保持稳定的流式响应 |
| API 兼容性较好 | 当前支持 OpenAI API、Gemini API、Anthropic API，建议优先使用经过验证或接入方式清晰的模型服务 |
API 支持状态
当前版本支持接入下面几类模型 API：
- OpenAI API / OpenAI-compatible API
- Gemini API
- Anthropic API
但需要注意，当前开发和测试过程中基本使用 OpenAI API / OpenAI-compatible API。Gemini API 和 Anthropic API 的供应商协议兼容性暂时无法完全保证。如果你手上有对应 API，可以在模型配置中接入测试，重点验证普通聊天、流式输出、工具调用、长上下文和长任务稳定性。
上下文建议
xAgent 会在会话中加载动态提示词、默认工具说明和必要的任务上下文。由于内置动态提示词与默认工具的加载，初始上下文通常会在 20k tokens 左右。
当前上下文已经针对提示词前缀缓存做了优化。在支持前缀缓存的模型服务上，可以明显降低重复加载系统提示词、默认工具说明等固定前缀带来的开销。
当上下文达到最大上下文的 80% 左右时，xAgent 会触发上下文压缩。压缩可以帮助长任务继续执行，但压缩本身也会消耗模型能力，并可能影响部分细节的保留。
因此建议：
- 最低建议：64k 上下文以上。
- 更推荐：100k 上下文以上。
- 长任务、复杂文件、多工具、多轮确认和 Skill 创建场景：尽量配置更长上下文。
如果模型上下文过短，可能出现任务中途频繁压缩、细节丢失、工具选择不稳定或长任务完成质量下降。
前缀缓存可以降低固定提示词带来的重复成本，但不能替代长上下文能力。任务材料、工具结果、会话历史和用户补充信息仍然会持续占用上下文。
当前测试情况
当前开发环境受资源条件限制，主要使用 Qwen3.6-27B 进行测试。这个选择不是推荐配置，只是当前开发测试环境中可用的模型之一，不代表 xAgent 只能使用这个模型，也不代表它是生产环境的最佳选择。
目前测试过的较小模型包括 Gemma4-12B，也可以正常执行长任务。实际部署时，仍建议根据任务复杂度、模型供应商稳定性、上下文长度、工具调用能力和成本来选择模型。
后续模型不会局限于某一个模型或某一家供应商。不同模型各有所长，xAgent 会根据测试结果持续优化模型选择、任务路由和默认参数建议。
开发环境测试参数
下面这组参数是开发环境测试参数，不是推荐配置。由于不同模型服务对参数支持不完全一致，实际配置应以供应商文档、模型能力和测试结果为准。
当前开发环境同时验证了提示词前缀缓存效果。在稳定会话中，前缀缓存率通常可以达到 90% 以上，这也是当前动态提示词和默认工具加载能够控制重复成本的重要原因。
上图为开发环境模型服务日志示例，可以看到 Prefix cache hit rate 接近 90%，MM cache hit rate 也保持在 90% 左右。该截图只用于说明当前测试环境的缓存效果，实际表现取决于模型服务、部署方式和请求形态。
{
"chat_template_kwargs": {
"enable_thinking": true,
"preserve_thinking": false
},
"max_completion_tokens": 4096,
"max_context_tokens": 200000,
"max_tokens": 4096,
"presence_penalty": 1.5,
"reasoning_effort": "high",
"temperature": 0.9,
"thinking_token_budget": 1024,
"top_k": 20,
"top_p": 0.95
}
如果模型服务不支持某些字段，可以删除对应字段，先保证聊天、流式输出、工具调用和长任务执行稳定。
配置建议
初次配置模型时，建议按下面顺序验证：
- 在模型配置页面添加模型。
- 测试普通聊天是否正常。
- 测试流式输出是否稳定。
- 测试工具调用是否能正确触发和返回。
- 创建一个 Agent 会话，上传小文件并要求生成结果。
- 再测试一个需要多步骤工具调用的任务。
如果模型能够稳定完成文件读取、工具调用、结果生成和多轮确认，再交给普通用户使用。