Give an agent a tool

A tool is its own sandboxed component, with its own grants: a folder, a list of hosts, or neither. This guide adds a tool to an agent and grants it what it needs, first in Cosmonic Desktop and then in a Cosmonic Control workload. The agent harness never gets the tool's grants; it reaches the tool only through the host.

For why tools are separate components, see Tools.

In Cosmonic Desktop

In Desktop, tools belong to a session, not to the agent. You add them when you start a session, or the agent finds them in your tool catalog while it works. Any agent whose harness imports cosmonic:agent/tools can take them.

Add a tool to a new session

1. On the Agents page, select New and choose the agent.
2. Under the message box, select Tool settings…, then Add tools yourself….
3. In Search tools, find the tool and select Add. Each tool's card says what it reaches, such as a host it calls or a folder it reads.
4. Select Done, type your first message, and select Start session with 1 tool.

Grant a folder

Desktop's folder tools (Workspace (read), Workspace (write) and git) work in one folder you choose. Choose it with the folder chip under the message box, which shows No folder until you pick one:

1. Select the folder chip, then Choose a folder…, and pick the folder.
2. Select the access chip next to it, and choose how much the tools may do there:
   • Read only: tools can read files in the folder.
   • Edit with undo: changes apply as they happen, and you can undo any of them in the session panel.
   • Ask before each edit: each change waits for you.

Desktop adds the folder tools that match: Workspace (read) always, git when the folder is a git repository, and Workspace (write) unless you chose Read only. Each tool sees that folder and nothing outside it. Only you choose folders: an agent that asks to add a folder tool always waits for you.

A tool added in Add tools yourself… that reads a folder asks which one: select Use and a recent folder, or Choose another folder….

Control which hosts a tool reaches

A tool's hosts are part of its catalog entry. Its card shows them, and it can reach those hosts and no others. You choose whether its first request to each host waits for you:

• For one session: in Tool settings…, turn on Ask first before a tool reaches each host before you start. Once the session is running, the Network access dropdown in its header switches between Asks before new hosts and Listed hosts allowed.
• For new sessions: in Settings, open Sandboxed agents under Agent workspace, and use the Ask first before a tool reaches each host switch in the Agent sessions card. It is off by default.

Hosts you allow appear under Allowed hosts in the session details panel, each with Revoke. Hosts a tool does not list stay blocked either way.

Let the agent add tools

With Let the agent find tools on in Tool settings… (the default), the agent can search your catalog and ask to add a tool. Desktop shows what the tool reaches and the agent's reason, and adds it only if you select Allow. If you turn off Ask before adding each tool, tools from your catalog are added without asking, except one that needs a folder or opens its own connections.

To decide per tool, open Settings, then Tools, and set Who decides for each tool to Ask each time, Allow without asking or Never offer to agents.

Add your own tool to the catalog

1. Open Settings, then Tools, and select Add a tool.
2. Choose where it comes from: Image (an OCI image pinned by its digest), Component file, or Remote MCP server.
3. For an image or file, list Hosts it may reach (leave it empty for no network), and check It reads a folder you choose for each session if it needs a folder. For a typed tool, add its WIT package so agents get its descriptions.
4. Select Review, check what it reaches, then select Add tool.

The form takes a typed tool, a tool provider (a component that exports cosmonic:agent/tools), an MCP server built as a component, or a remote MCP server that needs no sign-in. Write a typed tool walks through adding one.

Check what a session can reach

Select Show session details in the session header. This session can… lists each kind of reach (Change files in a folder, Read a folder, Reach hosts) with the tools that grant it. Select a tool to see its calls.

On Cosmonic Control

A tool image on Control must be a typed tool: a component that exports its own interfaces and nothing from cosmonic:agent. Control refuses an image that exports cosmonic:agent/tools, such as ghcr.io/cosmonic/agents/tools.

On Control, the workload spec decides an agent's tools, and the spec is the approval. Tools are components in the agent's own workload, each with its own grants. There is no discovery on Control yet.

Add tool components

Add each tool as a component of the workload, and name it in tool-components on the tools entry:

spec:
  template:
    spec:
      hostInterfaces:
        - namespace: cosmonic
          package: agent
          interfaces: [tools]
          version: 0.4.1
          name: cosmonic-agent-tools
          config:
            components: agent
            tool-components: github, wikipedia
      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:… # your tool's image
          localResources:
            allowedHosts:
              - api.github.com
        - name: wikipedia
          image: ghcr.io/example/tools/wikipedia@sha256:…
          localResources:
            allowedHosts:
              - en.wikipedia.org

• tool-components lists the components whose exported functions become tools. Control serves typed tools only: components that export their own interfaces and nothing from cosmonic:agent.
• Grant hosts on the tool, not the agent. Each tool's allowedHosts is its own. The agent keeps allowedHosts: [].
• To offer only some functions, add tool-functions: 'github: list-pulls, get-pull'. To rename one for the model, add tool-aliases: 'wikipedia: search=wiki_search'.

Every value in config is a string. Lists are comma separated, and per-component values are written component: items; component: items.

Grant a folder

Mount a volume into the tool component alone, read only unless it needs to write. See Mount a volume for the volume fields.

volumes:
  - name: notes
    ephemeral: {}
components:
  - name: notes-reader
    image: ghcr.io/example/tools/notes-reader@sha256:…
    localResources:
      volumeMounts:
        - name: notes
          mountPath: /workspace
          readOnly: true

Give a tool its own store

A tool that keeps state between calls needs its own store. Name it in tool-components on the session entry as well:

- namespace: cosmonic
  package: agent
  interfaces: [session]
  version: 0.4.1
  name: cosmonic-agent-session
  config:
    components: agent
    tool-components: notes-reader

A tool never gets the conversation: the host refuses a tool that is granted the agent's session.

Apply the changed spec with kubectl apply. A change to an agent's tools is a new revision of its workload.

Related

• Agent workload reference lists every key on the tools and session entries.
• Capabilities explains why the grant is the boundary.