Skip to main content
Source: 02_agent_with_tools.py · 02-agent-with-tools.ts
A tool is a Python or TypeScript function the agent may decide to call. The SDK introspects parameters, sends a JSON Schema to the model, and executes the function when the model picks it.

​
Define a tool

from opperai.agent import tool

@tool
def lookup_product(product_id: str) -> dict:
    """Look up a product by its ID."""
    return {"name": "Headphones", "price": 79.99, "stock": 42}
In Python, the schema is derived from type hints; the docstring becomes the description. In TypeScript, you pass an explicit Zod schema (or any Standard Schema — Valibot, ArkType, etc.) — or raw JSON Schema.

​
Attach tools to an agent

from opperai.agent import Agent

agent = Agent(
    name="shop-assistant",
    instructions="Use tools to look up products. Be concise.",
    tools=[lookup_product, check_availability],
)

result = await agent.run("Can I order 10 units of prod-002?")
The agent loops automatically: it calls a tool, observes the result, and either calls another tool or produces a final answer.

​
Inspect tool calls

Every tool invocation is captured in result.meta: 
for call in result.meta.tool_calls:
    print(call.name, call.input, "->", call.output, f"({call.duration_ms:.0f}ms)")

​
Tips

  • Return JSON-serialisable data. Dicts, lists, and primitives work best — the SDK serializes them for the model.
  • Keep the docstring / description tight. That text is what the model sees when deciding whether to call the tool.
  • Errors are fine. If the function raises, the SDK reports the error to the model so it can recover or report back.
  • Parallel by default. If the model issues multiple tool calls in one turn, the SDK runs them concurrently. Disable with parallel_tool_execution=False (Python) / parallelToolExecution: false (TS) on the Agent if needed.