Agents API (sessions)
Call an agent through server-kept sessions — create, continue, stream live and read the record. Same interface as OpenAI's Agents API, served by every execution mode (UnieAI Harness, Harness Lite, plain model).
/v1/chat/completions is stateless: every request carries the whole conversation. The Agents API keeps the conversation on the server, so the caller sends only the new message, and it can stream the answer and every step the agent takes (tool calls, retrieval) as they happen.
| Interface | Conversation kept by | Use it for |
|---|---|---|
POST /v1/chat/completions | The caller | Single questions, existing OpenAI SDK integrations |
POST /v1/agents/sessions | The server | Multi-turn conversations, showing the agent's steps live, reviewing records later |
Both use the same API key and the same model ID (the agent's model ID) and are billed the same way.
Endpoints
| Method and path | Purpose |
|---|---|
POST /v1/agents/sessions | Create a session, optionally with the first message (input); with stream: true events stream as SSE until that turn ends |
POST /v1/agents/sessions/{id}/events | Send a new message agent.session.input.message, or cancel the running turn agent.session.input.cancel |
GET /v1/agents/sessions/{id}/events?stream=true | Stream events live (SSE) |
GET /v1/agents/sessions/{id}/events?after={sequence} | Read stored events |
GET /v1/agents/sessions/{id}/items | The conversation (user and agent messages) |
GET /v1/agents/sessions/{id}/turns | Each turn's status, answer, steps, usage and request ID |
GET /v1/agents/sessions?model={model ID} | All sessions of this key with that agent |
GET / DELETE /v1/agents/sessions/{id} | Read or delete a session |
POST accepts an Idempotency-Key header; resending the same message with the same key does not run it twice.
Example
# Create a session with the first message
curl -s https://api.example.com/v1/agents/sessions \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent": {"model": "store-ops-analyst"}, "input": "What was the Xinyi store gross margin last week?"}'
# Continue the same session
curl -s https://api.example.com/v1/agents/sessions/SESSION_ID/events \
-H "Authorization: Bearer sk-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"events": [{"type": "agent.session.input.message", "input": "Compared with the week before?"}]}'
# Stream live
curl -N "https://api.example.com/v1/agents/sessions/SESSION_ID/events?stream=true" \
-H "Authorization: Bearer sk-YOUR_API_KEY"Events
| Event | Meaning |
|---|---|
agent.session.created | Session created |
agent.session.turn.started | A turn started, with its request_id |
agent.session.turn.output_text.delta | Incremental answer text (streamed only, not stored) |
agent.session.turn.step | One step: tool.call, tool.result, step.started or run.notice |
agent.session.turn.output_text.done | The full answer |
agent.session.turn.completed / failed / cancelled | The turn ended, with usage or the error |
agent.session.idle | No messages waiting |
Records in the console
On the agent's page, Request Logs → Sessions lists every session of this agent. Select one to see each turn's question, answer, steps, duration, usage and request ID; the request ID finds the same call in the request log.
An agent set to confirm every tool before it runs is refused on /v1/chat/completions, which has no session to hold the confirmation; use the Agents API.
A model ID that is a plain model connected to api.openai.com (not an agent) is relayed to OpenAI's Agents API.
API Compatibility
Use the OpenAI, Responses, and Anthropic-compatible Runtime endpoints and understand UnieAI extensions, streaming metadata, and upstream differences.
Knowledge Base and Feedback APIs
Search an authorized knowledge base from an external service and submit ratings or explicitly authorized feedback memories for a Customize Model.