agent-versions

Read an agent's promoted version history, newest first, or a field-level diff between two versions. Needs the fabric:orchestrate.read grant.

curl -sS -X POST https://fabric.wexa.ai/mcp/$FABRIC_PROJECT_ID \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "Mcp-Session-Id: $MCP_SESSION_ID" \
  -H "content-type: application/json" -H "accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agent-versions","arguments":{"agent_id":"6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc"}}}'

{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000176\",\"result\":{\"agent_id\":\"6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc\",\"live_version\":0,\"versions\":[]}}"
    }
  ],
  "isError": false
}

curl -sS https://fabric.wexa.ai/v1/agent-versions \
  -H "authorization: Bearer $FABRIC_API_KEY" \
  -H "content-type: application/json" \
  -d '{"agent_id":"6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc"}'

{
  "lifecycle_id": "qlc_000176",
  "result": {
    "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
    "live_version": 0,
    "versions": []
  }
}

import { Fabric } from '@wexa-fabric/sdk'

const fabric = new Fabric()
const result = await fabric.agentVersions({
  agent_id: '6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc'
})

// result is the payload itself, with no `.result` to read
{
  agent_id: '6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc',
  live_version: 0,
  versions: []
}

from wexa import Fabric

fabric = Fabric()
out = fabric.agent_versions(
    agent_id="6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
)

# out is the result, already unwrapped
{
    "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
    "live_version": 0,
    "versions": []
}

Parameters

Parameter	Type	Required	Notes
`agent_id`	string	Required	Agent id (an agent inside a process flow). Any agent id; one with no promoted version lists as empty.
`from_version`	integer	Optional	With `to_version` (both or neither): return a diff between these two versions instead of the list. Starts at 1.
`to_version`	integer	Optional	With `from_version` (both or neither): the version to diff against. Starts at 1.

Errors

NotFound (404): a diff (from_version and to_version) names a version the agent does not have ("one or both versions not found").

Show full response

A real response, captured from a live call to agent-versions:

{
  "content": [
    {
      "type": "text",
      "text": "{\"lifecycle_id\":\"qlc_000176\",\"result\":{\"agent_id\":\"6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc\",\"live_version\":0,\"versions\":[]}}"
    }
  ],
  "isError": false
}

{
  "lifecycle_id": "qlc_000176",
  "result": {
    "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
    "live_version": 0,
    "versions": []
  }
}

// the object you get back IS the result — there is no `.result` to read
{
  agent_id: '6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc',
  live_version: 0,
  versions: []
}

// The TS SDK names these camelCase — lifecycleId, traceId — where Python uses
// lifecycle_id and trace_id. Both are non-enumerable: readable, but omitted by
// Object.keys() and JSON.stringify(). `result.lifecycleId` here is undefined.
result.lifecycleId // 'qlc_000176'

# a dict subclass; `result` is already unwrapped
{
 "agent_id": "6ab1945e7566f41b5c28e303.6ab1945e83ff5845d7db96bc",
 "live_version": 0,
 "versions": []
}

out.lifecycle_id  # 'qlc_000176' — an attribute, not a key

More details

Every promote records a snapshot: the version number, the config as promoted, who promoted it and with what role, its test pass rate, and which version it replaced. A version has one of three statuses: promoted, superseded or rolled_back. The live version is the one marked promoted, which is not necessarily the highest number, because a rollback can make an earlier version live again. Use rollback-agent-version to change which one is live.

A version exists only after a promote. An agent you have just made with create-agent has none, so agent-versions answers versions: [] for it, and that is not an error. The first version of an agent is promoted in the console, in Agent Simulation. No tool creates it. Once an agent has versions, rollback-agent-version can make any of them live. A Proxy agent needs a promoted version before its chat completions endpoint answers. run-agent needs none.

In the console, open the agent, open the actions menu and choose Version history. It stays greyed out until the agent has a promoted version, and the live one is marked Currently live. For an agent there is no promote tool: choose Simulate & Promote in the same menu. Promotion is a step taken on a tested version, not a field you set on the agent definition.

Two version tracks

Agents and process flows are versioned separately, and each track captures something the other cannot.

	Process-flow version	Agent version
Snapshot of	The whole process flow when promoted: every agent, its configuration and the wiring	One agent's own configuration
Also records	Which version is live	Who promoted it, under what role, which version it replaced and how its tests scored
Catches	Structural change: an agent added, removed or rewired	Changes to that agent only

They move independently. Making a different version of an agent live changes what every process flow naming that agent does, without the process flow's own version changing. Merging the two histories would make one of the two changes invisible.

Editing records nothing on its own: history exists because something was promoted. A process flow has flow-versions to list its versions and name the live one, and promote-flow to snapshot it. Numbers are never reassigned: roll back to v1 while v2 was live and v2 stays in the history as rolled_back, v1 is live again, and the next promote is v3.

Every tool call works the same way: How every tool call works.