Anatomy of an agent

When people say "agent," they usually mean the entire agentic experience: the user gives a task to an entity that thinks, uses tools, and responds.

Under the hood, that experience is made up of several distinct parts. The Cosmonic Agent SDK gives developers the core building blocks and typed interfaces for composing agents out of separate sandboxes. This page defines the pieces that make up the agentic experience and walks through what happens when you send an agent a message.

What is an agent harness?

The agent harness is the control loop at the center of an agent: it sends the conversation to a model, runs the tools the model asks for, feeds the results back, and repeats until it has an answer. It also owns the prompts, how history is handled, and when older context gets summarized.

The harness is the part you write, or the part you take from a framework such as Goose or Codex. It does not include the model, the tools, or the storage for the conversation. Those live elsewhere, which is the whole point.

The host

The host is the runtime that runs the harness and its tools, much as a container runtime runs containers. In Cosmonic Desktop the host is the daemon on your machine. In Cosmonic Control, hosts run as pods in your Kubernetes cluster.

The host is the only part with real access to anything. It holds the model credentials, keeps the conversation, decides which tools a session can use, and checks every request a tool makes against what that tool was granted.

Components and workloads

The harness and each tool are built as components: small WebAssembly programs that start with no files, network, environment, or credentials. A component can only use what the host grants it. Components are pushed to and pulled from OCI registries, like container images.

A workload is a group of components the host runs together, with its own memory and its own grants. In Desktop, each agent session is its own workload: the harness plus the session's active tools.

The host makes every model call

The model is the language model that reads the conversation and decides what to say or which tool to call. It never runs inside the sandbox.

The harness asks for a model by a short name, such as default or fast, called an alias. The host looks up what that alias means for this workload: which provider, which model, which endpoint and which credential. Then the host makes the call and streams the reply back.

The harness never sees an endpoint or a key. That has a few consequences:

• A tricked harness cannot leak a key it never had. Prompt injection can change what a harness tries to do, but there is no credential in its memory or environment to send anywhere.
• The harness cannot pick its own provider. It cannot point itself at an endpoint you did not configure, because it has no network and only names aliases.
• You can change models without changing code. Point an alias at a local model on your laptop and at a hosted model in production, and the same harness runs on both.
• Every model call can be metered and recorded. The host sees each request, so it can count calls, tokens and spend, and apply budgets.

This is similar to how a serverless platform hands a function a database binding instead of a connection string: the function uses the resource, and the platform owns the credential.

Tools

A tool is a component the harness can call through the host, such as a web fetcher, a search over one folder, or a GitHub reader. Each tool gets its own reach, separate from the harness and from every other tool. See Typed tools for how a component becomes a tool.

Every arrow out of the harness goes through the host. The harness has no direct path to the model provider, the network, your files, or the tools themselves.

What happens in a run

A run is one message and everything the agent does to answer it. Chat apps call this a turn. A run is usually several model calls with tool calls between them, and it ends when the harness has its reply or stops.

Whatever starts the run is the driver. In Desktop, the driver is the chat window. In Control, a run can start from an HTTP request in the OpenAI Responses API format or from a NATS message.

Here is one run, where someone asks about open issues in a repository and the session has a GitHub tool:

A few things to notice:

• The run never names a session. The host chooses which conversation a run works in and binds it, so a driver cannot point a harness at someone else's conversation.
• Everything is recorded as it happens. The harness writes each step to the session through the host, so a run that fails halfway still shows what was asked and what was done. Sessions explains the journal.
• One run at a time per session. Two runs in one conversation would interleave it, so the driver serializes them.
• Approvals happen at the host. When a step needs approval, such as a tool's first request to a host in Desktop, the host holds it until you decide. The harness only sees the result, or a denial. It never receives or answers an approval itself, so it cannot fake one.
• A run has limits. The driver can cap the steps, tokens and time a run may use, so a runaway loop ends with a reply instead of running forever.

How an agent finds and adds tools

A session does not have to start with every tool it might need. A host can let the harness find tools and ask for them while it works. Desktop does this by offering the model two tools of its own, find_tools and load_tools, next to the session's other tools. This is a host feature: to the harness, they are ordinary tool calls.

The new tool arrives on the agent's next run, not partway through the current one. In Desktop you approve tools as they are added, unless your settings allow them automatically. Some things always ask, such as a tool that reads or changes a folder, because only you choose folders.

The important property is that finding a tool grants nothing. The harness can ask for anything in the catalog, but only the host adds a tool, and in Desktop only after you approve it or your settings allow it.