agno v3.0.10发布：Azure OpenAI Responses、Elasticsearch、MCP 路由与一批关键稳定性修复全解析

2026年9月20日，agno 正式发布 v3.0.10 版本。

本次更新覆盖模型接入、向量数据库、知识库文档转换、MCP 服务路由、安全限制、工具执行、工作流、文件读取、分块处理、站点地图解析、Slack 事件去重、DynamoDB 存储以及 agnoctl 配置编码等多个方向。

v3.0.10 的核心特点是：新增 Azure OpenAI Responses、Elasticsearch 向量数据库支持、DocumentationMarkdown 文档转换能力，并围绕 MCP、工具结果保留、异步读取、文本分块、CSV 分页读取和 Shell 执行安全进行了大量改进与修复。

---

一、版本发布时间

agno v3.0.10 发布于 2026 年 9 月 20 日。

本次版本既包含新功能，也包含多个兼容性与稳定性修复，同时带来了两项需要特别注意的破坏性变更：

• CodingTools 的 run_shell 不再默认启用。
• 使用授权与公开 MCP Surface 时，MCP 默认只接受 localhost 访问，需要显式配置允许的域名。

---

二、新功能：Azure OpenAI Responses 正式加入

v3.0.10 新增了 AzureOpenAIResponses。

该能力用于通过 Azure OpenAI 部署使用 Responses API。对于使用 Azure OpenAI 部署的场景，现在可以通过 AzureOpenAIResponses 接入 Responses API。

这一新增模型能力对应 Azure OpenAI 的部署模式，使 Azure OpenAI 场景具备使用 Responses API 的入口。

相关使用方式可参考 cookbook。

---

三、新功能：新增 Elasticsearch 向量数据库支持

v3.0.10 新增 Elasticsearch 向量数据库支持。

Elasticsearch 现可用于以下检索能力：

• 向量搜索
• 关键词搜索
• 混合搜索

这意味着 Elasticsearch 在 agno 中可以同时承载向量、关键词以及混合检索需求。

对于知识库、检索增强场景或需要结合向量结果与关键词结果的场景，v3.0.10 已新增对应的 Elasticsearch 集成能力。

相关示例可参考 cookbook。

---

四、新功能：DocumentationMarkdown 文档转换能力

v3.0.10 新增 DocumentationMarkdown 转换能力。

该转换能力用于 Knowledge.sync_pages，可以将 Mintlify 和 Fumadocs 组件转换为纯 Markdown。

具体来说，当文档内容中包含 Mintlify 或 Fumadocs 的组件时，DocumentationMarkdown 可以在同步页面过程中将这些组件转换为普通 Markdown 内容。

该能力面向文档同步和知识库页面处理场景，使包含相关文档组件的页面可以被转换为纯 Markdown 形式。

本次更新同时完成了以下相关调整：

• 新增可选的文档 Markdown 源转换能力。
• 在 cookbook 中导出 DocumentationMarkdown。
• 修复并完善对应示例，使示例能够端到端运行。

相关使用方式可参考 cookbook。

---

五、MCPConfig 升级：支持独立主机名与自定义路径

v3.0.10 为 MCPConfig 新增了以下配置项：

• root_host
• path
• path_aliases

通过这些配置，MCP 可以部署在专用主机名上，也可以使用自定义端点路径。

其中：

• root_host 用于支持 MCP 使用专用主机名。
• path 用于配置自定义端点路径。
• path_aliases 用于配置路径别名。

这项更新扩展了 MCP 服务的主机名与路由配置能力，使 MCP 的服务入口能够使用独立主机名或自定义路径。

此外，本次更新还完善了 MCP 的公开访问检测逻辑，使其能够与 JWT REST 授权场景一起正确识别公共 MCP 访问。

---

六、MCP Server Card 输出优化

v3.0.10 调整了 MCP Server Card 的返回格式。

现在访问 /mcp/server-card 时，返回的是格式化后的 JSON。

此前的 JSON 输出现在变为易读的格式化结果，便于查看 MCP Server Card 内容。

---

七、MCP 工具结果：保留 AudioContent 音频内容

v3.0.10 修复了 MCP 工具结果中的音频内容保留问题。

现在，当 MCP 工具结果中包含 AudioContent 时，音频内容会作为音频 artifact 被保留。

这意味着 MCP 工具返回的音频内容不再在结果处理过程中丢失，而是可以保留为音频 artifact。

---

八、Slack：按 event_id 去重事件重试

v3.0.10 改进了 Slack 事件重试的去重方式。

现在，Slack 对事件重试使用 event_id 进行去重，而不是直接丢弃事件。

本次调整的重点包括：

• 通过 event_id 识别重复的事件重试。
• 避免重复处理相同事件。
• 不再采用直接丢弃事件的方式进行处理。

这一改动优化了 Slack 事件重试时的去重逻辑。

---

九、RemoteAgent 与 RemoteTeam：role 改为属性访问

v3.0.10 调整了 RemoteAgent.role 和 RemoteTeam.role 的使用方式。

现在：

• RemoteAgent.role 是属性。
• RemoteTeam.role 是属性。
• 应使用 .role 获取角色。
• 不应再使用 .role()。

也就是说，角色信息现在通过属性访问，而不是调用绑定方法。

正确方式：

agent.role

team.role

不再使用：

agent.role()

team.role()

---

十、Readers 升级：多个 Reader 支持文本流

v3.0.10 为多个读取器新增文本流支持。

以下 Reader 现已支持接收文本流：

• TextReader
• MarkdownReader
• FieldLabeledCSVReader

这意味着上述 Reader 可以处理文本流形式的输入。

本次更新分别完成了以下修复与支持：

• FieldLabeledCSVReader 支持接收文本流。
• MarkdownReader 支持接收文本流。
• TextReader 支持接收文本流。

---

十一、PPTXReader：支持读取组合形状中的文本

v3.0.10 修复了 PPTXReader 对组合形状文本的读取问题。

现在，PPTXReader 可以读取组合形状内部的文本内容。

对于 PowerPoint 文件中使用 grouped shapes 的内容，读取器现在能够提取其中的文本。

---

十二、JSONReader：async_read 使用异步分块策略

v3.0.10 修复了 JSONReader 的异步读取分块行为。

现在，async_read() 会使用分块策略的异步 achunk() 方法。

也就是说，JSONReader 的异步读取流程会等待并使用异步分块逻辑，而不是遗漏异步分块处理。

---

十三、Chunking：清理文本时保留换行与制表符

v3.0.10 改进了文本清理与分块行为。

现在，在分块前清理文本时，会保留：

• 换行符
• 制表符

此前文本清理可能会影响换行和制表符，本次更新后，clean_text 在处理文本时能够保留这些字符。

这一改动使清理后的文本仍保有原始内容中的换行与制表符信息。

---

十四、CSVReader：分页读取时保留全部数据行

v3.0.10 修复了 CSVReader 在分页读取和跳过表头时的数据行保留问题。

现在，当使用：

RowChunking(skip_header=True)

并通过 async_read() 异步读取 CSV 数据时，能够保留跨页面的每一条数据行。

本次修复确保在跳过表头的情况下，CSV 分页读取不会遗漏数据行。

---

十五、SitemapReader：保留文件名并继续发现站点地图

v3.0.10 改进了 SitemapReader 的多个处理细节。

首先，文件名如 myindex.html 会被完整保留。

这意味着站点地图 URL 规范化过程中，不会错误影响这类非 index 文件名。

其次，当遇到无效的 .xml.gz sitemap 时，站点地图发现流程仍会继续。

也就是说，即使某个 gzip 格式的站点地图数据无效，SitemapReader 也不会因此停止后续 sitemap 的发现。

本次更新包含以下修复点：

• 在 sitemap URL 规范化时保留非 index 文件名。
• 保持如 myindex.html 这类文件名完整。
• 在 gzip 数据无效后继续进行 sitemap 发现。

---

十六、Tools 与 Workflows：保留 0、False 和空列表等假值

v3.0.10 修复了工具与工作流中假值结果被丢弃的问题。

现在，在同步工具结果和并行工作流步骤输出中，以下值可以被正确保留：

• 0
• False
• []

本次修复覆盖以下场景：

• 同步工具执行路径中的工具结果。
• Parallel 工作流步骤输出。
• 之前工作流内容中的假值结果。

这意味着，当工具执行结果为 0、False 或空列表时，系统不会再将它们错误视为无结果并丢弃。

---

十七、agnoctl：客户端配置统一使用 UTF-8

v3.0.10 中，agno connect 读取与写入客户端配置时使用 UTF-8 编码。

该更新对应 agnoctl 0.2.1。

本次调整包括：

• agno connect 读取客户端配置使用 UTF-8。
• agno connect 写入客户端配置使用 UTF-8。
• 基础设施文件辅助方法使用 UTF-8 处理文本。
• agnoctl 客户端配置文本使用 UTF-8。

这一变更统一了 agnoctl 客户端配置相关的文本编码处理方式。

---

十八、DynamoDB：布尔值序列化为原生 BOOL

v3.0.10 修复了 DynamoDB 中布尔值的序列化方式。

现在，布尔值会被序列化为 DynamoDB 原生 BOOL 类型。

此前布尔值可能会以类似下面的数值形式保存：

{"N": "True"}

现在，布尔值将作为原生 BOOL 值进行序列化。

这一修复确保 DynamoDB 存储中的布尔类型使用正确的原生类型表达。

---

十九、依赖与示例修复

v3.0.10 还包含多个文档、示例和依赖相关修复。

包括：

• 修复 cookbook 中损坏的外部链接。
• 修复 cookbook 的导入、失效链接和拼写问题。
• 修复 CONTRIBUTING 路径、agno_infra 许可证说明和文档字符串准确性。
• 修正文档字符串中 Perplexity 和 v0 的 base_url 默认值说明。
• 说明 PythonTools 不提供代码沙箱。
• 修复一个不稳定的工具钩子消息测试。
• 在 mcp_toolbox_demo 中升级 urllib3 至 2.7.0。
• 在 mcp_toolbox_demo 中升级 requests 至 2.33.0。

这些变更涵盖 cookbook、文档链接、示例导入、依赖版本、贡献说明以及测试稳定性。

---

二十、破坏性变更一：CodingTools 的 run_shell 改为显式启用

v3.0.10 对 CodingTools 的 Shell 执行行为进行了安全调整。

run_shell 现在改为默认不启用。

如果需要使用 run_shell，必须显式设置：

enable_run_shell=True

也就是说，Shell 执行能力已变为 opt-in，需要主动开启。

本次更新还调整了 restricted mode 的命令执行方式。

在 restricted mode 下，命令会在不使用 shell 的情况下执行。

这一调整用于避免操作符注入问题，并强化对解释器远程代码执行风险的防护。

本次与 CodingTools 相关的调整包括：

• run_shell 改为显式启用。
• 需要通过 enable_run_shell=True 开启。
• restricted mode 不再通过 shell 执行命令。
• restricted shell 执行改为无 shell 方式。
• 强化 run_shell 的安全性。
• 降低解释器远程代码执行风险。
• 消除操作符注入风险。
• 文档明确 PythonTools 不提供代码沙箱。

---

二十一、破坏性变更二：PublicSurface MCP 默认只允许 localhost

v3.0.10 调整了带授权的公开 MCP Surface 访问限制。

当同时满足以下条件时：

authorization=True

以及：

PublicSurface(mcp=True)

MCP 默认只接受 localhost 访问。

如果需要通过其他域名访问 MCP，必须在 MCPConfig 中显式添加允许的域名：

MCPConfig(
    allowed_hosts=[...]
)

也就是说，在带授权且启用公开 MCP Surface 的情况下，MCP 不再默认接受任意主机访问，而是仅允许 localhost。

如需开放其他域名，必须通过 allowed_hosts 显式配置。

---

二十二、v3.0.10 更新内容汇总

代码地址：github.com/agno-agi/agno

agno v3.0.10 的新增能力包括：

• 新增 AzureOpenAIResponses，用于 Azure OpenAI 部署的 Responses API。
• 新增 Elasticsearch 向量数据库支持。
• Elasticsearch 支持向量搜索、关键词搜索和混合搜索。
• 新增 DocumentationMarkdown。
• DocumentationMarkdown 可在 Knowledge.sync_pages 中将 Mintlify 和 Fumadocs 组件转换为纯 Markdown。
• MCPConfig 新增 root_host、path 和 path_aliases。
• MCP 支持专用主机名和自定义端点路径。
• /mcp/server-card 返回格式化 JSON。

本次修复与改进包括：

• MCP 工具结果中的 AudioContent 保留为音频 artifact。
• Slack 根据 event_id 对事件重试去重。
• RemoteAgent.role 和 RemoteTeam.role 改为属性访问。
• TextReader 支持文本流。
• MarkdownReader 支持文本流。
• FieldLabeledCSVReader 支持文本流。
• PPTXReader 支持读取组合形状中的文本。
• JSONReader.async_read() 使用异步 achunk()。
• 清理文本时保留换行符和制表符。
• CSVReader.async_read() 在 RowChunking(skip_header=True) 下保留跨页面全部数据行。
• SitemapReader 保留如 myindex.html 的文件名。
• 无效 .xml.gz sitemap 不会阻止后续 sitemap 发现。
• 同步工具结果保留 0、False 和 []。
• Parallel 工作流步骤输出保留 0、False 和 []。
• 工作流历史内容保留假值结果。
• agnoctl 使用 UTF-8 读写客户端配置。
• DynamoDB 布尔值使用原生 BOOL 类型序列化。
• cookbook、外部链接、导入、拼写和示例得到修复。
• mcp_toolbox_demo 升级 urllib3 至 2.7.0。
• mcp_toolbox_demo 升级 requests 至 2.33.0。
• 修复测试稳定性问题。
• 修正文档字符串中的默认地址说明。
• 明确 PythonTools 不提供代码沙箱。