Skip to main content
AFK maintains a clear boundary between its public API surface and internal implementation details. This page explains the import policy, shows canonical import patterns organized by use case, and provides guidance for migrating from internal imports to stable public imports. Understanding this boundary is important: public imports are covered by semantic versioning guarantees, while internal imports may change without notice in any release.

​
Import policy

AFK follows three rules for its public API surface: 1. Prefer public package exports. Every AFK package defines an __all__ list in its __init__.py file. These exports are the public API. Import from the package level rather than reaching into internal sub-modules. 
# Preferred: import from public package surface
from afk.agents import Agent, PolicyEngine, AgentResult
from afk.core import Runner, RunnerConfig
from afk.llms import LLMBuilder, LLMRequest, Message

# Avoid: importing from internal sub-modules
from afk.agents.core.base import Agent          # internal path
from afk.core.runner.api import RunnerAPIMixin  # internal mixin
from afk.llms.builder import LLMBuilder         # internal module
Why this matters: Internal module paths may be reorganized between releases (sub-modules renamed, code moved between files). The package-level __init__.py exports are the stable contract. If you import from the package level, your code survives internal refactors without changes. 2. Avoid importing private or internal modules. Any module with a leading underscore (_helpers.py), or any path containing _internal or _private, is not part of the public API. These modules exist to support the framework’s internal implementation and may change without notice. 3. Keep interfaces contract-first and explicit. When extending AFK (implementing custom tools, assertions, interaction providers, etc.), implement the documented protocol interfaces rather than subclassing internal classes. Protocol-based contracts are stable; internal class hierarchies are not.

​
Canonical import patterns by use case

​
Agent definition and execution

from afk.agents import Agent, BaseAgent, ChatAgent
from afk.agents import AgentResult, AgentRunEvent, AgentRunHandle, AgentState
from afk.agents import FailSafeConfig, UsageAggregate
from afk.core import Runner, RunnerConfig

​
Policy and security

from afk.agents import PolicyEngine, PolicyRule, PolicyEvent, PolicyDecision
from afk.agents import ApprovalRequest, ApprovalDecision
from afk.agents import UserInputRequest, UserInputDecision
from afk.tools.security import SandboxProfile, SandboxProfileProvider, SecretScopeProvider

​
Tool development

from afk.tools import tool, ToolResult, ToolContext

​
LLM client (direct usage)

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

​
Delegation and subagents

from afk.agents import DelegationPlan, DelegationNode, DelegationEdge
from afk.agents import RetryPolicy, JoinPolicy, DelegationResult
from afk.agents import SubagentExecutionRecord, ToolExecutionRecord

​
A2A protocol

from afk.agents import InternalA2AProtocol, A2AServiceHost
from afk.agents import AgentInvocationRequest, AgentInvocationResponse
from afk.agents import JWTA2AAuthProvider, APIKeyA2AAuthProvider

​
Eval suite

from afk.evals import run_suite, EvalBudget
from afk.evals.models import EvalCase, EvalSuiteConfig, EvalSuiteResult
from afk.evals.models import EvalCaseResult, EvalAssertionResult
from afk.evals.reporting import write_suite_report_json, suite_report_payload
from afk.evals.golden import write_golden_trace, compare_event_types

​
Observability

from afk.observability.models import RunMetrics
from afk.observability.contracts import SPAN_AGENT_RUN, SPAN_AGENT_LLM_CALL
from afk.observability.exporters.console import ConsoleRunMetricsExporter
from afk.observability.projectors import project_run_metrics_from_result

​
Interaction providers

from afk.core import InteractionProvider, HeadlessInteractionProvider
from afk.core import InMemoryInteractiveProvider

​
Streaming

from afk.core import AgentStreamHandle, AgentStreamEvent

​
Memory

from afk.memory import MemoryStore, RetentionPolicy, StateRetentionPolicy
from afk.memory import compact_thread_memory, MemoryCompactionResult

​
Errors

from afk.agents import (
    AgentError,
    AgentExecutionError,
    AgentCancelledError,
    AgentInterruptedError,
    AgentLoopLimitError,
    AgentBudgetExceededError,
    SubagentRoutingError,
    SubagentExecutionError,
)
from afk.llms import LLMError, LLMTimeoutError, LLMRetryableError

​
Migration guide

If you have existing code that imports from internal module paths, use this table to find the correct public import:
Internal Import (avoid)Public Import (use instead)
from afk.agents.core.base import Agentfrom afk.agents import Agent
from afk.agents.types.result import AgentResultfrom afk.agents import AgentResult
from afk.agents.policy.engine import PolicyEnginefrom afk.agents import PolicyEngine
from afk.core.runner.api import RunnerAPIMixinfrom afk.core import Runner
from afk.core.runner.types import RunnerConfigfrom afk.core import RunnerConfig
from afk.llms.builder import LLMBuilderfrom afk.llms import LLMBuilder
from afk.llms.types import LLMRequestfrom afk.llms import LLMRequest
from afk.evals.suite import run_suitefrom afk.evals import run_suite
from afk.evals.budgets import EvalBudgetfrom afk.evals import EvalBudget
from afk.tools.core.base import ToolResultfrom afk.tools import ToolResult
To find all internal imports in your project, search for patterns like from afk.*.*. (three or more dots of depth) and check whether a shallower public import exists.