Build Multi-Agent Systems with Structured Outputs
Build a 4-agent data-analysis system using Structured Outputs' strict schema enforcement for reliable tool calls.
Why it matters
Develop sophisticated multi-agent systems that leverage structured outputs for guaranteed schema adherence, enhancing performance and reliability in complex task execution.
Outcomes
What it gets done
Implement a triaging agent to route tasks to specialized sub-agents.
Configure data pre-processing, analysis, and visualization agents with specific tool sets.
Utilize structured outputs to ensure model responses strictly adhere to predefined schemas.
Orchestrate tool execution and manage conversation history within the multi-agent framework.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/oai-structuredoutputsmultiagent | bash Steps
Steps in the chain
Overview
Structured Outputs for Multi-Agent Systems
An OpenAI Cookbook multi-agent system using Structured Outputs' strict schema enforcement, splitting data-analysis tools across a triaging, pre-processing, analysis, and visualization agent. Use it when one agent's tool set has grown large enough to hurt function-calling accuracy. Group tools into specialized agents and route through a triaging agent instead.
What it does
This cookbook uses OpenAI's Structured Outputs feature - which builds on top of JSON mode and function calling with a strict: true parameter to guarantee a model's response conforms exactly to a provided schema - to build a multi-agent data-analysis system. It addresses a specific function-calling problem: as the number of tools grows, performance degrades, so tools are grouped into specialized agents instead of one agent holding every tool.
When to use - and when NOT to
Use this pattern when a single agent's tool set has grown large enough to hurt function-calling accuracy, and the tools naturally cluster into distinct sub-tasks. The worked example is a 4-agent data-analysis pipeline: a Triaging Agent that decides which agent(s) to call, a Data Pre-processing Agent (clean, transform, aggregate data), a Data Analysis Agent (statistical, correlation, and regression analysis), and a Data Visualization Agent (bar, line, and pie charts) - each agent gets its own system prompt and only the tools relevant to its role.
Inputs and outputs
Each sub-agent's model call returns a Structured Output that's guaranteed to match its tool schema, removing the need to validate arguments or handle malformed tool calls on your own side. An execution function maps each tool call to its corresponding Python function and appends the function's output back into the conversation history, so multi-step tool use (for example, clean_data, then start_analysis, then use_line_chart, for a single query that genuinely needs all three steps performed in sequence) stays coherent across agent handoffs rather than losing context partway through.
Integrations
An overarching handle_user_message function is the single entry point: it takes the user query, gets a response from the triaging agent, routes to the appropriate sub-agent tool handlers, and maintains the state of the ongoing conversation across however many specialized agents end up getting invoked to fully answer that one query.
Who it's for
Developers building multi-agent systems with function calling who are hitting accuracy problems from too many tools on one agent, and want schema-guaranteed tool calls instead of hand-rolled argument validation. The cookbook's closing point is that this same pattern - grouping related tools under a specialized agent and relying on strict schema conformance to avoid manual validation - generalizes well beyond data analysis to essentially any multi-agent workflow built on function calling, since the core problem (too many tools degrading one agent's accuracy) and the fix (schema-enforced, logically-grouped sub-agents) aren't specific to this particular use case.
Source README
Structured Outputs for Multi-Agent Systems
In this cookbook, we will explore how to use Structured Outputs to build multi-agent systems.
Structured Outputs is a new capability that builds upon JSON mode and function calling to enforce a strict schema in a model output.
By using the new parameter strict: true, we are able to guarantee the response abides by a provided schema.
To demonstrate the power of this feature, we will use it to build a multi-agent system.
Why build a Multi-Agent System?
When using function calling, if the number of functions (or tools) increases, the performance may suffer.
To mitigate this, we can logically group the tools together and have specialized "agents" that are able to solve specific tasks or sub-tasks, which will increase the overall system performance.
Environment set up
Agents set up
The use case we will tackle is a data analysis task.
Let's first set up our 4-agents system:
- Triaging agent: Decides which agent(s) to call
- Data pre-processing Agent: Prepares data for analysis - for example by cleaning it up
- Data Analysis Agent: Performs analysis on the data
- Data Visualization Agent: Visualizes the output of the analysis to extract insights
We will start by defining the system prompts for each of these agents.
We will then define the tools for each agent.
Apart from the triaging agent, each agent will be equipped with tools specific to their role:
Data pre-processing agent
- Clean data
- Transform data
- Aggregate data
Data analysis agent
- Statistical analysis
- Correlation analysis
- Regression Analysis
Data visualization agent
- Create bar chart
- Create line chart
- Create pie chart
Tool execution
We need to write the code logic to:
- handle passing the user query to the multi-agent system
- handle the internal workings of the multi-agent system
- execute the tool calls
For the sake of brevity, we will only define the logic for tools that are relevant to the user query.
From the user query, we can infer that the tools we would need to call are clean_data, start_analysis and use_line_chart.
We will first define the execution function which runs tool calls.
This maps a tool call to the corresponding function. It then appends the output of the function to the conversation history.
Next, we will create the tool handlers for each of the sub-agents.
These have a unique prompt and tool set passed to the model.
The output is then passed to an execution function which runs the tool calls.
We will also append the messages to the conversation history.
Finally, we create the overarching tool to handle processing the user query.
This function takes the user query, gets a response from the model and handles passing it to the other agents to execute. In addition to this, we will keep the state of the ongoing conversation.
Multi-agent system execution
Finally, we run the overarching handle_user_message function on the user query and view the output.
Conclusion
In this cookbook, we've explored how to leverage Structured Outputs to build more robust multi-agent systems.
Using this new feature allows to make sure that tool calls follow the specified schema and avoids having to handle edge cases or validate arguments on your side.
This can be applied to many more use cases, and we hope you can take inspiration from this to build your own use case!
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.