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.

AFK is an agent runtime for Python applications. It is designed for teams that need agent behavior to be typed, observable, testable, and bounded by explicit controls. The core idea is simple:

​
The three core objects

ObjectWhat it ownsWhat it does not own
AgentName, model, instructions, tools, subagents, skills, MCP servers, defaults, fail-safe limitsNetwork calls, event loops, persistence, telemetry export
RunnerExecution loop, tool dispatch, streaming, memory, checkpointing, policy/HITL, telemetryAgent identity or instructions
AgentResultFinal text, terminal state, tool/subagent records, usage aggregate, cost, run/thread idsFuture execution
This separation is the main design rule. Agents describe behavior. Runners execute behavior. Runtime subsystems provide capabilities.

​
When AFK is a good fit

Use AFK when your agent will:
  • call tools or external systems;
  • run for more than one step;
  • need cost, time, step, or tool-call limits;
  • stream progress to a UI;
  • persist memory or resume a run;
  • require evals, telemetry, or production incident debugging;
  • coordinate specialist subagents.
A direct LLM provider SDK may be simpler for one-off single-turn text generation. AFK is useful when the agent needs operational structure.

​
Builder path

If you are building an app with AFK, read in this order:
  1. Quickstart for the smallest complete agent.
  2. Learn AFK in 15 Minutes for the guided path.
  3. Agents, Runner, and Tools for the core building blocks.
  4. Building with AI, Evals, and Observability before production.

​
Maintainer path

If you are changing AFK itself, read in this order:
  1. Developer Guide for local setup, commands, and docs workflow.
  2. Architecture for package boundaries.
  3. Public API Rules before changing exports or examples.
  4. Tested Behaviors before changing runner, tools, LLM runtime, memory, queues, or telemetry.

​
Source-of-truth rules

  • Public examples import from afk.*, never src.afk.*.
  • Runner is imported from afk.core.
  • User-facing docs should explain behavior before internals.
  • Maintainer docs may reference internal modules, but must identify the public contract affected by a change.
  • Generated agent-facing docs and skill indexes must be refreshed when navigation, examples, or skill references change.

​
Next steps

Quickstart

Build one agent and one typed tool.

Developer Guide

Set up the repo and understand the contributor workflow.