Orchestration and shared state: cheatsheet

For education only. Multi-agent architecture taught via stock analysis; not investment, financial, or trading advice.

The one idea

A team of agents is held together by two things: orchestration (who runs next) and shared state (what they pass along). (Anchored to the TradingAgents framework, frozen snapshot 7e9e7b8; shared state in agents/utils/agent_states.py, graph in graph/setup.py.)

Two questions, two mechanisms

Question	Name	Mechanism
Whose turn is it next?	Control flow	The graph’s arrows (fixed or conditional)
How does work reach the next agent?	Data flow	One shared state every agent reads and writes

Shared state: one source of truth

The whole team shares one structured workspace (AgentState). Each labelled space holds one piece of the work, and the handoffs from earlier lessons are just reads and writes of those spaces:

• analyst reports (one space each) feed the debate
• the judge’s plan (investment_plan) is read by the trader
• the trader’s plan (trader_investment_plan) is read by the risk seats
• the gate writes the final decision (final_trade_decision)

Nobody passes private notes. One board, labelled spaces, read and written in turn.

The graph: fixed versus conditional arrows

Arrow	What it means	Example in the code
Fixed	Always go to the same next agent	workflow.add_edge("Research Manager", "Trader")
Fixed (end)	This agent is the last step	workflow.add_edge("Portfolio Manager", END)
Conditional	A function reads the state and picks next	workflow.add_conditional_edges("Bull Researcher", should_continue_debate, {...})

The reveal

The “should we continue” checks from earlier lessons are the conditional arrows of this one graph:

• whether an analyst needs another tool call (data-fetching lesson)
• whether the debate runs another round (should_continue_debate, the bull and the bear)
• whether the risk seats rotate again or route to the gate (should_continue_risk_analysis, the risk gate)

How to follow along

Read it free in your browser at github.com/TauricResearch/TradingAgents (pinned snapshot). No account, no Git, no programming knowledge needed. The short code 7e9e7b8 marks one frozen version, so the lessons match what you see.

Build your own (the transferable pattern)

1. Keep one source of truth: a single place the work accumulates, that each step reads from and writes to.
2. Make handoffs fixed where the order never changes.
3. Make handoffs conditional where the work must adapt (loop, escalate, finish), with a small function reading the shared state to choose.

Pitfalls to dodge

• No shared source of truth, so each step sees only a thinned-out summary of the last.
• Everything conditional, so the flow is hard to follow and easy to misroute.
• Confusing “who runs next” with “what they can see”: a step can be next and still be missing the information it needs.

Words to use precisely

• Control flow: the order agents run in; who goes next.
• Data flow: how one agent’s output reaches the next.
• Shared state: the one structured workspace that is the team’s source of truth.
• Conditional edge: an arrow whose destination a function decides from the current state.