In Koog, what does a PromptExecutor do, and how does MultiLLMPromptExecutor differ?

## The three pieces Koog keeps separate Koog deliberately splits *what you say* from *which model* from *how you reach it*. A `Prompt` is an immutable, typed list of messages. An `LLModel` is a value object naming a provider, a model id, and the capabilities that model declares. An `LLMClient` is the provider-specific adapter that knows one vendor's HTTP API. `PromptExecutor` is the interface that ties all three together, and it is the only one of them that most of your code touches. You hand an executor a prompt, a model, and optionally the descriptors of tools the model may call; it suspends and returns the model's response messages. There is also a streaming form that returns a Flow so you can push tokens to a client as they arrive, and moderation support on providers that offer it. ## The client layer underneath Concrete clients include `OpenAILLMClient`, `AnthropicLLMClient`, `GoogleLLMClient`, `OllamaClient` and `OpenRouterLLMClient`. Each one owns credentials, base URL and HTTP settings, converts Koog's typed messages into that vendor's request shape, and converts the reply back into Koog's message types. That conversion is where provider differences are absorbed: system-message handling, tool-call encoding, and structured-output mechanics all differ between vendors, and the client is what makes them look the same upstream. ## Single versus multi provider `SingleLLMPromptExecutor` wraps exactly one client. It is the right default: one provider, one key, no routing logic. If you pass it a model belonging to a different provider, the call fails — Koog does not quietly substitute anything, and that strictness is deliberate, because a silent substitution would change cost, latency and capability behind your back. `MultiLLMPromptExecutor` is built from provider-to-client pairs and selects the client for each call from the model you passed. This is what makes per-call model choice real: a cheap small model for classification and routing, a large model for the final synthesis step, a local Ollama model in tests, all through one injected dependency. Convenience builders such as `simpleOpenAIExecutor`, `simpleAnthropicExecutor` and `simpleOllamaAIExecutor` exist for the one-provider case so demos and tests stay short. ## Capabilities are part of the model, not the executor Because `LLModel` carries declared capabilities — tool calling, structured/JSON schema output, vision and so on — Koog can reject an incompatible combination early rather than letting a tool-using agent silently degrade into a chat-only model that never calls anything. Model constants are provided per provider (for example `OpenAIModels` and `AnthropicModels` objects) so you are not typing model id strings by hand, though you can construct an `LLModel` yourself for a model Koog does not ship a constant for. ## What the abstraction buys Provider portability is the obvious win: swapping vendors is a change to executor construction, not to your strategy, tools or prompts. Beyond that, a single choke point for every model call is exactly where you want retry, caching, rate limiting, token accounting and tracing to live. Testing benefits most of all — a fake `PromptExecutor` that returns canned responses lets you test an agent's control flow with no network and no key. ## What it costs An abstraction over five vendors is necessarily close to a lowest common denominator: a provider-specific knob Koog does not model is not reachable through it, and you may need to configure it on the client or drop to the client directly. Capability drift is the practical failure mode — the same prompt against two providers can produce different tool-calling behaviour or different adherence to a JSON schema, so "we can swap providers" is true at the API level and only partly true at the behaviour level; you still re-evaluate. Also remember the executor is stateless. It does not accumulate conversation history for you: history lives in the `Prompt` you build and pass. Anything long-lived — sessions, memory, checkpoints — is a separate concern layered on top. ## Where it sits in an agent An agent is constructed with an executor and a model, and every model-calling step in it goes through that executor. So in a production service the executor is usually a single injected singleton, configured once with keys and timeouts, wrapped with whatever cross-cutting behaviour you need, and shared by every agent and every one-shot prompt call in the process.