Agent Store

Persist agent configurations — prompts, tools, model, settings. Version control your agent definitions, rollback to previous versions, and duplicate to share across your organization.

Agent Store manages definitions (templates). Agent Lifecycle manages running instances (state transitions). Define once, create many.

Defining an agent

Use platform.agents.define() to persist an agent configuration. The definition captures everything needed to create identical agents — compute, model, system prompt, tools, browser settings, timeout, and custom config.

define.ts

const definition = await platform.agents.define({
  name: class="cb-str">'Research Analyst',
  description: class="cb-str">'Scrapes the web and produces structured reports',
  compute: {
    provider: class="cb-str">'e2b',
    region: class="cb-str">'us-east-1',
  },
  model: class="cb-str">'claude-3-5-sonnet-20241022',
  systemPrompt: class="cb-str">'You are a research analyst. Be concise, cite sources, output markdown.',
  tools: [class="cb-str">'web_search', class="cb-str">'write_file', class="cb-str">'screenshot', class="cb-str">'pdf_reader'],
  browser: true,
  timeout: class="cb-str">'15m',
  config: {
    maxRetries: class="cb-num">2,
    costCap: { amount: class="cb-num">500, currency: class="cb-str">'usd' },
  },
})

console.log(definition.id)       class="cb-cmt">// 'adef_r3s34rch...'
console.log(definition.version)  class="cb-cmt">// 1

Listing definitions

Retrieve all agent definitions for your platform. Returns an array of definition objects with their current version and metadata.

list-definitions.ts

const definitions = await platform.agents.listDefinitions()

for (const def of definitions) {
  console.log(def.id, def.name, def.version)
}
// 'adef_r3s34rch...'  'Research Analyst'    3
// 'adef_wr1t3r...'    'Content Writer'      1
// 'adef_c0d3r...'     'Code Review Bot'     7

Updating definitions

Updates create a new version — definitions are immutable. Every change is tracked with an optional changelog message, so you always know what changed and when.

update-definition.ts

const updated = await platform.agents.updateDefinition(class="cb-str">'adef_r3s34rch...', {
  systemPrompt: class="cb-str">'You are a senior research analyst. Be thorough, cite all sources, output markdown with tables.',
  changelog: class="cb-str">'Upgraded to senior analyst prompt with table formatting',
})

console.log(updated.version)  class="cb-cmt">// 4  (previous was 3)

Each update creates a new immutable version. The previous versions remain accessible via platform.agents.versions() and can be restored with platform.agents.rollback().

Version history

Retrieve the full version history of a definition. Each entry includes the version number, creation timestamp, and changelog message.

versions.ts

const versions = await platform.agents.versions(class="cb-str">'adef_r3s34rch...')

for (const v of versions) {
  console.log(v.version, v.createdAt, v.changelog)
}
// 4  2025-05-09T14:32:00Z  'Upgraded to senior analyst prompt with table formatting'
// 3  2025-05-07T09:15:00Z  'Added pdf_reader tool'
// 2  2025-05-03T11:20:00Z  'Increased timeout to 15m'
// 1  2025-05-01T08:00:00Z  'Initial definition'

Rollback

Restore a definition to a previous version. This creates a new version with the same configuration as the target version, so the version history remains a clean, append-only log.

rollback.ts

// Roll back to version 1
const rolled = await platform.agents.rollback(class="cb-str">'adef_r3s34rch...', {
  version: class="cb-num">1,
})

console.log(rolled.version)  class="cb-cmt">// 5  (new version with v1's config)

Duplicate

Clone an existing definition under a new name. The duplicate starts at version 1 with the same configuration as the source definition's current version. Useful for creating variants or sharing templates across teams.

duplicate.ts

const clone = await platform.agents.duplicate(class="cb-str">'adef_r3s34rch...', {
  name: class="cb-str">'Research v2',
})

console.log(clone.id)       class="cb-cmt">// 'adef_n3wcl0n...'  (new ID)
console.log(clone.name)     class="cb-cmt">// 'Research v2'
console.log(clone.version)  class="cb-cmt">// 1

Using definitions

Create a running agent from a stored definition. Pass the definition ID and optionally override specific fields — the overrides are applied on top of the stored configuration without modifying the definition itself.

use-definition.ts

// Create an agent from a definition
const agent = await session.agents.create({
  definition: class="cb-str">'adef_r3s34rch...',
  overrides: {
    timeout: class="cb-str">'20m',
  },
})

// The agent inherits the definition's model, prompt, tools, compute...
// ...but uses a 20-minute timeout instead of the stored 15m
const result = await agent.run(class="cb-str">'Analyze Q2 earnings reports for FAANG companies')

API reference

platform.agents.define(opts)Promise<AgentDefinition>Persist a new agent definition with compute, model, prompt, tools, and config.

platform.agents.listDefinitions()Promise<AgentDefinition[]>List all agent definitions for the platform with current version metadata.

platform.agents.updateDefinition(id, patch)Promise<AgentDefinition>Update a definition. Creates a new immutable version with an optional changelog.

platform.agents.versions(id)Promise<Version[]>Retrieve full version history: version number, createdAt, and changelog per entry.

platform.agents.rollback(id, opts)Promise<AgentDefinition>Restore to a previous version. Creates a new version with the target's config.

platform.agents.duplicate(id, opts)Promise<AgentDefinition>Clone a definition under a new name. Starts at version 1 with the source's config.