Talk to the world itself (model world) or an agent: the one named as the model, or the one whose base URL this is
const url = 'http://localhost:11044/api/v1/openai/v1/chat/completions';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"embabel_conversation":"example","embabel_evidence":true,"embabel_observing":true,"embabel_realms":["example"],"embabel_verbosity":"example","max_completion_tokens":1,"max_tokens":1,"messages":[{"content":"example","role":"example"}],"model":"example","stream":true,"temperature":1,"user":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/openai/v1/chat/completions \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "embabel_conversation": "example", "embabel_evidence": true, "embabel_observing": true, "embabel_realms": [ "example" ], "embabel_verbosity": "example", "max_completion_tokens": 1, "max_tokens": 1, "messages": [ { "content": "example", "role": "example" } ], "model": "example", "stream": true, "temperature": 1, "user": "example" }'Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”An OpenAI chat request. model names the agent on /openai/v1, or is world for the world itself, and is ignored on an agent’s own base URL. messages is the history (string content, or the text parts of a part list) and needs at least one non-blank user message, or it is a 400. stream: true answers server-sent chunks, the whole answer arriving as one. temperature and max_completion_tokens (else max_tokens) are held to the agent’s declared sampling bounds and ignored without them, and for the world; user keeps a client’s end users’ chats apart. Embabel extensions: embabel_conversation, a caller-chosen conversation id; embabel_realms, narrowing to some of the agent’s realms (ignored for the world); embabel_verbosity, terse, normal or full; embabel_observing, refusing and reporting every effect the turn attempts (a 400 for the world, which has no routine to observe); embabel_evidence, adding an embabel block with the conversation, run, raised requests and refusals. Other fields, such as tools, are ignored
An OpenAI chat completion request to an agent, sent to POST /openai/v1/chat/completions or /agents/{name}/v1/chat/completions. Fields OpenAI defines and this does not list (tools, top_p…) are ignored; the embabel_ fields are this server’s own.
object
Conversation name the caller chooses: the same name, from any client, continues the same conversation with this agent. Absent or blank, the conversation is recognised from the user and how the history began.
True adds the embabel evidence object to the response (on the final chunk when streaming); otherwise it is absent
True refuses every effect the agent attempts this turn, even if it is on duty, and reports what it would have done
Realm names to narrow the conversation to, from among the agent’s own; never adds one. Absent or empty keeps all of them.
Reply length: terse asks for a sentence or two, full for a full answer, normal (or absent, or any other value) for neither. Case-insensitive.
Reply length cap in tokens, preferred over max_tokens; capped at the agent’s declared most, ignored when it declares none
Reply length cap in tokens, used when max_completion_tokens is absent; capped at the agent’s declared most, ignored when it declares none
The conversation so far, oldest first, as OpenAI clients resend it each time. The newest user message is the turn answered; earlier user and assistant messages are context. At least one non-blank user message is required.
One message of an OpenAI chat request’s history
object
A string, or a list of content parts of which only the {type: text, text} ones are read, joined by newlines; anything else reads as empty
User or assistant; messages with any other role, such as system, are not read
Name of the agent to talk to, as listed by GET /openai/v1/models, or world for the world itself; ignored on an agent’s own base URL, where the path names the agent
True answers as server-sent chat.completion.chunk events ending in [DONE]; the whole answer arrives as one content chunk. Absent or false answers one chat.completion.
Sampling temperature, clamped into the range the agent declares; ignored when the agent declares none
The client’s own end-user id, when it sends one; part of how a conversation is recognised, so two of its users’ chats stay apart
Example generated
{ "embabel_conversation": "example", "embabel_evidence": true, "embabel_observing": true, "embabel_realms": [ "example" ], "embabel_verbosity": "example", "max_completion_tokens": 1, "max_tokens": 1, "messages": [ { "content": "example", "role": "example" } ], "model": "example", "stream": true, "temperature": 1, "user": "example"}Responses
Section titled “Responses”The world’s or the agent’s answer; with stream, server-sent chat.completion.chunk events and [DONE]
An agent’s answer in OpenAI’s chat.completion shape, answered by the chat completions endpoints when stream is not true
object
Exactly one choice, holding the agent’s answer
One answer in a chat completion; there is only ever one
object
Always stop
Always 0
The agent’s answer
object
The agent’s whole answer. When the turn raised requests still waiting for approval, it ends with a note listing each one, the run that raised it, and a link to decide it.
Always assistant
When the turn started, in Unix epoch seconds
What the turn did; present only when the request set embabel_evidence
object
Id of the chat session the turn ran in
What the Gatekeeper refused the agent this turn, each as tool (why), e.g. observing, never or egress; empty when nothing was refused
Requests for a person’s approval this turn’s run raised, in any status; empty when it raised none
A request for a person’s approval raised during a chat completion turn
object
What would happen and why, in the business’s words
Request id, as the approvals surface knows it
Pending, approved, failed, rejected or expired
Gateway tool the request would call on approval, e.g. odoo_partnerMessagePost
Id of the agent run the turn went as; every request it raised names it. Absent when the turn ran as no agent.
Chatcmpl- followed by a random UUID, new for every completion
Name of the agent that answered, or world
Always chat.completion
No user message to answer, or embabel_observing asked of the world itself
An OpenAI-shaped error body, answered by the OpenAI-compatible endpoints when they refuse a request
object
The refusal
object
Model_not_found when no agent of that name may be talked to now, key_scope when the API key does not reach the agent or the world itself, invalid_request when there is no user message to answer or embabel_observing is asked of the world
Human-readable reason, e.g. why the agent may not be talked to now
Always invalid_request_error
No API key or session
An OpenAI-shaped error body, answered by the OpenAI-compatible endpoints when they refuse a request
object
The refusal
object
Model_not_found when no agent of that name may be talked to now, key_scope when the API key does not reach the agent or the world itself, invalid_request when there is no user message to answer or embabel_observing is asked of the world
Human-readable reason, e.g. why the agent may not be talked to now
Always invalid_request_error
This key does not reach that model: an agent outside its scope, or the world itself for any agent key, which needs a full key
An OpenAI-shaped error body, answered by the OpenAI-compatible endpoints when they refuse a request
object
The refusal
object
Model_not_found when no agent of that name may be talked to now, key_scope when the API key does not reach the agent or the world itself, invalid_request when there is no user message to answer or embabel_observing is asked of the world
Human-readable reason, e.g. why the agent may not be talked to now
Always invalid_request_error
No agent of that name may be talked to now
An OpenAI-shaped error body, answered by the OpenAI-compatible endpoints when they refuse a request
object
The refusal
object
Model_not_found when no agent of that name may be talked to now, key_scope when the API key does not reach the agent or the world itself, invalid_request when there is no user message to answer or embabel_observing is asked of the world
Human-readable reason, e.g. why the agent may not be talked to now
Always invalid_request_error