Quickstart

Installation

JavaScript
Python
HTTPie

npm install agi

pip install pyagi

# macOS
brew install httpie

# Linux
apt install httpie

# Windows
pip install httpie

Quick Example

30 seconds to your first agent. Here’s everything you need:

JavaScript
Python
cURL

import { AGIClient } from 'agi';

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

// Create session and run task
const session = await client.createSession('agi-0');
try {
    const result = await session.runTask('Find three nonstop SFO→JFK flights next month under $450');
    console.log(result);
} finally {
    await session.delete();
}

from pyagi import AGIClient

client = AGIClient(api_key="your_api_key")

# Create session and run task
with client.session("agi-0") as session:
    result = session.run_task("Find three nonstop SFO→JFK flights next month under $450")
    print(result)

# Set your API key
export AGI_API_KEY="your_api_key_here"

# 1. Create a session
curl -X POST https://api.agi.tech/v1/sessions \
  -H "Authorization: Bearer $AGI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"agi-0"}'

# 2. Send a message to start a task
curl -X POST https://api.agi.tech/v1/sessions/<session_id>/message \
  -H "Authorization: Bearer $AGI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Find three nonstop SFO→JFK options next month under $450"}'

# 3. Check execution status
curl https://api.agi.tech/v1/sessions/<session_id>/status \
  -H "Authorization: Bearer $AGI_API_KEY"

# 4. Poll for messages
curl "https://api.agi.tech/v1/sessions/<session_id>/messages?after_id=0" \
  -H "Authorization: Bearer $AGI_API_KEY"

# 5. Delete the session when done
curl -X DELETE https://api.agi.tech/v1/sessions/<session_id> \
  -H "Authorization: Bearer $AGI_API_KEY"

Step-by-Step Guide

Follow these steps to deploy your first production-ready agent.

Get your API key

Get Access

Store it securely as it provides access to create and manage agent sessions.

Create a session

Start by creating a new agent session. The packages handle this automatically:

JavaScript
Python
HTTPie

import { AGIClient } from 'agi';

const client = new AGIClient({ apiKey: 'your_api_key' });
const session = await client.createSession('agi-0');

// Get VNC URL to watch agent work
console.log(session.vncUrl);

from pyagi import AGIClient

client = AGIClient(api_key="your_api_key")
session = client.create_session("agi-0")

# Get VNC URL to watch agent work
print(session.vnc_url)

export AGI_API_KEY="your_api_key"

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

# Get VNC URL
http GET https://api.agi.tech/v1/sessions/$SESSION \
  Authorization:"Bearer $AGI_API_KEY" | jq '.vnc_url'

Open the vnc_url in a browser to watch the agent work in real-time!

Send a task message

Give the agent a task. The packages handle polling automatically:

JavaScript
Python
HTTPie

const result = await session.runTask('Search for the top 3 articles about AI agents and summarize them');

result = session.run_task("Search for the top 3 articles about AI agents and summarize them")

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Search for the top 3 articles about AI agents and summarize them"

Monitor progress

The packages automatically poll for results. For real-time updates, use event streaming:

JavaScript
Python
HTTPie

// Automatic polling (default)
const result = await session.runTask('Your task');

// Real-time streaming
for await (const event of session.streamEvents()) {
    console.log(event);
}

# Automatic polling (default)
result = session.run_task("Your task")

# Real-time streaming
async for event in session.stream_events():
    print(event)

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

# Real-time streaming (SSE) - use curl for streaming
curl -N https://api.agi.tech/v1/sessions/$SESSION/events \
  -H "Authorization: Bearer $AGI_API_KEY" \
  -H "Accept: text/event-stream"

Respond to questions

If the agent asks a question, respond using the same method:

JavaScript
Python
HTTPie

const result = await session.runTask('Yes, evening flights are preferred');

result = session.run_task("Yes, evening flights are preferred")

http POST https://api.agi.tech/v1/sessions/$SESSION/message \
  Authorization:"Bearer $AGI_API_KEY" \
  message="Yes, evening flights are preferred"

Clean up

The packages handle cleanup automatically. With context managers (Python) or try/finally (JavaScript):

JavaScript
Python
HTTPie

// Manual cleanup
const session = await client.createSession('agi-0');
try {
    const result = await session.runTask('Your task');
} finally {
    await session.delete();
}

# Automatic cleanup with context manager
with client.session("agi-0") as session:
    result = session.run_task("Your task")
# Session deleted automatically

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

Complete Examples

Here are complete examples using the official packages:

JavaScript
Python
HTTPie

import { AGIClient } from 'agi';

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

// Simple usage with manual cleanup
const session = await client.createSession('agi-0');
try {
    const result = await session.runTask('Find three nonstop SFO→JFK options next month under $450');
    console.log(result);
} finally {
    await session.delete();
}

from pyagi import AGIClient

client = AGIClient(api_key="your_api_key")

# Simple usage with automatic cleanup
with client.session("agi-0") as session:
    result = session.run_task("Find three nonstop SFO→JFK options next month under $450")
    print(result)

# Set your API key
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 three nonstop SFO→JFK options next month under $450"

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

Additional Operations

Control Execution

Pause, resume, or cancel a running task:

JavaScript
Python
HTTPie

// Pause
await session.pause();

// Resume
await session.resume();

// Cancel
await session.cancel();

# Pause
session.pause()

# Resume
session.resume()

# Cancel
session.cancel()

# Pause
http POST https://api.agi.tech/v1/sessions/<session_id>/pause \
  Authorization:"Bearer $AGI_API_KEY"

# Resume
http POST https://api.agi.tech/v1/sessions/<session_id>/resume \
  Authorization:"Bearer $AGI_API_KEY"

# Cancel
http POST https://api.agi.tech/v1/sessions/<session_id>/cancel \
  Authorization:"Bearer $AGI_API_KEY"

Navigate Browser

Manually navigate the browser to a specific URL:

JavaScript
Python
HTTPie

await session.navigate('https://www.example.com');

session.navigate('https://www.example.com')

http POST https://api.agi.tech/v1/sessions/<session_id>/navigate \
  Authorization:"Bearer $AGI_API_KEY" \
  url="https://www.example.com"

Take Screenshot

Get a base64-encoded screenshot of the current browser state:

JavaScript
Python
HTTPie

const screenshot = await session.screenshot();

screenshot = session.screenshot()

http GET https://api.agi.tech/v1/sessions/<session_id>/screenshot \
  Authorization:"Bearer $AGI_API_KEY"

Next Steps

You’re ready to build. Explore these resources to take your agents to the next level:

Full API Reference

Complete endpoint documentation and parameters

Use Cases & Examples

Real-world examples and patterns

Best Practices

Production-ready patterns and optimizations

Error Handling

Robust error handling strategies

Need help? Our team is here to support you. Reach out at [email protected] or visit theagi.company.

Getting Started

Session Management

Agent Interaction

Session Control

Installation

Quick Example

Step-by-Step Guide

Get Access

Complete Examples

Additional Operations

Control Execution

Navigate Browser

Take Screenshot

Next Steps

Full API Reference

Use Cases & Examples

Best Practices

Error Handling

Getting Started

Session Management

Agent Interaction

Session Control

​Installation

​Quick Example

​Step-by-Step Guide

Get Access

​Complete Examples

​Additional Operations

​Control Execution

​Navigate Browser

​Take Screenshot

​Next Steps

Full API Reference

Use Cases & Examples

Best Practices

Error Handling

Installation

Quick Example

Step-by-Step Guide

Complete Examples

Additional Operations

Control Execution

Navigate Browser

Take Screenshot

Next Steps