Agently 文档

中文

EN

中文

EN

Appearance

工具快速开始 ​

适用版本：v4.0.8.2

1. 从注册工具到最终回复 ​

如何阅读这张图 ​

  • 这不是“模型自己执行工具”，而是 Agent 在中间承接规划、执行和证据注入。
  • 如果你只想拿规划结果，不想真正执行工具，链路会在规划器结束。

2. 注册工具 ​

方式 A：@agent.tool_func ​

python
from agently import Agently

agent = Agently.create_agent()

@agent.tool_func
def add(a: int, b: int) -> int:
    return a + b

方式 B：register_tool ​

python
agent.register_tool(
    name="search_docs",
    desc="在内部文档中搜索关键词",
    kwargs={"query": (str, "检索词")},
    func=lambda query: [f"doc:{query}"],
)

3. 让 Agent 使用工具 ​

python
agent.use_tools([add, "search_docs"])

response = agent.input("请用工具计算 12 + 34，并顺便搜索内部文档").get_response()
print(response.result.get_data())

agent.use_tools(...) 的本质是给当前 agent 打 tag，后续 Tool Loop 只会读取这个 agent 可见的工具列表。

4. 调整 Tool Loop 参数 ​

python
agent.set_tool_loop(
    enabled=True,
    max_rounds=4,
    concurrency=2,
    timeout=20,
)

对应设置项：

  • tool.loop.enabled
  • tool.loop.max_rounds
  • tool.loop.concurrency
  • tool.loop.timeout

5. 查看执行记录 ​

python
full = response.result.full_result_data
tool_logs = full.get("extra", {}).get("tool_logs", [])
print(tool_logs)

每条 ToolExecutionRecord 通常包含：

  • purpose
  • tool_name
  • kwargs
  • todo_suggestion
  • success
  • result
  • error

6. 只生成指令，不执行工具 ​

python
commands = agent.generate_tool_command()
print(commands)

这一步只会调用规划器，不会真正执行工具。它返回的是归一化后的 execution_commands，适合：

  • 外部调度器执行
  • 审批后再执行
  • 自定义执行层

7. 当前推荐的规划输出 ​

python
{
    "next_action": "execute",
    "execution_commands": [
        {
            "purpose": "查找官方文档",
            "tool_name": "search",
            "tool_kwargs": {"query": "Agently TriggerFlow"},
            "todo_suggestion": "拿到 URL 后继续 browse",
        }
    ],
}

说明：

  • execution_commands 是主字段
  • todo_suggestion 会进入下一轮决策上下文
  • must_call() / async_must_call() 不再是推荐入口

8. 自动注入了什么 ​

当 Tool Loop 真正执行了工具并产出记录时，框架会自动：

  1. 把记录转成 prompt.action_results
  2. 注入 prompt.extra_instruction
  3. 把完整记录写入 extra.tool_logs

下一步建议阅读：工具运行流程（Tool Loop）