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.
The Agent Forge Kit (AFK) Python SDK is organized into top-level packages, each owning a distinct responsibility. This page summarizes the package map, key public imports, and extension boundaries.
Use this reference when you need to find which package owns a capability. For field-level details, read the focused reference pages linked from the sidebar.
Module dependencies
The AFK architecture is organized around a few stable boundaries:
afk.agents owns declarative agent configuration, policy, prompts, skills, delegation metadata, and A2A contracts.afk.core owns execution: runner lifecycle, streaming, interaction providers, delegation scheduling, checkpointing, memory wiring, and telemetry wiring.afk.llms owns model provider adapters, runtime policies, structured output helpers, routing, caching, and LLM request/response types.afk.tools owns tool definitions, registries, hooks, middleware, sandbox profiles, and prebuilt runtime tools.
Extension points
The framework is designed to be extended at specific protocol boundaries. Do not subclass internal classes. Instead, implement these protocols:
InteractionProvider (afk.core): Build custom human-in-the-loop interfaces (for example Slack, Discord, or web approval UIs).MemoryStore (afk.memory): Add support for new databases (Mongo, DynamoDB).LLMProvider (afk.llms): Integrate new model providers (local inference, exotic APIs).TelemetrySink (afk.observability): Export metrics/traces to custom backends (Datadog, Honeycomb).
afk.agents
Agent definitions, lifecycle types, delegation, policy, A2A protocol, and error hierarchy.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.agents.core | Agent and BaseAgent definitions, ChatAgent variant. |
afk.agents.types | Runtime types: AgentResult, AgentRunEvent, AgentRunHandle, AgentState, PolicyEvent, PolicyDecision, FailSafeConfig, UsageAggregate, execution records. |
afk.agents.policy | PolicyEngine, PolicyRule, PolicyEvaluation, policy subject inference. |
afk.agents.delegation | DelegationPlan, DelegationNode, DelegationEdge, RetryPolicy, JoinPolicy, DelegationResult. |
afk.agents.a2a | InternalA2AProtocol, A2A auth providers (AllowAllA2AAuthProvider, APIKeyA2AAuthProvider, JWTA2AAuthProvider), A2AServiceHost, delivery stores. |
afk.agents.contracts | AgentCommunicationProtocol, AgentInvocationRequest, AgentInvocationResponse, AgentDeadLetter. |
afk.agents.prompts | PromptStore, prompt file resolution, template rendering. |
afk.agents.lifecycle | Checkpoint versioning, schema migration, runtime helpers (circuit breaker, effect journal, state snapshots). |
afk.agents.skills | SkillStore, SkillDoc, SKILL.md parsing, checksum verification, and process-wide caching. |
afk.agents.security | Prompt-injection sanitization, untrusted tool-output redaction, and channel markers for trusted vs untrusted content. |
afk.agents.errors | Full error hierarchy: AgentError, AgentExecutionError, AgentCancelledError, SubagentRoutingError, etc. |
from afk.agents import Agent, AgentResult, AgentRunEvent, PolicyEngine, PolicyRule
from afk.agents import DelegationPlan, DelegationNode, FailSafeConfig
from afk.agents import JWTA2AAuthProvider, A2AServiceHost
afk.core
Runner execution engine, streaming, interaction providers, and delegation engine.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.core.runner | Runner class with run(), run_sync(), run_handle(), run_stream(), resume(), compact_thread(). RunnerConfig for safety and behavior defaults. |
afk.core.streaming | AgentStreamHandle, AgentStreamEvent, stream event constructors (text_delta, tool_started, stream_completed). |
afk.core.interaction | InteractionProvider protocol, HeadlessInteractionProvider, InMemoryInteractiveProvider. |
afk.core.runtime | DelegationEngine, DelegationPlanner, DelegationScheduler, backpressure and graph validation. |
from afk.core import Runner, RunnerConfig
from afk.core import AgentStreamHandle, AgentStreamEvent
from afk.core import InteractionProvider, HeadlessInteractionProvider
from afk.core import DelegationEngine
afk.llms
LLM client builder, provider registry, runtime policies, caching, routing, middleware, and type definitions.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.llms.builder | LLMBuilder — fluent builder for constructing LLM client instances. |
afk.llms.providers | Provider registry: OpenAIProvider, LiteLLMProvider, AnthropicAgentProvider, register_llm_provider(). |
afk.llms.runtime | LLMClient with production policies: RetryPolicy, TimeoutPolicy, RateLimitPolicy, CircuitBreakerPolicy, HedgingPolicy, CachePolicy. |
afk.llms.routing | Router registry: create_llm_router(), register_llm_router(). |
afk.llms.cache | Cache backends: create_llm_cache(), in-memory and Redis implementations. |
afk.llms.middleware | MiddlewareStack for request/response transformation pipelines. |
afk.llms.types | LLMRequest, LLMResponse, Message, ToolCall, Usage, streaming event types. |
afk.llms.config | LLMConfig dataclass for model configuration. |
afk.llms.profiles | Production/development profile presets. |
afk.llms.errors | LLMError, LLMTimeoutError, LLMRetryableError, etc. |
from afk.llms import LLMBuilder, LLMClient, LLMRequest, LLMResponse, Message
from afk.llms import RetryPolicy, TimeoutPolicy, CircuitBreakerPolicy
from afk.llms import LLMConfig, LLMSettings, PROFILES
| Sub-module | Responsibility |
|---|
afk.tools.core | tool decorator, ToolSpec, ToolContext, ToolResult, ToolRegistry. |
afk.tools.security | SandboxProfile, SandboxProfileProvider, SecretScopeProvider, argument validation. |
afk.tools.prebuilts | Built-in runtime tools (file read, directory list, command execution, skill tools). |
afk.tools.registry | Shared registry and registry middleware helpers. |
from afk.tools import tool, ToolResult, ToolContext
from afk.tools.security import SandboxProfile, SecretScopeProvider
afk.memory
Pluggable memory stores, compaction, retention policies, long-term memory, vector search, and thread state persistence.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.memory.store | MemoryStore abstract base class, MemoryCapabilities declarations. |
afk.memory.types | MemoryEvent, LongTermMemory, JsonValue, retention policy models. |
afk.memory.lifecycle | apply_event_retention(), apply_state_retention(), compact_thread_memory(), MemoryCompactionResult. |
afk.memory.vector | cosine_similarity(), vector scoring utilities for embedding-based search. |
afk.memory.factory | create_memory_store_from_env() factory for environment-based backend selection. |
afk.memory.adapters | Backend implementations: InMemoryMemoryStore, SQLiteMemoryStore, PostgresMemoryStore, RedisMemoryStore. |
from afk.memory import MemoryStore, RetentionPolicy, compact_thread_memory
from afk.memory import InMemoryMemoryStore
from afk.memory.adapters.sqlite import SQLiteMemoryStore
from afk.memory.adapters.postgres import PostgresMemoryStore
from afk.memory.adapters.redis import RedisMemoryStore
from afk.memory.types import MemoryEvent, LongTermMemory
afk.queues
Task queue abstraction, worker lifecycle, failure classification, and metrics.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.queues.base | Base queue types and enqueue/dequeue contracts. |
afk.queues.contracts | Queue protocol definitions. |
afk.queues.factory | Queue backend factory for creating queue instances. |
afk.queues.worker | Worker lifecycle management and task dispatch. |
afk.queues.metrics | Queue-level operational metrics. |
from afk.queues import TaskQueue, TaskWorker
afk.observability
Telemetry collection, projection, and export for runtime monitoring.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.observability.models | RunMetrics dataclass with aggregated run statistics. |
afk.observability.contracts | Span and metric name constants (SPAN_AGENT_RUN, METRIC_AGENT_LLM_CALLS_TOTAL, etc.). |
afk.observability.projectors | Projection functions that transform run results into RunMetrics. |
afk.observability.exporters | ConsoleRunMetricsExporter and other output formatters. |
afk.observability.backends | Telemetry sink creation (create_telemetry_sink). |
from afk.observability.models import RunMetrics
from afk.observability.contracts import SPAN_AGENT_RUN, METRIC_AGENT_LLM_CALLS_TOTAL
from afk.observability.exporters.console import ConsoleRunMetricsExporter
afk.evals
Eval suite execution, assertion contracts, budget constraints, and report serialization.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.evals.suite | run_suite() and arun_suite() entrypoints. |
afk.evals.executor | Single-case execution via run_case() and arun_case(). |
afk.evals.models | EvalCase, EvalCaseResult, EvalSuiteConfig, EvalSuiteResult, EvalAssertionResult. |
afk.evals.contracts | EvalAssertion, AsyncEvalAssertion, EvalScorer protocols. |
afk.evals.budgets | EvalBudget dataclass and evaluate_budget() function. |
afk.evals.reporting | suite_report_payload(), write_suite_report_json(). |
afk.evals.golden | write_golden_trace(), compare_event_types() for deterministic trace comparison. |
from afk.evals import run_suite, EvalBudget
from afk.evals.models import EvalCase, EvalSuiteConfig, EvalSuiteResult
from afk.evals.reporting import write_suite_report_json
from afk.evals.golden import compare_event_types
afk.mcp
Model Context Protocol server implementation, tool store, and server registration.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.mcp.server | MCP protocol handler. |
afk.mcp.store | Tool store registry and utility functions for MCP tool loading. |
from afk.mcp import get_mcp_store
afk.messaging
Protocol-first agent-to-agent messaging exports.
Sub-modules:
| Sub-module | Responsibility |
|---|
afk.messaging | Public re-exports for A2A contracts, envelopes, auth providers, hosts, and delivery stores. |
afk.agents.a2a | Internal implementation modules for protocol, auth, delivery, hosting, and Google adapter. |
from afk.messaging import InternalA2AEnvelope, InternalA2AProtocol
from afk.messaging import AgentInvocationRequest, AgentInvocationResponse
