Versions

Everything that shapes how an agent works has versions: the agent's settings, the mesh settings, playground changes, skills, API tools, Tools-page sources, knowledge and vault connections. Every run records which version of each it used, so you can always answer "what was true when this happened?"

Think of a restaurant recipe book:

• Default is the recipe on the menu. Every run uses it.
• Draft is a new recipe written in the notebook. It is kept, but nobody is served it.
• Try cooks one dish from the notebook, just for tasting. Customers keep getting the menu recipe.
• Make default puts a version on the menu. Every old recipe stays in the notebook, so going back is one step.

What gets a version

A new version is recorded whenever the content changes: a save in Studio, a change to config.yaml while the mesh was down, a skill updated in its store, an API spec re-uploaded, an MCP server that now offers different tools, a rotated key. Saving the same content again does not make a new version, and content identical to an older version brings that version back instead of a new number.

Versions never hold a secret: every credential-looking value is removed before a version is kept, and put back from what runs now when a version is made the default.

Every run records its versions

Each run's trace and output carry the versions it used, by name — for example Agent · support v3, API tools · shop v2 — and what moved since the agent's previous run ("API tools · shop v1→v2 (endpoints switched)"). An empty list means nothing changed.

What an agent learned keeps the versions it learned under. When it recalls an experience or a past run, it is told what has changed since — "Skill · refunds v4→v5 (skill text)" — so it checks that part again instead of repeating it blindly.

Save as draft or as default

A save is one of two kinds:

• Save as default — live now, as saving always was.
• Save as draft — kept as the next version; runs keep the default (POST .../drafts, below).

A draft is checked like a save: an agent draft that would not load is refused, naming the field.

Every version is kept, however many there are. The list is paged and searchable by number or by what changed, and each version shows how it differs from the default.

Try a version once

Before making a version the default, run it once:

1. Mark it for testing (one per item), or name it when you start the trial.
2. Try an agent: give it a task. The agent runs once, the normal way — its tools, its trace — with the marked versions of what it uses. Everything else stays on the default.
3. Read the result and its trace. The trace says it was a trial and which versions it tried, against the default each stands in for.
4. Make default if you like it — or leave it as a draft.

A trial is a tasting, not a second menu:

• Only that one run uses the tried versions. A schedule, a channel message or a hand-off running at the same moment uses the default.
• It stops at the agent's answer. Nothing is handed to the next agent and nothing goes on the board, so a trial never starts real work further along.
• Nothing is learned from it. A bad version never teaches the agent.
• The next real run is compared with the previous real run, never with the trial.

Side by side

A trial is a real test. Run the same task on the default as well (compare), or run a small set of up to 10 tasks, each on the candidate and then on the default. Every run reports what it took:

• time
• tokens in and out
• model calls
• cost
• tool calls, by name

Each set gets a summary per side. Every trial is kept, so a test can be read and compared later. You can also run the default on its own as a baseline, in the same isolated way.

What can be tried in one run:

Making a version the default and going back are each one step, so mesh settings are tried by switching and, if needed, switching back.

Make any version the default

Pick any version and make it the default. It goes through the same save as editing the item by hand — the same checks, applied live, and you are told if a setting needs a restart. Going back to an older version reuses its number.

Knowledge (the documents live in your vector store) and connections (old keys are never kept) cannot be switched to an older version.

API

kind is one of agent_config, mesh_config, mesh_yaml, host_settings, playground, skill, api_tools, tool_entry, knowledge, connection, model. A skill's name is <source>/<skill>; a Tools-page source's is <type>:<name> (mcp:github). Without versions, a trial uses the versions marked for testing among the things the agent uses.