> ## Documentation Index
> Fetch the complete documentation index at: https://afk.arpan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build one AFK agent with one typed tool.

This page is the shortest useful AFK path: install the package, define an agent, attach one typed tool, and run it.

## Prerequisites

* Python 3.13+
* An LLM provider key, such as `OPENAI_API_KEY`

```bash theme={null}
python -m pip install afk-py
export OPENAI_API_KEY="..."
```

When working from this repository instead of an installed package:

```bash theme={null}
python -m pip install -e . pytest
```

## 1. Define an agent

```python theme={null}
from afk.agents import Agent
from afk.core import Runner

agent = Agent(
    name="assistant",
    model="gpt-5.5",
    instructions="Answer directly. Keep responses under 120 words.",
)

result = Runner().run_sync(
    agent,
    user_message="What is a mutex?",
)

print(result.final_text)
print(result.state)
```

`Agent` stores configuration. `Runner` executes the run. `AgentResult.final_text` is the assistant response.

## 2. Add one typed tool

Tools are Python functions with Pydantic argument models. AFK turns the model into a tool schema, validates model-provided arguments, executes the function, and feeds the result back into the agent loop.

```python theme={null}
from pydantic import BaseModel

from afk.agents import Agent, FailSafeConfig
from afk.core import Runner
from afk.tools import tool


class OrderArgs(BaseModel):
    order_id: str


@tool(
    args_model=OrderArgs,
    name="lookup_order",
    description="Look up a customer order by id.",
)
def lookup_order(args: OrderArgs) -> dict:
    return {
        "order_id": args.order_id,
        "status": "shipped",
        "eta": "Friday",
    }


agent = Agent(
    name="support-agent",
    model="gpt-5.5",
    instructions="Use lookup_order when the user asks about an order.",
    tools=[lookup_order],
    fail_safe=FailSafeConfig(
        max_steps=8,
        max_tool_calls=4,
        max_total_cost_usd=0.10,
    ),
)

result = Runner().run_sync(
    agent,
    user_message="Where is order A123?",
)

print(result.final_text)
print(len(result.tool_executions))
```

## 3. Read the result

Common fields on `AgentResult`:

| Field                 | Meaning                                                                  |
| --------------------- | ------------------------------------------------------------------------ |
| `final_text`          | Final assistant text                                                     |
| `state`               | Terminal state such as `completed`, `failed`, `cancelled`, or `degraded` |
| `run_id`              | Unique id for this run                                                   |
| `thread_id`           | Conversation/thread id used by memory                                    |
| `tool_executions`     | Ordered records for tool calls                                           |
| `subagent_executions` | Ordered records for subagent calls                                       |
| `usage_aggregate`     | Aggregated token usage                                                   |
| `total_cost_usd`      | Estimated total run cost when available                                  |

## 4. Keep going

<CardGroup cols={2}>
  <Card title="Learn AFK in 15 Minutes" icon="graduation-cap" href="/library/learn-in-15-minutes">
    Add streaming, memory, and safety controls.
  </Card>

  <Card title="Examples" icon="code" href="/library/examples/index">
    Find complete snippets for common scenarios.
  </Card>

  <Card title="Agents" icon="robot" href="/library/agents">
    Understand the agent configuration object.
  </Card>

  <Card title="Runner" icon="play" href="/library/core-runner">
    Understand sync, async, and streaming execution.
  </Card>
</CardGroup>