Session Management

Installation

JavaScript
Python
HTTPie

npm install agi

pip install pyagi

# macOS
brew install httpie

# Linux
apt install httpie

# Windows
pip install httpie

Quick Reference

Always clean up sessions. The packages handle cleanup automatically.

JavaScript
Python
HTTPie

import { AGIClient } from 'agi';

const client = new AGIClient({ apiKey: 'your_api_key' });

// Usage - manual cleanup
const session = await client.createSession('agi-0');
try {
    const result = await session.runTask('Find iPhone 15 Pro prices');
} finally {
    await session.delete();
}

from pyagi import AGIClient

client = AGIClient(api_key="your_api_key")

# Usage - automatic cleanup
with client.session("agi-0") as session:
    result = session.run_task("Find iPhone 15 Pro prices")

export AGI_API_KEY="your_api_key"

# Create session
SESSION=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 | jq -r '.session_id')

# Send task
http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find iPhone 15 Pro prices"

# Poll for results
while true; do
  STATUS=$(http GET https://api.agi.tech/v1/sessions/$SESSION/status \
    Authorization:"Bearer $AGI_API_KEY" | jq -r '.status')
  if [ "$STATUS" = "finished" ]; then
    http GET https://api.agi.tech/v1/sessions/$SESSION/messages \
      Authorization:"Bearer $AGI_API_KEY" | jq '.messages[] | select(.type=="DONE")'
    break
  fi
  sleep 2
done

# Cleanup
http DELETE https://api.agi.tech/v1/sessions/$SESSION \
  Authorization:"Bearer $AGI_API_KEY"

Always delete sessions. Failing to clean up leads to resource exhaustion and unexpected billing.

Choose the Right Agent

Agent	Use For	Speed
`agi-0`	Complex tasks, analysis, multi-step research	Standard
`agi-0-fast`	Simple tasks, price checks, data extraction	Fast

JavaScript
Python
HTTPie

// Simple task → fast agent
const session1 = await client.createSession('agi-0-fast');
try {
    const result = await session1.runTask('Get iPhone 15 price on Amazon');
} finally {
    await session1.delete();
}

// Complex task → standard agent
const session2 = await client.createSession('agi-0');
try {
    const result = await session2.runTask(`
        Research iPhone 15 Pro:
        1. Compare specs with competitors
        2. Analyze reviews
        3. Find best prices
    `);
} finally {
    await session2.delete();
}

# Simple task → fast agent
with client.session("agi-0-fast") as session:
    result = session.run_task("Get iPhone 15 price on Amazon")

# Complex task → standard agent
with client.session("agi-0") as session:
    result = session.run_task("""
        Research iPhone 15 Pro:
        1. Compare specs with competitors
        2. Analyze reviews
        3. Find best prices
    """)

export AGI_API_KEY="your_api_key"

# Simple task → fast agent
SESSION1=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0-fast | jq -r '.session_id')

http POST https://api.agi.tech/v1/sessions/$SESSION1/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Get iPhone 15 price on Amazon"

# Complex task → standard agent
SESSION2=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 | jq -r '.session_id')

http POST https://api.agi.tech/v1/sessions/$SESSION2/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Research iPhone 15 Pro: 1. Compare specs with competitors 2. Analyze reviews 3. Find best prices"

# Cleanup
http DELETE https://api.agi.tech/v1/sessions/$SESSION1 \
  Authorization:"Bearer $AGI_API_KEY"
http DELETE https://api.agi.tech/v1/sessions/$SESSION2 \
  Authorization:"Bearer $AGI_API_KEY"

Use one session for multiple related tasks to maintain context.

JavaScript
Python
HTTPie

const session = await client.createSession('agi-0');
try {
    // Task 1: Get specs
    const specs = await session.runTask('Find iPhone 15 Pro specifications');
    
    // Task 2: Find prices (same session maintains context)
    const prices = await session.runTask('Find iPhone 15 Pro prices at major retailers');
} finally {
    await session.delete();
}

with client.session("agi-0") as session:
    # Task 1: Get specs
    specs = session.run_task("Find iPhone 15 Pro specifications")
    
    # Task 2: Find prices (same session maintains context)
    prices = session.run_task("Find iPhone 15 Pro prices at major retailers")

export AGI_API_KEY="your_api_key"

# Create session
SESSION=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 | jq -r '.session_id')

# Task 1: Get specs
http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find iPhone 15 Pro specifications"

# Wait for completion, then Task 2: Find prices
while true; do
  STATUS=$(http GET https://api.agi.tech/v1/sessions/$SESSION/status \
    Authorization:"Bearer $AGI_API_KEY" | jq -r '.status')
  if [ "$STATUS" = "finished" ]; then break; fi
  sleep 2
done

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Find iPhone 15 Pro prices at major retailers"

# Cleanup
http DELETE https://api.agi.tech/v1/sessions/$SESSION \
  Authorization:"Bearer $AGI_API_KEY"

Preserve Authentication

Save snapshots to maintain logged-in state across sessions.

JavaScript
Python
HTTPie

// After logging in, save snapshot
const session = await client.createSession('agi-0');
await session.runTask('Login to example.com');
await session.delete({ 
    saveSnapshotMode: 'filesystem', 
    saveAsDefault: true 
});

// Future sessions auto-restore authentication
const newSession = await client.createSession('agi-0', {
    restoreDefaultEnvironmentFromUserId: user_id
});

# After logging in, save snapshot
with client.session("agi-0") as session:
    session.run_task("Login to example.com")
    session.delete(save_snapshot_mode="filesystem", save_as_default=True)

# Future sessions auto-restore authentication
session = client.create_session("agi-0", restore_default_environment_from_user_id=user_id)

export AGI_API_KEY="your_api_key"

# Create session and login
SESSION=$(http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 | jq -r '.session_id')

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Login to example.com"

# Wait for completion, then save snapshot
while true; do
  STATUS=$(http GET https://api.agi.tech/v1/sessions/$SESSION/status \
    Authorization:"Bearer $AGI_API_KEY" | jq -r '.status')
  if [ "$STATUS" = "finished" ]; then break; fi
  sleep 2
done

# Save snapshot on delete
http DELETE "https://api.agi.tech/v1/sessions/$SESSION?save_snapshot_mode=filesystem&save_as_default=true" \
  Authorization:"Bearer $AGI_API_KEY"

# Future sessions auto-restore authentication
http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0 \
  restore_default_environment_from_user_id=$user_id

Use snapshots to preserve cookies, authentication tokens, and browser state.

Best Practices

Always Cleanup

Use try-finally or context managers to ensure session deletion

Choose Right Model

Use agi-0-fast for simple tasks, agi-0 for complex ones

Reuse When Appropriate

Use single session for related sequential tasks

Preserve Authentication

Use snapshots to maintain logged-in sessions

Session Snapshots

Preserve authentication and browser state

Task Design

Write effective task instructions

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

Installation

Quick Reference

Choose the Right Agent

Preserve Authentication

Best Practices

Always Cleanup

Choose Right Model

Reuse When Appropriate

Preserve Authentication

Session Snapshots

Task Design

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

​Installation

​Quick Reference

​Choose the Right Agent

​Reuse Sessions for Related Tasks

​Preserve Authentication

​Best Practices

Always Cleanup

Choose Right Model

Reuse When Appropriate

Preserve Authentication

​Related Guides

Session Snapshots

Task Design

Installation

Quick Reference

Choose the Right Agent

Reuse Sessions for Related Tasks

Preserve Authentication

Best Practices

Related Guides