Skip to main content

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.

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
python -m pip install afk-py
export OPENAI_API_KEY="..."
When working from this repository instead of an installed package: 
python -m pip install -e . pytest

​
1. Define an agent

from afk.agents import Agent
from afk.core import Runner

agent = Agent(
    name="assistant",
    model="gpt-4.1-mini",
    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. 
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-4.1-mini",
    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:
FieldMeaning
final_textFinal assistant text
stateTerminal state such as completed, failed, cancelled, or degraded
run_idUnique id for this run
thread_idConversation/thread id used by memory
tool_executionsOrdered records for tool calls
subagent_executionsOrdered records for subagent calls
usage_aggregateAggregated token usage
total_cost_usdEstimated total run cost when available

​
4. Keep going

Learn AFK in 15 Minutes

Add streaming, memory, and safety controls.

Examples

Find complete snippets for common scenarios.

Agents

Understand the agent configuration object.

Runner

Understand sync, async, and streaming execution.