English mirror

This English page is generated from the current Chinese documentation so every route, anchor, code sample, and language switch stays available on agently.tech. Human-edited English copy can replace this generated body page by page.

Read the Chinese source page

工具兼容

如果你正在维护旧 Agently 项目，可能会看到 tool_func、use_tool、use_tools、extra.tool_logs。这些入口仍可用，但新项目应该从 Action Runtime 的 action 入口开始。

这页只处理兼容关系，不把旧 tools 当新手默认路径。

旧入口和新入口

兼容入口	推荐入口	说明
@agent.tool_func	@agent.action_func	从函数签名和 docstring 推 schema
agent.use_tool(fn)	agent.use_actions(fn)	注册一个能力
agent.use_tools([a, b])	agent.use_actions([a, b])	注册多个能力
extra.tool_logs	extra.action_logs	action loop 调用记录
Agently.tool	Agently.action	全局注册 helper
agent.use_mcp(url)	agent.use_mcp(url)	MCP 入口保持不变

旧名会路由进当前 Action Runtime。它们不是独立的新 ToolManager 实现。

旧代码还能这样写

from agently import Agently

agent = Agently.create_agent()


@agent.tool_func
def add(a: int, b: int) -> int:
    """两个整数相加。"""
    return a + b


agent.use_tool(add)

result = agent.input("3333 + 6666 等于多少？").get_result()
answer = result.get_text()

迁移时可以改成：

@agent.action_func
async def add(a: int, b: int) -> int:
    """两个整数相加。"""
    return a + b


agent.use_actions([add])

auto_func 仍然可用

@agent.auto_func 把函数签名和 docstring 交给模型实现，并使用 agent 上已经注册的 action / tool：

@agent.auto_func
def calculate(formula: str) -> int:
    """计算 {formula}。需要使用可用 action 确保结果正确。"""
    ...


print(calculate("3333+6666=?"))

它适合示范“模型调用能力完成函数实现”。生产代码里要注意可观测性和 action logs。

内置能力的当前路径

新代码使用 action-native import：

from agently.builtins.actions import Browse, Search

agent.use_actions(Search(timeout=15, backend="auto"))
agent.use_actions(Browse())

Search 注册 search、search_news、search_wikipedia、search_arxiv。Browse 注册 browse。agently.builtins.tools 只保留为旧代码的薄 compatibility facade。

Search 由 ddgs package 支撑。默认 backend="auto"，也可以指定 yahoo、brave、duckduckgo、google、startpage、mojeek、wikipedia 或 yandex。某个 backend 返回 HTTP 200 不代表已经解析到可用结果；无结果时会继续 fallback，真实无结果会以成功 action result 返回 []。

如果前面的 backend 失败，但 fallback 返回可用结果，Action result 会使用 status="partial_success"，同时保持 success=True 并携带 diagnostics。这表示“有可用证据但搜索源发生降级”，不应该被 ActionFlow 当成 action.failed。

shell 能力优先用：

agent.enable_shell(commands=["pwd", "pytest"])

Cmd 仍作为低层兼容 package 与 Bash 执行 helper 保留。

什么时候迁移

应该迁移：

• 新代码还在使用 tool_func。
• 要接内置 Search / Browse / shell 等新能力。
• 要写自定义插件或后端。
• 需要统一 action logs 和 execution artifacts。

可以暂时不迁：

• 旧项目稳定运行，短期只做维护。
• 第三方库仍暴露旧 tools 入口。

即便暂时不迁，也建议在文档和注释里标明它是兼容入口。

常见误用

• 把 ToolManager 当新插件扩展点。
• 用 agently.builtins.tools 写新内置能力。
• 迁移时只改函数名，不检查 logs、artifact 和 action planning 行为。
• 把 legacy tools 文档放在新手路径里。

下一步

• 推荐入口：Action Runtime
• MCP：MCP
• Coding-agent 项目指引：Coding Agents