Get typed structured output from a Koog 1.0 agent — pick between `nodeLLMRequestStructured` (graph DSL, schema-driven JSON) and `responseProcessor` (top-level on the agent factory, simpler shape). Defines the `@Serializable` output class and wires it into the strategy or the factory. Use when the user asks to "return JSON", "get a typed response", "use structured output", "return a data class from the agent", or shows a `data class` they want as the agent's output.

Add token-budgeting and per-provider tokenizer support to a Koog 1.0 agent — install the tokenizer feature, set per-run or per-node budgets, and react to budget exhaustion (compress history, abort, swap models). Use when the user asks to "limit tokens per run", "add a token budget", "prevent runaway agent costs", "use a tokenizer", or describes cost containment requirements.

Add a new tool to an existing Koog 1.0 agent. Pick the right registration style (@Tool + ToolSet annotation, Tool[TArgs,TResult] subclass, or sub-agent-as-tool), define the args, and wire the tool into the agent's ToolRegistry. Use when the user asks to "add a tool to my agent", "expose something to the LLM", "let the agent call a function", or "wrap this agent as a tool for another agent". Assumes a scaffolded Koog 1.0 project — for new projects start with the scaffold-agent skill.

Author a custom graph strategy for a Koog 1.0 agent — pick the right node types, chain tool execution correctly, build edges with the infix vocabulary, and reach for subgraphs (`subgraphWithTask`, `subgraphWithVerification`) when steps deserve their own model, prompt, or tool subset while still sharing the agent's message history. Use when the user asks to "write a custom strategy", "build a graph for the agent", "author a strategy DSL", "add a verify-and-fix loop", "use subgraphs", or describes multi-step orchestration that won't fit inside `singleRunStrategy()`. Subgraphs are not for context isolation — for an independent agent that does not see the parent's history, use `Skill(skill: "add-tool")` Step 3 (sub-agent-as-tool).

Add in-process caching of LLM calls to a Koog 1.0 agent via `prompt-executor-cached` — cache whole prompt→response pairs locally so identical calls skip the API. Distinct from provider-side Anthropic prompt caching (covered by `enable-prompt-caching`). Backends include in-memory (default), file-based, and Redis. Use when the user asks to "cache LLM responses", "avoid duplicate API calls", "add a response cache", "cache to Redis", or describes repeated identical prompts in dev/test.

Author prompts for a Koog 1.0 agent using the `prompt { ... }` DSL — system messages, user turns, few-shot examples, mixed media, and runtime augmentation via the `SystemPromptAugmenter` / `UserPromptAugmenter` family. Use when the user asks to "write a system prompt with examples", "add few-shot examples", "build a prompt", "augment the prompt at runtime", or moves beyond the single-string `systemPrompt` parameter on the factory.

Author a Koog 1.0 agent as a typed pipeline of domain-modeled subtasks — tools sliced by access pattern (read / write / communication) into separate ToolSets, inter-subtask handoffs as `@Serializable` `@LLMDescription`-annotated data classes (not text prompts), each subtask wired with `subgraphWithTask[In, Out]` using its own model and tool subset, self-correction loops via `subgraphWithVerification[T]` + `CriticResult[T]`. The integration pattern Koog's own banking demo uses. Use when the user asks to "model the agent as a pipeline", "build a multi-stage agent with typed handoffs", "give each stage its own tools", "build a verify-and-fix loop with typed data", or describes a workflow with distinct phases that should hand structured data to each other.

Enable Anthropic prompt caching for a Koog 1.0 agent — automatic caching is on by default in 1.0, but explicit `cacheControl` breakpoints let you control which parts of long prompts get cached. Surfaces cache-hit metrics through the OpenTelemetry token-usage span. Use when the user asks to "enable prompt caching", "reduce Anthropic costs", "add cache_control", "set cache breakpoints", or describes expensive repeated calls with shared system prompt content.

Install per-step event handlers on a Koog 1.0 agent — tool-call start/end, LLM request/response, agent finish, error events. Useful for stdout logging during development, visualizing planner decisions on stage during demos, or pushing events to a non-OTel sink. Use when the user asks to "log tool calls", "see what the agent is doing", "add event handlers", "visualize the planner", "trace each step" — anything where the goal is human-readable per-step output, not production metrics.

Work with Koog 1.0 agent state — typed key-value `storage` on `AIAgentContext`, history compression strategies (TL;DR, sliding window, fact retrieval), and the `LongTermMemory` feature (which replaces the removed `AgentMemory`) for cross-session recall. Use when the user asks to "store state across nodes", "compress conversation history", "remember things across sessions", "add long-term memory", or names any of these surfaces.

Migrate a Koog 0.x codebase to 1.0. Koog 1.0 (2026-05-21) removed every @Deprecated API in one sweep — 0.x code does not compile against 1.0. Walks through construction surface, planner module split, graph DSL renames, Java interop overhaul, HTTP transport decoupling, memory APIs, OpenTelemetry, persistence, prompt package move, retired models, and JDK/tooling minima. Use when the user asks to "migrate from 0.x", "bump Koog to 1.0", "upgrade Koog", or shows code that uses pre-1.0 APIs (e.g., AIAgent.invoke, AgentMemory, AIAgentPlannerStrategy.builder).

Model a problem domain as a tree of typed subtasks the Koog 1.0 planner can execute — the `PlannerNode` data model, parallel vs sequential composition, accessing in-flight subtasks through `AIAgentStorage`, retry-on-parse-failure edges, and TL;DR compression between phases. Goes deeper than `use-planner` (which only picks the planner factory). Use when the user asks to "decompose into subtasks", "model the agent's work as a tree", "compose parallel and sequential steps", "retry failed subtasks", or describes a richer planner usage than the basic factory.

Persist a Koog 1.0 agent's chat history to a durable backend — JDBC database (`chat-history-jdbc`), AWS storage (`chat-history-aws`), or SQL-typed chat memory (`chat-memory-sql`) — so conversations survive process restarts and can be retrieved by session ID. Distinct from generic agent persistence (state checkpoints) and from LongTermMemory (fact retrieval). Use when the user asks to "save chat history", "persist conversations", "resume a chat by session", "store chat in Postgres / DynamoDB".

Give a Koog 1.0 agent the ability to query a SQL database safely — install `agents-features-sql`, register the database connection, and expose schema-aware query tools the LLM can call. Includes safety guidance (read-only by default, schema scoping, parameterized queries). Use when the user asks to "let the agent query the database", "add SQL to my agent", "expose a database to the LLM", or describes data-retrieval needs the LLM should drive.

Bootstrap a new Koog 1.0 Kotlin agent project from scratch: Gradle setup with the right dependencies, JDK 17 toolchain, application Main that constructs an AIAgent via the top-level factory, and an environment-variable wiring for the LLM API key. Use when the user asks to "create a new Koog agent", "start a Koog project", "scaffold an agent app", or provides a directory and says "set up Koog here". Produces a runnable hello-world agent that the user can extend with tools, strategies, or features. Do NOT use when the user is constructing a planner, picking a strategy variant, or naming a specific agent shape inside an existing project — use `use-planner` or `author-strategy` instead.

Snapshot a running Koog 1.0 agent's state at arbitrary points and restore later — distinct from the persistence checkpoint loop in `add-persistence`. Snapshots are caller-triggered; persistence is automatic and continuous. Use when the user asks to "snapshot the agent", "save state at this point", "restore from a snapshot", or names the `agents-features-snapshot` module.

Test Koog 1.0 agents deterministically — install `agents-test`, mock the prompt executor with scripted responses, inject a fake `KoogClock` for time-sensitive logic, and assert on tool-call sequences. Use when the user asks to "test the agent", "mock the LLM in tests", "write unit tests for my Koog agent", or describes flaky or expensive tests that hit a real LLM.

Install the `agents-features-trace` feature to capture detailed internal trace events from a Koog 1.0 agent — node entries, edge transitions, planner decisions, feature lifecycle. Distinct from OpenTelemetry (production signal, GenAI vocabulary) and event handlers (high-level callbacks). Use when the user asks to "debug what the strategy is doing", "trace internal agent decisions", "see why the planner picked that step", or describes deep diagnostic needs.

Send non-text content (images, files, audio) to the LLM as message attachments in a Koog 1.0 agent — provider-aware encoding and the `attachments` block in the prompt DSL. Use when the user asks to "send an image to the LLM", "use multimodal input", "attach a file", "pass a PDF", or describes input the LLM should process that isn't plain text.

Use `FunctionalAIAgent` — the third concrete agent subtype in Koog 1.0 (alongside `GraphAIAgent` and `PlannerAIAgent`). Wraps a single suspending block, no graph DSL, no planner — just programmer-written logic that calls the LLM and tools directly. Use when the user asks to "skip the graph DSL", "write the agent body as plain code", "use AIAgentFunctionalStrategy", or describes a one-shot agent shape that doesn't warrant a topology.

Use a non-default LLM node variant inside a Koog 1.0 strategy — streaming output, multiple-choice sampling, content moderation, or forcing a specific tool call. Use when the user asks for "streaming", "multiple completions / sampling", "moderation", "force one tool", "force the LLM to call a specific tool", or names any of `nodeLLMRequestStreaming`, `nodeLLMRequestMultipleChoices`, `nodeLLMModerateText`, `nodeLLMRequestForceOneTool`.

Pick and wire a planner-driven Koog 1.0 agent — either LLM-based (the LLM picks the next action each turn, optionally with a critic loop) or GOAP (a classical planner searches a typed state space toward a goal). Pulls `ai.koog:agents-planner`, constructs the planner strategy, and wires it into `AIAgent(...)`. Use when the user asks to "use a planner", "let the agent plan", "use GOAP", "build a planning agent", names any of `Planners.llmBased`, `Planners.llmBasedWithCritic`, `Planners.goap`, `PlannerAIAgent`, `agents-planner`, or describes an open-ended task whose step sequence depends on runtime context.

Wire the Agent-to-Agent (A2A) protocol — expose a Koog 1.0 agent as an A2A server, or consume a remote A2A server as a client (typically to make a remote agent callable as a tool by a local agent). Use when the user asks to "expose the agent via A2A", "use A2A protocol", "call a remote agent", "register an A2A client", or names any of `a2a-server`, `a2a-client`.

Expose a Koog 1.0 agent through the Agent Client Protocol (ACP) — the lower-level bidirectional protocol used by tooling that needs fine-grained control over agent invocation lifecycle (cancellation, streaming progress, multi-turn negotiation). Use when the user asks to "expose the agent via ACP", "use Agent Client Protocol", "wire ACP", or names the `agents-features-acp` module.

Expose a Koog 1.0 agent through a Ktor server — install the `koog-ktor` plugin, load agent configuration from `application.conf` / `.yaml`, and register MCP servers inside the plugin block. Use when the user asks to "expose the agent over HTTP", "add Koog to my Ktor app", "wire the Ktor plugin", or describes a server-shaped deployment.

Connect a Koog 1.0 agent to an MCP (Model Context Protocol) server, using the primary 1.0 Streamable HTTP transport — or fall back to SSE / stdio when the remote server doesn't speak Streamable HTTP yet. Adds the agents-mcp dependency, builds a ToolRegistry from the MCP server's exposed tools, and merges it with the agent's existing tool registry. Use when the user asks to "connect to an MCP server", "use the GitHub MCP server", "add MCP tools to my agent", "wire Playwright MCP" or similar. Assumes a scaffolded Koog 1.0 project.

Wire Koog 1.0 into a Spring Boot application via `koog-spring-boot-starter` — per-provider autoconfig, `MultiLLMAutoConfiguration` aggregation, and the `application.yml` shape for agent name, model, system prompt, and tools (including MCP entries). Use when the user asks to "use Koog in Spring Boot", "wire the Spring starter", "configure providers via application.yml", "add Koog to my Spring app".