Building Multi-Agent Systems with AgentKit 2.0 in Antigravity — A Production Implementation Guide

import { Agent, Workflow, Coordinator } from '@google-cloud/agentkit';
 
// Three specialist researchers
const webSearchAgent = new Agent({
  name: 'web_search_agent',
  systemPrompt: 'Search for information using web sources only.',
  tools: ['google_search', 'summarize'],
  maxIterations: 4,
  timeoutMs: 40000,
});
 
const githubAgent = new Agent({
  name: 'github_agent',
  systemPrompt: 'Find information from GitHub repositories, issues, and discussions.',
  tools: ['github_api', 'code_analysis'],
  maxIterations: 3,
  timeoutMs: 30000,
});
 
const docsAgent = new Agent({
  name: 'docs_agent',
  systemPrompt: 'Extract relevant information from official documentation.',
  tools: ['docs_fetch', 'parse_markdown'],
  maxIterations: 3,
  timeoutMs: 25000,
});
 
// Synthesis Agent
const synthesisAgent = new Agent({
  name: 'synthesis_agent',
  systemPrompt: `You receive research from 3 parallel sources:
- web_search_agent: web findings
- github_agent: GitHub findings  
- docs_agent: documentation findings
 
Synthesize into ONE coherent report. Clearly attribute each claim to its source. Call out conflicts.`,
  tools: ['format', 'validate'],
  maxIterations: 5,
  timeoutMs: 30000,
});
 
// Define the workflow
const researchWorkflow = new Workflow({
  name: 'parallel_research_workflow',
  agents: {
    web: webSearchAgent,
    github: githubAgent,
    docs: docsAgent,
    synthesis: synthesisAgent,
  },
  edges: [
    // All three researchers feed into synthesis
    new Edge('web', 'synthesis', () => true),
    new Edge('github', 'synthesis', () => true),
    new Edge('docs', 'synthesis', () => true),
  ],
});
 
const result = await researchWorkflow.execute({
  input: {
    topic: 'Antigravity IDE 2026 Roadmap',
    context: 'Find the most recent information from all sources',
  },
});
 
console.log(result);
// Output:
// {
//   status: 'success',
//   synthesis_result: { 
//     report: "Antigravity's...",
//     sources: { web: [...], github: [...], docs: [...] }
//   }
// }

// Propose
const proposalAgent = new Agent({
  name: 'proposal_agent',
  systemPrompt: `Generate a concrete implementation plan given a requirement.
Output ONLY valid JSON:
{
  "title": "...",
  "steps": [...],
  "estimated_hours": N,
  "risk_level": "low|medium|high",
  "alternatives": [...]
}`,
  tools: ['plan', 'estimate'],
  maxIterations: 5,
  timeoutMs: 45000,
});
 
// Review
const reviewerAgent = new Agent({
  name: 'reviewer_agent',
  systemPrompt: `You are a technical reviewer. Evaluate the proposal.
Check feasibility, timeline realism, risks.
Output ONLY valid JSON:
{
  "decision": "APPROVED" | "REJECTED",
  "explanation": "..."
}`,
  tools: ['assess_feasibility', 'historical_data'],
  maxIterations: 3,
  timeoutMs: 30000,
});
 
// Execute
const executorAgent = new Agent({
  name: 'executor_agent',
  systemPrompt: `You received an APPROVED proposal.
Break it into actionable tasks, assign resources, set up monitoring.`,
  tools: ['task_create', 'resource_allocate', 'monitoring_setup'],
  maxIterations: 6,
  timeoutMs: 60000,
});
 
// Approval chain
const approvalWorkflow = new Workflow({
  name: 'approval_chain',
  agents: {
    propose: proposalAgent,
    review: reviewerAgent,
    execute: executorAgent,
  },
  edges: [
    new Edge('propose', 'review', () => true),
    // Conditional: only proceed to execute if APPROVED
    new Edge('review', 'execute', (reviewOutput) => {
      return reviewOutput.decision === 'APPROVED';
    }),
  ],
});
 
const approval = await approvalWorkflow.execute({
  input: {
    requirement: 'Add code quality analysis to Antigravity IDE',
    budget_hours: 80,
  },
});
 
console.log(approval);
// Output:
// {
//   status: 'success',
//   proposal: { title: '...', steps: [...], estimated_hours: 72 },
//   review_decision: 'APPROVED',
//   execution_plan: { tasks: [...], resources: [...] }
// }

// Specialists
const architectAgent = new Agent({
  name: 'architect',
  systemPrompt: 'You are a software architect. Design the system architecture.',
  tools: ['design_pattern', 'architecture_decision'],
  maxIterations: 4,
  timeoutMs: 30000,
});
 
const securityAgent = new Agent({
  name: 'security_expert',
  systemPrompt: 'You are a security expert. Identify risks and recommend mitigations.',
  tools: ['threat_analysis', 'security_best_practices'],
  maxIterations: 4,
  timeoutMs: 30000,
});
 
const performanceAgent = new Agent({
  name: 'performance_expert',
  systemPrompt: 'You are a performance engineer. Analyze and suggest optimizations.',
  tools: ['profiling', 'benchmarking'],
  maxIterations: 4,
  timeoutMs: 30000,
});
 
// Director
const supervisorAgent = new Agent({
  name: 'supervisor',
  systemPrompt: `You oversee 3 specialists: architect, security_expert, performance_expert.
Delegate the requirement to each. Collect feedback. Produce a final integrated decision.`,
  tools: ['delegate_task', 'integrate_feedback', 'decision_make'],
  maxIterations: 8,
  timeoutMs: 60000,
});
 
// Hierarchical orchestration
const hierarchicalWorkflow = new Workflow({
  name: 'hierarchical_review',
  agents: {
    supervisor: supervisorAgent,
    architect: architectAgent,
    security: securityAgent,
    performance: performanceAgent,
  },
  edges: [
    // Supervisor delegates to all three specialists
    new Edge('supervisor', 'architect', () => true),
    new Edge('supervisor', 'security', () => true),
    new Edge('supervisor', 'performance', () => true),
  ],
});
 
const result = await hierarchicalWorkflow.execute({
  input: {
    requirement: 'Develop a local LLM plugin for Antigravity',
    constraints: { budget_days: 10, team_size: 2 },
  },
});
 
console.log(result);

// ❌ Naive: fixed timeouts don't adapt
const agent = new Agent({ timeoutMs: 30000 });
 
// ✅ Adaptive: budget remaining time
class AdaptiveAgent {
  private baseTimeoutMs = 30000;
  private workflowStartTime = 0;
  
  async execute(input: any, workflowDeadlineMs: number) {
    const elapsedMs = Date.now() - this.workflowStartTime;
    const remainingMs = workflowDeadlineMs - elapsedMs;
    // Never go below 5s, never exceed base timeout
    const timeoutMs = Math.min(this.baseTimeoutMs, Math.max(remainingMs - 5000, 5000));
    return agent.execute(input, { timeoutMs });
  }
}

// ❌ Vague termination: "determine if reliable"
const agent = new Agent({
  systemPrompt: 'Determine if the information is reliable.',
  maxIterations: 10,
});
 
// ✅ Explicit termination: structured output only
const agent = new Agent({
  systemPrompt: `Determine if the information is reliable.
Output ONLY valid JSON:
{
  "is_reliable": true | false,
  "confidence": 0.0 to 1.0,
  "reasoning": "..."
}
Do not think further once JSON is output.`,
  maxIterations: 3,
});

import { Agent, RateLimiter } from '@google-cloud/agentkit';
 
const rateLimiter = new RateLimiter({
  maxRequests: 100,
  windowMs: 60000, // 100 requests/minute across all agents
});
 
const agent = new Agent({
  name: 'search_agent',
  rateLimiter, // All calls throttled globally
  tools: ['google_search'],
});

// ✅ Defensive parsing
function safeJsonParse(output: string) {
  try {
    return JSON.parse(output);
  } catch (e) {
    // Extract JSON-like content
    const match = output.match(/\{[\s\S]*\}/);
    if (match) {
      try {
        return JSON.parse(match[0]);
      } catch (e2) {
        // Last resort: return raw, flag for human review
        return { raw_output: output, parse_error: true };
      }
    }
    throw new Error('Failed to parse agent output');
  }
}

// Cost tracking per request
interface CostTracker {
  completionTokens: number;
  promptTokens: number;
  costUsd: number;
  estimatedCostUsd: number;
}
 
const tracker: CostTracker = { completionTokens: 0, promptTokens: 0, costUsd: 0, estimatedCostUsd: 0 };
 
const coordinator = new Coordinator({
  workflows: { /* ... */ },
  onAgentComplete: (result) => {
    const { tokens } = result.usage;
    tracker.completionTokens += tokens.completion;
    tracker.promptTokens += tokens.prompt;
    
    // Gemini 1.5 Pro: $7.50/M prompts, $30/M completions
    const costUsd = (tokens.prompt * 7.50 + tokens.completion * 30) / 1_000_000;
    tracker.costUsd += costUsd;
    tracker.estimatedCostUsd = tracker.costUsd * 1.2;
    
    // Hard stop if approaching budget
    if (tracker.estimatedCostUsd > 100) {
      console.warn('Cost limit hit, rolling back...');
      return { action: 'halt' };
    }
  },
});

// Full event trace
const debuggingWorkflow = new Workflow({
  /* ... */
  onEdgeTransition: (from, to, data) => {
    console.log(`[TRACE] ${from} → ${to}`);
    console.log(`[DATA] ${JSON.stringify(data, null, 2)}`);
  },
  onAgentStart: (agentName, input) => {
    console.log(`[START] ${agentName} @ ${new Date().toISOString()}`);
  },
  onAgentError: (agentName, error) => {
    console.error(`[ERROR] ${agentName}:`);
    console.error(error.stack);
  },
});
 
const result = await debuggingWorkflow.execute(input);

interface Trace {
  agent: string;
  startMs: number;
  endMs: number;
  durationMs: number;
  tokens: number;
}
 
const traces: Trace[] = [];
 
coordinator.onAgentComplete = (result) => {
  traces.push({
    agent: result.agent,
    startMs: result.startTime,
    endMs: result.endTime,
    durationMs: result.endTime - result.startTime,
    tokens: result.usage.tokens.total,
  });
};
 
// Identify bottlenecks
function findSlowPath() {
  const totalMs = Math.max(...traces.map(t => t.endMs)) - Math.min(...traces.map(t => t.startMs));
  const criticalPath = traces
    .sort((a, b) => a.startMs - b.startMs)
    .map(t => `${t.agent}(${t.durationMs}ms)`)
    .join(' → ');
  console.log(`Total: ${totalMs}ms\nPath: ${criticalPath}`);
}

const mixedWorkflow = new Workflow({
  agents: {
    research: researchAgent, // AgentKit
    browser_check: new BrowserAgent({
      task: 'Check GitHub Actions deployment status',
    }), // Antigravity built-in
    summary: summaryAgent,
  },
  edges: [
    new Edge('research', 'browser_check'),
    new Edge('browser_check', 'summary'),
  ],
});