streamlit-langgraph: Agent-First Multi-Agent Framework
Executive Summary
Building effective multi-agent systems is fundamentally about designing agent instructions, tasks, and context, not about complex orchestration logic. As emphasized by modern agent frameworks, system quality depends far more on context engineering and task design than on how agents are wired together.
streamlit-langgraph was created with this principle in mind. The package is designed so users can focus on defining agents and tasks, while multi-agent orchestration and UI implementation details are handled automatically. By combining opinionated orchestration abstractions with fast deployment through Streamlit, the framework removes much of the engineering overhead that typically slows down multi-agent development.
This agent-first approach enables rapid iteration, experimentation, and deployment of multi-agent systems, allowing developers to spend their effort where it matters most — improving agent reasoning and task design rather than infrastructure.
Key Contributions
- A. Agent-First Architecture & Design Philosophy: Designed the framework around the idea that agent instructions, task definitions, and context engineering are the primary drivers of system quality, intentionally de-emphasizing orchestration complexity.
- B. Built-in Multi-Agent Orchestration (Abstracted): Implemented reusable orchestration patterns (supervisor, hierarchical, networked) as infrastructure-level utilities, enabling users to leverage multi-agent execution without managing graph logic directly.
- C. Rapid Deployment via Streamlit: Integrated Streamlit to provide instant, zero-frontend deployment, allowing users to interact with and iterate on multi-agent systems immediately.
- D. Extensibility & Open-Source Maintenance: Designed the package to support additional LLM providers and workflows while maintaining a minimal and opinionated API surface.
Achievements
- Open-source deployment with active development.
- Adopted as the core architecture for multi-agent–based chat development at Macrogen.
Introduction, Problem, and Goal
Introduction
Multi-agent systems rely on multiple autonomous agents collaborating to solve complex tasks. While orchestration frameworks make this technically possible, they often push developers to focus on execution flow, state management, and UI setup rather than on agent reasoning quality.
Problem
- Developers spend excessive time designing orchestration logic instead of agent behavior.
- UI and deployment setup slow down experimentation.
- Iterating on agent instructions and task definitions requires unnecessary infrastructure changes.
Goal
- Enable developers to build multi-agent systems while focusing primarily on agents and tasks.
- Provide orchestration and UI as out-of-the-box infrastructure, not design burdens.
Technical Overview
This project is built with a focus on practical multi-agent systems using Python and existing agent orchestration and web frameworks, integrating both UI deployment and agent workflow abstraction.
- Large Language Models (LLMs)
- OpenAI (primary LLM provider via Responses API and Chat)
- Google Gemini
- Experimental support (proof of concept) for other providers (e.g., Claude, etc.)
- Agent Orchestration Frameworks
- LangGraph: core multi-agent orchestration library used to structure and execute agent workflows
- LangChain: underlying framework used for model invocation, agent execution, and utility integrations
- Web Interface & Deployment
- Streamlit: interactive web interface for dashboards and AI interfaces, enabling instant application deployment without a frontend stack
- Workflow Patterns & Examples
- Supervisor (sequential & parallel) workflows
- Hierarchical agent workflows
- Network (peer-to-peer) workflows
- Human-in-the-Loop patterns with tool approval
- MCP Tools integration (e.g., external math, weather servers)
- Core System Components
- Executor architecture supporting different LLM execution paths
- Conversation history and context management
- Section/Block rendering system for interactive UI display
- Custom tools and MCP support modules
1. Overcoming Limitations of the OpenAI Responses API
Problem
While adopting the OpenAI Responses API, I found that existing executors and abstractions did not fully support key response features such as:
- Partial image outputs
- Real-time code interpreter streaming
- Incremental tool execution results
- Fine-grained response event handling
These limitations made it difficult to build rich, interactive multi-agent applications using the Responses API within existing frameworks.
Solution
To address this, I implemented a completely new executor architecture specifically for the OpenAI Responses API. This executor was designed to:
- Correctly handle streaming and partial outputs
- Support real-time code interpreter execution results
- Process multimodal response events (e.g., images, text, tool outputs)
- Integrate seamlessly with Streamlit’s interactive rendering model
Impact
This enabled full utilization of the Responses API’s capabilities within multi-agent workflows, unlocking richer interactions and more expressive agent behaviors that were not possible with existing executors.
2. Unifying LangGraph State with Streamlit st.session_state
Problem
LangGraph workflows operate on a state object that agents read from and write to, while Streamlit reruns the script and relies on
st.session_state for persistence across reruns. This “two state systems” model caused issues such as duplicated messages, disappearing UI blocks after reruns, and inconsistencies between execution state and rendered output.Solution
I introduced a clear separation of responsibilities:
workflow_stateas the single source of truth for application state and chat history (messages and display metadata), designed to persist across Streamlit reruns and be directly readable and writable by LangGraph workflows.
st.session_stateas Streamlit runtime state, holding references toworkflow_stateand managing non-persistent runtime objects (e.g., executor instances, uploaded file handles).
- A synchronization mechanism to ensure that user inputs, agent outputs, and UI rendering consistently update and reflect the same canonical state.
Impact
This eliminated state desynchronization between LangGraph execution and Streamlit rendering. The UI remains stable across reruns, workflows are reproducible, and debugging becomes significantly easier due to a single canonical state model.
3. Reducing Cognitive Load in Multi-Agent Development
Problem
Building multi-agent systems often required developers to spend excessive time on orchestration graphs, execution flow, and state management. This shifted focus away from agent instructions, task definitions, and context design — the aspects that most strongly influence system quality.
Solution
I designed the framework so orchestration logic is treated as infrastructure rather than a primary design concern. Common multi-agent patterns (e.g., supervisor, hierarchical, networked) are provided as predefined abstractions, allowing users to leverage multi-agent execution without manually wiring graphs or managing state transitions.
Impact
This significantly reduced cognitive overhead and enabled faster iteration on agent behavior and task design.
4. Simplifying Human-in-the-Loop Workflows
Problem
Developers building human-in-the-loop systems faced challenges managing streaming states and asynchronous input handling in UI contexts, particularly when combining Streamlit interactions with LangGraph’s asynchronous execution model.
Solution
The framework abstracts away these complexities by wrapping agent workflows into synchronous Streamlit execution frames, allowing users to interact naturally with agent states and asynchronous outputs without manual orchestration or thread-management code.
Impact
This makes it significantly easier to build practical chat applications and conditional human-interaction workflows without deep expertise in asynchronous event loops or Streamlit internals.