Mount

A mount defines workspace-level cloud storage configuration. It is not a tool runtime — it is shared infrastructure that multiple parts of the system use to read and write persistent data.

When an agent has a non-none mount scope, the following features become available:

• Template variables — {mount.bucket}, {mount.prefix}, {mount.backend} are available for {expression} interpolation in all tool runtime execute blocks (HTTP URLs, headers, bodies, MCP config, etc.) and agent bindings.
• CEL I/O functions — mount.read() and mount.write() are available in CEL tool expressions.
• LLM file references — the file() function becomes available in the LLM capability script environment, allowing the LLM to reference files in mount storage without exposing their raw contents.
• Multimedia output — when model_capabilities includes image-generation, audio-generation, or video-generation, the runtime writes LLM-generated media to mount storage. Agents with these model capabilities require a non-none mount.

Schema

name: str

path_prefixes:
  workspace: str       # e.g. "/{namespace}/"
  agent: str           # e.g. "/{namespace}/{agent}/"
  task: str            # e.g. "/{namespace}/{agent}/{task}/"

# Exactly ONE backend must be specified:
gcs:
  bucket: str
  sa: str | None       # Service account for workload identity

s3:                     # STUB — not implemented in this release
  bucket: str
  profile: str | None
  region: str | None

Fields

1. name — Identifies this mount within the workspace.
2. path_prefixes — Templates for each scope level. The runtime substitutes {namespace}, {agent}, and {task} tokens during resolution. The resolved prefix is exposed as mount.prefix based on the agent's mount scope.
3. Backend — Exactly one backend block must be specified.

Scope Resolution

The agent's mount field (none, task, agent, workspace) determines which path_prefixes template is used to compute mount.prefix:

Agent mount value	mount.prefix source	Example result
none	N/A — mount features not available	—
task	path_prefixes.task	/myworkspace/coder/abc123/
agent	path_prefixes.agent	/myworkspace/coder/
workspace	path_prefixes.workspace	/myworkspace/

Template Variables

When the agent's mount scope is non-none, the following variables are available in {expression} interpolation in all tool execute blocks (URLs, headers, bodies) and in agent/middleware bindings:

Variable	Type	Description
mount.bucket	string	The resolved bucket name from the workspace mount
mount.prefix	string	The scoped prefix (evaluated from agent's mount field + mount path_prefixes)
mount.backend	string	Backend type: "gcs" or "s3"

These variables allow any tool runtime (HTTP, stateful session, MCP, etc.) to connect to the agent's storage. For example, an HTTP tool can target a cloud storage API using {mount.bucket} and {mount.prefix} in its URL.

CEL I/O Functions

When the agent's mount scope is non-none, the following functions are available in CEL tool expressions:

Function	Description
mount.read(path)	Reads a file relative to mount.prefix. When the returned handle is part of the action result it is delivered to the model as an attachment on the next request.
mount.write(path, content)	Writes content to a file relative to mount.prefix. Returns the written content.
mount.list()	Lists the files under mount.prefix as sorted file:{name} reference tokens — including files the user uploaded to the task and files produced in earlier turns.

These functions are only available in CEL tool expression fields — not in middleware, bindings, or guardrails. Paths containing ../ are rejected.

LLM File References

When mount is configured, the file(path) function becomes available in the LLM capability script environment. This allows the LLM to reference a file in mount storage without its raw contents being inlined into the conversation.

# LLM-authored capability script — pass a file to a tool
post_attachment({"file": file("reports/summary.pdf")})

The LLM sees a summary description of the file (e.g., report.pdf (application/pdf, 1.2MB)) rather than the binary content. The reference can be passed as a capability argument so that tools can operate on the file directly. See CEL Reference.

Multimedia Output

Model capabilities that produce binary output (image-generation, audio-generation, video-generation) write their generated media to mount storage automatically. The runtime:

1. Writes the media to the agent's scoped mount prefix.
2. Returns a storage URI and content metadata to the task as a content part.

Agents with multimedia model capabilities must have a non-none mount scope.

Examples

Workspace mount configuration

name: default
path_prefixes:
  workspace: "/{namespace}/"
  agent: "/{namespace}/{agent}/"
  task: "/{namespace}/{agent}/{task}/"
gcs:
  bucket: my-company-agents
  sa: agentmesh@my-project.iam.gserviceaccount.com

Agent using mount with bindings

kind: commonagents.info/v1beta2/agent
namespace: engineering
name: coder
mount: task  # mount.prefix = /engineering/coder/{task}/

capabilities:
  code-search:
    bindings:
      bucket: "{mount.bucket}"
      prefix: "{mount.prefix}"

In this example, code-search receives bucket: "my-company-agents" and prefix: "/engineering/coder/abc123/" as deterministic bindings. The code-search tool can use these in any runtime — HTTP, MCP, etc.

Memory tool using CEL mount functions

kind: commonagents.info/v1beta2/tool
namespace: default
name: memory
description: Key-value memory for agents, persisted to mount storage.

actions:
  - name: write
    description: Save a key-value pair to persistent memory.
    parameters:
      type: object
      properties:
        key:
          type: string
        value:
          type: string
    execute:
      cel:
        expression: >
          mount.write("_memory/" + input.key, input.value)

  - name: read
    description: Read a value from persistent memory by key.
    parameters:
      type: object
      properties:
        key:
          type: string
    execute:
      cel:
        expression: >
          mount.read("_memory/" + input.key)