Multi-agent workflow

What you'll build

Step-by-step build

1. 1

   Design the shared state

   Define one typed state object holding the goal, the plan, the research notes, the draft, and the critique. Every agent reads from and writes to this shared state, which is how they coordinate. Getting the state shape right first makes every later handoff clean.

2. 2

   Build the planner node

   Write the planner as a graph node that reads the goal and writes an ordered task list into state. Test it alone to confirm the plan is sensible before adding others. A node is just a function that transforms the shared state.

3. 3

   Build the researcher node

   Give the researcher a web search tool and have it gather notes for the planned tasks, writing them into state with sources. Keep it focused on finding facts, not writing prose. Grounding here keeps the final output from being invented.

4. 4

   Build the writer node

   Have the writer draft the deliverable using only the researcher's notes in state, then write the draft back. It should not do its own research; that separation is the point. Test that it produces a coherent draft from sample notes.

5. 5

   Build the critic node

   The critic reads the draft against the original goal and writes a critique plus an approve-or-revise verdict into state. Give it concrete criteria so feedback is actionable. This is the agent that raises quality without a human in the loop.

6. 6

   Wire the handoffs into a graph

   Connect the nodes in LangGraph so control flows planner to researcher to writer to critic. Each edge is an explicit handoff of control and shared state. Now you can see the whole workflow as one inspectable graph.

7. 7

   Add the revise loop

   Route a revise verdict from the critic back to the writer, and an approve verdict to the end. Cap the number of revise cycles so it cannot loop forever. This closed loop is what makes the output improve over passes.

8. 8

   Expose and trace the run

   Put the graph behind a FastAPI endpoint that takes a goal and returns the final approved output. Log the path the run took through the graph and the state at each step. Tracing is what lets you debug a multi-agent system when it misbehaves.

Done when

• ✓Each agent does only its job; the writer never researches and the critic never writes the draft
• ✓A revise verdict visibly changes the next draft
• ✓The revise loop always ends, by approval or by its cap
• ✓You can read the trace and see which agent produced each part of the output
• ✓The final output is grounded in the researcher's cited notes, not invented

Ship it

Host the FastAPI graph on a free Hugging Face Space with a small UI to enter a goal and watch the run. Store the Groq and search keys as Space secrets. Write a README with a diagram of the graph, one example goal, and the approved output it produced.

What it proves: Shows you can orchestrate multiple specialized agents with explicit handoffs and shared state, the core skill behind complex agent systems.

Paste this into Cursor, Claude, or ChatGPT and build it step by step.

You are my senior AI engineer pair. Help me build "Multi-agent workflow" step by step. Each agent is an LLM with one job; orchestration means designing how they hand off control and share state. A handoff passes control and the shared state object from one agent to the next.

Stack: LangGraph to model agents and handoffs as an inspectable state graph, Python with FastAPI, Groq API for inference, a free web search API for the researcher, and Pydantic for the typed shared state.

Requirements:
1. Define one typed shared state: goal, plan, notes, draft, critique.
2. Build four nodes: planner, researcher with a search tool, writer, and critic.
3. Wire handoffs planner to researcher to writer to critic in LangGraph.
4. Add a revise loop from critic back to writer with a hard cap.
5. Expose it via FastAPI and log the path and state at each step.

Work in this order: shared state, then planner, then researcher, then writer, then critic, then the graph wiring, then the revise loop, then the endpoint and tracing. Give me commands and code for each step and STOP after each so I can test. Do not write the whole app at once.