> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
last_verified: 2026-10-09
title: Agents
description: Create agents with Agent, run or stream them, hand off between agents, and use agents as tools
category: Python SDK
hideRightSidebar: true
---

An agent is a model running in a loop with instructions and tools: it calls tools until it can answer. For a guided introduction, see [Agents](/docs/build/agents.md).

## `Agent(...)`

```python
from agnt5 import Agent, Context, FunctionContext, function, tool


@tool(name="get_weather", description="Get the weather for a city")
async def get_weather(ctx: Context, city: str) -> str:
    return f"Sunny, 22°C in {city}"


weather_agent = Agent(
    name="weather_agent",
    model="openai/gpt-6-luna",
    instructions="Answer weather questions. Call get_weather for the city.",
    tools=[get_weather],
    max_iterations=5,
)


@function
async def ask_weather(ctx: FunctionContext, message: str) -> str:
    result = await weather_agent.run(message, context=ctx)
    return result.output
```

| Parameter | Description |
|---|---|
| `name` | The agent's name, shown in traces. |
| `model` | The model, as `provider/model`, for example `"openai/gpt-6-luna"`. |
| `instructions` | The system instructions. |
| `tools` | [Tools](/sdk/python/tools.md) the agent can call. |
| `handoffs` | Agents to hand the conversation to. See [Handoffs](#handoffs). |
| `max_iterations` | Most model calls in one run. |
| `cache` | [Prompt caching](/docs/build/prompt-caching.md) policy, for example `lm.PromptCache(ttl="1h")`. |
| `sandbox` | A [sandbox](/docs/build/sandboxes.md) for file and code tools. |
| `skills`, `skills_dir`, `agents_md` | [Skills](/docs/build/skills.md) and `AGENTS.md` guidance. |

## Run an agent

### `await agent.run(message, context=None, history=None)`

Runs the loop and returns an `AgentResult`. Pass the handler's `ctx` as `context` so model and tool calls are traced inside the run.

| `AgentResult` field | Description |
|---|---|
| `output` | The agent's final answer. |
| `tool_calls` | Each tool call: `name`, `arguments`, and `iteration`. |
| `handoff_to` | The name of the agent that took over, or `None`. |
| `handoff_metadata` | Details of the handoff. |

### `agent.stream(message, context=None, history=None)`

An async generator of events while the agent runs:

```python
async for event in weather_agent.stream(message, context=ctx):
    print(event.event_type)
```

Event types include `agent.started`, `tool_call.started`, `tool_call.completed`, `lm.content_block.started`, `lm.content_block.delta`, `lm.content_block.completed`, and `agent.completed`.

### Register an agent

Pass the agent to the worker's `agents` list to run it on its own:

```bash
agnt5 run weather_agent --type agent --input '{"message": "Weather in Rome?"}'
```

## Handoffs

`handoff(agent, description=...)` lets an agent pass the conversation to another agent. The run's `handoff_to` names the agent that answered:

```python
from agnt5 import handoff

billing = Agent(
    name="billing",
    model="openai/gpt-6-luna",
    instructions="You handle billing questions.",
)

triage = Agent(
    name="triage",
    model="openai/gpt-6-luna",
    instructions="Route billing questions to the billing agent.",
    handoffs=[handoff(billing, description="Billing questions")],
)
```

## Agents as tools

`agent.to_tool()` returns a tool named `ask_<agent>`. Another agent calls it and gets the agent's answer back as the tool result:

```python
coordinator = Agent(
    name="coordinator",
    model="openai/gpt-6-luna",
    instructions="Use the billing tool for billing questions.",
    tools=[billing.to_tool()],
)
```

## Next steps

* [Tools](/sdk/python/tools.md): define the tools an agent calls.
* [LM](/sdk/python/lm.md): call a model directly.
* [Agents guide](/docs/build/agents.md): streaming, handoffs, and agents as tools in practice.