Agently 文档

中文

English

中文

English

Appearance

工具 ​

语言：English · 中文

工具系列是 Agently 让模型调函数、MCP 服务、沙箱的兼容入口。新代码优先 action 入口 —— 见 Action Runtime。工具系列仍可用，干净映射到新 runtime，本页给已有它在代码里的用户。

入口对照 ​

旧（兼容）新（推荐）做什么
@agent.tool_func@agent.action_func标记函数并推 schema
agent.use_tool(my_func)agent.use_actions(my_func)注册一个
agent.use_tools([a, b])agent.use_actions([a, b])注册多个
agent.use_mcp(url)agent.use_mcp(url)不变 —— MCP 挂载
agent.use_sandbox(...)agent.use_sandbox(...)不变 —— 沙箱挂载
extra.tool_logsextra.action_logsloop 产生的调用记录
Agently.toolAgently.action全局注册帮手

两边都路由进同一个 action runtime。旧名不是独立 ToolManager 插件实现 —— 是别名。

最小例子 ​

python
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 等于多少？").start()
print(result)

模型把 add 看作可调用工具并决定是否调用。

auto-func —— 模型驱动的实现 ​

@agent.auto_func 装饰器把函数签名 + docstring 变成由模型驱动并使用 agent tool / action 的实现：

python
@agent.auto_func
def calculate(formula: str) -> int:
    """计算 {formula}。必须用 ACTION 确保答案正确。"""
    ...


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

被装饰函数无函数体（...）。调用时 agent 用注册的 tool 跑模型并返回结果。

何时用哪个入口 ​

新项目：用 action 入口（见 Action Runtime）。新功能、插件类型、架构改进都在 action 一侧。

留在 tool 入口当：

  • 维护已有用旧名的代码。
  • 依赖库或旧样例仍使用旧名。

工具系列不会消失 —— 但新功能优先在 action 那侧落地。

内置 actions 与 legacy tools ​

几个常用能力作为内置 action package 发布：

  • Search —— web 搜索包装
  • Browse —— 页面抓取与可读正文提取
  • Cmd —— 低层受限 shell 执行

新代码使用 action-native import path：

python
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.actions。 agently.builtins.tools 只保留为旧代码的薄 legacy import facade；它可以补旧的 tool_info_list 元数据，但不应该拥有内置能力实现。agent.use_tools(...)、 agent.tool_func 和 Agently.tool 也仍是受支持的兼容入口。新的内置能力不要再以 tool_info_list / BuiltInTool 作为 authoring API。

Search 由 ddgs package 支撑。默认保留 backend="auto"，也可以传入具体 ddgs backend，例如 yahoo、brave、duckduckgo、google、startpage、 mojeek、wikipedia 或 yandex。某个 backend 返回 HTTP 200 不代表已经解析到 可用搜索结果；当 backend 没有可用结果时，Search 会继续尝试配置或默认的 ddgs fallback backends。真实无结果会以成功 action result 返回 []，不会让 action loop 因为“没有结果”而失败。

如果前面的 backend 失败，但后续 fallback backend 返回了可用结果，Action result 会使用 status="partial_success"，同时保持 success=True 并携带 backend diagnostics。这表示“有可用证据但存在外部搜索源降级”，不应被 ActionFlow 当作 action.failed 终止条件。

shell 能力优先使用 agent.enable_shell(...)，它挂载托管 run_bash action。 Cmd 仍作为低层兼容 package 与 Bash 执行实现 helper 保留。

当前 action-native 示例见 examples/builtin_actions/。历史 built-in tool 示例已移到 examples/archived/builtin_tools/，并在 README 中指向当前替代案例。

另见 ​

  • Action Runtime —— 推荐入口，含完整架构
  • MCP —— agent.use_mcp(...) 详细
  • Coding Agents —— 使用内置 search/browse 和自定义 action 的项目如何给 coding agent 提供指引