Agent Gateway

Session

View as Markdown

Sessions group related gateway requests and agent runs into one user journey, workflow execution, or multi-step task.

Use sessions when a single business interaction includes multiple model calls, tool calls, retries, or agent runs. A support conversation, n8n workflow execution, research job, or paid endpoint call can all be represented as sessions.

Session vs Run vs Request

ConceptScopeExample
SessionBroader interaction or workflow contextOne support case, workflow execution, or customer conversation
RunOne agent task inside the sessionClassify ticket, draft reply, verify refund eligibility
RequestOne gateway model requestA single /v1/chat/completions call

Use one session ID across related runs. Use a new run ID for each task. Use a unique request ID for each gateway request.

HeaderPurpose
alephant-session-idGroups related requests and runs into one session
alephant-session-nameHuman-readable session label
alephant-session-pathOptional workflow or route path
Alephant-Agent-IdStable Alephant agent identity
Alephant-Run-IdOne task execution inside the session
x-request-idOne request-level identifier

Example:

$curl https://ai.alephant.io/v1/chat/completions \
>  -H "Authorization: Bearer $ALEPHANT_VIRTUAL_KEY" \
>  -H "Content-Type: application/json" \
>  -H "alephant-session-id: sess_customer_123_support_20260609" \
>  -H "alephant-session-name: support ticket 8421" \
>  -H "alephant-session-path: /support/triage" \
>  -H "Alephant-Agent-Id: agt_support_bot_8f3a" \
>  -H "Alephant-Run-Id: run_ticket_8421_20260609_001" \
>  -H "x-request-id: 018f7f83-2a7a-7f1a-9b2f-2f2b21e8a001" \
>  -d '{
>    "model": "openai/gpt-4o-mini",
>    "messages": [
>      { "role": "user", "content": "Classify this support ticket." }
>    ]
>  }'

Session Analytics

Session analytics helps answer:

  • Which sessions are active, completed, or intercepted?
  • Which agents and workflows created the most session cost?
  • Which sessions contain policy events?
  • Which sessions had high latency, repeated retries, or unusual token usage?
  • Which session steps contributed to total cost?

The lower-level Analytics API includes session endpoints for session lists, vitals, and session detail. Use the API Reference for exact parameters and response shapes.

Implementation Pattern

  1. Generate or load a stable session ID when the conversation, workflow, or job starts.
  2. Generate a new Run ID for each agent task inside the session.
  3. Send alephant-session-id, Alephant-Agent-Id, and Alephant-Run-Id with every gateway request.
  4. Send x-request-id for each individual request when your application can generate one.
  5. Query logs, analytics, or session detail views to inspect cost, policy events, and execution steps.