Skip to content

Creating 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.

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 BaseModel
from 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})"

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 connections

The 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() 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 None

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.

ParameterTypeDescription
descriptionstrDescription for the LLM
rate_limitdict{"max_calls": N, "window_seconds": N}
requires_approvalboolRequire approval before execution. Default False
timeoutintTimeout 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).

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, and result.answer ends with Para confirmar respondé SI. Voy a ejecutar: pay con amount: 10. Confirm exactly as on a node: run again in the same session_id with "si" (also confirmo, 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 in result.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 declaring origen: "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.

@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."""
Built by FAiNANSU