Creating Tools
Decorator-Based Tools
Section titled “Decorator-Based Tools”from astromesh_adk import tool
@tool(description="Search the web for information")async def web_search(query: str, max_results: int = 5) -> str: # JSON schema auto-generated from type hints return f"Results for {query}"Supported types: str, int, float, bool, list, dict, Optional, X | None.
A Pydantic model as the only parameter
Section titled “A Pydantic model as the only parameter”When a @tool function takes a single parameter annotated as a Pydantic BaseModel, the model’s own JSON schema is what the LLM sees, so it fills the real fields instead of a generic string. The ADK builds the model from the arguments before calling your function:
from pydantic import BaseModelfrom astromesh_adk import tool
class Ticket(BaseModel): title: str priority: int = 3
@tool(description="Open a support ticket")async def open_ticket(ticket: Ticket) -> str: return f"opened {ticket.title} (P{ticket.priority})"Class-Based Tools
Section titled “Class-Based Tools”For tools with state or lifecycle management:
from astromesh_adk import Tool
class DatabaseTool(Tool): name = "query_db" description = "Query the database"
def __init__(self, connection_string: str): self.conn = connection_string
def parameters(self): return {"sql": {"type": "string", "description": "SQL query"}}
async def execute(self, args, ctx=None): return f"Results for: {args['sql']}"
async def cleanup(self): pass # Close connectionsThe runner calls execute(args), but it does not read parameters() (the model sees the tool with an empty schema) and never calls cleanup(). Prefer @tool when the model needs the argument schema.
MCP Tools
Section titled “MCP Tools”mcp_tools() builds a lazy MCPToolSet, but the runner does not run its discovery yet: the set reaches the model as a single tool with no schema, and the server’s tools are not called. The API is shown for reference.
from astromesh_adk import mcp_tools
github = mcp_tools( transport="stdio", command="npx", args=["-y", "@modelcontextprotocol/server-github"], env={"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},)
@agent(name="dev", model="openai/gpt-4o", tools=[web_search, *github])async def dev_agent(ctx): """Developer agent.""" return NoneCallbacks
Section titled “Callbacks”Pass a Callbacks subclass to run() or stream() to observe a run. Callbacks are read-only: they cannot change or block execution, and an exception inside a callback is swallowed.
from astromesh_adk import Callbacks
class Log(Callbacks): async def on_tool_result(self, tool_name, args, result): print("tool", tool_name, args, "->", result)
async def on_error(self, error, context): print("tool failed:", context["tool"], error)
await my_agent.run("hi", callbacks=Log())The runner fires on_tool_result after each tool call succeeds and on_error (with {"tool": name}) when a tool raises. on_step and on_model_call exist on the base class but the runner does not call them yet.
Tool Options
Section titled “Tool Options”| Parameter | Type | Description |
|---|---|---|
description | str | Description for the LLM |
rate_limit | dict | {"max_calls": N, "window_seconds": N} |
requires_approval | bool | Require approval before execution. Default False |
timeout | int | Timeout in seconds. Default 30 |
rate_limit and timeout are stored on the tool but not enforced by the ADK runner. requires_approval and mode are (see below).
Confirmation and proposals in local runs
Section titled “Confirmation and proposals in local runs”Local runs use the same gate as the core.
@tool(description="Pay", requires_approval=True)async def pay(amount: int) -> str: ...
@tool(description="Create a record", mode="propose")async def create(name: str) -> str: ...requires_approval=True: the first time the tool does not run, andresult.answerends withPara confirmar respondé SI. Voy a ejecutar: pay con amount: 10. Confirm exactly as on a node: run again in the samesession_idwith"si"(alsoconfirmo,dale,ok,listo), e.g.await agent.run("si", session_id=...). It runs once, and only if the model repeats the call with the same arguments; any other message discards what was pending.mode="propose": the tool never runs; the call comes out inresult.propuestas(tool,tipo: "adk",destino= agent name,operacion,argumentos) for the caller to approve and execute.- This covers calls the model makes. A tool called from handler code (
ctx.call_tool) runs as is. - In a team or with an agent as a tool (
other.as_tool()), the “si” is read by the run that talks to the person, never by the member or sub-agent. The child runs in the same session, its prompt appears in the parent’s answer, and it cannot propose: the model is told nothing was recorded. - Remote sub-agents. An agent with
bind()/connect()/remote()used as a tool calls the node declaringorigen: "agente", so the remote node never accepts the parent model’s"si"as human confirmation: its approval-gated tools stay pending. The person confirms by talking to that agent directly.
Result size and knowledge bundles
Section titled “Result size and knowledge bundles”@tool(max_result_tokens=N) caps one tool’s result before it reaches the model (the agent-wide default is max_tool_result_tokens, 8000).
kb_tools(path) returns the core’s kb_index, kb_read and kb_find tools over an OKF knowledge bundle directory; they return errors as results instead of raising:
from astromesh_adk import agent, kb_tools
@agent(name="docs", model="openai/gpt-4o", tools=[*kb_tools("./kb")])async def docs(ctx): """Answer from the knowledge bundle."""