Skip to main content

AFK is the Python SDK for building AI agents that are reliable by default. Define agents with typed contracts, wire in tools and policies, and ship to production with observability, evals, and safety limits built in.

Install

pip install afk
NOTE: You need an LLM provider API key. Set OPENAI_API_KEY, or configure any provider supported by LiteLLM.

Your first agent

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

agent = Agent(
    name="my-agent",
    model="gpt-5.2-mini",
    instructions="You are a helpful assistant. Be concise and accurate.",
)

runner = Runner()
result = runner.run_sync(agent, user_message="What is an error budget in SRE?")
print(result.final_text)   # ← The agent's response
print(result.state)        # ← "completed"
  1. Agent(...) defines the agent — its name, model, and system prompt instructions. 2. Runner() creates the execution engine with safe defaults (headless mode, in-memory state). 3. run_sync() sends the user message to the LLM, waits for the response, and returns an AgentResult. 4. final_text holds the model’s response. state tells you how the run ended (completed, failed, degraded, or cancelled).

Add a tool in 30 seconds

from pydantic import BaseModel
from afk.agents import Agent
from afk.tools import tool
from afk.core import Runner

class WeatherArgs(BaseModel):
    city: str

@tool(args_model=WeatherArgs, name="get_weather", description="Get current weather for a city.")
def get_weather(args: WeatherArgs) -> dict:
    return {"city": args.city, "temp_f": 72, "condition": "sunny"}

agent = Agent(
    name="weather-bot",
    model="gpt-5.2-mini",
    instructions="Answer weather questions using your tools.",
    tools=[get_weather],           # ← Attach tools here
)

runner = Runner()
result = runner.run_sync(agent, user_message="What's the weather in Austin?")
print(result.final_text)           # ← "It's 72°F and sunny in Austin."

What AFK gives you

Agents

Define agents with typed inputs, instructions, tools, and subagents. Single-agent or multi-agent — you choose.

Runner

Execute agents synchronously, asynchronously, or with real-time streaming. Pause, resume, cancel at any point.

Tools

Give agents capabilities through typed Python functions. Schema validation, policy gates, and output sanitization built in.

Memory

Persist conversation state across runs. Resume interrupted runs from checkpoints. Compact long threads automatically.

Multi-Agent

Orchestrate subagent DAGs with fan-out/fan-in, join policies, and backpressure controls.

LLM Layer

Provider-portable LLM runtime with retry, circuit breaking, caching, rate limiting, and fallback chains.

Observability

Built-in telemetry pipeline with spans, metrics, and exporters for console, JSON, and OpenTelemetry.

Evals

Behavioral testing framework with assertions, budgets, golden traces, and CI-ready reporting.

Security

Policy engine, sandbox profiles, tool allowlists, A2A auth, and secret scope isolation out of the box.

How it all fits together

Where to go next

Quickstart

Build your first agent with tools and streaming in 5 minutes.

Learn in 15 Minutes

Hands-on tutorial covering agents, tools, streaming, multi-agent, and memory.

Examples

Runnable code examples for every major AFK feature.

API Reference

Complete import reference organized by task.