Add Function Tools and Hosted Tools

OpenAI Agents SDK tools let a model request controlled capabilities. Function tools wrap your Python functions and derive schemas from types and documentation; hosted tools provide platform-managed capabilities such as web or file search when supported. Your handler still owns identity, validation, timeout, authorization, redaction, and side-effect safety.

What will you be able to do?

You will add a read-only SupportOps tool, inspect its boundary, and choose between application-hosted and provider-hosted capabilities.

How do you create a function tool?

read_tool.py:

python

import asyncio
from dataclasses import dataclass

from agents import Agent, RunContextWrapper, Runner, function_tool


@dataclass(frozen=True)
class AppContext:
    tenant_id: str


TICKETS = {
    ("tenant_demo", "T-100"): {
        "id": "T-100",
        "subject": "Duplicate charge",
        "status": "open",
    }
}


@function_tool
async def get_ticket(
    wrapper: RunContextWrapper[AppContext], ticket_id: str
) -> dict[str, str]:
    """Return a support ticket from the authenticated tenant scope."""
    if not ticket_id.startswith("T-"):
        raise ValueError("ticket_id must begin with T-")
    ticket = TICKETS.get((wrapper.context.tenant_id, ticket_id))
    if ticket is None:
        raise LookupError("ticket not found")
    return ticket


agent = Agent[AppContext](
    name="Ticket reader",
    instructions="Use get_ticket for ticket facts. Never claim to modify a ticket.",
    tools=[get_ticket],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Summarize ticket T-100.",
        context=AppContext(tenant_id="tenant_demo"),
    )
    print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

The model chooses ticket_id; trusted host context chooses the tenant. The handler returns only fields required for the task.

When should you use hosted tools?

Use a hosted tool when the platform capability matches your trust and data requirements and removes infrastructure you do not need to own. Use a function tool when you need private application logic, strict domain contracts, custom policy, or full control of data movement.

Before enabling any hosted tool, verify current documentation, data handling, approval options, regional/compliance fit, and trace behavior. Never assume “hosted” means automatically safe for your data.

How do you prove tool behavior?

Unit-test the function directly for valid, invalid, missing, and cross-tenant IDs. At the agent level, assert that a ticket question produces a get_ticket call with the correct argument and that unrelated questions do not.

Failure injection: Ask for T-100 while the runtime context contains another tenant. The tool must return not found; it must never trust a tenant ID supplied by the model.

What changes for mutating tools?

Use needs_approval, idempotency keys, proposal/commit separation, current-state checks, and reconciliation. The next guardrails chapter implements the approval pause.

What mistakes should you avoid?

Returning database rows with secret/internal fields.
Using docstrings that overpromise capability.
Giving every agent every tool.
Treating a tool exception as safe user-facing text.
Enabling web or file access without a data policy.

Check your understanding

Which tool argument comes from trusted runtime context?
When is a function tool preferable to a hosted tool?
Which tests should run without a model call?

Expert extension

Add a search_knowledge function tool with tenant filters, bounded results, stable source IDs, timeout, and sanitized errors. Test prompt-injection text inside a result.

Official references