Batch Management

Why Batch Management Matters

Critical System Requirement: All tool approvals within the same toolExecutionBatchId must be responded to simultaneously in a single API call. Individual responses will cause the batch to complete prematurely, potentially leaving some tools unprocessed. This is a fundamental constraint of the approval system that directly impacts both backend processing and user experience design.

Understanding Tool Execution Batches

Batch Identification

Every tool requiring approval includes a toolExecutionBatchId field that groups related tool executions:

{
  "toolExecutionApprovalRequest": [
    {
      "toolExecutionId": "exec_123",
      "toolExecutionBatchId": "batch_456",
      "toolName": "send_email",
      // ... other fields
    },
    {
      "toolExecutionId": "exec_124", 
      "toolExecutionBatchId": "batch_456",
      "toolName": "create_calendar_event",
      // ... other fields
    }
  ]
}

Both tools share batch_456, meaning they must be approved or denied together.

Why Batches Exist

Batches ensure atomic operations and maintain workflow integrity:

Atomic Operations: Related tools succeed or fail together
Workflow Consistency: Prevents partial execution of multi-step processes
User Context: Groups logically related actions for easier decision-making

Batch Response Requirements

Single Response Rule

The backend expects exactly one response containing decisions for all tools in a batch:

// ✅ CORRECT: Single response with all approvals
const batchResponse = {
  content: [
    {
      type: 'tool_approval_result',
      tool_approval_results: [
        {
          toolExecutionId: 'exec_123',
          toolExecutionBatchId: 'batch_456',
          approvalResult: 'APPROVED'
        },
        {
          toolExecutionId: 'exec_124',
          toolExecutionBatchId: 'batch_456', 
          approvalResult: 'DENIED'
        }
      ]
    }
  ]
};

// ❌ INCORRECT: Separate responses
// This will cause premature batch completion
await approveIndividualTool('exec_123', 'APPROVED');
await approveIndividualTool('exec_124', 'DENIED');

Incomplete Batch Consequences

When a batch receives partial responses:

Premature Completion: The agent may respond before all tools are processed
Undefined State: Unresponded tools may be left in pending state
Workflow Failure: Multi-step processes may fail due to missing tool results

UX Implications

Batch Processing Patterns

Recommended: Collect all decisions before submitting

// Collect user decisions for entire batch
const batchDecisions = new Map();
const batchId = 'batch_456';

// User makes decisions through UI
batchDecisions.set('exec_123', 'APPROVED');
batchDecisions.set('exec_124', 'DENIED');

// Submit all decisions at once when batch is complete
if (batchDecisions.size === totalToolsInBatch) {
  submitBatchResponse(batchId, batchDecisions);
}

Avoid: Immediate individual processing

// ❌ This pattern causes batch completion issues
function onApproveButtonClick(toolExecutionId) {
  // Don't immediately submit individual approvals
  submitApproval(toolExecutionId, 'APPROVED'); // WRONG
}

UI Design Patterns

Batch-Aware Interface:

Group tools by toolExecutionBatchId in the UI
Show batch completion progress (e.g., “2 of 3 tools decided”)
Disable submission until all tools in batch are decided
Provide batch-level actions (“Approve All”, “Deny All”)

Example Batch UI State:

interface BatchState {
  batchId: string;
  tools: ToolApprovalRequest[];
  decisions: Map<string, ApprovalDecision>;
  isComplete: boolean;
  canSubmit: boolean;
}

const batchState = {
  batchId: 'batch_456',
  tools: [tool1, tool2, tool3],
  decisions: new Map([
    ['exec_123', 'APPROVED'],
    ['exec_124', 'PENDING'], // Still waiting
    ['exec_125', 'DENIED']
  ]),
  isComplete: false,
  canSubmit: false
};

Implementation Strategies

Batch Collection Pattern

class ApprovalBatchManager {
  private batches = new Map<string, BatchState>();
  
  addApprovalRequest(request: ToolApprovalRequest) {
    const batchId = request.toolExecutionBatchId;
    
    if (!this.batches.has(batchId)) {
      this.batches.set(batchId, {
        batchId,
        tools: [],
        decisions: new Map(),
        isComplete: false
      });
    }
    
    const batch = this.batches.get(batchId)!;
    batch.tools.push(request);
  }
  
  setDecision(toolExecutionId: string, decision: ApprovalDecision) {
    for (const batch of this.batches.values()) {
      if (batch.tools.find(t => t.toolExecutionId === toolExecutionId)) {
        batch.decisions.set(toolExecutionId, decision);
        
        // Check if batch is complete
        if (batch.decisions.size === batch.tools.length) {
          batch.isComplete = true;
          this.submitBatch(batch);
        }
        break;
      }
    }
  }
  
  private submitBatch(batch: BatchState) {
    const approvalResults = Array.from(batch.decisions.entries()).map(
      ([toolExecutionId, decision]) => ({
        toolExecutionId,
        toolExecutionBatchId: batch.batchId,
        approvalResult: decision
      })
    );
    
    // Submit all approvals in single API call
    submitApprovalResponse(approvalResults);
  }
}

Common Pitfalls

Immediate Processing: Don’t submit approvals as soon as user clicks buttons
Ignoring Batch ID: Always group tools by toolExecutionBatchId
Partial Submissions: Never submit incomplete batches
State Management: Don’t lose track of pending decisions across UI updates

Next Steps

Learn about Approval States and their constraints
Review API Integration for proper request formatting
See Best Practices for UX recommendations

Getting Started

Team Personal Assistants

Sub Assistants

Human-in-the-Loop API Guide

Multi-Assistant Collaboration API Guide

Why Batch Management Matters

Understanding Tool Execution Batches

Batch Identification

Why Batches Exist

Batch Response Requirements

Single Response Rule

Incomplete Batch Consequences

UX Implications

Batch Processing Patterns

UI Design Patterns

Implementation Strategies

Batch Collection Pattern

Common Pitfalls

Next Steps

​Why Batch Management Matters

​Understanding Tool Execution Batches

​Batch Identification

​Why Batches Exist

​Batch Response Requirements

​Single Response Rule

​Incomplete Batch Consequences

​UX Implications

​Batch Processing Patterns

​UI Design Patterns

​Implementation Strategies

​Batch Collection Pattern

​Common Pitfalls

​Next Steps

Why Batch Management Matters

Understanding Tool Execution Batches

Batch Identification

Why Batches Exist

Batch Response Requirements

Single Response Rule

Incomplete Batch Consequences

UX Implications

Batch Processing Patterns

UI Design Patterns

Implementation Strategies

Batch Collection Pattern

Common Pitfalls

Next Steps