BatchedGridWorkflow
Overview
The BatchedGridWorkflow swarm type executes multiple tasks across multiple agents in a grid-like pattern, where each agent processes every task independently. This creates a comprehensive matrix of results, allowing you to compare how different agents approach the same set of tasks. The workflow supports iterative refinement through themax_loops parameter, enabling agents to improve their outputs over multiple iterations.
Key features:
- Grid Execution Pattern: Each agent processes every task, creating a complete task-agent matrix
- Parallel Batch Processing: All agent-task combinations run in parallel for maximum efficiency
- Iterative Refinement: Support for multiple loops to refine and improve outputs
- Comparative Analysis: Easy comparison of different agent approaches to the same tasks
- Structured Output Mapping: Results organized by agent name for each task
Use Cases
- A/B testing different agent configurations on the same tasks
- Multi-perspective analysis where each expert reviews all aspects
- Quality assurance with multiple reviewers checking all items
- Comparative research across different methodological approaches
- Content generation with multiple styles or tones for the same topics
API Usage
Basic BatchedGridWorkflow Example
- Shell (curl)
- Python (requests)
- JavaScript (fetch)
- Go
- Rust
Advanced Example: Multi-Loop Refinement
- Python
Request Schema
BatchedGridWorkflowInput
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The name of the batched grid workflow |
description | string | Yes | A description of what the workflow does |
agent_completions | array | Yes | List of agent configurations (see AgentSpec below) |
tasks | array | Yes | List of tasks that each agent will process |
max_loops | integer | No | Number of iterations for refinement (default: 1) |
imgs | array | No | List of image URLs for vision-enabled models |
AgentSpec
| Field | Type | Required | Description |
|---|---|---|---|
agent_name | string | Yes | Unique name for the agent |
description | string | No | Description of the agent’s role |
system_prompt | string | Yes | System prompt defining agent behavior |
model_name | string | Yes | Model to use (e.g., “gpt-4o”, “claude-3-5-sonnet-20241022”) |
max_loops | integer | No | Max loops per agent (default: 1) |
temperature | float | No | Sampling temperature 0.0-1.0 (default: 0.5) |
context_length | integer | No | Maximum context window size |
user_name | string | No | User name for the agent |
Response Schema
BatchedGridWorkflowOutput
| Field | Type | Description |
|---|---|---|
job_id | string | Unique identifier for the workflow execution |
name | string | Name of the workflow |
description | string | Description of the workflow |
status | string | Execution status (“success” or “error”) |
outputs | array | Array of task results, each containing agent outputs mapped by agent name |
usage | object | Token usage and cost information |
timestamp | string | ISO 8601 timestamp of completion |
Usage Object
| Field | Type | Description |
|---|---|---|
input_tokens | integer | Total input tokens consumed |
output_tokens | integer | Total output tokens generated |
total_tokens | integer | Sum of input and output tokens |
token_cost | float | Cost in credits for token usage |
cost_per_agent | float | Fixed cost per agent (0.01 credits per agent) |
Pricing
BatchedGridWorkflow pricing consists of two components:- Agent Cost: $0.01 per agent
- Token Cost:
- Input tokens: $4.00 per 1M tokens
- Output tokens: $12.50 per 1M tokens
Implementation Note: There is currently a bug in the API implementation where the
cost_per_agent is calculated before agents are added to the list (line 136), resulting in zero agent costs being charged. This will be fixed in a future update. The pricing model described here reflects the intended behavior.- 3 agents processing 3 tasks
- 450 input tokens, 4850 output tokens
- Agent cost: 3 × 0.03
- Input cost: (450 / 1,000,000) × 0.0018
- Output cost: (4850 / 1,000,000) × 0.0606
- Total: $0.0924
- Agent cost: $0.00 (bug: calculated before agents are populated)
- Token costs: $0.0624
- Total: $0.0624
Grid Execution Pattern
The BatchedGridWorkflow creates a matrix where:- Rows: Represent tasks
- Columns: Represent agents
- Cells: Contain each agent’s response to each task
Best Practices
When to Use BatchedGridWorkflow
- Comparative Analysis: Need multiple perspectives on the same set of tasks
- A/B Testing: Testing different agent configurations on identical inputs
- Multi-Expert Review: Multiple specialists reviewing the same items
- Style Variations: Generating content in different styles or tones
- Quality Assurance: Multiple reviewers checking all aspects
When to Use Other Workflows
- Sequential dependencies: Use SequentialWorkflow
- Independent parallel tasks: Use ConcurrentWorkflow
- Task routing: Use MultiAgentRouter
- Consensus decisions: Use MajorityVoting
Design Recommendations
- Agent Diversity: Design agents with distinct specializations for meaningful comparisons
- Task Granularity: Break complex topics into specific tasks for better analysis
- Temperature Settings: Use lower temperatures (0.3-0.5) for analytical tasks, higher (0.6-0.8) for creative tasks
- Iterative Refinement: Use
max_loops > 1when quality improvement is worth the added cost - Result Processing: Implement post-processing to compare and synthesize agent outputs
Cost Optimization
- Start with fewer agents and tasks to test your workflow
- Use appropriate models (GPT-4o for quality, GPT-3.5-turbo for cost)
- Monitor token usage and adjust prompt verbosity
- Cache common results when possible
- Batch multiple related workflows in a single session
Error Handling
The API returns standard HTTP status codes:- 200: Success
- 400: Bad request (invalid configuration)
- 401: Unauthorized (invalid API key)
- 402: Payment required (insufficient credits)
- 500: Server error
Limitations
- Maximum recommended: 10 agents × 10 tasks (100 total executions per workflow)
- Each agent-task combination counts toward rate limits
- Large grids may experience longer processing times
- Token limits apply per agent execution
Related Workflows
- SequentialWorkflow - For step-by-step processing
- ConcurrentWorkflow - For parallel independent tasks
- MixtureOfAgents - For combining diverse specialists
- MajorityVoting - For consensus-based decisions