agi-python 0.5.1

Official Python SDK for AGI.tech API

AGI Python SDK

Website • Documentation • Platform • Blog

---

Universal Computer-Use AI

from agi import AGIClient

client = AGIClient()

with client.session("agi-0") as session:
    result = session.run_task(
        "Find three nonstop flights from SFO to JFK next month under $450. "
        "Return flight times, airlines, and booking links."
    )
    print(result)

Powered by AGI.tech - the world's most capable computer agent. Trusted by Visa for agentic commerce. Evaluated with REAL Bench.

Installation

pip install agi-python

Get your API key at platform.agi.tech

export AGI_API_KEY="your-api-key"

Quick Start

Simple Task

from agi import AGIClient

client = AGIClient()

with client.session("agi-0") as session:
    result = session.run_task("Find the cheapest iPhone 15 on Amazon")
    print(result)

Real-Time Event Streaming

with client.session("agi-0") as session:
    session.send_message("Research the top 5 AI companies in 2025")

    for event in session.stream_events():
        if event.event == "thought":
            print(f"💭 Agent: {event.data}")
        elif event.event == "done":
            print(f"✅ Result: {event.data}")
            break

Session Control

with client.session("agi-0") as session:
    session.send_message("Long research task...")

    # Control execution
    session.pause()    # Pause the agent
    session.resume()   # Resume later
    session.cancel()   # Or cancel

---

Core Concepts

Understanding the building blocks of agi

Sessions: The Container for Tasks

Every task runs inside a session - an isolated browser environment:

# Context manager (recommended) - automatic cleanup
with client.session("agi-0") as session:
    session.run_task("Find flights...")

# Manual management - full control
session = client.sessions.create(agent_name="agi-0")
client.sessions.send_message(session.session_id, "task")
client.sessions.delete(session.session_id)

▸ Use context managers for most tasks. Use manual management when you need fine-grained control.

Available Agents

• agi-0 - General purpose agent (recommended)
• agi-0-fast - Faster agent for simple tasks
• agi-1 - Advanced agent with enhanced capabilities

See docs.agi.tech for the full list.

---

Features

• Natural Language - Describe tasks in plain English, no selectors or scraping code
• Real-Time Streaming - Watch agent execution live with Server-Sent Events
• Session Control - Pause, resume, or cancel long-running tasks
• Browser Control - Navigate and screenshot for visual debugging
• Type-Safe - Full type hints with Pydantic validation
• Production-Ready - Built-in retries, automatic cleanup, comprehensive error handling

---

Common Use Cases

Price Monitoring

Monitor product prices and availability across retailers.

with client.session("agi-0") as session:
    result = session.run_task(
        "Go to amazon.com and search for 'Sony WH-1000XM5'. "
        "Get the current price, check if it's in stock, and return the product rating. "
        "Return as JSON with fields: price, in_stock, rating, url."
    )

Lead Generation

Extract structured data from public sources.

with client.session("agi-0") as session:
    result = session.run_task(
        "Go to ycombinator.com/companies, find companies in the 'AI' category "
        "from the latest batch. For the first 10 companies, get their name, "
        "description, and website. Return as a JSON array."
    )

Flight Booking Research

with client.session("agi-0") as session:
    result = session.run_task(
        "Find three nonstop SFO→JFK flights next month under $450. "
        "Compare prices on Google Flights, Kayak, and Expedia. "
        "Return flight details and booking links."
    )

Browser Control – Navigate and take screenshots for visual debugging

with client.session("agi-0") as session:
    # Navigate to specific URL
    session.navigate("https://amazon.com")

    # Get screenshot for debugging
    screenshot = session.screenshot()
    print(screenshot.url)    # Current page URL
    print(screenshot.title)  # Page title
    # screenshot.screenshot contains base64 JPEG data

Session Snapshots – Preserve authentication and browser state

# Create session and save environment
session1 = client.sessions.create(agent_name="agi-0")
# ... do some work ...
client.sessions.delete(session1.session_id, save_snapshot_mode="filesystem")

# Later, restore from saved environment
session2 = client.sessions.create(
    agent_name="agi-0",
    restore_from_environment_id=session1.environment_id
)
# Authentication state and cookies preserved!

Advanced Session Management – Full control over session lifecycle

# Create session manually
session = client.sessions.create(
    agent_name="agi-0-fast",
    webhook_url="https://yourapp.com/webhook",
    max_steps=200
)

# Send message
client.sessions.send_message(
    session.session_id,
    "Find flights from SFO to JFK under $450"
)

# Check status
status = client.sessions.get_status(session.session_id)
print(status.status)  # "running", "finished", etc.

# List all sessions
sessions = client.sessions.list()

# Delete when done
client.sessions.delete(session.session_id)

Webhooks – Get notified when tasks complete

session = client.sessions.create(
    agent_name="agi-0",
    webhook_url="https://yourapp.com/webhook"
)

# Your webhook will receive events:
# POST https://yourapp.com/webhook
# {
#   "event": "done",
#   "session_id": "sess_...",
#   "data": {...}
# }

Client-Driven Sessions – Run agents on desktop, mobile, or custom environments

Note: Desktop mode is currently feature-gated. For enterprise access, contact [e-mail].

For scenarios where you control the execution environment (desktop automation, mobile apps, custom browsers), use client-driven sessions with AgentLoop:

import asyncio
from agi import AGIClient, AgentLoop

async def main():
    client = AGIClient()

    # Create a client-driven session
    session = client.sessions.create(
        agent_name="agi-2-claude",
        agent_session_type="desktop",
        goal="Open calculator and compute 2+2"
    )

    # Define your callbacks
    async def capture_screenshot() -> str:
        # Return base64-encoded screenshot from your environment
        return "..."

    async def execute_actions(actions):
        for action in actions:
            print(f"Executing: {action['type']}")
            # Execute action in your environment

    # Create and run the loop
    loop = AgentLoop(
        client=client,
        agent_url=session.agent_url,
        capture_screenshot=capture_screenshot,
        execute_actions=execute_actions,
        on_thinking=lambda t: print(f"💭 {t}"),
    )

    result = await loop.start()
    print(f"Finished: {result.finished}")

asyncio.run(main())

Loop Control:

# Start in background
task = asyncio.create_task(loop.start())

# Pause/resume/stop
loop.pause()   # Pause after current step
loop.resume()  # Continue execution
loop.stop()    # Stop the loop

# Check state
loop.state          # LoopState.RUNNING, PAUSED, STOPPED, FINISHED
loop.current_step   # Current step number
loop.last_result    # Last StepDesktopResponse

Manual Step Control:

# Or manage the loop yourself
while not finished:
    screenshot = capture_screenshot()
    result = client.sessions.step(session.agent_url, screenshot)
    execute_actions(result.actions)
    finished = result.finished

---

Error Handling

Robust error handling with detailed debugging

from agi import (
    AGIClient,
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    AgentExecutionError
)

client = AGIClient()

try:
    with client.session("agi-0") as session:
        result = session.run_task("Find flights...")
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Session not found")
except RateLimitError:
    print("Rate limit exceeded - please retry")
except AgentExecutionError as e:
    print(f"Task failed: {e}")
    # Debug at VNC URL if available
except AGIError as e:
    print(f"API error: {e}")

---

Documentation & Resources

Learn More

• API Reference – Complete API documentation
• Code Examples – Working examples for common tasks
• GitHub Issues – Report bugs or request features

Get Help

• Platform – Manage API keys and monitor usage
• Documentation – Guides and tutorials

---

License

MIT License - see LICENSE for details.