Agents & Sessions

Agents are the core abstraction in Aphelion. Each agent represents a logical AI application with isolated memory, separate sessions, and independent usage tracking.

What is an Agent?

An agent is a named container that groups together:

Memory

All executions are stored in the agent's memory, searchable semantically

Sessions

Conversations/tasks that group related executions together

Usage

Credits and usage tracked independently per agent

Creating Agents

Agents are created automatically when you execute your first tool with a new agent name:

Python

from aphelion import Aphelion

# Agent "support-bot" is created automatically
client = Aphelion(
    api_key="ap_live_...",
    agent="support-bot"
)

# Execute a tool - agent created on first use
result = client.execute("stripe.customers.list", {})

Explicit Agent Creation

POST/v1/agents

curl -X POST https://api.aphl.ai/v1/agents \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "description": "Customer support automation agent"
  }'

Managing Agents

List Agents

GET/v1/agents

curl https://api.aphl.ai/v1/agents \
  -H "Authorization: Bearer ap_live_..."

Response

{
  "agents": [
    {
      "name": "support-bot",
      "created_at": "2024-01-15T10:30:00Z",
      "total_executions": 1247,
      "memory_count": 892,
      "active_sessions": 3
    },
    {
      "name": "sales-assistant",
      "created_at": "2024-01-10T08:00:00Z",
      "total_executions": 456,
      "memory_count": 234,
      "active_sessions": 1
    }
  ]
}

Get Agent Details

GET/v1/agents/{agent_name}

curl https://api.aphl.ai/v1/agents/support-bot \
  -H "Authorization: Bearer ap_live_..."

Sessions

A session represents a single conversation or task. Sessions group related tool executions together and provide short-term context within a conversation.

Session Behavior

Auto-created on first execution if not specified
Expires after 30 minutes of inactivity
Summarized on completion and stored as memory
Each session belongs to one agent

When to Use Sessions

Multi-turn conversations
Tasks that span multiple tool calls
When you need execution grouping
For context within a conversation

Create Session

POST/v1/agents/{agent_name}/sessions

Python

# Create explicit session
session = client.sessions.create()

print(f"Session ID: {session.id}")
print(f"Expires: {session.expires_at}")

cURL

curl -X POST https://api.aphl.ai/v1/agents/support-bot/sessions \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json"

Tool Execution

Execute tools using the unified /v1/execute endpoint. Tools follow the naming pattern provider.resource.action.

POST/v1/execute

Request Parameters

Parameter	Type	Description
`tool`required	`string`	Tool name (e.g., stripe.customers.create)
`params`required	`object`	Parameters to pass to the tool
`agent`	`string`	Agent name (uses default from SDK init if not specified)
`session_id`	`string`	Session ID (auto-created if not specified)

Basic Execution

Python

from aphelion import Aphelion

client = Aphelion(
    api_key="ap_live_...",
    agent="my-agent"
)

# Execute a tool
result = client.execute(
    "stripe.customers.create",
    {
        "email": "jane@example.com",
        "name": "Jane Doe"
    }
)

print(result)
# {"id": "cus_abc123", "email": "jane@example.com", ...}

cURL Example

curl -X POST https://api.aphl.ai/v1/execute \
  -H "Authorization: Bearer ap_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "stripe.customers.create",
    "params": {
      "email": "jane@example.com",
      "name": "Jane Doe"
    },
    "agent": "my-agent"
  }'

Response

{
  "data": {
    "id": "cus_abc123",
    "object": "customer",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "created": 1704326400
  },
  "meta": {
    "request_id": "req_xyz789",
    "execution_id": "exec_def456",
    "latency_ms": 142,
    "memory_id": "mem_ghi789"
  }
}

ℹ️Automatic Memory

Every execution is automatically summarized and stored in the agent's memory. The memory_id in the response references the stored memory.

Execution with Session Context

For multi-turn conversations, use explicit sessions:

Python

# Create a session
session = client.sessions.create()

# Execute within session context
result1 = client.execute(
    "stripe.customers.create",
    {"email": "jane@example.com"},
    session_id=session.id
)

# Second execution in same session
result2 = client.execute(
    "stripe.subscriptions.create",
    {
        "customer": result1["id"],
        "price": "price_monthly"
    },
    session_id=session.id
)

# Complete the session
summary = session.complete()
print(f"Session summary: {summary.text}")

Tool Naming Convention

Tools follow a consistent naming pattern:

{provider}.{resource}.{action}

# Examples:
stripe.customers.create      # Create Stripe customer
stripe.customers.list        # List Stripe customers
github.repos.list_issues     # List GitHub issues
slack.messages.post          # Post Slack message
notion.pages.create          # Create Notion page

Component	Description	Examples
provider	The API service	stripe, github, slack
resource	The entity type	customers, repos, messages
action	The operation	create, list, update, delete

Error Handling

HTTP Code	Error Code	Description
400	`invalid_params`	Missing or invalid parameters
401	`unauthorized`	Invalid or missing API key
402	`insufficient_credits`	Not enough credits
404	`tool_not_found`	Tool doesn't exist or not subscribed
429	`rate_limited`	Too many requests
502	`upstream_error`	Error from the underlying API

Error Response

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to execute this tool",
    "details": {
      "credits_required": 5,
      "credits_available": 2
    }
  }
}

Next Steps

Tools Catalog

Browse and discover available tools

→

Memory System

Learn how memory and context work

→

Credits & Subscriptions

Understand the billing model

→