Agents

Configure LLM agents with instructions, models, tools, handoffs, and loop limits.

An Agent is an LLM that runs in a loop: it reads your instructions, calls tools when it needs to, and keeps going until it has a final answer. You give it a model, a purpose, and optionally a set of tools. The SDK handles the loop, tool dispatch, and result collection.

Creating an Agent

Three things are required: a name, a model, and instructions.

from agnt5 import Agent

agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="You are a research assistant. Answer questions with cited sources.",
)

Parameter	Type	Required	Description
`name`	`str`	yes	Identifier for this agent
`model`	`str`	yes	Model to use, as `"provider/model-name"` (e.g. `"openai/gpt-4o"`, `"anthropic/claude-3-5-sonnet-20241022"`)
`instructions`	`str`	yes	System prompt that tells the agent its role and behavior
`tools`	`list`	no	Tools the agent can call (see Tools)
`built_in_tools`	`list[BuiltInTool]`	no	Provider-hosted tools like web search (see Built-in Tools)
`handoffs`	`list`	no	Agents to delegate to (see Handoffs)
`max_iterations`	`int`	no	Max reasoning loops before stopping. Default: `10`
`temperature`	`float`	no	Sampling temperature (0–1). Lower = more deterministic. Default: `0.7`
`max_tokens`	`int`	no	Maximum tokens in the model response
`top_p`	`float`	no	Top-p nucleus sampling (0–1)
`model_config`	`ModelConfig`	no	Custom endpoint config: `base_url`, `api_key`, `timeout`, `headers`

Example with generation settings:

agent = Agent(
    name="analyst",
    model="openai/gpt-4o-mini",
    instructions="You are a precise data analyst.",
    temperature=0.2,      # more focused, less creative
    max_tokens=4096,
    max_iterations=5,
)

Running an Agent

`run()`: wait for the final answer

Use run() when you want the complete result in one call.

result = await agent.run("What causes northern lights?")
print(result.output)

result.output is the agent’s final text response. result.tool_calls lists every tool call made along the way.

`stream()`: receive events as they happen

Use stream() when you want to show output progressively or react to tool calls in real time.

async for event in agent.stream("What causes northern lights?"):
    if event.event_type == "lm.content_block.delta":
        print(event.content, end="", flush=True)

Key event types:

Event type	When it fires
`agent.started`	Agent loop begins
`lm.content_block.delta`	A chunk of the LLM response arrives
`lm.content_block.completed`	LLM response block is complete
`tool_call.started`	A tool call begins
`tool_call.completed`	A tool call finishes
`agent.completed`	Agent loop ends. Final answer is available

Tools

Tools give your agent the ability to take actions: call an API, run code, or search the web. Pass them via tools (custom functions or other agents) or built_in_tools (provider-hosted tools like web search).

See Tools for the full reference. Covers custom tools, sandbox tools, built-in tools, and human-in-the-loop tools.

Multi-Agent Patterns

Agents as tools

The calling agent invokes a specialist, gets the result back, and continues its own reasoning. Good for workflows where the coordinator needs to synthesize results from multiple specialists.

from agnt5 import Agent

research_agent = Agent(
    name="researcher",
    model="openai/gpt-4o-mini",
    instructions="You research topics and return concise summaries.",
)

analyst_agent = Agent(
    name="analyst",
    model="openai/gpt-4o-mini",
    instructions="You analyze data and identify trends.",
)

coordinator = Agent(
    name="coordinator",
    model="openai/gpt-4o-mini",
    instructions="Use the researcher and analyst to answer complex questions.",
    tools=[research_agent, analyst_agent],   # each becomes ask_researcher / ask_analyst
)

result = await coordinator.run("What are the latest trends in renewable energy?")
print(result.output)

Handoffs

The calling agent transfers control entirely to a specialist. The specialist runs and its output is returned as the final result. Good for routing: when the triage agent’s job is done once it knows who should handle the request.

from agnt5 import Agent, handoff

billing_agent = Agent(
    name="billing",
    model="openai/gpt-4o-mini",
    instructions="You handle billing questions and subscription changes.",
)

technical_agent = Agent(
    name="technical",
    model="openai/gpt-4o-mini",
    instructions="You handle technical support and bug reports.",
)

triage_agent = Agent(
    name="triage",
    model="openai/gpt-4o-mini",
    instructions="Route the user to the right specialist.",
    handoffs=[
        handoff(billing_agent, "Transfer when the user has a billing or payment question"),
        handoff(technical_agent, "Transfer when the user has a technical or product issue"),
    ],
)

result = await triage_agent.run("My payment failed but I was still charged.")
print(result.output)          # billing_agent's response
print(result.handoff_to)      # "billing"

handoff() parameters:

Parameter	Type	Default	Description
`agent`	`Agent`	required	The target agent
`description`	`str`	agent’s instructions	What the LLM sees when deciding whether to hand off
`tool_name`	`str`	`transfer_to_{name}`	Custom name for the transfer tool
`pass_full_history`	`bool`	`True`	Whether to pass the full conversation to the target agent

To hand off without customization, pass the agent directly (no handoff() call needed):

triage_agent = Agent(
    name="triage",
    model="openai/gpt-4o-mini",
    instructions="Route the user to the right specialist.",
    handoffs=[billing_agent, technical_agent],   # simple form
)