Agent Workbench

Internal agent task ledger, traces, artifacts, policy approvals, SDK execution, and Service Bus dispatch.

Owner: Agent runtime backend

Source Modules

• scripts/serve_client_portal.py
• LeafEnterprise/agents/

Endpoint Summary

Method	Path	Summary	Auth	Handler
GET	/api/agents/tasks	Lists agent task ledger records.	trusted frontend proxy	_handle_agent_tasks_list
POST	/api/agents/tasks	Creates a governed agent task.	trusted frontend proxy	_handle_agent_task_create
POST	/api/agents/tasks/from-it-request/{request_number}	Creates an agent task seeded from an ITR.	trusted frontend proxy	_handle_agent_task_from_it_request
GET	/api/agents/tasks/{task_id}	Returns one task record.	trusted frontend proxy	_handle_agent_task_detail
POST	/api/agents/tasks/{task_id}/approve	Approves a task requiring operator review.	trusted frontend proxy	_handle_agent_task_approve
GET	/api/agents/tasks/{task_id}/artifacts	Returns artifact records for one task.	trusted frontend proxy	_handle_agent_task_artifacts
POST	/api/agents/tasks/{task_id}/cancel	Cancels an agent task.	trusted frontend proxy	_handle_agent_task_cancel
POST	/api/agents/tasks/{task_id}/dispatch	Dispatches a task to Service Bus / AKS worker lane.	trusted frontend proxy	_handle_agent_task_dispatch
POST	/api/agents/tasks/{task_id}/retry	Marks an agent task for retry.	trusted frontend proxy	_handle_agent_task_retry
POST	/api/agents/tasks/{task_id}/rollback	Requests rollback or remediation for an agent task.	trusted frontend proxy	_handle_agent_task_rollback
POST	/api/agents/tasks/{task_id}/run	Runs the task through the local OpenAI Agents SDK hook.	trusted frontend proxy	_handle_agent_task_run
GET	/api/agents/tasks/{task_id}/traces	Returns trace events for one task.	trusted frontend proxy	_handle_agent_task_traces
GET	/api/agents/workspaces	Returns available agent lanes, role profile, source systems, and provider policy posture.	trusted frontend proxy	_handle_agent_workspaces

Endpoint Details

GET /api/agents/tasks

Lists agent task ledger records.

Property	Value
Handler	_handle_agent_tasks_list
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 500

Query parameters: status, lane, limit

Body fields: none

Response sections: tasks

Tests / smoke paths: tests/test_agents_service.py

Notes: Task records are backend truth for workbench state.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/agents/tasks
• Route family: agent-workbench
• Source handler: _handle_agent_tasks_list
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks

Creates a governed agent task.

Property	Value
Handler	_handle_agent_task_create
Auth	trusted frontend proxy
Cache	none
Status codes	200, 201, 400, 401, 409, 500

Query parameters: none

Body fields: lane, title, instructions, source_systems, scope, mutation_level, model_provider, break_glass_acknowledged

Response sections: task, policy_verdict

Tests / smoke paths: tests/test_agents_service.py

Notes: Policy verdict must be explicit at creation.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks
• Route family: agent-workbench
• Source handler: _handle_agent_task_create
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/from-it-request/{request_number}

Creates an agent task seeded from an ITR.

Property	Value
Handler	_handle_agent_task_from_it_request
Auth	trusted frontend proxy
Cache	none
Status codes	200, 201, 400, 401, 404, 409, 500

Query parameters: none

Body fields: lane, title, instructions, mutation_level, model_provider

Response sections: task, policy_verdict, itr_context

Tests / smoke paths: tests/test_agents_service.py

Notes: Source request lineage must remain in task scope.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/from-it-request/{request_number}
• Route family: agent-workbench
• Source handler: _handle_agent_task_from_it_request
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/agents/tasks/{task_id}

Returns one task record.

Property	Value
Handler	_handle_agent_task_detail
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 404, 500

Query parameters: none

Body fields: none

Response sections: task

Tests / smoke paths: tests/test_agents_service.py

Notes: Includes policy verdict and terminal reason when present.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/agents/tasks/{task_id}
• Route family: agent-workbench
• Source handler: _handle_agent_task_detail
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/{task_id}/approve

Approves a task requiring operator review.

Property	Value
Handler	_handle_agent_task_approve
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: none

Body fields: reason, break_glass_acknowledged

Response sections: task, trace

Tests / smoke paths: tests/test_agents_service.py

Notes: Owner break-glass must be explicit and audited.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/{task_id}/approve
• Route family: agent-workbench
• Source handler: _handle_agent_task_approve
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/agents/tasks/{task_id}/artifacts

Returns artifact records for one task.

Property	Value
Handler	_handle_agent_task_artifacts
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 404, 500

Query parameters: none

Body fields: none

Response sections: artifacts

Tests / smoke paths: tests/test_agents_service.py

Notes: Artifact payloads should reference safe storage metadata, not secrets.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/agents/tasks/{task_id}/artifacts
• Route family: agent-workbench
• Source handler: _handle_agent_task_artifacts
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/{task_id}/cancel

Cancels an agent task.

Property	Value
Handler	_handle_agent_task_cancel
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: none

Body fields: reason

Response sections: task, trace

Tests / smoke paths: tests/test_agents_service.py

Notes: Cancellation should be traceable.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/{task_id}/cancel
• Route family: agent-workbench
• Source handler: _handle_agent_task_cancel
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/{task_id}/dispatch

Dispatches a task to Service Bus / AKS worker lane.

Property	Value
Handler	_handle_agent_task_dispatch
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: none

Body fields: none

Response sections: status, dispatch, task

Tests / smoke paths: tests/test_agents_service.py

Notes: Unconfigured Service Bus returns not_configured and records trace.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/{task_id}/dispatch
• Route family: agent-workbench
• Source handler: _handle_agent_task_dispatch
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/{task_id}/retry

Marks an agent task for retry.

Property	Value
Handler	_handle_agent_task_retry
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: none

Body fields: reason

Response sections: task, trace

Tests / smoke paths: tests/test_agents_service.py

Notes: Retry should preserve prior traces and artifacts.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/{task_id}/retry
• Route family: agent-workbench
• Source handler: _handle_agent_task_retry
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/{task_id}/rollback

Requests rollback or remediation for an agent task.

Property	Value
Handler	_handle_agent_task_rollback
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: none

Body fields: reason, remediation

Response sections: task, trace

Tests / smoke paths: tests/test_agents_service.py

Notes: Production write lanes require rollback/remediation metadata.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/{task_id}/rollback
• Route family: agent-workbench
• Source handler: _handle_agent_task_rollback
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/agents/tasks/{task_id}/run

Runs the task through the local OpenAI Agents SDK hook.

Property	Value
Handler	_handle_agent_task_run
Auth	trusted frontend proxy
Cache	none
Status codes	200, 400, 401, 404, 409, 500

Query parameters: none

Body fields: none

Response sections: status, task, sdk_available, artifacts, traces

Tests / smoke paths: tests/test_agents_runner.py, tests/test_agents_service.py

Notes: Missing SDK or policy denial must record explicit blocked state.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/agents/tasks/{task_id}/run
• Route family: agent-workbench
• Source handler: _handle_agent_task_run
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/agents/tasks/{task_id}/traces

Returns trace events for one task.

Property	Value
Handler	_handle_agent_task_traces
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 404, 500

Query parameters: none

Body fields: none

Response sections: traces

Tests / smoke paths: tests/test_agents_service.py

Notes: Policy blocks, SDK missing, dispatch, worker receipt, and terminal transitions must be traceable.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/agents/tasks/{task_id}/traces
• Route family: agent-workbench
• Source handler: _handle_agent_task_traces
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/agents/workspaces

Returns available agent lanes, role profile, source systems, and provider policy posture.

Property	Value
Handler	_handle_agent_workspaces
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 500

Query parameters: none

Body fields: none

Response sections: lanes, sources, role, providers, policy_profiles

Tests / smoke paths: tests/test_agents_service.py

Notes: Use for task composer defaults and policy-aware UI state.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/agents/workspaces
• Route family: agent-workbench
• Source handler: _handle_agent_workspaces
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.