Agent workload reference

An agent runs in a workload: the agent harness component, any tool components, and hostInterfaces entries that grant each cosmonic:agent interface to the components that may use it. This page lists those entries and their config keys.

In Cosmonic Desktop, Desktop writes the workload for each session; you don't apply it yourself. On Cosmonic Control, you write it, as a Workload or WorkloadDeployment (runtime.wasmcloud.dev/v1alpha1), and the spec is the approval.

Entry fields

Each cosmonic:agent entry in spec.hostInterfaces:

Field	Value
`namespace`	`cosmonic`
`package`	`agent`
`version`	A 0.4.x version. Desktop writes `0.4.0`; Control's examples use `0.4.1`. A component built against any 0.4.x links to it.
`interfaces`	The interfaces this entry serves. One plugin serves each group below, so each group is its own entry.
`name`	Optional. A workload may have one unnamed `cosmonic:agent` entry; name the others (see each entry).
`config`	String keys and string values. Lists are comma separated.
`secretFrom`	Optional. Secrets whose keys are merged into `config` (Control).

Every value in config is a string. Per-component values are written component: items; component: items, for example github: list-pulls, get-pull; wiki: search.

The key components means the same on every entry: the components the entry is granted to, comma separated. Only those components are linked to the interface, and an entry that names none grants none.

Session

Grants session: the conversation journal and working state.

Interfaces	`session`
Name	`cosmonic-agent-session` on Control when another `cosmonic:agent` entry is unnamed

Key	Host	Meaning
`components`	Desktop, Control	The components that work in the workload's conversation, usually `agent`.
`tool-components`	Desktop, Control	Tool components that each get a store of their own. A tool never gets the conversation.

On Control, an entry with neither key is refused. The conversation is scoped to the namespace and WorkloadDeployment, shared by its replicas.

Inference

Grants models and chat (and the inference-types they use): models by alias.

Interfaces	Desktop writes `inference-types`, `models`, `chat`; Control's examples use `models`, `chat`
Name	None for the entry that answers every alias. On Control, a name makes the entry answer only the alias it names.

Key	Host	Meaning
`components`	Desktop, Control	The components that may open models and chat.
`backend`	Desktop, Control	The model source, by name. On Control, `source` is the same key.
`source`	Control	The model source, by its `name` in `agents.models.sources`. Optional when the host has one.
`model`	Desktop, Control	A model of that source. Without it, the source's default model.
`max-requests`, `max-tokens`	Desktop, Control	Narrow the source's limits for this workload. Never raise them.

The endpoint and the key belong to the host. Keys such as base-url, url, endpoint, api-key, key, token and authorization are refused.

Tools

Grants tools: the tools the host lists and calls for the agent.

Interfaces	`tools`
Name	`cosmonic-agent-tools` on Control when another entry is unnamed

Key	Host	Meaning
`components`	Desktop, Control	The agent components granted `tools`. Required on Control.
`tool-components`	Control	Components of the same workload whose exported functions are the tools. Without it, no tools.
`tool-functions`	Control	Per tool component, the functions offered. Without it, every function.
`tool-aliases`	Control	Per tool component, renames for the model, such as `wiki: search=wiki_search`.
`toolsets-selection`	Desktop	`approved`: the session's tools are the ones the person approved for it. Written by Desktop.
`toolsets-profile`	Desktop	A profile name from the operator's `toolsets.yaml`.

On Control, tool components must be typed tools: components that export their own interfaces and nothing from cosmonic:agent. Each keeps its own localResources (allowedHosts, volume mounts) and its own instance pool. A tool call has a 30-second deadline.

In Desktop, a session's tools are components of its workload, each with its own grants. Changing them is a new revision.

Run

Grants the host's driver the agent's run export. Exporting run gives the agent nothing.

Interfaces	`run`
Name	`cosmonic-agent-run` on Control when another entry is unnamed

In Desktop, you never write this entry. Desktop adds it when a session starts, and refuses a manifest that names run.

On Control:

Key	Required	Meaning
`components`	yes	The component whose `cosmonic:agent/run@0.4.x` export the triggers call.
`triggers`	yes	`http`, `nats`, or `http,nats`. The host must have each trigger turned on.
`max-duration-secs`	no	A run's default and longest wall-clock time, 1 to 3600 seconds. Default 600.
`host`	no	An extra `Host` header the HTTP trigger answers.
`auth-token`	no	A bearer token every HTTP request must carry, at least 16 bytes. Supply it with `secretFrom`.

A workload that also serves wasi:http cannot take the HTTP trigger.

Components and placement

Field	Value
Agent component name	Any name the entries' `components` key uses. Desktop names it `agent`.
Agent `localResources.allowedHosts`	`[]`. The host makes model calls, so the agent needs no egress.
Tool `localResources.allowedHosts`	The hosts that tool calls, and no others.
`hostSelector` (Control)	`cosmonic.io/agents: 'true'`, the label hosts with agent support set on themselves.
`image`	Pin by digest (`@sha256:…`) in production. Desktop pins agent and tool images by digest itself.

Example (Control)

apiVersion: runtime.wasmcloud.dev/v1alpha1
kind: WorkloadDeployment
metadata:
  name: research-agent
  namespace: default
spec:
  replicas: 1
  template:
    spec:
      hostSelector:
        cosmonic.io/agents: 'true'
      hostInterfaces:
        - namespace: cosmonic
          package: agent
          interfaces: [models, chat]
          version: 0.4.1
          config:
            components: agent
            source: openai
        - namespace: cosmonic
          package: agent
          interfaces: [tools]
          version: 0.4.1
          name: cosmonic-agent-tools
          config:
            components: agent
            tool-components: github
        - namespace: cosmonic
          package: agent
          interfaces: [session]
          version: 0.4.1
          name: cosmonic-agent-session
          config:
            components: agent
        - namespace: cosmonic
          package: agent
          interfaces: [run]
          version: 0.4.1
          name: cosmonic-agent-run
          config:
            components: agent
            triggers: http,nats
      components:
        - name: agent
          image: ghcr.io/cosmonic-labs/components/minimal-agent:0.3.1
          localResources:
            allowedHosts: []
        - name: github
          image: ghcr.io/example/tools/github@sha256:…
          localResources:
            allowedHosts:
              - api.github.com

Host settings (Control)

These HostGroup chart values must be set for the entries above to work. Run an agent on Cosmonic Control walks through them.

Value	Meaning
`agents.enabled`	Turns on the agent plugins and labels hosts `cosmonic.io/agents: "true"`.
`agents.models.sources`	The model sources: `name`, `baseUrl`, `defaultModel`, `models`, `existingSecret`, `limits`, `features`.
`agents.sessions.storage.key.existingSecret`	`name`, `key` and `namingKey` of the Secret that encrypts sessions. Required for `session`.
`agents.sessions.storage.backend.nats`	The JetStream KV bucket (`bucket`, default `cosmonic-agent-sessions`), `replicas`, `maxBytes` and `credentials`.
`agents.run.http.enabled`, `agents.run.nats.enabled`	Turn on the HTTP and NATS triggers. Both off by default.
`agents.run.nats.subjectPrefix`	The NATS subject prefix. Default `cosmonic.agents`.

cosmonic:agent interfaces lists the functions each entry grants.
Security model and limits explains the boundaries these grants enforce.

Entry fields​

Session​

Inference​

Tools​

Run​

Components and placement​

Example (Control)​

Host settings (Control)​

Related​