Full Module Reference

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.

Key imports:

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.

Key imports:

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.

Key imports:

from afk.llms import LLMBuilder, LLMClient, LLMRequest, LLMResponse, Message
from afk.llms import RetryPolicy, TimeoutPolicy, CircuitBreakerPolicy
from afk.llms import LLMConfig, LLMSettings, PROFILES

`afk.tools`

Tool definition, registry, hooks, middleware, security, and prebuilt runtime tools. Sub-modules:

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.

Key imports:

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

Key imports:

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.

Key imports:

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`).

Key imports:

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.

Key imports:

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.

Key imports:

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.

Key imports:

from afk.messaging import InternalA2AEnvelope, InternalA2AProtocol
from afk.messaging import AgentInvocationRequest, AgentInvocationResponse

​Module dependencies

​Extension points

​afk.agents

​afk.core

​afk.llms

​afk.tools

​afk.memory

​afk.queues

​afk.observability

​afk.evals

​afk.mcp

​afk.messaging

Module dependencies

Extension points

`afk.agents`

`afk.core`

`afk.llms`

`afk.tools`

`afk.memory`

`afk.queues`

`afk.observability`

`afk.evals`

`afk.mcp`

`afk.messaging`