Custom Tools

Custom Tools

Custom tools are the main way to connect Agiwo agents to external systems, internal services, or focused computation.

Implement the stable contract

from agiwo.tool import BaseTool, ToolContext, ToolResult


class WeatherTool(BaseTool):
    name = "get_weather"
    description = "Get the current weather for a city"

    def get_parameters(self) -> dict:
        return {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Target city name"},
            },
            "required": ["city"],
        }

    async def execute(
        self,
        parameters: dict,
        context: ToolContext,
        abort_signal=None,
    ) -> ToolResult:
        city = parameters["city"]
        return ToolResult.success(
            tool_name=self.name,
            content=f"{city}: sunny, 25C",
            content_for_user=f"Weather in {city}: sunny, 25C",
            output={"city": city, "temp_c": 25, "condition": "sunny"},
        )

Design guidelines

• keep content short and useful for the model’s next reasoning step
• use output for structured machine-readable data
• use content_for_user only when a UI-friendly rendering helps
• return ToolResult.success(), failed(), aborted(), or denied() instead of constructing results directly

Runtime controls

Caching

Set cacheable = True when identical arguments within one session should reuse the same result.

class EmbeddingTool(BaseTool):
    cacheable = True
    timeout_seconds = 60

Timeout

Override timeout_seconds if the default 30 seconds is too short.

Concurrency

Leave concurrency_safe = True for read-only or stateless work. Set it to False when the tool mutates shared state or depends on strict ordering.

Context and permissions

ToolContext gives you runtime metadata such as session_id, agent_id, agent_name, depth, and custom metadata. Keep plain tools dependent on ToolContext, not on agent-internal runtime objects.

If you need policy checks, override gate(...) for a lightweight preflight and deny execution before the main tool logic runs.

Register tools

agent = Agent(
    AgentConfig(
        name="assistant",
        description="Helpful assistant",
        system_prompt="Use tools only when they materially help.",
    ),
    model=model,
    tools=[WeatherTool()],
)

When to use Agent.as_tool()

Use a custom BaseTool when the operation is a direct external action or function call.

Use Agent.as_tool() when the delegated work needs its own prompt, tool set, and reasoning loop.