Query Plans

Compose AI agent orchestration plans with reusable templates and branch-based workflows.

What are Query Plans?

Query Plans are specialized workflows designed for AI agent orchestration. Unlike general DAG workflows, query plans focus on:

• Agent coordination - Orchestrate multiple AI agents with different roles
• Reusable templates - Save and share common patterns as prefabs
• Branch-based execution - Track execution branches and merge points
• Canvas composition - Visual editor optimized for agent flows

Query plans are built on the same DAG execution engine as workflows but provide higher-level abstractions for multi-agent scenarios.

Key Concepts

Agents vs Nodes

In query plans, nodes represent AI agents rather than low-level operations:

• Planner Agent - Breaks down complex queries into subtasks
• Executor Agent - Performs specific operations (search, extract, transform)
• Reviewer Agent - Validates outputs and provides feedback
• Coordinator Agent - Merges results from parallel agents

Each agent node encapsulates prompts, tools, and validation logic.

Prefabs

Prefabs are reusable query plan templates stored in the prefab library. Common prefabs include:

Branch Tracking

Query plans track execution branches for:

• Parallel agent execution - Multiple agents working on subtasks
• Conditional routing - Different paths based on intermediate results
• Merge points - Combining outputs from parallel branches
• Branch metadata - Timestamps, costs, token usage per branch

Creating Query Plans

Canvas Features

Branch Visualization

The query plan canvas highlights execution branches with color coding:

• Active branch - Currently executing agents (green)
• Completed branch - Finished execution (blue)
• Failed branch - Encountered error (red)
• Pending branch - Waiting for dependencies (gray)

Agent Timeline

View chronological execution in the timeline panel:

• Start/end timestamps per agent
• Token usage and API cost per agent
• Output preview for each completed agent
• Error details for failed agents

Branch Metadata

Inspect metadata for each branch:

{
  "branch_id": "branch_1",
  "parent_branch_id": null,
  "agents": ["planner_1", "executor_1", "executor_2"],
  "status": "completed",
  "total_tokens": 2456,
  "total_cost_usd": 0.047,
  "duration_ms": 3421,
  "merge_point": "merger_1"
}

Common Patterns

Multi-Step RAG

Agent Roles:

• Retriever - Semantic search over knowledge base
• Reranker - Score and filter retrieved docs
• Generator - Synthesize response using top docs
• Validator - Check faithfulness and relevance

Parallel Analysis

Agent Roles:

• Classifier - Categorize document type
• NER Agent - Extract named entities
• Sentiment Agent - Analyze tone and sentiment
• Merger - Combine all analyses into unified output

Iterative Refinement

Agent Roles:

• Generator - Create initial response
• Reviewer - Evaluate quality with rubric
• Refiner - Incorporate feedback and regenerate

Prefab Management

Creating Prefabs

1. Build and test a query plan
2. Click Save as Prefab
3. Define parameters:
   • Name - Descriptive identifier
   • Category - RAG, Analysis, Processing, etc.
   • Description - Use case and expected inputs
   • Parameters - Configurable fields (model, threshold, etc.)
4. Click Publish

Using Prefabs

1. Navigate to Query Plans → Prefabs
2. Browse by category or search
3. Click a prefab to preview
4. Click Use Template to instantiate
5. Customize parameters for your use case

Sharing Prefabs

Prefabs are stored in the M3 Forge database and available to all workspace users. To share across workspaces:

1. Export prefab as JSON
2. Send to other workspace admin
3. Import via Prefabs → Import

Execution and Monitoring

Running Query Plans

Query plans can be executed:

• Manually - Click Run in the editor
• Via API - tRPC endpoint queryPlans.execute
• Via triggers - Schedule or event-based (see Triggers)

Monitoring Runs

Navigate to OPERATE → Runs and filter by type: query_plan:

• Status - Pending, Running, Completed, Failed
• Duration - Total execution time
• Cost - Total API cost across all agents
• Branch count - Number of execution branches

Click a run to view detailed timeline and agent outputs.

Debugging

Use the timeline view to identify issues:

• Slow agents - High duration agents causing bottlenecks
• Failed branches - Agents with errors or timeouts
• Cost spikes - Agents consuming excessive tokens
• Validation failures - Agents producing low-quality outputs

Best Practices

1. Design for reusability - Create prefabs for common patterns
2. Limit parallel branches - Too many parallel agents increase cost and complexity
3. Add validation gates - Use reviewer agents to catch quality issues early
4. Monitor costs - Set token budgets and timeouts for expensive agents
5. Test with edge cases - Validate behavior on unusual or malformed queries
6. Document agent roles - Add descriptions explaining each agent’s responsibility

Example: Customer Support Query Plan

A complete query plan for handling customer support inquiries:

Related Resources

• Building Workflows - General DAG composition
• Nodes - Available node types
• Runs - Monitoring execution
• Agents - Single-agent patterns