awslabs / awslabs/loom

Add orchestrated workflows

Open
#36 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.