Quickstart
Start with the service URL, an Organization API Key, an End User ID and a saved AgentTemplate. Provision the End User and select an agentTemplateId from the Template catalog. Keep the Organization Key on your backend.
Create a Session
Section titled “Create a Session”export BASE_URL='https://your-agent-service-host'export ORGANIZATION_API_KEY='<organization-api-key>'export USER_ID='<end-user-id>'export SESSIONS_URL="$BASE_URL/api/v1/org/users/$USER_ID/sessions"
curl --fail-with-body "$SESSIONS_URL" \ -H "Authorization: Bearer $ORGANIZATION_API_KEY" \ -H 'Idempotency-Key: support-session-001' \ -H 'Content-Type: application/json' \ --data '{"agentTemplateId":"<template-id>"}'Save session.sessionId from the response. After an uncertain response, replay the same Idempotency-Key and body. If the selected Template enables cross-Session Recall, send acknowledgeSessionRecall: true to confirm that access.
Send a message and read the result
Section titled “Send a message and read the result”export SESSION_ID='<session-id>'
curl --fail-with-body "$SESSIONS_URL/$SESSION_ID/events" \ -H "Authorization: Bearer $ORGANIZATION_API_KEY" \ -H 'Content-Type: application/json' \ --data '{"type":"agent.session.input.message","clientEventId":"support-message-001","data":{"text":"Hello"}}'
curl --fail-with-body "$SESSIONS_URL/$SESSION_ID/interactions/support-message-001" \ -H "Authorization: Bearer $ORGANIZATION_API_KEY"
curl --fail-with-body "$SESSIONS_URL/$SESSION_ID/turns/<turn-id>" \ -H "Authorization: Bearer $ORGANIZATION_API_KEY"POST returns a command receipt; accepted execution runs on without the response. Read the receipt again with /interactions/{receiptId}, using the clientEventId as the receipt ID, and read the Turn its turnId names with /turns/{turnId} until that Turn’s status is no longer running. To receive progress and results as they happen, your backend follows the Session over a Backend Connection. Reuse the original clientEventId and text when replaying the message.
Continue with Sessions and Turns for Template switches, Session events and recovery for following events and reconnects, or Realtime voice to speak in the same Session.