Skip to main content

Tool

The Tool class lets you register custom tools with agents, configure approval gates, and execute tools directly.

Registering tools

Pass a Python function directly — the SDK extracts the name, docstring, and parameter types automatically:
async def analyze_sentiment(text: str, language: str = "en") -> dict:
    """Analyze the sentiment of customer feedback text."""
    result = await nlp_service.analyze(text, language)
    return {
        "sentiment": result.label,
        "confidence": result.score,
        "language": language,
    }

tool = await agent.register_tool(
    analyze_sentiment,
    tags=["nlp", "analytics"],
    group="Analytics Tools",
    require_approval=False,
)

With explicit parameters

tool = await af.Tool.create(
    agent_id=agent.id,
    name="query_database",
    description="Execute a read-only SQL query against the analytics database",
    function_code="async def query_database(sql: str): ...",
    tags=["data", "sql"],
    require_approval=True,
    execution_timeout=30.0,
)

Retrieving tools

# Get a specific tool by name
tool = await af.Tool.get(agent.id, "analyze_sentiment")

# List all tools for an agent
tools = await af.Tool.list(agent.id)
for tool in tools:
    print(f"{tool.name}: {tool.description}")

# List ALL tools across all agents (global registry)
all_tools = await af.Tool.list_all()

Approval gates

# Enable approval with custom timeout
await tool.set_approval(enabled=True, timeout=600)  # 10 minute timeout

# Disable approval
await tool.set_approval(enabled=False)

Direct execution

Execute a tool outside of an agent conversation (dry-run / sandbox mode):
result = await tool.execute({
    "text": "The product quality has been declining lately",
    "language": "en",
})
print(result)
# {"sentiment": "negative", "confidence": 0.92, "language": "en"}

Deleting tools

await tool.delete()

# Or via the agent
await agent.unregister_tool("analyze_sentiment")

Properties

PropertyTypeDescription
idstrTool UUID
namestrTool name
agent_idstrID of the agent this tool belongs to
description`strNone`Tool description
function_code`strNone`Python source code
configToolConfigFull configuration dataclass