Google Antigravity TypeScript SDK

The Google Antigravity SDK is a TypeScript/JavaScript SDK for building AI agents powered by Antigravity and Gemini. It provides a secure, scalable, and stateful infrastructure layer that abstracts the agentic loop, letting you focus on what your agent does rather than how it runs.

Installation

npm install antigravity-sdk-ts

[!IMPORTANT] The Google Antigravity SDK relies on a compiled runtime binary (localharness) to orchestrate agent loops. Ensure this runtime is installed and accessible on your system PATH before running the SDK.

Quickstart

Get started by running one of the examples or running the hello world script:

import { Agent, LocalAgentConfig } from 'antigravity-sdk-ts';

async function main() {
  const config = new LocalAgentConfig({
    systemInstructions: 'You are an expert assistant for codebase navigation.',
  });
  
  const agent = new Agent(config);
  await agent.start();
  
  try {
    const response = await agent.chat('What files are in the current directory?');
    console.log(await response.text());
  } finally {
    await agent.close();
  }
}

main().catch(console.error);

Concepts

Simple Agent

The Agent class is the easiest way to get started. It manages the full lifecycle — binary discovery, tool wiring, hook registration, and policy defaults.

You can also use modern Explicit Resource Management (using statements with Symbol.asyncDispose) if your environment supports it:

import { Agent, LocalAgentConfig } from 'antigravity-sdk-ts';

async function main() {
  const config = new LocalAgentConfig();
  
  // Uses Symbol.asyncDispose to automatically clean up resources when exiting block
  await using agent = await new Agent(config).start();
  
  const response = await agent.chat('Hello!');
  console.log(await response.text());
}

Streaming Responses

To stream agent output in real-time (e.g., for fluid UI or console applications), iterate over the ChatResponse object using a for await...of loop:

import { Agent, LocalAgentConfig } from 'antigravity-sdk-ts';

async function main() {
  const config = new LocalAgentConfig();
  const agent = new Agent(config);
  await agent.start();
  
  try {
    const response = await agent.chat('Write a short poem about space.');
    
    for await (const token of response) {
      process.stdout.write(token);
    }
    console.log();
  } finally {
    await agent.close();
  }
}

Sugared Thoughts & Tool Call Streams (Advanced)

For more complex use cases, you can also stream internal model reasoning/thinking or intercept tool call dispatches in real-time using dedicated async generator methods:

// 1. Stream reasoning/thinking deltas
for await (const thought of response.thoughts()) {
  showThinkingBubble(thought);
}

// 2. Stream strongly-typed ToolCall events
for await (const call of response.toolCalls()) {
  showExecutingSpinner(call.name);
}

By default, Agent runs in read-only mode for safety. Pass a custom CapabilitiesConfig to enable write tools or other modifications.

Interactive Loop

import { Agent, LocalAgentConfig, CapabilitiesConfig, runInteractiveLoop } from 'antigravity-sdk-ts';

const config = new LocalAgentConfig({
  capabilities: new CapabilitiesConfig(),
});
const agent = new Agent(config);
await agent.start();

try {
  await runInteractiveLoop(agent);
} finally {
  await agent.close();
}

Advanced Usage with Conversation

For full control over the connection lifecycle, use Conversation with a ConnectionStrategy directly. Conversation is a stateful session that accumulates step history, provides a chat() convenience method, and exposes state introspection:

import {
  LocalConnectionStrategy,
  Conversation,
  ToolRunner,
} from 'antigravity-sdk-ts';

async function main() {
  const toolRunner = new ToolRunner();
  const strategy = new LocalConnectionStrategy(toolRunner);
  
  // Setup strategy connection
  await strategy.__aenter__();
  
  try {
    const connection = strategy.connect();
    const conversation = new Conversation(connection);
    
    // High-level: one-call send + collect
    const response = await conversation.chat('What files are here?');
    console.log(await response.text());
    
    // Step history accumulates automatically
    console.log(`Turns: ${conversation.turnCount}`);
    
    // Low-level: streaming steps
    await conversation.send('Tell me more.');
    for await (const step of conversation.receiveSteps()) {
      if (step.isCompleteResponse) {
        console.log(step.content);
      }
    }
  } finally {
    await strategy.__aexit__();
  }
}

Features

Multimodal Ingestion

Pass rich multimedia file attachments (images, videos, audio, and documents) to the agent alongside textual instructions.

You can attach assets directly using content classes (perfect for in-memory bytes) or conveniently from a filesystem path (which automatically resolves types and guesses MIME formats):

import { Agent, LocalAgentConfig, Image, fromFile } from 'antigravity-sdk-ts';

const config = new LocalAgentConfig();
const agent = new Agent(config);
await agent.start();

try {
  // 1. Filesystem shortcut (automatically resolves file extension and reads contents)
  const pdfSpec = fromFile('spec.pdf');
  
  // 2. Direct constructor instantiation (perfect for in-memory raw bytes)
  const chartImage = new Image(
    new Uint8Array([/* raw PNG bytes */]), 
    'image/png', 
    'Architecture blueprint'
  );
  
  // Send a mixed list of text instructions and content classes
  const prompt = [
    'Analyze this chart against the specification and list three security vulnerabilities:',
    chartImage,
    pdfSpec
  ];
  
  const response = await agent.chat(prompt);
  console.log(await response.text());
} finally {
  await agent.close();
}

Custom Tools

Register TypeScript functions wrapped in ToolWithSchema as tools that the agent can call:

import { Agent, LocalAgentConfig, ToolWithSchema } from 'antigravity-sdk-ts';

function getWeatherFn(args: { city: string }): string {
  return `It's sunny in ${args.city}.`;
}

const getWeather = new ToolWithSchema(
  getWeatherFn,
  {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'The city to get weather for' }
    },
    required: ['city']
  },
  'get_weather',
  'Returns the current weather for a city.'
);

const config = new LocalAgentConfig({
  tools: [getWeather],
});
const agent = new Agent(config);
await agent.start();

try {
  const response = await agent.chat("What's the weather in Tokyo?");
  console.log(await response.text());
} finally {
  await agent.close();
}

MCP Integration

Connect to external MCP servers and expose their tools to the agent:

import { Agent, LocalAgentConfig } from 'antigravity-sdk-ts';

const config = new LocalAgentConfig({
  mcpServers: [
    {
      type: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-postgres', 'postgresql://localhost/mydb']
    }
  ],
});
const agent = new Agent(config);
await agent.start();

try {
  const response = await agent.chat('Query the database.');
} finally {
  await agent.close();
}

Hooks and Policies

Control agent behavior with a declarative policy system:

import { Agent, LocalAgentConfig, CapabilitiesConfig, policy } from 'antigravity-sdk-ts';

const policies = [
  policy.denyAll(),                    // Block all tools by default
  policy.allow('view_file'),           // Allow reading files
  policy.askUser('run_command', myApprovalHandler), // Ask before running commands
];

const config = new LocalAgentConfig({
  capabilities: new CapabilitiesConfig(),
  policies: policies,
});

Triggers

Run background tasks that react to external events and push messages into the agent:

import { Agent, LocalAgentConfig, every, runInteractiveLoop } from 'antigravity-sdk-ts';

async function checkStatus(ctx: any) {
  await ctx.send('Check the deployment status.');
}

const config = new LocalAgentConfig({
  triggers: [every(60, checkStatus)],
});
const agent = new Agent(config);
await agent.start();

try {
  await runInteractiveLoop(agent);
} finally {
  await agent.close();
}

Architecture

The SDK follows a three-layer architecture:

| Layer | Purpose | Key Classes | |:------|:--------|:------------| | Layer 1 — Simplified | High-level, batteries-included entry point | Agent | | Layer 2 — Session | Stateful session with history and convenience methods | Conversation, ChatResponse, Step, ToolCall, AgentConfig, HookRunner, ToolRunner, TriggerRunner | | Layer 3 — Adapter | Transport and backend abstraction | Connection, ConnectionStrategy, LocalConnection |

License

MIT License