Versions and lifecycle

Every Agent has immutable, monotonically numbered Versions and a separate active or disabled lifecycle status. Use Versions to audit or select configuration, and disable an Agent when you must stop new work without deleting it.

How Versions are created

Agent creation writes Version 1. For a tenant-managed Agent, every accepted ordinary update atomically advances the number and stores the complete resulting update document as the next Version, even when the submitted value matches the current value. The platform writes the Admin Agent's Versions.

Versions are read-only: there is no draft, publish, direct Version update, or Version deletion. For a tenant-managed Agent, avatar operations and the enable and disable verbs do not create Versions.

Latest resolution and Version Pins

For chat and stateless generation, an unpinned request resolves the Agent's latest Version when its Turn is admitted. A caller can set a Pin when creating a Session, on a Task definition, or on one stateless generation call. A Session row stores its immutable configured Pin or null; later Turns cannot override a Pin, while an unpinned Session continues to resolve latest. A Task's optional Pin is mutable through Task update. When a Task run is enqueued, Blazing Agents resolves that Pin or the then-current latest Version and stores it on the Task run, so later Agent updates cannot affect a queued run.

The Version actually resolved is recorded in per-Turn usage and on every Task run. A Session records only its nullable configured Pin, not each Turn's resolved Version.

The Admin Agent is platform-managed. Tenants can list and get its Versions and create Sessions with a Version Pin, but cannot update or restore it, disable or enable it, delete it, change its avatar or MCP attachments, or assign it to a Task. Rejected mutations return ADMIN_AGENT_MANAGED.

Inspect and restore a Version

Version lists are newest first and cursor-paginated, with a default page size of 50 and maximum of 200. Get retrieves one numbered Version. For a tenant-managed Agent, restore copies that Version's stored fields through the ordinary Agent update path; it creates a newer Version and never rewrites history. The Admin Agent's Versions can be inspected but not restored.

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({
  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});
const agentId = process.env.AGENT_ID!;

const page = await client.agents.listVersions(agentId, { limit: 10 });
const versionNumber = page.data[0]?.version;
if (!versionNumber) throw new Error("No Agent Versions found");

const inspected = await client.agents.getVersion(agentId, versionNumber);
const restored = await client.agents.restoreVersion(
  agentId,
  inspected.version
);

if (restored.version <= inspected.version) {
  throw new Error("Restore did not create a newer Version");
}
console.log(`${inspected.version} -> ${restored.version}`);

Enable and disable an Agent

A tenant-managed Agent's status is active or disabled. The idempotent disable and enable methods change only operational status and are reversible; they do not create a Version. A disabled Agent rejects every newly admitted Turn with AGENT_DISABLED and HTTP 409. It can still be read, updated, inspected, restored, or deleted. The Admin Agent remains active and cannot be disabled or enabled by a Tenant.

Effects on Sessions, Tasks, and in-flight work

Disabling preserves Sessions, Task definitions, schedules, and history, but blocks Session resumes, stateless generation, manual Task runs, and Tool-approval continuations. A Turn already in flight finishes.

Scheduled fires while the Agent is disabled are skipped without a Task-run row, and schedules are not paused or rewritten. After enable, the next eligible fire can run. See Tasks and schedules and Generation and streaming for those execution paths.

Snapshot boundaries

A Version captures Agent-authored configuration: name, model, providerId, historical sandboxId, Memory injection setting, Skill IDs, Tool groups, instructions, metadata, and MCP Connection IDs. It does not capture Attribution userId, avatar, status, timestamps from the current Agent, or a copy of referenced resources.

Provider credentials, Skill content, MCP Connection state, and Memories remain live. Execution always uses the Agent's current Sandbox, even when a historical Version recorded a different sandboxId. A Version is therefore an audit and configuration selection boundary, not a deploy artifact or hermetic runtime snapshot.

See Usage and quotas for per-Turn metering and quota behavior, and Agents for current configuration fields.

Follow Run a background Task to choose latest configuration or a Version Pin for asynchronous work.

Reference

See the TypeScript SDK methods to list Versions, get a Version, and restore a Version, plus disable and enable. The matching REST operations list Agent Versions, get an Agent Version, update an Agent, disable an Agent, and enable an Agent. Return to Configure your Agent for related topics.

On this page