Full Module Reference

The Agent Forge Kit (AFK) Python SDK is organized into a set of top-level packages, each owning a distinct responsibility. This page provides a comprehensive inventory of every package, its sub-modules, key classes and functions, and example imports. Use this reference when you need to find where a comprehensive inventory of every package, its sub-modules, key classes and functions, and example imports.

Module dependencies

The AFK architecture is layered. Dependencies flow strictly downwards:

afk.agents (High-level definitions) -> depends on afk.core, afk.tools, afk.llms
afk.core (Execution engine) -> depends on afk.model, afk.memory, afk.observability
afk.llms (Provider I/O) -> independent
afk.tools (Capabilities) -> independent

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 interaces (e.g. Slack, Discord, Web).
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.hooks`	Pre/post execution hook system for tool middleware.

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()` 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 QueueWorker, TaskQueue

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

Internal agent-to-agent messaging primitives with delivery guarantees. Sub-modules:

Sub-module	Responsibility
`afk.messaging.bus`	`MessageBus` protocol for pub/sub messaging between agents.
`afk.messaging.delivery`	Delivery tracking, acknowledgment, and retry for inter-agent messages.
`afk.messaging.types`	`AgentMessage`, `MessageEnvelope`, delivery status types.

Key imports:

from afk.messaging import MessageBus, AgentMessage

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