Struct Agent 

pub struct Agent { /* private fields */ }

High-level orchestrator that manages an agentic execution session.

An Agent encapsulates binary discovery, WebSocket upgrades, tool wiring, safety policy enforcement, and observer hook dispatch. It provides a simple chat API for sending prompts and retrieving responses.

Examples

use antigravity_sdk_rust::agent::{Agent, AgentConfig};
use antigravity_sdk_rust::policy;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let mut config = AgentConfig::default();
    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    agent.start().await?;

    let response = agent.chat("What is 2+2?").await?;
    println!("Agent: {}", response.text);

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

Implementations

impl Agent

pub fn new(config: AgentConfig) -> Self

Creates a new Agent with the given configuration.

Examples found in repository

examples/hello_world.rs (line 34)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber to print info/debug logs by default
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    // Check if the user specified a binary path or check the environment variable
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    // Configure Gemini Configuration with API Key and explicit model name
    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    // Explicitly set the model to gemini-3.5-flash
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Say 'Hello World!'";
    println!("  User: {}", prompt);

    let response = agent.chat(prompt).await?;
    println!("  Agent: {}", response.text);

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

examples/subagents.rs (line 104)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Enable subagents capability and file viewing
    let capabilities = CapabilitiesConfig {
        enabled_tools: Some(vec![
            BuiltinTools::StartSubagent,
            BuiltinTools::ListDir,
            BuiltinTools::ViewFile,
            BuiltinTools::Finish,
        ]),
        ..Default::default()
    };
    config.capabilities = capabilities;

    // Add Hook for visibility
    let subagent_active = Arc::new(AtomicBool::new(false));
    config
        .hooks
        .push(Arc::new(SubagentHook { subagent_active }));

    // Allow tools
    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Use a subagent to research the files in the current directory. \
                  Delegate the task of listing the directory to the subagent, and then \
                  tell me what files you found.";

    println!("  User: {}", prompt);
    let response = agent.chat(prompt).await?;
    println!("\n  Agent:\n{}", response.text);

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

examples/streaming.rs (line 32)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Solve this riddle: I speak without a mouth and hear without ears. I have no body, but I come alive with wind. What am I? Explain your reasoning.";
    println!("\n  User: {}\n", prompt);

    let conversation = agent.conversation()?;
    let mut stream = conversation.chat(prompt).await?;

    println!("  Agent (Streaming response):");
    println!("  -------------------------------------------------------");

    while let Some(chunk_res) = stream.next().await {
        match chunk_res? {
            StreamChunk::Thought { text, .. } => {
                // Print thought chunks (e.g. in grey or wrapped in brackets if desired, or directly)
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::Text { text, .. } => {
                // Print response text chunks
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::ToolCall(call) => {
                println!(
                    "\n[Tool Call Requested: {} with args: {}]",
                    call.name, call.args
                );
            }
        }
    }
    println!("\n  -------------------------------------------------------\n");

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

examples/custom_tools.rs (line 160)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.system_instructions = Some(antigravity_sdk_rust::types::SystemInstructions::Custom(
        antigravity_sdk_rust::types::CustomSystemInstructions {
            text:
                "You keep track of fruit inventory. To record fruits, you MUST first look up the \
                   fruit's SKU using lookup_fruit_sku, and then use that SKU with record_fruit."
                    .to_string(),
        },
    ));

    // Initialize shared mutable state for stateful tool
    let inventory = Arc::new(Mutex::new(HashMap::new()));

    // Register our custom tools
    config.tools = vec![
        Arc::new(LookupSkuTool),
        Arc::new(RecordFruitTool {
            inventory: inventory.clone(),
        }),
    ];

    // Restrict agent to ONLY these tools
    config.policies = Some(vec![
        policy::deny_all(),
        policy::allow("lookup_fruit_sku"),
        policy::allow("record_fruit"),
    ]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("  === Custom Tools Demo ===");

    // Turn 1: Lookup fruit SKU
    let prompt1 = "What is the SKU for apples? We need to order more.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // Stateful interaction: record fruits across multiple turns
    println!("\n  === Stateful Tool (Fruit Counter) Demo ===");

    let turns = vec![
        "I have 5 apples.",
        "And I just got 3 bananas.",
        "Oh, and another 2 apples.",
    ];

    for user_input in turns {
        println!("\n  User: {}", user_input);
        let response = agent.chat(user_input).await?;
        println!("  Agent: {}", response.text);
    }

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

examples/policies.rs (line 92)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Configure policies using the recommended "Deny by Default" posture.
    let policies = vec![
        // 1. Deny everything by default
        policy::deny_all(),
        // 2. Allow listing directories
        policy::allow("LIST_DIR"),
        // 3. Allow running commands, but block dangerous 'rm' commands
        Policy::new(
            "RUN_COMMAND".to_string(),
            Decision::Deny,
            Some(Arc::new(block_rm_predicate)),
            None,
            "block-rm".to_string(),
        ),
        // Fallback: Allow general RUN_COMMAND calls if they don't match the rm block predicate
        policy::allow("RUN_COMMAND"),
        // 4. Allow editing/creating files, but ask the user first if it's a critical file
        Policy::new(
            "WRITE_TO_FILE".to_string(),
            Decision::AskUser,
            Some(Arc::new(critical_file_predicate)),
            Some(Arc::new(programmatic_approval_handler)),
            "ask-for-critical-writes".to_string(),
        ),
        policy::allow("WRITE_TO_FILE"),
    ];
    config.policies = Some(policies);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("\n  Chatting with agent...");

    // 1. Try a safe command (should be allowed)
    let prompt1 = "List the files in the current directory.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // 2. Try a dangerous command (should be denied by policy)
    let prompt2 = "Delete all files using rm -rf.";
    println!("\n  User: {}", prompt2);
    let response2 = agent.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    // 3. Try creating a critical file (triggers programmatic ask_user handler)
    let prompt3 = "Create a new configuration file named production.key with content 'debug=true'.";
    println!("\n  User: {}", prompt3);
    let response3 = agent.chat(prompt3).await?;
    println!("  Agent: {}", response3.text);

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

examples/persistence.rs (line 46)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    // Create a temporary path for save_dir
    let mut save_dir = std::env::temp_dir();
    let epoch = SystemTime::now()
        .duration_since(SystemTime::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    save_dir.push(format!("agent_session_{}", epoch));
    let save_dir_str = save_dir.to_string_lossy().to_string();
    println!("  Save directory: {}", save_dir_str);

    // Ensure the save_dir exists
    std::fs::create_dir_all(&save_dir)?;

    println!("\n  === Session 1: establishing context ===");

    let mut config1 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config1.binary_path = Some(harness_path);
    }
    let mut gemini_config1 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config1.api_key = Some(api_key);
    }
    gemini_config1.models.default.name = "gemini-3.5-flash".to_string();
    config1.gemini_config = gemini_config1;
    config1.policies = Some(vec![policy::allow_all()]);
    config1.save_dir = Some(save_dir_str.clone());

    let conversation_id = {
        let mut agent1 = Agent::new(config1);
        agent1.start().await?;

        let prompt1 = "Remember this: my favorite color is blue.";
        println!("  User: {}", prompt1);
        let response1 = agent1.chat(prompt1).await?;
        println!("  Agent: {}", response1.text);

        let conv_id = agent1
            .conversation_id()
            .ok_or_else(|| anyhow::anyhow!("Failed to retrieve conversation ID"))?;
        println!("  Assigned conversation ID: {}", conv_id);

        agent1.stop().await?;
        println!("  Session 1 ended.\n");
        conv_id
    };

    println!("  === Session 2: resuming and verifying recall ===");

    let mut config2 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config2.binary_path = Some(harness_path);
    }
    let mut gemini_config2 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config2.api_key = Some(api_key);
    }
    gemini_config2.models.default.name = "gemini-3.5-flash".to_string();
    config2.gemini_config = gemini_config2;
    config2.policies = Some(vec![policy::allow_all()]);
    config2.save_dir = Some(save_dir_str.clone());
    config2.conversation_id = Some(conversation_id);

    let mut agent2 = Agent::new(config2);
    agent2.start().await?;

    let prompt2 = "What is my favorite color?";
    println!("  User: {}", prompt2);
    let response2 = agent2.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    agent2.stop().await?;
    println!("  Session 2 ended.");

    // Clean up temporary session directory
    let _ = std::fs::remove_dir_all(&save_dir);

    Ok(())
}

Additional examples can be found in:

• examples/structured_output.rs

pub fn register_hook(&self, hook: Arc<dyn DynHook>)

Registers a custom lifecycle hook. Hooks can observe or modify agent transitions.

pub fn register_trigger( &mut self, trigger: Arc<dyn DynTrigger>, ) -> Result<(), Error>

Registers a custom background trigger. Triggers must be registered before the agent starts.

Errors

Returns an error if the agent session has already been started.

pub fn register_tool(&self, tool: Arc<dyn DynTool>)

Registers a custom tool available for execution by the agent.

pub async fn start(&mut self) -> Result<(), Error>

Spawns the subprocess communication harness, initializes safety policies, registers tools/hooks, establishes the WebSocket session, and starts any configured triggers.

Errors

Returns an error if:

• The localharness binary cannot be resolved.
• Write tools are enabled but no safety policies are configured.
• The WebSocket upgrade or subprocess connection fails.

Examples found in repository

examples/hello_world.rs (line 36)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber to print info/debug logs by default
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    // Check if the user specified a binary path or check the environment variable
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    // Configure Gemini Configuration with API Key and explicit model name
    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    // Explicitly set the model to gemini-3.5-flash
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Say 'Hello World!'";
    println!("  User: {}", prompt);

    let response = agent.chat(prompt).await?;
    println!("  Agent: {}", response.text);

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

examples/subagents.rs (line 106)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Enable subagents capability and file viewing
    let capabilities = CapabilitiesConfig {
        enabled_tools: Some(vec![
            BuiltinTools::StartSubagent,
            BuiltinTools::ListDir,
            BuiltinTools::ViewFile,
            BuiltinTools::Finish,
        ]),
        ..Default::default()
    };
    config.capabilities = capabilities;

    // Add Hook for visibility
    let subagent_active = Arc::new(AtomicBool::new(false));
    config
        .hooks
        .push(Arc::new(SubagentHook { subagent_active }));

    // Allow tools
    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Use a subagent to research the files in the current directory. \
                  Delegate the task of listing the directory to the subagent, and then \
                  tell me what files you found.";

    println!("  User: {}", prompt);
    let response = agent.chat(prompt).await?;
    println!("\n  Agent:\n{}", response.text);

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

examples/streaming.rs (line 34)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Solve this riddle: I speak without a mouth and hear without ears. I have no body, but I come alive with wind. What am I? Explain your reasoning.";
    println!("\n  User: {}\n", prompt);

    let conversation = agent.conversation()?;
    let mut stream = conversation.chat(prompt).await?;

    println!("  Agent (Streaming response):");
    println!("  -------------------------------------------------------");

    while let Some(chunk_res) = stream.next().await {
        match chunk_res? {
            StreamChunk::Thought { text, .. } => {
                // Print thought chunks (e.g. in grey or wrapped in brackets if desired, or directly)
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::Text { text, .. } => {
                // Print response text chunks
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::ToolCall(call) => {
                println!(
                    "\n[Tool Call Requested: {} with args: {}]",
                    call.name, call.args
                );
            }
        }
    }
    println!("\n  -------------------------------------------------------\n");

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

examples/custom_tools.rs (line 162)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.system_instructions = Some(antigravity_sdk_rust::types::SystemInstructions::Custom(
        antigravity_sdk_rust::types::CustomSystemInstructions {
            text:
                "You keep track of fruit inventory. To record fruits, you MUST first look up the \
                   fruit's SKU using lookup_fruit_sku, and then use that SKU with record_fruit."
                    .to_string(),
        },
    ));

    // Initialize shared mutable state for stateful tool
    let inventory = Arc::new(Mutex::new(HashMap::new()));

    // Register our custom tools
    config.tools = vec![
        Arc::new(LookupSkuTool),
        Arc::new(RecordFruitTool {
            inventory: inventory.clone(),
        }),
    ];

    // Restrict agent to ONLY these tools
    config.policies = Some(vec![
        policy::deny_all(),
        policy::allow("lookup_fruit_sku"),
        policy::allow("record_fruit"),
    ]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("  === Custom Tools Demo ===");

    // Turn 1: Lookup fruit SKU
    let prompt1 = "What is the SKU for apples? We need to order more.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // Stateful interaction: record fruits across multiple turns
    println!("\n  === Stateful Tool (Fruit Counter) Demo ===");

    let turns = vec![
        "I have 5 apples.",
        "And I just got 3 bananas.",
        "Oh, and another 2 apples.",
    ];

    for user_input in turns {
        println!("\n  User: {}", user_input);
        let response = agent.chat(user_input).await?;
        println!("  Agent: {}", response.text);
    }

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

examples/policies.rs (line 94)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Configure policies using the recommended "Deny by Default" posture.
    let policies = vec![
        // 1. Deny everything by default
        policy::deny_all(),
        // 2. Allow listing directories
        policy::allow("LIST_DIR"),
        // 3. Allow running commands, but block dangerous 'rm' commands
        Policy::new(
            "RUN_COMMAND".to_string(),
            Decision::Deny,
            Some(Arc::new(block_rm_predicate)),
            None,
            "block-rm".to_string(),
        ),
        // Fallback: Allow general RUN_COMMAND calls if they don't match the rm block predicate
        policy::allow("RUN_COMMAND"),
        // 4. Allow editing/creating files, but ask the user first if it's a critical file
        Policy::new(
            "WRITE_TO_FILE".to_string(),
            Decision::AskUser,
            Some(Arc::new(critical_file_predicate)),
            Some(Arc::new(programmatic_approval_handler)),
            "ask-for-critical-writes".to_string(),
        ),
        policy::allow("WRITE_TO_FILE"),
    ];
    config.policies = Some(policies);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("\n  Chatting with agent...");

    // 1. Try a safe command (should be allowed)
    let prompt1 = "List the files in the current directory.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // 2. Try a dangerous command (should be denied by policy)
    let prompt2 = "Delete all files using rm -rf.";
    println!("\n  User: {}", prompt2);
    let response2 = agent.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    // 3. Try creating a critical file (triggers programmatic ask_user handler)
    let prompt3 = "Create a new configuration file named production.key with content 'debug=true'.";
    println!("\n  User: {}", prompt3);
    let response3 = agent.chat(prompt3).await?;
    println!("  Agent: {}", response3.text);

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

examples/persistence.rs (line 47)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    // Create a temporary path for save_dir
    let mut save_dir = std::env::temp_dir();
    let epoch = SystemTime::now()
        .duration_since(SystemTime::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    save_dir.push(format!("agent_session_{}", epoch));
    let save_dir_str = save_dir.to_string_lossy().to_string();
    println!("  Save directory: {}", save_dir_str);

    // Ensure the save_dir exists
    std::fs::create_dir_all(&save_dir)?;

    println!("\n  === Session 1: establishing context ===");

    let mut config1 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config1.binary_path = Some(harness_path);
    }
    let mut gemini_config1 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config1.api_key = Some(api_key);
    }
    gemini_config1.models.default.name = "gemini-3.5-flash".to_string();
    config1.gemini_config = gemini_config1;
    config1.policies = Some(vec![policy::allow_all()]);
    config1.save_dir = Some(save_dir_str.clone());

    let conversation_id = {
        let mut agent1 = Agent::new(config1);
        agent1.start().await?;

        let prompt1 = "Remember this: my favorite color is blue.";
        println!("  User: {}", prompt1);
        let response1 = agent1.chat(prompt1).await?;
        println!("  Agent: {}", response1.text);

        let conv_id = agent1
            .conversation_id()
            .ok_or_else(|| anyhow::anyhow!("Failed to retrieve conversation ID"))?;
        println!("  Assigned conversation ID: {}", conv_id);

        agent1.stop().await?;
        println!("  Session 1 ended.\n");
        conv_id
    };

    println!("  === Session 2: resuming and verifying recall ===");

    let mut config2 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config2.binary_path = Some(harness_path);
    }
    let mut gemini_config2 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config2.api_key = Some(api_key);
    }
    gemini_config2.models.default.name = "gemini-3.5-flash".to_string();
    config2.gemini_config = gemini_config2;
    config2.policies = Some(vec![policy::allow_all()]);
    config2.save_dir = Some(save_dir_str.clone());
    config2.conversation_id = Some(conversation_id);

    let mut agent2 = Agent::new(config2);
    agent2.start().await?;

    let prompt2 = "What is my favorite color?";
    println!("  User: {}", prompt2);
    let response2 = agent2.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    agent2.stop().await?;
    println!("  Session 2 ended.");

    // Clean up temporary session directory
    let _ = std::fs::remove_dir_all(&save_dir);

    Ok(())
}

Additional examples can be found in:

• examples/structured_output.rs

pub async fn chat(&self, prompt: &str) -> Result<ChatResponse, Error>

Sends a prompt message to the active agent session and awaits the final completed response.

Errors

Returns an error if the agent is not yet started or if the execution stream encounters a failure.

Examples found in repository

examples/hello_world.rs (line 41)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber to print info/debug logs by default
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    // Check if the user specified a binary path or check the environment variable
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    // Configure Gemini Configuration with API Key and explicit model name
    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    // Explicitly set the model to gemini-3.5-flash
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Say 'Hello World!'";
    println!("  User: {}", prompt);

    let response = agent.chat(prompt).await?;
    println!("  Agent: {}", response.text);

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

examples/subagents.rs (line 113)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Enable subagents capability and file viewing
    let capabilities = CapabilitiesConfig {
        enabled_tools: Some(vec![
            BuiltinTools::StartSubagent,
            BuiltinTools::ListDir,
            BuiltinTools::ViewFile,
            BuiltinTools::Finish,
        ]),
        ..Default::default()
    };
    config.capabilities = capabilities;

    // Add Hook for visibility
    let subagent_active = Arc::new(AtomicBool::new(false));
    config
        .hooks
        .push(Arc::new(SubagentHook { subagent_active }));

    // Allow tools
    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Use a subagent to research the files in the current directory. \
                  Delegate the task of listing the directory to the subagent, and then \
                  tell me what files you found.";

    println!("  User: {}", prompt);
    let response = agent.chat(prompt).await?;
    println!("\n  Agent:\n{}", response.text);

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

examples/custom_tools.rs (line 169)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.system_instructions = Some(antigravity_sdk_rust::types::SystemInstructions::Custom(
        antigravity_sdk_rust::types::CustomSystemInstructions {
            text:
                "You keep track of fruit inventory. To record fruits, you MUST first look up the \
                   fruit's SKU using lookup_fruit_sku, and then use that SKU with record_fruit."
                    .to_string(),
        },
    ));

    // Initialize shared mutable state for stateful tool
    let inventory = Arc::new(Mutex::new(HashMap::new()));

    // Register our custom tools
    config.tools = vec![
        Arc::new(LookupSkuTool),
        Arc::new(RecordFruitTool {
            inventory: inventory.clone(),
        }),
    ];

    // Restrict agent to ONLY these tools
    config.policies = Some(vec![
        policy::deny_all(),
        policy::allow("lookup_fruit_sku"),
        policy::allow("record_fruit"),
    ]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("  === Custom Tools Demo ===");

    // Turn 1: Lookup fruit SKU
    let prompt1 = "What is the SKU for apples? We need to order more.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // Stateful interaction: record fruits across multiple turns
    println!("\n  === Stateful Tool (Fruit Counter) Demo ===");

    let turns = vec![
        "I have 5 apples.",
        "And I just got 3 bananas.",
        "Oh, and another 2 apples.",
    ];

    for user_input in turns {
        println!("\n  User: {}", user_input);
        let response = agent.chat(user_input).await?;
        println!("  Agent: {}", response.text);
    }

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

examples/policies.rs (line 101)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Configure policies using the recommended "Deny by Default" posture.
    let policies = vec![
        // 1. Deny everything by default
        policy::deny_all(),
        // 2. Allow listing directories
        policy::allow("LIST_DIR"),
        // 3. Allow running commands, but block dangerous 'rm' commands
        Policy::new(
            "RUN_COMMAND".to_string(),
            Decision::Deny,
            Some(Arc::new(block_rm_predicate)),
            None,
            "block-rm".to_string(),
        ),
        // Fallback: Allow general RUN_COMMAND calls if they don't match the rm block predicate
        policy::allow("RUN_COMMAND"),
        // 4. Allow editing/creating files, but ask the user first if it's a critical file
        Policy::new(
            "WRITE_TO_FILE".to_string(),
            Decision::AskUser,
            Some(Arc::new(critical_file_predicate)),
            Some(Arc::new(programmatic_approval_handler)),
            "ask-for-critical-writes".to_string(),
        ),
        policy::allow("WRITE_TO_FILE"),
    ];
    config.policies = Some(policies);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("\n  Chatting with agent...");

    // 1. Try a safe command (should be allowed)
    let prompt1 = "List the files in the current directory.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // 2. Try a dangerous command (should be denied by policy)
    let prompt2 = "Delete all files using rm -rf.";
    println!("\n  User: {}", prompt2);
    let response2 = agent.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    // 3. Try creating a critical file (triggers programmatic ask_user handler)
    let prompt3 = "Create a new configuration file named production.key with content 'debug=true'.";
    println!("\n  User: {}", prompt3);
    let response3 = agent.chat(prompt3).await?;
    println!("  Agent: {}", response3.text);

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

examples/persistence.rs (line 51)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    // Create a temporary path for save_dir
    let mut save_dir = std::env::temp_dir();
    let epoch = SystemTime::now()
        .duration_since(SystemTime::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    save_dir.push(format!("agent_session_{}", epoch));
    let save_dir_str = save_dir.to_string_lossy().to_string();
    println!("  Save directory: {}", save_dir_str);

    // Ensure the save_dir exists
    std::fs::create_dir_all(&save_dir)?;

    println!("\n  === Session 1: establishing context ===");

    let mut config1 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config1.binary_path = Some(harness_path);
    }
    let mut gemini_config1 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config1.api_key = Some(api_key);
    }
    gemini_config1.models.default.name = "gemini-3.5-flash".to_string();
    config1.gemini_config = gemini_config1;
    config1.policies = Some(vec![policy::allow_all()]);
    config1.save_dir = Some(save_dir_str.clone());

    let conversation_id = {
        let mut agent1 = Agent::new(config1);
        agent1.start().await?;

        let prompt1 = "Remember this: my favorite color is blue.";
        println!("  User: {}", prompt1);
        let response1 = agent1.chat(prompt1).await?;
        println!("  Agent: {}", response1.text);

        let conv_id = agent1
            .conversation_id()
            .ok_or_else(|| anyhow::anyhow!("Failed to retrieve conversation ID"))?;
        println!("  Assigned conversation ID: {}", conv_id);

        agent1.stop().await?;
        println!("  Session 1 ended.\n");
        conv_id
    };

    println!("  === Session 2: resuming and verifying recall ===");

    let mut config2 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config2.binary_path = Some(harness_path);
    }
    let mut gemini_config2 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config2.api_key = Some(api_key);
    }
    gemini_config2.models.default.name = "gemini-3.5-flash".to_string();
    config2.gemini_config = gemini_config2;
    config2.policies = Some(vec![policy::allow_all()]);
    config2.save_dir = Some(save_dir_str.clone());
    config2.conversation_id = Some(conversation_id);

    let mut agent2 = Agent::new(config2);
    agent2.start().await?;

    let prompt2 = "What is my favorite color?";
    println!("  User: {}", prompt2);
    let response2 = agent2.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    agent2.stop().await?;
    println!("  Session 2 ended.");

    // Clean up temporary session directory
    let _ = std::fs::remove_dir_all(&save_dir);

    Ok(())
}

examples/structured_output.rs (line 114)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Define response schema for meeting summaries and action items
    let response_schema = r#"{
        "type": "object",
        "properties": {
            "action_items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "assignee": { "type": "string" },
                        "task": { "type": "string" },
                        "deadline": { "type": "string" }
                    },
                    "required": ["assignee", "task", "deadline"]
                }
            }
        },
        "required": ["action_items"]
    }"#;
    config.response_schema = Some(response_schema.to_string());

    // Register our custom tool
    config.tools = vec![Arc::new(FetchNotesTool)];

    // Allow our tool and standard tools
    config.policies = Some(vec![
        policy::deny_all(),
        policy::allow("fetch_unstructured_meeting_notes"),
    ]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Use the fetch_unstructured_meeting_notes tool to retrieve notes for \
                  'meeting-2026-05' and return the meeting summary with the appropriate \
                  action item list. Ensure each action item includes 'assignee', \
                  'task', and 'deadline'.";

    println!("\n  Sending prompt to agent...\n  {}", prompt);
    let response = agent.chat(prompt).await?;

    println!("\n  Extracting structured meeting action items...");

    // Find the step that contains structured_output
    let mut found = false;
    for step in &response.steps {
        if let Some(ref structured) = step.structured_output {
            println!("\n  === Structured Meeting Action Items ===");
            if let Some(items) = structured.get("action_items").and_then(Value::as_array) {
                for item in items {
                    println!(
                        "  - Assignee: {:?}",
                        item.get("assignee").and_then(Value::as_str).unwrap_or("")
                    );
                    println!(
                        "    Task:     {:?}",
                        item.get("task").and_then(Value::as_str).unwrap_or("")
                    );
                    println!(
                        "    Deadline: {:?}",
                        item.get("deadline").and_then(Value::as_str).unwrap_or("")
                    );
                    println!();
                }
            } else {
                println!("No action_items field or not an array: {:?}", structured);
            }
            found = true;
            break;
        }
    }

    if !found {
        println!("\n  Failed to extract structured summary natively.");
        println!("  Final Text Response: {}", response.text);
    }

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

pub fn conversation(&self) -> Result<Arc<Conversation>, Error>

Returns the active Conversation session.

Errors

Returns an error if the agent is not yet started.

Examples found in repository

examples/streaming.rs (line 39)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Solve this riddle: I speak without a mouth and hear without ears. I have no body, but I come alive with wind. What am I? Explain your reasoning.";
    println!("\n  User: {}\n", prompt);

    let conversation = agent.conversation()?;
    let mut stream = conversation.chat(prompt).await?;

    println!("  Agent (Streaming response):");
    println!("  -------------------------------------------------------");

    while let Some(chunk_res) = stream.next().await {
        match chunk_res? {
            StreamChunk::Thought { text, .. } => {
                // Print thought chunks (e.g. in grey or wrapped in brackets if desired, or directly)
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::Text { text, .. } => {
                // Print response text chunks
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::ToolCall(call) => {
                println!(
                    "\n[Tool Call Requested: {} with args: {}]",
                    call.name, call.args
                );
            }
        }
    }
    println!("\n  -------------------------------------------------------\n");

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

pub fn conversation_id(&self) -> Option<String>

Returns the active conversation ID if the session has started.

Examples found in repository

examples/persistence.rs (line 55)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    // Create a temporary path for save_dir
    let mut save_dir = std::env::temp_dir();
    let epoch = SystemTime::now()
        .duration_since(SystemTime::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    save_dir.push(format!("agent_session_{}", epoch));
    let save_dir_str = save_dir.to_string_lossy().to_string();
    println!("  Save directory: {}", save_dir_str);

    // Ensure the save_dir exists
    std::fs::create_dir_all(&save_dir)?;

    println!("\n  === Session 1: establishing context ===");

    let mut config1 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config1.binary_path = Some(harness_path);
    }
    let mut gemini_config1 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config1.api_key = Some(api_key);
    }
    gemini_config1.models.default.name = "gemini-3.5-flash".to_string();
    config1.gemini_config = gemini_config1;
    config1.policies = Some(vec![policy::allow_all()]);
    config1.save_dir = Some(save_dir_str.clone());

    let conversation_id = {
        let mut agent1 = Agent::new(config1);
        agent1.start().await?;

        let prompt1 = "Remember this: my favorite color is blue.";
        println!("  User: {}", prompt1);
        let response1 = agent1.chat(prompt1).await?;
        println!("  Agent: {}", response1.text);

        let conv_id = agent1
            .conversation_id()
            .ok_or_else(|| anyhow::anyhow!("Failed to retrieve conversation ID"))?;
        println!("  Assigned conversation ID: {}", conv_id);

        agent1.stop().await?;
        println!("  Session 1 ended.\n");
        conv_id
    };

    println!("  === Session 2: resuming and verifying recall ===");

    let mut config2 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config2.binary_path = Some(harness_path);
    }
    let mut gemini_config2 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config2.api_key = Some(api_key);
    }
    gemini_config2.models.default.name = "gemini-3.5-flash".to_string();
    config2.gemini_config = gemini_config2;
    config2.policies = Some(vec![policy::allow_all()]);
    config2.save_dir = Some(save_dir_str.clone());
    config2.conversation_id = Some(conversation_id);

    let mut agent2 = Agent::new(config2);
    agent2.start().await?;

    let prompt2 = "What is my favorite color?";
    println!("  User: {}", prompt2);
    let response2 = agent2.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    agent2.stop().await?;
    println!("  Session 2 ended.");

    // Clean up temporary session directory
    let _ = std::fs::remove_dir_all(&save_dir);

    Ok(())
}

pub async fn stop(&mut self) -> Result<(), Error>

Gracefully stops the agent connection and disconnects the underlying harness.

Errors

Returns an error if closing the connection fails.

Examples found in repository

examples/hello_world.rs (line 44)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber to print info/debug logs by default
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    // Check if the user specified a binary path or check the environment variable
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    // Configure Gemini Configuration with API Key and explicit model name
    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    // Explicitly set the model to gemini-3.5-flash
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Say 'Hello World!'";
    println!("  User: {}", prompt);

    let response = agent.chat(prompt).await?;
    println!("  Agent: {}", response.text);

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

examples/subagents.rs (line 116)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Enable subagents capability and file viewing
    let capabilities = CapabilitiesConfig {
        enabled_tools: Some(vec![
            BuiltinTools::StartSubagent,
            BuiltinTools::ListDir,
            BuiltinTools::ViewFile,
            BuiltinTools::Finish,
        ]),
        ..Default::default()
    };
    config.capabilities = capabilities;

    // Add Hook for visibility
    let subagent_active = Arc::new(AtomicBool::new(false));
    config
        .hooks
        .push(Arc::new(SubagentHook { subagent_active }));

    // Allow tools
    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Use a subagent to research the files in the current directory. \
                  Delegate the task of listing the directory to the subagent, and then \
                  tell me what files you found.";

    println!("  User: {}", prompt);
    let response = agent.chat(prompt).await?;
    println!("\n  Agent:\n{}", response.text);

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

examples/streaming.rs (line 67)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.policies = Some(vec![policy::allow_all()]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    let prompt = "Solve this riddle: I speak without a mouth and hear without ears. I have no body, but I come alive with wind. What am I? Explain your reasoning.";
    println!("\n  User: {}\n", prompt);

    let conversation = agent.conversation()?;
    let mut stream = conversation.chat(prompt).await?;

    println!("  Agent (Streaming response):");
    println!("  -------------------------------------------------------");

    while let Some(chunk_res) = stream.next().await {
        match chunk_res? {
            StreamChunk::Thought { text, .. } => {
                // Print thought chunks (e.g. in grey or wrapped in brackets if desired, or directly)
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::Text { text, .. } => {
                // Print response text chunks
                print!("{}", text);
                std::io::Write::flush(&mut std::io::stdout())?;
            }
            StreamChunk::ToolCall(call) => {
                println!(
                    "\n[Tool Call Requested: {} with args: {}]",
                    call.name, call.args
                );
            }
        }
    }
    println!("\n  -------------------------------------------------------\n");

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

examples/custom_tools.rs (line 187)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    config.system_instructions = Some(antigravity_sdk_rust::types::SystemInstructions::Custom(
        antigravity_sdk_rust::types::CustomSystemInstructions {
            text:
                "You keep track of fruit inventory. To record fruits, you MUST first look up the \
                   fruit's SKU using lookup_fruit_sku, and then use that SKU with record_fruit."
                    .to_string(),
        },
    ));

    // Initialize shared mutable state for stateful tool
    let inventory = Arc::new(Mutex::new(HashMap::new()));

    // Register our custom tools
    config.tools = vec![
        Arc::new(LookupSkuTool),
        Arc::new(RecordFruitTool {
            inventory: inventory.clone(),
        }),
    ];

    // Restrict agent to ONLY these tools
    config.policies = Some(vec![
        policy::deny_all(),
        policy::allow("lookup_fruit_sku"),
        policy::allow("record_fruit"),
    ]);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("  === Custom Tools Demo ===");

    // Turn 1: Lookup fruit SKU
    let prompt1 = "What is the SKU for apples? We need to order more.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // Stateful interaction: record fruits across multiple turns
    println!("\n  === Stateful Tool (Fruit Counter) Demo ===");

    let turns = vec![
        "I have 5 apples.",
        "And I just got 3 bananas.",
        "Oh, and another 2 apples.",
    ];

    for user_input in turns {
        println!("\n  User: {}", user_input);
        let response = agent.chat(user_input).await?;
        println!("  Agent: {}", response.text);
    }

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

examples/policies.rs (line 116)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    let mut config = AgentConfig::default();

    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config.binary_path = Some(harness_path);
    }

    let mut gemini_config = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config.api_key = Some(api_key);
    }
    gemini_config.models.default.name = "gemini-3.5-flash".to_string();
    config.gemini_config = gemini_config;

    // Configure policies using the recommended "Deny by Default" posture.
    let policies = vec![
        // 1. Deny everything by default
        policy::deny_all(),
        // 2. Allow listing directories
        policy::allow("LIST_DIR"),
        // 3. Allow running commands, but block dangerous 'rm' commands
        Policy::new(
            "RUN_COMMAND".to_string(),
            Decision::Deny,
            Some(Arc::new(block_rm_predicate)),
            None,
            "block-rm".to_string(),
        ),
        // Fallback: Allow general RUN_COMMAND calls if they don't match the rm block predicate
        policy::allow("RUN_COMMAND"),
        // 4. Allow editing/creating files, but ask the user first if it's a critical file
        Policy::new(
            "WRITE_TO_FILE".to_string(),
            Decision::AskUser,
            Some(Arc::new(critical_file_predicate)),
            Some(Arc::new(programmatic_approval_handler)),
            "ask-for-critical-writes".to_string(),
        ),
        policy::allow("WRITE_TO_FILE"),
    ];
    config.policies = Some(policies);

    let mut agent = Agent::new(config);
    println!("Starting agent...");
    agent.start().await?;

    println!("\n  Chatting with agent...");

    // 1. Try a safe command (should be allowed)
    let prompt1 = "List the files in the current directory.";
    println!("\n  User: {}", prompt1);
    let response1 = agent.chat(prompt1).await?;
    println!("  Agent: {}", response1.text);

    // 2. Try a dangerous command (should be denied by policy)
    let prompt2 = "Delete all files using rm -rf.";
    println!("\n  User: {}", prompt2);
    let response2 = agent.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    // 3. Try creating a critical file (triggers programmatic ask_user handler)
    let prompt3 = "Create a new configuration file named production.key with content 'debug=true'.";
    println!("\n  User: {}", prompt3);
    let response3 = agent.chat(prompt3).await?;
    println!("  Agent: {}", response3.text);

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

examples/persistence.rs (line 59)

async fn main() -> Result<(), anyhow::Error> {
    // Initialize tracing subscriber
    tracing_subscriber::fmt()
        .with_env_filter(EnvFilter::try_from_default_env().unwrap_or_else(|_| "info".into()))
        .init();

    // Load environment variables from .env file if present
    dotenvy::dotenv().ok();

    // Create a temporary path for save_dir
    let mut save_dir = std::env::temp_dir();
    let epoch = SystemTime::now()
        .duration_since(SystemTime::UNIX_EPOCH)
        .unwrap_or_default()
        .as_secs();
    save_dir.push(format!("agent_session_{}", epoch));
    let save_dir_str = save_dir.to_string_lossy().to_string();
    println!("  Save directory: {}", save_dir_str);

    // Ensure the save_dir exists
    std::fs::create_dir_all(&save_dir)?;

    println!("\n  === Session 1: establishing context ===");

    let mut config1 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config1.binary_path = Some(harness_path);
    }
    let mut gemini_config1 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config1.api_key = Some(api_key);
    }
    gemini_config1.models.default.name = "gemini-3.5-flash".to_string();
    config1.gemini_config = gemini_config1;
    config1.policies = Some(vec![policy::allow_all()]);
    config1.save_dir = Some(save_dir_str.clone());

    let conversation_id = {
        let mut agent1 = Agent::new(config1);
        agent1.start().await?;

        let prompt1 = "Remember this: my favorite color is blue.";
        println!("  User: {}", prompt1);
        let response1 = agent1.chat(prompt1).await?;
        println!("  Agent: {}", response1.text);

        let conv_id = agent1
            .conversation_id()
            .ok_or_else(|| anyhow::anyhow!("Failed to retrieve conversation ID"))?;
        println!("  Assigned conversation ID: {}", conv_id);

        agent1.stop().await?;
        println!("  Session 1 ended.\n");
        conv_id
    };

    println!("  === Session 2: resuming and verifying recall ===");

    let mut config2 = AgentConfig::default();
    if let Ok(harness_path) = std::env::var("ANTIGRAVITY_HARNESS_PATH") {
        config2.binary_path = Some(harness_path);
    }
    let mut gemini_config2 = GeminiConfig::default();
    if let Ok(api_key) = std::env::var("GEMINI_API_KEY") {
        gemini_config2.api_key = Some(api_key);
    }
    gemini_config2.models.default.name = "gemini-3.5-flash".to_string();
    config2.gemini_config = gemini_config2;
    config2.policies = Some(vec![policy::allow_all()]);
    config2.save_dir = Some(save_dir_str.clone());
    config2.conversation_id = Some(conversation_id);

    let mut agent2 = Agent::new(config2);
    agent2.start().await?;

    let prompt2 = "What is my favorite color?";
    println!("  User: {}", prompt2);
    let response2 = agent2.chat(prompt2).await?;
    println!("  Agent: {}", response2.text);

    agent2.stop().await?;
    println!("  Session 2 ended.");

    // Clean up temporary session directory
    let _ = std::fs::remove_dir_all(&save_dir);

    Ok(())
}

Additional examples can be found in:

• examples/structured_output.rs

Trait Implementations

impl Debug for Agent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.