Agents

Agents are the platform's multi-step orchestration resource. They turn prompts and tools into a workflow graph that can branch, transition, return structured outputs, and persist detailed run history.

What agents are

Current agent records include:

name, slug, and description
status
entry step key
published version
usage metrics such as run count, latency, and estimated cost

Agent versions hold the actual graph definition.

Graph structure

In the current product, agent versions can contain:

prompt_step
tool_step
return_step
condition_step

Transitions describe how the workflow moves between steps, for example:

next
success
failure
condition_true
condition_false

Publishing and validation

Publishing is not just a status toggle. The backend validates whether the graph is usable. Invalid graphs can fail with a structured AGENT_GRAPH_INVALID response that includes machine-readable details.

That validation step is important because the product treats published agent versions as operational artifacts, not just drafts.

API workflow

Create an agent

curl -X POST "$API_BASE/api/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "name": "Returns resolution agent",
    "description": "Multi-step returns workflow"
  }'

Save agent steps

curl -X POST "$API_BASE/api/agent-versions/version_123/steps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "steps": [
      {
        "stepKey": "triage",
        "name": "Triage request",
        "stepType": "prompt_step",
        "promptId": "prompt_123",
        "promptVersionId": "version_456",
        "positionIndex": 0
      }
    ]
  }'

Run an agent

curl -X POST "$API_BASE/api/agents/agent_123/run" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_123",
    "variables": {
      "orderId": "order_987"
    }
  }'