Bundles

A bundle is an ordered list of artifact references. It is the unit you reuse as a prompt prefix: a system policy, a tool registry, and a response schema grouped together once, then attached to many sessions instead of re-sent on every request.

{
  "id": "bnd_01jy...",
  "object": "bundle",
  "bundle_type": "agent_prefix",
  "project_id": "prj_01jy...",
  "items": [
    { "artifact_id": "art_policy", "role": "developer" },
    { "artifact_id": "art_tools",  "role": "tools" },
    { "artifact_id": "art_schema", "role": "response_schema" }
  ]
}

Each entry pairs an artifact_id with a role that says how the artifact is used in the rendered prompt. The bundle references artifacts; it never copies their content, so the immutability of the artifacts carries through to the bundle.

Ordering is semantic

The order of items is part of the bundle's meaning, not a presentation detail.

This matters for two reasons:

1. Correctness. A developer policy that appears before the tool definitions reads differently from one that appears after. Reordering can change behavior.
2. Reuse. Provider prompt caching matches on prefixes. Putting stable content first and dynamic content last is what lets a provider reuse the front of the prompt. A reordered bundle is, for caching purposes, a different prompt with a different materialization. The reuse you were counting on disappears.

The recommended logical order places the most stable content first:

1. system policy
2. developer policy
3. stable tool bundle
4. response schema
5. stable tenant or workspace context
6. compacted checkpoints
7. ordered branch history
8. dynamic retrieval blocks
9. latest user input
10. latest tool result

Immutability

Like artifacts, bundles are immutable once created. To change membership or order, you create a new bundle and reference it going forward. The old bundle ID always describes exactly the list it was created with, which is what makes a bundle a stable, reusable prefix that the platform can fingerprint and track across requests.

Bundles in a session

A session carries base_bundle_ids: the bundles that form its stable prefix. The session then accumulates dynamic events on top. The bundle is the reused front of the prompt; the branch events are the changing tail.