> ## 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. # API Reference > Canonical public imports and core signatures for AFK. This page is the public import contract for application developers. Use these imports in docs, examples, tests that exercise public behavior, and downstream applications. For field-by-field configuration, see [Configuration Reference](/library/configuration-reference). For generated module detail, see [Full Module Reference](/library/full-module-reference). ## Import map | Task | Public import | | ------------------------------ | ---------------------------------------------------------------------- | | Define an agent | `from afk.agents import Agent` | | Configure fail-safe limits | `from afk.agents import FailSafeConfig` | | Configure policy rules | `from afk.agents import PolicyEngine, PolicyRule` | | Implement dynamic policy hooks | `from afk.agents import PolicyRole` | | Run an agent | `from afk.core import Runner` | | Configure the runner | `from afk.core import RunnerConfig` | | Consume streaming events | `from afk.core import AgentStreamEvent, AgentStreamHandle` | | Define a tool | `from afk.tools import tool` | | Access tool context | `from afk.tools import ToolContext` | | Build an LLM client | `from afk.llms import LLMBuilder` | | Run eval suites | `from afk.evals import run_suite` | | Define eval cases | `from afk.evals import EvalCase, EvalBudget` | | Create memory stores | `from afk.memory import InMemoryMemoryStore, SQLiteMemoryStore` | | Create task queues | `from afk.queues import InMemoryTaskQueue, RedisTaskQueue, TaskWorker` | | Expose MCP tools | `from afk.mcp import MCPServer` | | Use A2A messaging | `from afk.messaging import InternalA2AProtocol` | Do not use `src.afk.*` imports in user-facing docs. ## Agent ```text theme={null} from afk.agents import Agent agent = Agent( *, model: str | LLM, name: str | None = None, tools: list | None = None, subagents: list[Agent] | None = None, instructions: str | callable | None = None, instruction_file: str | Path | None = None, prompts_dir: str | Path | None = None, context_defaults: dict | None = None, inherit_context_keys: list[str] | None = None, model_resolver: callable | None = None, skills: list[str] | None = None, mcp_servers: list | None = None, skills_dir: str | Path = ".agents/skills", instruction_roles: list | None = None, policy_roles: list | None = None, policy_engine: PolicyEngine | None = None, subagent_router: callable | None = None, max_steps: int = 20, tool_parallelism: int | None = None, subagent_parallelism_mode: str = "configurable", fail_safe: FailSafeConfig | None = None, reasoning_enabled: bool | None = None, reasoning_effort: str | None = None, reasoning_max_tokens: int | None = None, skill_tool_policy: SkillToolPolicy | None = None, enable_mcp_tools: bool = True, enable_skill_tools: bool = True, runner: Runner | None = None, ) ``` Only `model` is required. Most examples should also set `name` and `instructions` for clear traces and predictable behavior. ## Runner ```python theme={null} from afk.core import Runner, RunnerConfig runner = Runner( memory_store=None, interaction_provider=None, policy_engine=None, telemetry=None, telemetry_config=None, config=RunnerConfig(), ) ``` Common methods: | Method | Use when | Returns | | -------------------------------------------------------------------- | --------------------------------------------------- | ------------------------ | | `runner.run_sync(agent, user_message=..., thread_id=...)` | Scripts, CLIs, tests without an existing event loop | `AgentResult` | | `await runner.run(agent, user_message=..., thread_id=...)` | Async services, workers, APIs | `AgentResult` | | `await runner.run_stream(agent, user_message=..., thread_id=...)` | Chat UIs and progress streams | `AgentStreamHandle` | | `await runner.resume(agent, run_id=..., thread_id=..., context=...)` | Continue from persisted state | `AgentResult` | | `await runner.compact_thread(thread_id=...)` | Apply memory retention/compaction | `MemoryCompactionResult` | `run_sync()` is a convenience wrapper for synchronous code. Use `await runner.run(...)` inside async applications. ## RunnerConfig ```python theme={null} from afk.core import RunnerConfig config = RunnerConfig( interaction_mode="headless", approval_timeout_s=300.0, input_timeout_s=300.0, approval_fallback="deny", input_fallback="deny", sanitize_tool_output=True, untrusted_tool_preamble=True, tool_output_max_chars=12_000, max_parallel_subagents_global=64, max_parallel_subagents_per_parent=8, max_parallel_subagents_per_target_agent=4, checkpoint_async_writes=True, debug=False, background_tools_enabled=True, ) ``` Use [Configuration Reference](/library/configuration-reference) for the complete set of runner fields and defaults. ## FailSafeConfig ```python theme={null} from afk.agents import FailSafeConfig fail_safe = FailSafeConfig( llm_failure_policy="retry_then_fail", tool_failure_policy="continue_with_error", subagent_failure_policy="continue", approval_denial_policy="skip_action", max_steps=20, max_wall_time_s=300.0, max_llm_calls=50, max_tool_calls=200, max_parallel_tools=16, max_subagent_depth=3, max_total_cost_usd=None, fallback_model_chain=[], ) ``` Set `max_total_cost_usd` for production agents. The default is intentionally unset because acceptable budgets vary by application. ## Tool decorator ```python theme={null} from pydantic import BaseModel from afk.tools import tool class SearchArgs(BaseModel): query: str @tool(args_model=SearchArgs, name="search", description="Search by query.") def search(args: SearchArgs) -> dict: return {"query": args.query, "results": []} ``` Tool functions may be sync or async. They may accept `(args)`, `(args, ctx)`, or `(ctx, args)`. ## AgentResult ```python theme={null} result = Runner().run_sync(agent, user_message="Hello") print(result.final_text) print(result.state) print(result.run_id) print(result.thread_id) print(result.tool_executions) print(result.subagent_executions) print(result.usage_aggregate.total_tokens) print(result.total_cost_usd) ``` Important fields: | Field | Meaning | | --------------------- | ----------------------------------------- | | `final_text` | Final assistant text | | `state` | Terminal run state | | `requested_model` | Model requested by the caller or agent | | `normalized_model` | Effective normalized model when available | | `provider_adapter` | Provider/adapter used when available | | `tool_executions` | Ordered tool execution records | | `subagent_executions` | Ordered subagent execution records | | `usage_aggregate` | Aggregated input/output/total tokens | | `total_cost_usd` | Estimated total cost when available | | `state_snapshot` | Terminal runtime snapshot payload | ## API stability * Public docs and examples should use imports from `afk.agents`, `afk.core`, `afk.tools`, `afk.llms`, `afk.memory`, `afk.queues`, `afk.mcp`, `afk.messaging`, `afk.observability`, and `afk.evals`. * Internal modules under package subdirectories may change faster than public exports. * When changing public exports, update this page, [Public API Rules](/library/public-imports-and-function-improvement), examples, and generated agent-facing docs.