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 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

PackageResponsibility
afk.agentsAgent definitions, policy, prompts, skills, lifecycle, workflow, A2A
afk.coreRunner, interaction providers, streaming handles, telemetry contracts
afk.llmsProvider-portable LLM runtime, adapters, retry/timeout/cache/routing policies
afk.toolsTyped tools, decorators, registry, sandboxing, output limiting
afk.memoryMemory stores, checkpoints, retention, compaction, vector helpers
afk.queuesAsync task queues, execution contracts, workers, retry/DLQ behavior
afk.observabilityTelemetry collectors, projectors, exporters
afk.mcp, afk.messaging, afk.debugger, afk.evalsOptional 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

  1. Identify the public contract affected by the change.
  2. Inspect the existing module and tests before editing.
  3. Make the smallest behavior change that preserves package boundaries.
  4. Add or update focused tests for success and failure paths.
  5. Update docs when behavior, public imports, configuration, env vars, or examples change.
  6. 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:
AreaRisk
src/afk/core/runner/execution loop, checkpoints, resume, policy/failure routing
src/afk/core/streaming.pystream events and handle lifecycle
src/afk/tools/core/base.py, src/afk/tools/registry.pytool invocation semantics
src/afk/tools/security.pysandbox, 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.