bundle-format.mdx

Layout

Odyssey bundles are now multi-agent OCI payloads built from a filesystem layout like this:

<project>/
  odyssey.bundle.yaml
  README.md
  agents/
    <agent-id>/
      agent.yaml
      module.wasm
      src/
        ...
  skills/
  shared/
  resources/

odyssey.bundle.yaml describes the bundle as a whole. Each agents/<agent-id>/agent.yaml describes one selectable agent component. Bundles can also package skills/, resources/, and other shared assets. A runtime run always resolves bundle_ref + agent_id.

Bundle Descriptor

Minimal example:

apiVersion: odyssey.ai/bundle.v1
kind: AgentBundle
metadata:
  name: odyssey-agent
  version: 0.1.0
spec:
  abiVersion: v3
  agents:
    - id: odyssey-agent
      spec: agents/odyssey-agent/agent.yaml
      module: agents/odyssey-agent/module.wasm
      default: true

Important fields:

Field	Description
apiVersion	Must be odyssey.ai/bundle.v1
kind	Must be AgentBundle
metadata.name	Bundle identifier
metadata.version	Bundle version
spec.abiVersion	WASM agent ABI version understood by the runtime
spec.agents[].default	Marks the default selectable agent entry
spec.agents[]	Agent entries with id, spec, and optional module

Agent Descriptor

Minimal WASM agent:

apiVersion: odyssey.ai/v1
kind: Agent
metadata:
  name: odyssey-agent
  version: 0.1.0
spec:
  kind: wasm
  abiVersion: v3
  prompt: |
    You are Odyssey Cowork, a powerful assistant to help the user. You are built by LiquidOS.
  program:
    runner_class: wasm-component
    entrypoint: agents/odyssey-agent/module.wasm
  execution:
    memory: session-window/v1
  requires:
    features:
      - streaming

Important fields:

Field	Description
spec.kind	prompt or wasm; new runtime work targets wasm
spec.abiVersion	WASM agent ABI version
spec.prompt	Runtime-owned base prompt
spec.program.runner_class	Runner class, currently wasm-component for WASM agents
spec.program.entrypoint	Relative path to the WASM agent module
spec.execution.executor	Executor class, currently react/v1
spec.execution.memory	Memory class such as session-window/v1
spec.tools.require[]	Tool ids or names the agent expects to have available before permission rules apply
spec.policyHints.*	Isolation and side-effect hints used by the runtime

Runtime Model

The bundle stores portable behavior and static assets. The runtime still owns:

• model calls
• tool execution
• memory hydration
• approvals
• event streaming

The WASM agent module runs the AutoAgents loop internally and talks to Odyssey through host bindings for LLM access, tool calls, and emitted events. The runtime also passes the resolved host tool catalog for the selected agent, so agent code can use the same built-in tool set declared in agent.yaml without re-declaring those tools in Rust source.

Validation Rules

• odyssey.bundle.yaml must exist and remain inside the project root.
• Every referenced agents/<id>/agent.yaml must exist.
• WASM agents must declare a non-empty program.entrypoint.
• Relative paths must stay inside the bundle root; path escapes are rejected.
• The selected agent must exist when a session is created.
• module.wasm is runtime-loaded exactly from the normalized descriptor path.
• The component ABI must match the runtime-supported Odyssey WASM ABI version.

Current Runtime Limits

• The embedded runtime executes one selected agent per run, even though a bundle can package many.
• session-window/v1 is the practical memory class today.
• WASM agent modules are invoked directly by the Odyssey runtime through the Odyssey host ABI.