agi-python 0.0.1

Official Python SDK for AGI.tech API

AGI Python SDK

Website • Documentation • Platform • Blog

---

AI agent that actually works on the web.

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": {...}
# }

---

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.