Skip to content

Sessions#

The Eden API uses a session-based communication model where you create sessions with specific agents and then exchange messages within those sessions. Each session maintains context and conversation history.

Core Concepts#

Sessions#

Sessions are persistent conversations between your application and Eden's AI agents. They maintain:

  • Context: Conversation history and understanding
  • Agent Relationships: Which agents are participating
  • Budget Management: Resource allocation and usage tracking
  • Configuration: Autonomy settings and behavior parameters

Agents#

Eden provides various AI agents, each with specialized capabilities. You can interact with one or more agents within a single session.

Budgets#

Sessions operate within defined budgets that control resource usage:

  • Manna Budget: Computational resources for agent processing (100-50,000)
  • Token Budget: Text generation limits (1,000-1,000,000)
  • Turn Budget: Maximum conversation exchanges (1-1,000)

Creating a Session#

Before sending messages, you must create a session with one or more agents.

Endpoint: POST https://api.eden.art/v2/sessions/create

Request Body: 

{
  "agent_ids": ["agent-id-1", "agent-id-2"],
  "scenario": "Optional description of what you want to accomplish",
  "title": "Human-readable session title",
  "budget": {
    "manna_budget": 1000,      // Range: 100-50000 (computational resources)
    "token_budget": 10000,     // Range: 1000-1000000 (text generation)
    "turn_budget": 100         // Range: 1-1000 (conversation turns)
  },
  "autonomy_settings": {
    "auto_reply": true,        // Agents respond automatically
    "reply_interval": 5,       // Seconds between responses (0-3600)
    "actor_selection_method": "random"  // How agents are selected to respond
  }
}

Response: 

{
  "session_id": "generated-session-id-string"
}

Example#

const sessionResponse = await fetch('https://api.eden.art/v2/sessions/create', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_ids: ['agent-id-here'],
    title: 'My First Session',
    scenario: 'Help me brainstorm creative ideas',
    budget: {
      manna_budget: 1000,
      token_budget: 10000,
      turn_budget: 100
    },
    autonomy_settings: {
      auto_reply: true,
      reply_interval: 2,
      actor_selection_method: "random"
    }
  })
});

const { session_id } = await sessionResponse.json();

Sending Messages#

Once you have a session ID, you can send messages to the agents.

Endpoint: POST https://api.eden.art/v2/sessions

Request Body: 

{
  "session_id": "your-session-id",
  "content": "Your message to the agent(s)",
  "attachments": ["https://example.com/file1.png"],  // Optional file URLs
  "stream": true,              // Enable real-time streaming responses
  "thinking": true,            // Show agent's reasoning process
  "agent_ids": ["specific-agent-id"]  // Optional: target specific agents only
}

Example#

const messageResponse = await fetch('https://api.eden.art/v2/sessions', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    session_id: session_id,
    content: 'Hello! Can you help me create something amazing?',
    stream: true,
    thinking: true
  })
});

Response Formats#

The API supports both streaming and non-streaming responses:

Streaming Responses (stream: true)#

Receive real-time chunks as content is generated (recommended for better UX):

async function handleStreamingResponse(response, onChunk, onComplete, onError) {
  try {
    const reader = response.body.getReader();
    const decoder = new TextDecoder();
    let buffer = '';

    while (true) {
      const { done, value } = await reader.read();

      if (done) {
        if (buffer) {
          onChunk(buffer);
        }
        onComplete();
        break;
      }

      buffer += decoder.decode(value, { stream: true });

      // Process complete chunks (assuming newline-delimited)
      const lines = buffer.split('\n');
      buffer = lines.pop(); // Keep incomplete line in buffer

      for (const line of lines) {
        if (line.trim()) {
          try {
            const data = JSON.parse(line);
            onChunk(data);
          } catch {
            onChunk(line);
          }
        }
      }
    }
  } catch (error) {
    onError(error);
  }
}

Non-streaming Responses#

Wait for complete response before receiving data:

const data = await response.json();
console.log(data.content);

Session Management#

Get Session Details#

async function getSession(sessionId) {
  const response = await fetch(`https://api.eden.art/v2/sessions/${sessionId}`, {
    headers: {
      'X-Api-Key': 'your-api-key',
      'Content-Type': 'application/json'
    }
  });
  return response.json();
}

List All Sessions#

async function listSessions() {
  const response = await fetch('https://api.eden.art/v2/sessions', {
    headers: {
      'X-Api-Key': 'your-api-key',
      'Content-Type': 'application/json'
    }
  });
  return response.json();
}

Delete Session#

async function deleteSession(sessionId) {
  await fetch(`https://api.eden.art/v2/sessions/${sessionId}`, {
    method: 'DELETE',
    headers: {
      'X-Api-Key': 'your-api-key',
      'Content-Type': 'application/json'
    }
  });
}

Autonomy Settings#

Control how agents behave within sessions:

Auto Reply#

When auto_reply is true, agents will automatically respond to messages without requiring explicit prompting.

Reply Interval#

Sets the delay (in seconds) between agent responses. Range: 0-3600 seconds.

Actor Selection Method#

Determines how agents are chosen to respond in multi-agent sessions:

  • "random": Agents are selected randomly
  • "round_robin": Agents take turns in order
  • "most_relevant": System selects the most appropriate agent

Budget Management#

Monitor and manage resource usage:

Manna Budget#

Computational resources for agent processing. Higher values allow for more complex operations and longer conversations.

Token Budget#

Controls the amount of text generation. Each response consumes tokens based on length and complexity.

Turn Budget#

Limits the total number of message exchanges in a session.

Budget Optimization

Start with conservative budgets and increase as needed. Monitor usage to optimize costs while maintaining quality.

Error Handling#

Common session-related errors:

async function handleSessionError(error) {
  switch (error.response?.status) {
    case 400:
      console.error('Invalid session parameters:', error.message);
      break;
    case 404:
      console.error('Session not found:', error.message);
      break;
    case 409:
      console.error('Session budget exceeded:', error.message);
      break;
    default:
      console.error('Session error:', error.message);
  }
}

Best Practices#

1. Session Lifecycle#

  • Create sessions for specific conversations or tasks
  • Reuse sessions for related interactions
  • Clean up sessions when no longer needed
  • Implement session persistence for better UX

2. Budget Planning#

  • Estimate resource needs before creating sessions
  • Monitor budget usage during conversations
  • Implement warnings when approaching limits
  • Use appropriate budgets for different use cases

3. Agent Selection#

  • Choose agents based on their capabilities
  • Consider multi-agent sessions for complex tasks
  • Use appropriate actor selection methods
  • Test different configurations for optimal results

4. Message Optimization#

  • Be clear and specific in messages
  • Use appropriate streaming settings
  • Handle attachments efficiently
  • Implement proper error recovery

Next Steps#