Agently Docs

EN

中文

EN

中文

Appearance

Tool Quickstart ​

Applies to: 4.0.8.1+

This page covers “how to use tools” and “how to inspect runtime effects”.

1) Register tools ​

Option 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, "first number"], b: Annotated[int, "second number"]) -> int:
    """Return a + b"""
    return a + b

Option 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="Search internal docs",
    kwargs={"query": (str, "query"), "top_k": (int, "count")},
    func=search_docs,
)

2) Let the model decide tool calls ​

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

response = (
    agent
    .input("Use tools to calculate 345 + 678 and search related docs")
    .get_response()
)

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

3) Tune loop options (optional) ​

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

Related settings:

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

4) Inspect runtime effect (tool_logs) ​

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

Typical tool_log fields:

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

5) Generate commands only (no execution) ​

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

This returns planned execution_commands for external executors.

6) Result injection behavior ​

When tool records exist, framework will:

  1. write tool outputs into prompt.action_results
  2. append extra_instruction for evidence quoting
  3. append logs into extra.tool_logs

Next: Tool Runtime (Tool Loop)