Session Issues

Session Creation Fails

Problem: Unable to create a new session Quick Fix: Check your API key, rate limits, and agent name.

Check API Key

Verify your API key is correct and active:

JavaScript
Python
HTTPie

const response = await fetch('https://api.agi.tech/v1/models', {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

if (response.status === 401) {
  console.log('Invalid API key');
} else if (response.status === 403) {
  console.log('API key not authorized');
} else {
  console.log('Authentication successful');
}

response = requests.get(
    "https://api.agi.tech/v1/models",
    headers={"Authorization": f"Bearer {API_KEY}"}
)

if response.status_code == 401:
    print("Invalid API key")
elif response.status_code == 403:
    print("API key not authorized")
else:
    print("Authentication successful")

http GET https://api.agi.tech/v1/models \
  Authorization:"Bearer $AGI_API_KEY"

Check Rate Limits

You may have hit rate limits. Implement exponential backoff:

JavaScript
Python
HTTPie

async function createSessionWithRetry(maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await client.createSession('agi-0');
    } catch (e) {
      if (e.response?.status === 429) {
        const waitTime = Math.pow(2, attempt);
        console.log(`Rate limited. Waiting ${waitTime}s...`);
        await new Promise(resolve => setTimeout(resolve, waitTime * 1000));
      } else {
        throw e;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

import time

def create_session_with_retry(max_retries=3):
    for attempt in range(max_retries):
        try:
            return create_session()
        except requests.HTTPError as e:
            if e.response.status_code == 429:
                wait_time = 2 ** attempt
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise
    raise Exception("Max retries exceeded")

# Retry with exponential backoff
for i in {1..3}; do
  http POST https://api.agi.tech/v1/sessions \
    Authorization:"Bearer $AGI_API_KEY" \
    agent_name=agi-0 && break || sleep $((2 ** i))
done

Invalid Agent Name

Ensure you’re using a valid agent name:

JavaScript
Python
HTTPie

const models = await client.getModels();
console.log(`Available models: ${models}`);

const session = await client.createSession('agi-0'); // or 'agi-0-fast'

models = get_available_models()
print(f"Available models: {models}")

session = create_session(agent_name="agi-0")  # or "agi-0-fast"

http GET https://api.agi.tech/v1/models \
  Authorization:"Bearer $AGI_API_KEY"

http POST https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" \
  agent_name=agi-0

Session Not Found (404)

Problem: Get 404 error when accessing a session Common Causes:

Session was deleted
Session ID typo
Session expired

1. Check if session was deleted

List all active sessions to verify:

JavaScript
Python
HTTPie

const sessions = await client.listSessions();
const sessionIds = sessions.map(s => s.session_id);

if (!sessionIds.includes(mySessionId)) {
  console.log('Session no longer exists');
}

sessions = get_all_sessions()
session_ids = [s["session_id"] for s in sessions]

if my_session_id not in session_ids:
    print("Session no longer exists")

http GET https://api.agi.tech/v1/sessions \
  Authorization:"Bearer $AGI_API_KEY" | jq '.[].session_id'

2. Verify session ID is correct

Store session ID immediately after creation:

JavaScript
Python
HTTPie

const session = await client.createSession('agi-0');
const sessionId = session.session_id;

// Save it for later use
fs.writeFileSync('session_id.txt', sessionId);

session = create_session()
session_id = session["session_id"]

with open("session_id.txt", "w") as f:
    f.write(session_id)

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

3. Handle session expiration

Sessions may expire after prolonged inactivity. Create a new session:

JavaScript
Python
HTTPie

async function getOrCreateSession(storedSessionId) {
  try {
    await client.getSessionStatus(storedSessionId);
    return storedSessionId;
  } catch (e) {
    if (e.response?.status === 404) {
      const session = await client.createSession('agi-0');
      return session.session_id;
    }
    throw e;
  }
}

def get_or_create_session(stored_session_id):
    try:
        get_status(stored_session_id)
        return stored_session_id
    except requests.HTTPError as e:
        if e.response.status_code == 404:
            return create_session()["session_id"]
        raise

STATUS=$(http GET https://api.agi.tech/v1/sessions/$SESSION_ID/status \
  Authorization:"Bearer $AGI_API_KEY" | jq -r '.status')

if [ "$STATUS" != "ready" ]; then
  SESSION_ID=$(http POST https://api.agi.tech/v1/sessions \
    Authorization:"Bearer $AGI_API_KEY" \
    agent_name=agi-0 | jq -r '.session_id')
fi

Session Stuck in “Initializing”

Problem: Session status remains “initializing” for too long Solution: Wait with timeout, then retry if needed

JavaScript
Python
HTTPie

async function waitForSessionReady(sessionId, timeout = 60) {
  const startTime = Date.now();
  
  while (true) {
    if (Date.now() - startTime > timeout * 1000) {
      await client.deleteSession(sessionId);
      throw new Error('Session initialization timeout');
    }
    
    const session = await client.getSessionStatus(sessionId);
    const status = session.status;
    
    if (status === 'ready') {
      return true;
    } else if (status === 'error') {
      throw new Error('Session initialization failed');
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
}

// Usage
const session = await client.createSession('agi-0');
await waitForSessionReady(session.session_id);
await client.sendMessage(session.session_id, task);

def wait_for_session_ready(session_id, timeout=60):
    start_time = time.time()
    
    while True:
        if time.time() - start_time > timeout:
            delete_session(session_id)
            raise TimeoutError("Session initialization timeout")
        
        session = get_session(session_id)
        status = session["status"]
        
        if status == "ready":
            return True
        elif status == "error":
            raise Exception("Session initialization failed")
        
        time.sleep(2)

# Usage
session_id = create_session()["session_id"]
wait_for_session_ready(session_id)
send_message(session_id, task)

# Poll until ready
TIMEOUT=60
START=$(date +%s)

while [ $(($(date +%s) - START)) -lt $TIMEOUT ]; do
  STATUS=$(http GET https://api.agi.tech/v1/sessions/$SESSION_ID/status \
    Authorization:"Bearer $AGI_API_KEY" | jq -r '.status')
  
  if [ "$STATUS" = "ready" ]; then
    break
  elif [ "$STATUS" = "error" ]; then
    echo "Session initialization failed"
    exit 1
  fi
  
  sleep 2
done

Session Management

Best practices for managing sessions

Troubleshooting Home

Back to troubleshooting overview

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

Session Creation Fails

Session Not Found (404)

Session Stuck in “Initializing”

Session Management

Troubleshooting Home

Getting Started

Use Cases

Best Practices

Advanced

Troubleshooting

​Session Creation Fails

​Session Not Found (404)

​Session Stuck in “Initializing”

​Related Guides

Session Management

Troubleshooting Home

Session Creation Fails

Session Not Found (404)

Session Stuck in “Initializing”

Related Guides