Agents

client.agents combines two public surfaces:

• stable runtime for get/run/replay/rerun flows
• public beta stateless authoring and iteration for create/update/version/publish/workflow/compare/diff/rollback flows

Stable runtime methods

• get(agentId, { organizationId }) -> GET /api/agents/:id
• run(agentId, { organizationId, agentVersionId?, input }) -> POST /api/agents/:id/run
• loadInputs(runId, { organizationId }) -> POST /api/agent-runs/:id/load-inputs
• rerunFromStep(runId, { organizationId, stepId }) -> POST /api/agent-runs/:id/rerun-from-step

Public beta stateless authoring methods

• list({ organizationId }) -> GET /api/agents
• create(...) -> POST /api/agents
• update(agentId, ...) -> PATCH /api/agents/:id
• createVersion(agentId, ...) -> POST /api/agents/:id/versions
• publish(agentId, ...) -> POST /api/agents/:id/publish
• saveWorkflow(agentVersionId, ...) -> PUT /api/agent-versions/:id/workflow
• validateWorkflow(agentVersionId, ...) -> POST /api/agent-versions/:id/workflow/validate
• compareRuns({ organizationId, leftRunId, rightRunId }) -> GET /api/agent-runs/compare
• diffVersion(agentId, versionId, { organizationId, againstVersionId }) -> GET /api/agents/:id/versions/:versionId/diff
• rollbackVersion(agentId, versionId, { organizationId }) -> POST /api/agents/:id/versions/:versionId/rollback

Workflow model

Workflow is public only as agent-scoped dependent configuration.

That means:

• build workflow through createVersion, validateWorkflow, and saveWorkflow
• publish through the owning agent
• do not expect a top-level client.workflows.* resource

Recommended stateless authoring loop

1. create
2. createVersion
3. validateWorkflow
4. saveWorkflow
5. publish
6. run
7. client.runs.get(...)
8. compareRuns, diffVersion, or rollbackVersion when iterating

End-to-end proof example

prompt-orchestra-ts/scripts/agent-authoring-e2e.ts is the canonical Sprint 2 example. It exercises the full promoted flow end to end and writes a structured evidence artifact for regression tracking.

Boundary notes

• Agent runtime remains stable.
• Stateless authoring and iteration remain public beta.
• Session-backed routes and realtime agent surfaces are not part of client.agents.