Agently 文档

中文

EN

中文

EN

Appearance

工具快速开始 ​

适用版本：4.0.8.1+

本页对应“工具怎么用 + 展示运行效果”。

1) 注册工具 ​

方式 A：@agent.tool_func ​

python
from typing import Annotated
from agently import Agently

agent = Agently.create_agent()

@agent.tool_func
def add(a: Annotated[int, "第一个数字"], b: Annotated[int, "第二个数字"]) -> int:
    """返回两个数字之和"""
    return a + b

方式 B：register_tool ​

python
def search_docs(query: str, top_k: int = 5):
    return [f"doc:{query}"][:top_k]

agent.register_tool(
    name="search_docs",
    desc="在内部文档中检索",
    kwargs={"query": (str, "检索词"), "top_k": (int, "数量")},
    func=search_docs,
)

2) 让模型自主决策调用 ​

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

response = (
    agent
    .input("请用工具计算 345 + 678，并补充相关文档检索")
    .get_response()
)

answer = response.result.get_data()
print(answer)

3) 调整工具回路参数（可选） ​

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

对应设置项：

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

4) 查看运行效果（tool logs） ​

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

典型单条 tool_log 包含：

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

5) 只生成指令，不执行工具 ​

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

返回的是本轮规划出的 execution_commands，适合交给外部执行器。

6) 结果注入机制 ​

当工具被执行且有记录时，框架会自动：

  1. 把结果写入 prompt.action_results
  2. 加入 extra_instruction（提醒回复引用工具证据）
  3. 将执行记录写入 extra.tool_logs

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