Developer Guide

This page is for contributors changing the AFK framework. If you are building an application with AFK, start with Quickstart or Building with AI.

Local setup

AFK targets Python 3.13+.

python -m pip install --upgrade pip
python -m pip install -e . pytest

Common commands:

PYTHONPATH=src pytest -q
PYTHONPATH=src pytest -q tests/agents/test_agent_runtime.py
PYTHONPATH=src pytest -q tests/llms/test_llm_settings.py
PYTHONPATH=src pytest -q tests/queues/test_queue_factory.py
ruff check src tests
ruff format src tests

Preview docs:

./scripts/docs_dev.sh

Regenerate agent-facing docs and skill indexes:

./scripts/build_agentic_ai_assets.sh

Install the repository skills with Vercel’s Skills CLI:

npx skills add https://github.com/arpan404/afk --skill afk-coder
npx skills add https://github.com/arpan404/afk --skill afk-maintainer

Use afk-coder when building with AFK. Use afk-maintainer when reviewing or changing AFK itself.

Repository boundaries

Package	Responsibility
`afk.agents`	Agent definitions, policy, prompts, skills, lifecycle, workflow, A2A
`afk.core`	Runner, interaction providers, streaming handles, telemetry contracts
`afk.llms`	Provider-portable LLM runtime, adapters, retry/timeout/cache/routing policies
`afk.tools`	Typed tools, decorators, registry, sandboxing, output limiting
`afk.memory`	Memory stores, checkpoints, retention, compaction, vector helpers
`afk.queues`	Async task queues, execution contracts, workers, retry/DLQ behavior
`afk.observability`	Telemetry collectors, projectors, exporters
`afk.mcp`, `afk.messaging`, `afk.debugger`, `afk.evals`	Optional integration and quality layers

Keep the Agent/Runner/Runtime boundary intact:

agents are configuration;
runners execute;
tools, memory, queues, LLM adapters, and telemetry provide runtime capabilities.

Change workflow

Identify the public contract affected by the change.
Inspect the existing module and tests before editing.
Make the smallest behavior change that preserves package boundaries.
Add or update focused tests for success and failure paths.
Update docs when behavior, public imports, configuration, env vars, or examples change.
Regenerate agent-facing docs when docs navigation, snippets, or skill metadata change.

Documentation workflow

User-facing docs must:

import from public package surfaces such as afk.agents and afk.core;
explain behavior before internals;
use Python 3.13+ guidance;
distinguish afk-py distribution install from afk imports;
include new pages in docs/docs.json;
keep examples aligned with current AgentResult, RunnerConfig, and FailSafeConfig fields.

Maintainer docs may reference internal files, but should state which public contract or invariant is being protected.

High-risk areas

Use targeted tests when touching:

Area	Risk
`src/afk/core/runner/`	execution loop, checkpoints, resume, policy/failure routing
`src/afk/core/streaming.py`	stream events and handle lifecycle
`src/afk/tools/core/base.py`, `src/afk/tools/registry.py`	tool invocation semantics
`src/afk/tools/security.py`	sandbox, secret scope, output limiting
`src/afk/llms/runtime/`	retries, circuit breakers, rate limits, caching, routing
`src/afk/memory/`	persistence, checkpoint keys, compaction, vector search
`src/afk/queues/`	execution contracts, retry/DLQ, worker lifecycle
`src/afk/agents/a2a/`	auth, delivery guarantees, protocol compatibility

Public API checklist

Before changing exports or constructor fields:

update package-level __all__;
update API Reference;
update Configuration Reference if defaults changed;
update snippets that use the changed field;
add public-import tests where useful.

Next steps

Architecture

Package boundaries and runtime flow.

Public API Rules

Maintainer rules for stable imports and docs examples.

Tested Behaviors

Behaviors that tests protect.

Full Module Reference

Generated source-level symbol map.

Contributor Guide

Internal Contracts

Migration

Developer Guide

Local setup

Repository boundaries

Change workflow

Documentation workflow

High-risk areas

Public API checklist

Next steps

Architecture

Public API Rules

Tested Behaviors

Full Module Reference

​Local setup

​Repository boundaries

​Change workflow

​Documentation workflow

​High-risk areas

​Public API checklist

​Next steps

Architecture

Public API Rules

Tested Behaviors

Full Module Reference

Local setup

Repository boundaries

Change workflow

Documentation workflow

High-risk areas

Public API checklist

Next steps