Deprecated names

Orchestration Agent replaces Workflow Agent. One execution is an orchestration run. Use the new names in new integrations.

The old routes and the new routes use the same agents and runs. An agent ID or a run ID does not change. The old routes keep their request fields, response fields, status codes, error codes, and operation IDs until removal. Their error messages use the new product name.

API routes

Method	Deprecated route	Use this route
POST	/v1/workflow-agents	/v1/orchestration-agents
GET	/v1/workflow-agents	/v1/orchestration-agents
GET	/v1/workflow-agents/{workflow_agent_id}	/v1/orchestration-agents/{orchestration_agent_id}
PUT	/v1/workflow-agents/{workflow_agent_id}	/v1/orchestration-agents/{orchestration_agent_id}
DELETE	/v1/workflow-agents/{workflow_agent_id}	/v1/orchestration-agents/{orchestration_agent_id}
POST	/v1/workflow-runs	/v1/orchestration-runs
GET	/v1/workflow-runs	/v1/orchestration-runs
GET	/v1/workflow-runs/{workflow_run_id}	/v1/orchestration-runs/{orchestration_run_id}
POST	/v1/workflow-runs/{workflow_run_id}/cancel	/v1/orchestration-runs/{orchestration_run_id}/cancel

Each old operation has deprecated: true in the OpenAPI contract. Each old route returns Deprecation: true and a Link header with rel="successor-version" and its new route.

Contract tags and operation IDs

The old tags Workflow Agents and Workflow Runs describe deprecated operations. The new tags are Orchestration Agents and Orchestration Runs. The old group is Workflows (deprecated). The new group is Orchestration. Generated clients keep the old method names for the old routes. Use these new operation IDs for the new routes:

Deprecated operation ID	New operation ID
list_customer_workflow_agents_v1_workflow_agents_get	list_customer_orchestration_agents_v1_orchestration_agents_get
create_customer_workflow_agent_v1_workflow_agents_post	create_customer_orchestration_agent_v1_orchestration_agents_post
archive_customer_workflow_agent_v1_workflow_agents__workflow_agent_id__delete	archive_customer_orchestration_agent_v1_orchestration_agents__orchestration_agent_id__delete
get_customer_workflow_agent_v1_workflow_agents__workflow_agent_id__get	get_customer_orchestration_agent_v1_orchestration_agents__orchestration_agent_id__get
replace_customer_workflow_agent_v1_workflow_agents__workflow_agent_id__put	replace_customer_orchestration_agent_v1_orchestration_agents__orchestration_agent_id__put
list_runs_v1_workflow_runs_get	list_runs_v1_orchestration_runs_get
create_run_v1_workflow_runs_post	create_run_v1_orchestration_runs_post
get_run_v1_workflow_runs__workflow_run_id__get	get_run_v1_orchestration_runs__orchestration_run_id__get
cancel_run_v1_workflow_runs__workflow_run_id__cancel_post	cancel_run_v1_orchestration_runs__orchestration_run_id__cancel_post

Request and response fields

Where	Deprecated name	New name
Agent path parameter, run request and response, run-list query	workflow_agent_id	orchestration_agent_id
Run path parameter and run response	workflow_run_id	orchestration_run_id
Monthly usage response	workflow_runs_count	orchestration_runs_count
Monthly spend response	workflow_tokens	orchestration_tokens

Use old field names with old routes. Use new field names with new routes. A run request with the other route family's agent field gets 422. It starts no run. Both monthly reports return the old and new fields with equal values. The old report fields have deprecated: true in the contract.

The JSON idempotency_key field works across both run routes. The same key, agent, and inputs return the same run. They do not create a second run.

OpenAPI schemas

The contract keeps these nine old schema names, with deprecated: true and a description of the new schema.

Deprecated schema	New schema
WorkflowAgentWrite	OrchestrationAgentWrite
WorkflowAgentResource	OrchestrationAgentResource
WorkflowAgentSummary	OrchestrationAgentSummary
WorkflowAgentSummaryPage	OrchestrationAgentSummaryPage
WorkflowRunCreateRequest	OrchestrationRunCreateRequest
WorkflowRunCreateResponse	OrchestrationRunCreateResponse
WorkflowRunResponse	OrchestrationRunResponse
WorkflowRunCancelResponse	OrchestrationRunCancelResponse
Page_WorkflowRunResponse_	Page_OrchestrationRunResponse_

The nested schemas now use OrchestrationRunChargeTotals, OrchestrationRunStatus, and OrchestrationRunFailureCode. Their field values do not change. The contract does not keep old copies of those nested schemas.

Webhook change

Update your receiver for all of these changes:

1. Read event type orchestration_run.ended instead of workflow_run.ended.
2. Read the run under orchestration_run instead of workflow_run.
3. Read orchestration_run_id and orchestration_agent_id inside that record.

The new event applies even when an old API route creates the run. The run_ended_webhook_url field does not change. Read Webhooks for the event and delivery rules.

Butler view context

Butler accepts focused_workflow_run_id until the removal date. New portal requests use focused_orchestration_run_id. Butler still asks for confirmation before either run route starts a run.

Portal, docs, and diagram URLs

Old URL	New URL
Portal /agents/workflow/<id>	/agents/orchestration/<id>
Portal /agents/workflow/new	/agents/orchestration/new
Portal /agents?type=workflow	/agents?type=orchestration
Docs /concepts/workflows	/concepts/orchestration-agents
Docs /guides/workflow-runs	/guides/orchestration-runs
Diagram /brand/workflow-agent.svg	/brand/orchestration-agent.svg

Old portal and docs URLs redirect to the new URLs. The old diagram URL returns a permanent 308 redirect until its removal.

Start with Orchestration Agents or Run an Orchestration Agent.