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

# 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!

# 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)

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

Note: Desktop mode is currently feature-gated. For enterprise access, contact partner@theagi.company.

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

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}")