agy-bridge

Build LLM agents in Rust — with tools, hooks, streaming, and multimodal input.

Rust bridge for the Google Antigravity SDK via PyO3.

Rust's compile-time checks make it a natural fit for vibe coding agents — schema mismatches, missing parameters, and typos in tool definitions (via #[llm_tool]) are caught at build time, not at runtime.

Installation

Option 1: Native Backend (Pure Rust, default)

Add agy-bridge to your Cargo.toml:

[dependencies]
agy-bridge = "0.16"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

This is the native feature, enabled by default. It talks to the localharness binary directly over WebSocket + protobuf and needs no Python interpreter.

Option 2: Python Backend

Drives the Python SDK in-process via PyO3. Choose this if you need features the native harness does not implement yet (triggers, initial history):

[dependencies]
agy-bridge = { version = "0.16", default-features = false, features = ["python"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Install the Python SDK alongside it:

pip install google-antigravity watchfiles

watchfiles is only needed for file-change triggers; timer triggers work without it.

API Key & Endpoint Setup

Set your API key (or put it in a .env file):

export GEMINI_API_KEY="your-key-here"

For custom gateways or local proxies (e.g. Beyond proxy):

export GEMINI_API_BASE_URL="http://127.0.0.1:8642"

Quick Start

use agy_bridge::AgyBridge;

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;
    let agent = bridge.default_agent().await?;

    // Send a message and get the full reply text.
    let text = agent
        .chat("Reply with 'Hello!' and nothing else.")
        .await?
        .text()
        .await?;
    println!("{text}");

    agent.shutdown().await?;
    Ok(())
}

Streaming Responses

use agy_bridge::{AgyBridge, config::AgentConfig};

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;

    // bridge.agent() returns an AgentBuilder — chain .tools() / .hooks()
    // before .await, or .await directly for a bare agent.
    let agent = bridge
        .agent(
            AgentConfig::builder()
                .system_instructions("You are a poet.")
                .build(),
        )
        .await?;

    let mut response = agent.chat("Write a short poem about space.").await?;

    if let Some(mut stream) = response.take_text_stream() {
        while let Some(chunk) = stream.recv().await {
            print!("{chunk}");
        }
    }
    println!();

    agent.shutdown().await?;
    Ok(())
}

Features

Multimodal Content

Pass text, images, audio, video, and documents in a single chat turn:

use agy_bridge::{
    AgyBridge,
    content::{Content, ContentPrimitive, Image},
};

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;
    let agent = bridge.default_agent().await?;

    // Load an image from a file path (auto-detects MIME type):
    let image = Image::from_file("blank.png")?;

    let content = Content::Multi {
        parts: vec![
            ContentPrimitive::Text { text: "Describe this image.".into() },
            ContentPrimitive::Image(image),
        ],
    };

    let text = agent.chat(content).await?.text().await?;
    println!("{text}");

    agent.shutdown().await?;
    Ok(())
}

Custom Tools

Define tools with the #[llm_tool] proc macro — doc comments become descriptions:

use agy_bridge::{AgyBridge, config::AgentConfig, prelude::*, tools::ToolRegistry};

/// Gets the current weather for a city.
#[llm_tool]
fn get_weather(
    /// The city to look up.
    city: &str,
) -> Result<String, String> {
    Ok(format!("It's sunny in {city}."))
}

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;

    let mut registry = ToolRegistry::new();
    registry.register(GetWeather);

    let agent = bridge
        .agent(AgentConfig::builder().build())
        .tools(registry)
        .await?;

    let text = agent.chat("What's the weather in Tokyo?").await?.text().await?;
    println!("{text}");

    agent.shutdown().await?;
    Ok(())
}

For full control, implement the RustTool trait directly:

use agy_bridge::tools::{JsonSchema, RustTool, ToolContext, ToolError, ToolOutput, ToolRegistry};
use serde::Deserialize;

#[derive(Deserialize, JsonSchema)]
struct SearchParams {
    /// The search query string.
    query: String,
}

struct SearchTool;

impl RustTool for SearchTool {
    type Params = SearchParams;
    const NAME: &'static str = "search";
    const DESCRIPTION: &'static str = "Search a knowledge base";

    async fn call(&self, params: Self::Params, _ctx: &ToolContext) -> Result<ToolOutput, ToolError> {
        Ok(format!("Results for: {}", params.query).into())
    }
}

let registry = ToolRegistry::new().with_tool(SearchTool);
assert_eq!(registry.definitions().len(), 1);

Tool Discovery

After agent creation, inspect all available tools — custom Rust tools, MCP server tools, and SDK builtins — with source, description, and schema:

use agy_bridge::AgyBridge;

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;
    let agent = bridge.default_agent().await?;

    // `tool.source` is a `ToolSource` (Builtin / Custom / Mcp).
    for tool in agent.available_tools() {
        println!("  [{}] {} — {}", tool.source, tool.name, tool.description);
    }

    agent.shutdown().await?;
    Ok(())
}

Structured Output

Constrain agent responses to a typed Rust struct:

use agy_bridge::config::{AgentConfig, JsonSchema};
use schemars::JsonSchema as JsonSchemaTrait;
use serde::Deserialize;

#[derive(Deserialize, JsonSchemaTrait)]
struct Summary {
    title: String,
    bullet_points: Vec<String>,
}

let schema = serde_json::to_value(schemars::schema_for!(Summary))
    .expect("schema serialization");

let config = AgentConfig::builder()
    .response_schema(JsonSchema::new(schema))
    .build();

// The agent's response will be valid JSON matching `Summary`.
assert!(config.response_schema.is_some());

MCP Integration

Connect external MCP servers:

use agy_bridge::config::{AgentConfig, McpServer};

let server = McpServer::stdio("npx")
    .args([
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://postgres:postgres@localhost:5432/postgres",
    ])
    .build();

let config = AgentConfig::builder().mcp_servers([server]).build();
assert_eq!(config.mcp_servers.len(), 1);

Hooks

Register lifecycle callbacks for logging, safety gates, and middleware:

use agy_bridge::{
    AgyBridge,
    config::AgentConfig,
    hooks::{HookResult, Hooks},
};

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;

    let mut hooks = Hooks::new();

    hooks.on_pre_turn("turn_logger", |ctx| {
        println!("[turn {}] {}", ctx.turn_number, ctx.prompt);
        HookResult::allow()
    });

    hooks.on_pre_tool_call_decide("safety_gate", |ctx| {
        if ctx.tool_name == "dangerous_tool" {
            HookResult::deny("blocked by policy")
        } else {
            HookResult::allow()
        }
    });

    hooks.on_stop("audit_stop", |args| {
        println!("Agent stop requested: {:?}", args.stop_reason);
        agy_bridge::hooks::StopHookResult::allow()
    });

    let agent = bridge
        .agent(AgentConfig::builder().build())
        .hooks(hooks)
        .await?;

    let text = agent.chat("What is the capital of Japan?").await?.text().await?;
    println!("{text}");

    agent.shutdown().await?;
    Ok(())
}

Execution Budgets & Shell Safety

Enforce hard operational bounds on model calls, tool calls, and token usage, configure session continuation, and harden background shell commands:

use agy_bridge::config::{
    AgentBehavior, AgentConfig, BudgetConfig, CapabilitiesConfig,
    RunCommandConfig, SessionContinuationMode,
};

let budget = BudgetConfig::builder()
    .max_model_calls(20)
    .max_tool_calls(100)
    .max_total_tokens(500_000)
    .build();

let shell_config = RunCommandConfig::builder()
    .enable_daemons(true)
    .timeout_seconds(60.0)
    .enable_sandbox(true)
    .build();

let config = AgentConfig::builder()
    .session_continuation_mode(SessionContinuationMode::CreateOrResume)
    .budget_config(budget)
    .capabilities(
        CapabilitiesConfig::builder()
            .agent_behavior(AgentBehavior::Autonomous)
            .run_command_config(shell_config)
            .build(),
    )
    .build();

assert!(config.budget_config.is_some());

Policies

Declarative tool access control — first matching rule wins:

use agy_bridge::policies::{PolicyRule, PolicySet};

let mut policies = PolicySet::new();
policies.push(PolicyRule::allow("view_file")).unwrap();
policies.push(PolicyRule::deny("run_command")).unwrap();
policies.push(PolicyRule::deny_all()).unwrap();

assert!(policies.evaluate("view_file").is_allowed());
assert!(policies.evaluate("run_command").is_denied());
assert!(policies.evaluate("unknown_tool").is_denied());

Triggers

Run background tasks that react to timers or file changes:

use agy_bridge::{
    AgyBridge,
    config::AgentConfig,
    triggers::{TriggerConfig, TriggerEntry},
};

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;

    let periodic = TriggerEntry::new(
        "poll_status",
        TriggerConfig::try_every(std::time::Duration::from_secs(30))?,
        "Check deployment status",
    );

    let file_watch = TriggerEntry::new(
        "watch_workspace",
        TriggerConfig::try_on_file_change(std::env::current_dir()?)?,
        "Files changed: {changes}",
    );

    let config = AgentConfig::builder()
        .triggers(vec![periodic, file_watch])
        .build();

    let agent = bridge.agent(config).await?;

    // The agent will now automatically run triggers in the background.
    let text = agent.chat("Hello!").await?.text().await?;
    println!("{text}");

    agent.shutdown().await?;
    Ok(())
}

Note: on_file_change triggers require the watchfiles Python package (pip install watchfiles). Timer triggers (every) work without extra dependencies.

Subagents

Spawn child agents that share the parent's runtime:

use agy_bridge::{AgyBridge, config::AgentConfig};

#[tokio::main]
async fn main() -> Result<(), agy_bridge::error::Error> {
    agy_bridge::load_dotenv();
    let bridge = AgyBridge::builder().build()?;

    let parent = bridge.agent(
        AgentConfig::builder()
            .system_instructions("You are a coordinator.")
            .build(),
    ).await?;

    let child = parent.spawn_subagent(
        AgentConfig::builder()
            .system_instructions("You are a math specialist.")
            .model("gemini-3.5-flash")
            .build(),
        None,
    ).await?;

    let text = child.chat("What is 17 * 23?").await?.text().await?;
    println!("{text}");

    child.shutdown().await?;
    parent.shutdown().await?;
    Ok(())
}

Examples

The examples/ directory has runnable demos:

Getting Started

Deep Dives

cargo run --example getting_started_hello_world

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.

This is not a Google product. Use at your own risk.