Add orchestrated workflows
- Dominant language
- Python
- Stars
- 183
- Forks
- 41
- Avg merge
- 8h 6m
- Merged PRs (30d)
- 2
Description
## Overview
Loom currently deploys single agents and can wire them together via A2A, but A2A is a loose, ad hoc integration — there is no first-class concept of a multi-step workflow, no way to visualize how agents connect, and no failure/retry handling across a chain of agent invocations. Add orchestrated workflows: a new top-level construct that composes multiple agents (and A2A agents) into a directed sequence, buildable either visually in the console or via a JSON manifest, with runtime visualization of workflow instances and failure handling with retries/redrive.
## Context
### Current State
- Agents are registered/deployed individually (`backend/app/models/agent.py`) and invoked one at a time via `backend/app/routers/invocations.py`, which streams a single agent's response over SSE/WebSocket (`invoke_agent`/`invoke_agent_ws` in `backend/app/services/agentcore.py`).
- A2A agents are modeled as standalone integrations (`backend/app/models/a2a.py`: `A2aAgent`, `A2aAgentSkill`, `A2aAgentAccess`) that an agent's config can call as remote tools (`agents/*/src/integrations/a2a_client.py`) — there is no concept of an ordered, multi-agent execution graph, only "agent A can call agent B."
- Invocations are tracked per-agent via `InvocationSession`/`Invocation` (`backend/app/models/session.py`, `backend/app/models/invocation.py`), with no cross-agent execution/run entity linking a chain of invocations together.
- There is no retry or redrive mechanism anywhere in the invocation path today — a failed invocation simply surfaces an error to the caller.
- The frontend has per-domain admin pages (`frontend/src/pages/`: `AgentListPage.tsx`, `A2aAgentsPage.tsx`, `RegistryPage.tsx`, etc.) but no page for composing or visualizing multi-agent flows.
### Key Files
- `backend/app/models/agent.py` — `Agent` ORM model; workflow steps reference agents by `arn`/`id`
- `backend/app/models/a2a.py` — `A2aAgent`, `A2aAgentSkill`; workflow steps may target A2A agents in addition to Loom-registered agents
- `backend/app/models/session.py`, `backend/app/models/invocation.py` — existing per-agent invocation/session tracking; a new workflow run entity should link to these rather than duplicate them
- `backend/app/routers/invocations.py` — `invoke_agent`/`invoke_agent_ws` call sites; the workflow engine will call into this same invocation path per step rather than bypassing it
- `backend/app/services/agentcore.py` — low-level AgentCore Runtime invoke helpers reused by workflow step execution
- `backend/app/routers/a2a.py`, `backend/app/services/a2a.py` — A2A agent card/skill fetch and connection testing; workflow steps targeting A2A agents reuse this
- `frontend/src/pages/` — existing per-domain pages; add `WorkflowsPage.tsx`, `WorkflowBuilderPage.tsx`, `WorkflowRunDetailPage.tsx` following this convention
- `frontend/src/api/` — existing per-domain API client modules (e.g. `a2a.ts`); add `workflows.ts`
### Technology Stack
- **Backend**: Python, FastAPI, SQLAlchemy, SQLite
- **Frontend**: TypeScript, React, Vite, shadcn/ui, Tailwind CSS
- **Agent Runtime**: AWS Bedrock AgentCore, existing A2A protocol integration
## Requirements
### R1: visual-workflow-builder
Users should be able to visually build workflows in the console.
- Add a `WorkflowBuilderPage.tsx` with a node/edge canvas where each node represents a workflow step (a Loom agent or an A2A agent) and edges represent execution order/data flow.
- Support adding, removing, and reordering steps, and configuring per-step input mapping (how a step's input is derived from a prior step's output or static workflow input).
- The visual builder and the JSON manifest (R2) must be two views of the same underlying workflow definition — building visually produces a manifest, and editing a manifest updates the visual graph, with no divergence between the two representations.
### R2: json-manifest-authoring
Users should be able to build workflows via JSON manifest.
- Define a workflow manifest schema (steps, step type — `agent` or `a2a_agent` — target reference, input mapping, retry policy per step, ordering/branching) and validate it server-side on create/update.
- Expose `POST /api/workflows` and `PUT /api/workflows/{workflow_id}` accepting the manifest JSON directly, alongside the visual builder's save path, so manifests can be authored, versioned, and imported/exported outside the console (e.g. checked into source control), consistent with the existing agent-config JSON export/import pattern in `AgentRegistrationForm.tsx`.
### R3: workflow-instance-status-view
Users should be able to view the operational status of any given workflow instance.
- Introduce a workflow run entity that tracks one execution of a workflow definition: overall status (`running`, `succeeded`, `failed`, `partially_failed`), start/end time, and a per-step record (status, linked `Invocation`/`InvocationSession` for that step, error detail on failure).
- Add `GET /api/workflows/{workflow_id}/runs` and `GET /api/workflows/{workflow_id}/runs/{run_id}` endpoints (scope-gated consistent with existing agent/invocation read scopes) returning run and per-step status.
- Add a `WorkflowRunDetailPage.tsx` visualizing the run against the workflow graph from R1 — each step node reflects its live/historical status, with drill-down into the underlying agent invocation (reusing `InvocationDetailPage.tsx` where applicable).
### R4: failure-handling-and-redrive
Users should be able to redrive failed executions.
- Support a per-step retry policy in the workflow manifest (max attempts, backoff) that the workflow engine applies automatically before marking a step failed.
- On terminal step failure, mark the run `failed`/`partially_failed` without silently continuing past a failed step unless the manifest explicitly marks that step as non-blocking.
- Add `POST /api/workflows/{workflow_id}/runs/{run_id}/redrive` to re-execute a failed run from its first failed step (reusing successful prior-step outputs as input rather than re-running the entire workflow from scratch), and surface a "Redrive" action on `WorkflowRunDetailPage.tsx` for failed/partially-failed runs.
## Testing
- Run backend tests: `cd backend && make test`
- Run frontend typecheck: `cd frontend && npx tsc --noEmit`
- Verify a workflow built visually and one authored as an equivalent JSON manifest produce identical run behavior
- Verify a workflow spanning both a Loom-registered agent step and an A2A agent step executes both step types correctly
- Verify a step configured with a retry policy retries on transient failure and eventually succeeds or exhausts attempts and fails the run
- Verify redrive resumes from the first failed step using prior successful step outputs, rather than re-invoking already-succeeded steps
- Verify run status and per-step status surfaced via the API match what's rendered on `WorkflowRunDetailPage.tsx`
## Out of Scope
- Scheduled/triggered workflow execution (e.g. cron-based or event-driven workflow starts) — this issue only covers on-demand and redrive execution
- Parallel/fan-out step execution within a single workflow (this issue targets a directed sequence with optional non-blocking steps, not general DAG concurrency)
- Cross-workflow composition (a workflow invoking another workflow as a step)
- Workflow-level versioning/rollback beyond the manifest update path in R2
Contributor guide
Research direction
Start by reading the existing models in backend/app/models/agent.py, session.py, and invocation.py, then trace invocation and A2A entry points in backend/app/routers/invocations.py and backend/app/services/agentcore.py. Review the frontend page and API conventions under frontend/src/pages/ and frontend/src/api/. Done means the manifest, builder, run-status APIs and views, retries, redrive behavior, and listed backend/frontend tests all work together.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- aws, fastapi, python, react, sqlalchemy, sqlite, tailwind, typescript, vite
- Domain
- api, backend, cloud, database, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 25/100