Your first API session
Creating a session also accepts its first task. Configure the default profile and make the codex template available first.
{
"namespace": "helpdesk",
"external_key": "support.example.com:ticket:4821",
"configuration": {
"agent": {
"profile": "default",
"instructions": "Help the support operator. Explain the likely cause and suggest a reply."
},
"sandbox": {
"template": "codex"
}
},
"messages": [
{
"text": "Ticket 4821: the customer cannot export a report. Ask for the error message.",
"external_key": "support.example.com:event:105",
"metadata": {
"ticket_id": 4821,
"event_id": 105
}
}
]
}This uses the default allow_multiple_runs: false. A new session per task is enough for a simple connector. For an ongoing conversation, set it to true when creating the session. An existing session's mode cannot be changed.
Save the JSON as request.json. Set ORPHEUS_API_KEY in your shell to the server's service key and send:
curl --fail-with-body http://localhost:8000/api/v1/sessions \
-H "Authorization: Bearer $ORPHEUS_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: helpdesk:ticket:4821:event:105' \
--data-binary @request.jsonThe 202 Accepted response contains session_id, run_id and message_id. It confirms admission. Execution results arrive later. Store these identifiers in your system.
namespace groups integration sessions. external_key associates a session with a ticket but does not prevent multiple sessions for that ticket. Use Idempotency-Key for retries.
The task text is in messages[].text. metadata is kept in history and is not passed to the agent. If the agent needs the ticket number, also include it in the text or instructions.