Skip to main content

Saved agent versions

Keep one logical agent while its reusable instruction evolves. A frozen execution creates a compilation. That compilation is a saved version; the agent's live pointer chooses the version used when a caller names only the agent.

Release candidate

This guide describes the saved-version and live-pointer candidate contract. Check that your MCP client lists save_instruction_version and set_live_version, or that your installed SDK has the corresponding client.compilations methods.

Freeze an accepted run​

First test the agent and choose an execution that completed the intended work. Use freeze_agent with that execution's public ID. Keep the returned integer compilation ID and poll get_compilation until its status is compiled or completed. A pending ID is a build request, not a ready instruction.

A successful freeze makes its version live. Input schemas, variable placeholders and the frozen context belong to that version; provide future variable values when running it. See Create, freeze, and embed one agent for the full freeze and integration workflow.

Save and test an edit​

Use list_compilations with agent_id to list the saved versions. Each includes is_live, name, note and source_compilation. The app's Saved versions control lets you inspect versions from a chat.

save_instruction_version saves edited Markdown as a new compilation and preserves the source. Supply the source compilation explicitly when editing an older version. The edit keeps its frozen context, including pinned subagents. A Team version must be changed by freezing its Team run again.

By default the edit stays beside the live version, so existing callers continue using the live one. If the agent has no live version, its first saved instruction becomes live. make_live: true explicitly selects the edit immediately. Saving the same text, name and note from the same source again returns the existing version.

Test a candidate with run_frozen and its compilation_id. Each new intentional run needs a new operation_key; an identical retry reuses its original key. Review the result before changing the live pointer.

Choose the live version or roll back​

set_live_version takes the integer ID of a runnable compilation owned by your agent. Choosing an older version is a rollback. run_frozen with agent_id and no compilation ID follows the live pointer; naming a compilation keeps that run pinned to that version.

A schedule on the previous live version follows the newly selected version. Active private deployments follow it too. Other deployments receive the candidate staged for publication. Inspect the returned deployments results for errors or required publication rather than assuming every surface changed immediately.

Python example​

from flymyai import AgentClient

client = AgentClient(api_key="YOUR_API_KEY")
versions = client.compilations.list(agent_id="YOUR_AGENT_UUID")
source = client.compilations.get_live("YOUR_AGENT_UUID")
candidate = client.compilations.save_instruction(
    execution_id="SOURCE_RUN_ID",
    source_compilation_id=source.id,
    instruction_md="Your reviewed instruction Markdown",
    name="Handles missing input",
    note="Review the candidate before making it live",
    make_live=False,
)
# Test candidate.id explicitly, then select it after reviewing the result.
live = client.compilations.set_live(candidate.id)

Use an execution from the same agent and check for a missing live source before this example. An agent UUID, execution public ID and integer compilation ID are different identifiers. Saving or choosing a version does not create another agent.