> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Agents
description: Configure LLM agents with instructions, models, tools, handoffs, and loop limits.
last_verified: 2026-06-02
---

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.

```python
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](#tools)) |
| `built_in_tools` | `list[BuiltInTool]` | no | Provider-hosted tools like web search (see [Built-in Tools](#built-in-tools)) |
| `handoffs` | `list` | no | Agents to delegate to (see [Handoffs](#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:**

```python
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.

```python
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.

```python
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](/docs/build/tools.md) 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.

```python
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.

```python
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):

```python
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
)
```