Articles/Agents & Manager

◈ Agents & Manager/2026-03-29Advanced

Antigravity AgentKit 2.0— to Production Multi-Agent Orchestration

Master AgentKit 2.0 multi-agent orchestration: Manager/Surface/Worker architecture, implementation patterns, and production-ready operational foundations.

AgentKit 2.0¹³ Multi-agent Orchestration⁴ Manager Agent Surface Agent Production Operations

✦ Premium Article

Antigravity's AgentKit 2.0 provides a powerful framework for building multi-agent systems where multiple agents collaborate to accomplish complex tasks. This guide walks you through designing, implementing, and operating agent orchestration systems that reliably run in production environments, complete with real-world code examples.

AgentKit 2.0 Architecture Overview

AgentKit 2.0 distributes large-scale task processing across multiple agents through three primary roles:

Manager Agent (Orchestration Lead)

Receives user requests and analyzes/decomposes tasks
Delegates work to Surface Agents with orchestration
Aggregates results from multiple Surfaces and generates final response
Implements error handling and fallback strategies

Surface Agent (Domain Specialist)

Executes processing specialized to specific domains (data analysis, text generation, image processing)
Manages Worker Agents based on clear Manager directives
Makes complex judgments within expertise area and optimizes workflows

Worker Agent (Execution Unit)

Executes concrete tool invocations, API integrations, and data processing
Takes instructions from Surface Agent and focuses on single responsibility
Reports back error logs and execution metrics

This hierarchy provides clear separation of concerns, allowing each layer to be tested and scaled independently.

Declarative Definition with agents.md

AgentKit 2.0 defines your entire agent system in a declarative agents.md file:

# Company Analytics System
 
## Manager: AnalyticsOrchestrator
role: Coordinates data collection and reporting
instructions: |
  1. Parse user queries for analytics scope
  2. Delegate to DataCollector and ReportGenerator in parallel
  3. Merge results with cross-validation
  4. Return formatted dashboard JSON
 
## Surface: DataCollector
role: Gathers metrics from multiple sources
delegated_workers:
  - GoogleAnalyticsWorker
  - StripeWorker
  - CustomMetricsWorker
 
instructions: |
  Normalize all metrics to common schema
  Validate completeness before returning
 
## Worker: GoogleAnalyticsWorker
role: Fetch GA4 data via API
instructions: |
  1. Authenticate with service account
  2. Query date range from parent instruction
  3. Transform response to standard format
  4. Return with timestamp

This markdown approach makes your agent system architecture immediately clear to the entire team and enables straightforward version control.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦Understand AgentKit 2.0 Manager/Surface/Worker architecture to design scalable agent systems

✦Master implementation patterns for task decomposition, parallel execution, and result aggregation to automate complex workflows

✦Build production-grade operational infrastructure including error recovery, cost control, and security sandboxing

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Manager Agent Task Decomposition Patterns

The Manager Agent must decompose complex requests appropriately and delegate to multiple Surfaces/Workers in parallel. Here's an e-commerce order processing example:

// Manager Agent: OrderProcessingOrchestrator
const managerInstructions = `
You are the Order Processing Manager. Your role is to:
1. Parse incoming orders and validate structure
2. Delegate payment processing to PaymentSurface (parallel)
3. Delegate inventory management to InventorySurface (parallel)
4. Delegate notification to NotificationSurface (parallel)
5. Aggregate results and detect conflicts
6. If conflicts detected, trigger RollbackSurface
7. Return final order status with timestamp
 
Error handling:
- If any Surface returns timeout, delegate to TimeoutRecoveryWorker
- Log all delegations with parent_task_id for tracing
`;
 
// Implementation in AgentKit 2.0
const manager = new Manager({
  name: 'OrderProcessingOrchestrator',
  model: 'claude-opus',
  instructions: managerInstructions,
  surfaces: [
    'PaymentSurface',
    'InventorySurface',
    'NotificationSurface',
    'RollbackSurface'
  ],
  parallel_workers: 3, // Max concurrent Surface invocations
  timeout: 30000,      // 30 seconds total
});

When the Manager delegates to Surfaces, context information (user ID, request metadata, timestamp) is automatically propagated. This ensures traceability across all layers.

Surface Agent Domain Specialization and Parallel Execution

Surface Agents receive high-level Manager directives and execute multiple Workers in parallel. Here's a data analysis Surface example:

// Surface Agent: DataAnalysisSurface
const surfaceInstructions = `
You are the Data Analysis Surface. Your responsibilities:
1. Receive analysis requests from Manager
2. Decompose into atomic analysis tasks:
   - StatisticalAnalysisWorker (descriptive stats, correlations)
   - AnomalyDetectionWorker (outlier identification)
   - TrendAnalysisWorker (time-series forecasting)
3. Execute Workers in parallel using delegation_ids
4. Validate consistency across results
5. Synthesize findings with confidence levels
 
For each Worker result:
- Check for data quality issues
- Map outputs to common schema
- Assign confidence scores
- Return integrated analysis report
`;
 
// Parallel Worker execution
const surface = new Surface({
  name: 'DataAnalysisSurface',
  model: 'claude-sonnet',
  instructions: surfaceInstructions,
  workers: {
    StatisticalAnalysisWorker: {
      role: 'Descriptive statistics and correlations',
      timeout: 15000
    },
    AnomalyDetectionWorker: {
      role: 'Outlier detection and validation',
      timeout: 15000
    },
    TrendAnalysisWorker: {
      role: 'Time-series forecasting',
      timeout: 15000
    }
  },
  max_parallel: 3,
});

The critical point: Surface Agents don't just aggregate Worker results; they perform cross-validation, detecting inconsistencies and mismatches. This significantly improves reliability in production.

Worker Agents and Tool Chain Design

Worker Agents handle concrete tool invocations and external API integrations. The Tool Chain architecture lets workers compose multiple tools into complex workflows:

// Worker Agent: DatabaseQueryWorker
const workerInstructions = `
You are the Database Query Worker. Execute with precision:
1. Receive query specification from parent Surface
2. Build parameterized SQL (using prepared statements)
3. Execute against READ_REPLICA for non-blocking reads
4. Transform results to standard JSON schema
5. Log execution metrics (rows returned, duration, memory)
 
Available tools:
- execute_read_query(sql, params, timeout=5000)
- validate_schema(data, schema_id)
- log_execution_metric(metric_name, value)
 
Security constraints:
- Maximum 10,000 rows per query
- Queries must match pre-approved patterns
- Log all parameters for audit trail
`;
 
// Tool Chain configuration
const toolChain = {
  tools: [
    {
      name: 'execute_read_query',
      description: 'Execute SELECT query on replica',
      input_schema: {
        sql: { type: 'string', description: 'Parameterized SQL' },
        params: { type: 'array', description: 'Query parameters' },
        timeout: { type: 'number', default: 5000 }
      }
    },
    {
      name: 'validate_schema',
      description: 'Validate result against schema',
      input_schema: {
        data: { type: 'object' },
        schema_id: { type: 'string' }
      }
    },
    {
      name: 'log_execution_metric',
      description: 'Log performance metrics',
      input_schema: {
        metric_name: { type: 'string' },
        value: { type: 'number' }
      }
    }
  ]
};
 
const worker = new Worker({
  name: 'DatabaseQueryWorker',
  model: 'claude-haiku', // Cost-optimized for simple tasks
  instructions: workerInstructions,
  tools: toolChain,
  execution_timeout: 30000,
});

This approach leverages the LLM's generality while ensuring reliable system integration through tools.

Error Recovery and Distributed Transactions

Production environments inevitably encounter network latency, timeouts, and partial failures. AgentKit 2.0 supports sophisticated error recovery patterns:

1. Timeout Detection and Retry

// Manager-level timeout handling
const managerConfig = {
  surface_timeout: 30000,
  worker_timeout: 15000,
  max_retries: 2,
  backoff_strategy: 'exponential', // 1s, 2s, 4s
 
  error_handlers: {
    TIMEOUT: (context) => {
      // Escalate to faster fallback
      return context.delegateTo('FastPathSurface');
    },
    NETWORK_ERROR: (context) => {
      // Queue for retry with state preservation
      return context.deferWithState();
    }
  }
};

2. Distributed Transaction Consistency

When multiple Surfaces execute in parallel, ensuring result consistency is critical:

// Saga Pattern implementation in Manager
const managerOrchestration = `
Execute compensation transactions if any Surface fails:
 
Primary flow:
1. PaymentSurface -> charge_id returned
2. InventorySurface -> reserved_items returned
3. ShippingSurface -> shipment_id returned
 
If InventorySurface fails after PaymentSurface succeeded:
1. Trigger PaymentSurface.refund(charge_id)
2. Wait for refund confirmation
3. Log failed order with rollback_reason
4. Notify user with specific failure details
 
Use idempotency keys for all operations:
- payment_idempotency_key = hash(order_id + 'payment')
- inventory_idempotency_key = hash(order_id + 'inventory')
`;

This pattern maintains data consistency even when some services fail.

Context Sharing Mechanism

In multi-agent systems, each agent must carry common context (user info, session ID, auth tokens):

// AgentKit 2.0 Context Management
const contextSchema = {
  request_id: 'uuid',
  user_id: 'string',
  session_token: 'encrypted_jwt',
  auth_scope: ['read:data', 'write:orders'],
  tenant_id: 'string',
  execution_deadline: 'timestamp',
 
  // Propagate through all delegations
  propagate_to_children: true,
 
  // Audit trail
  agent_chain: ['Manager', 'Surface', 'Worker']
};
 
// Automatic context injection
manager.delegate(surface, task, {
  context: requestContext,
  preserve_context: true, // Auto-propagate child calls
  audit_log: true
});

All agents access context as read-only and can append new metadata, enabling end-to-end tracing.

Cost Optimization Strategy

With multiple parallel agents, LLM API costs can balloon quickly. Here are practical optimization techniques:

1. Model Tiering

// Tier cost models by task complexity
const agentModelConfig = {
  Manager: 'claude-opus',          // High cost, high accuracy
  Surface: 'claude-sonnet',        // Mid cost, mid accuracy
  Worker: 'claude-haiku',          // Low cost, lightweight
};
 
// Dynamic model selection based on task
if (task.complexity === 'simple') {
  worker.model = 'claude-haiku';
} else if (task.complexity === 'complex') {
  worker.model = 'claude-sonnet';
}

2. Caching Strategy

// Leverage AgentKit's prompt caching
const cachedSurface = {
  name: 'DataAnalysisSurface',
  system_prompt_cache: true, // Cache surface instructions
  worker_instructions_cache: true,
 
  // Long context cached rarely changes
  cached_context: {
    company_taxonomy: LARGE_JSON,
    metric_definitions: LARGE_JSON,
  }
};
 
// Cache hit results in 90% cost reduction for follow-up calls

3. Batch Processing Efficiency

// Batch multiple worker tasks
const batchConfig = {
  batch_size: 50,
  batch_deadline: 60000, // 1 minute
 
  // Process queue asynchronously
  workers_per_batch: 3,
 
  // Cost reduction: ~40% via batch API
  batch_api_enabled: true
};

Security Sandbox

Multi-agent systems must enforce that agents don't have unlimited permissions:

// AgentKit 2.0 Sandbox Configuration
const sandboxPolicy = {
  worker_capabilities: {
    DatabaseQueryWorker: {
      allowed_tables: ['orders', 'products'],
      blocked_tables: ['users_pii', 'admin_logs'],
      max_rows: 10000,
      read_only: true
    },
    NotificationWorker: {
      allowed_channels: ['email', 'slack'],
      blocked_channels: ['sms'], // Expensive, requires approval
      rate_limit: 1000 // per minute
    }
  },
 
  // Prevent prompt injection via input validation
  input_validation: {
    user_query: (input) => {
      // Tokenize and check for injection patterns
      return sanitizeInput(input);
    }
  },
 
  // Audit all tool invocations
  tool_invocation_logging: true
};

Production Operations Checklist

Before deploying AgentKit 2.0 to production, complete this checklist:

Pre-Deployment Verification

Agent Communication Testing
- Verify Manager delegation to all Surfaces works correctly
- Verify Surface delegation to all Workers works correctly
- Confirm timeout recovery logic activates properly
Error Handling Validation
- Behavior with unexpected inputs at each layer
- Partial failure scenarios (one Worker fails, others succeed)
- Cascade failures (Manager fails, delegated Workers hang)
Performance Testing
- Response times as parallel Worker count increases
- Memory usage progression
- API rate limit handling
Security Audit
- Sandbox constraints are enforced
- Privilege escalation attempts are detected
- Audit logs are complete

Production Monitoring SLOs

const productionSLO = {
  availability: 0.999, // 99.9% uptime
  p99_latency: 5000,   // 5 seconds
  error_rate: 0.001,   // 0.1%
 
  // Agent-specific metrics
  manager_p99: 4000,
  surface_p99: 2000,
  worker_p99: 1000,
 
  // Cost metrics
  max_cost_per_request: 0.05, // USD
  monthly_budget: 10000
};

Rollout Verification Steps

Gradual Rollout: Route 1% of traffic to the new system for 24 hours of monitoring. If error-free, increase to 10%, 50%, 100%.
Canary Deployment

// Traffic splitting configuration
const deploymentConfig = {
  v1_system: { weight: 0.99, agentkit: false },
  v2_agentkit: { weight: 0.01, agentkit: true },
 
  // Monitor divergence in results
  divergence_tolerance: 0.05, // 5% difference acceptable
 
  // Automatic rollback if divergence exceeds threshold
  auto_rollback: true
};

Feedback Loop: Regularly collect user feedback, error logs, and performance metrics to refine your system.

A Note from an Indie Developer

Key Takeaways

Antigravity AgentKit 2.0 is a comprehensive framework for building scalable, reliable multi-agent systems. By combining Manager/Surface/Worker architecture, context sharing, error recovery, cost optimization, and security sandboxing, you can build production-grade AI-driven applications.

Through gradual rollout and continuous monitoring, establish a stable operational foundation that scales with your business needs.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.