Available models
Model availability follows the calling account’s subscription tier, tenant policy, and account-specific LLM profile. Read the current choices before selecting one:key is accepted by the message API. Omitting model uses
defaultModel. Its options list is the effective configuration available to
your account. Each option includes its type, allowed choices, and default value;
option values can be strings, numbers, or booleans.
Select a model
UNKNOWN_MODEL and the valid keys in
error.details.availableModels. Model options are checked against the selected
model’s effective definitions before the run starts; omitted options use their
published defaults.
Choose a persona
A persona sets who the agent is: its name, purpose, and approach. Projects define their own on each branch, and the built-in Davinci persona,standard, is always available. List the ones a
prompt can name, with the project’s default for new chats:
defaultPersonaId is always one of the listed ids, and is standard when the
project sets no default or the branch does not define the one it names.
Send a persona’s id as persona with a message:
persona keeps the one the session is running under, so send standard to
switch back to the built-in persona. An id the branch does not define is
rejected with UNKNOWN_PERSONA, and error.details.definedPersonas lists the
ones that would have worked, starting with standard.
Send images
A prompt can carry up to 10 images for the agent to look at: a photo of a part, a sketch, a screenshot of a drawing. A prompt may be images alone.images is a list of { "mimeType": ..., "data": ... } with the
file base64-encoded in data. Images are PNG, JPEG or WebP, at most 10 MB each,
and the whole request at most 50 MB. The format is read from the bytes, so a
mislabelled file still works, but HEIC photos are refused with
UNSUPPORTED_IMAGE_TYPE. Convert them to JPEG first.
The model must be able to read images. Each entry from agentModels.list has
supportsImages; sending images to a model without it returns
MODEL_CANNOT_READ_IMAGES before anything runs. Images over 2000 pixels on a
side or about 3.7 MB are scaled down before the model sees them, so sending them
at that size or smaller saves upload time and loses nothing.
A transcript describes each prompt’s images instead of including them:
images on the entry lists each one’s index, mimeType and byteSize.
Fetch the bytes by the chat, the entry’s messageId and the index. This works
for any transcript, including one read from a session; use its chatId.
When a run ends
Waiting returns the run’s terminal state. A terminal state is not necessarily a good one: whenstatus is failed, error.message says why, and
error.category names the provider’s error category when the failure came from
the model provider. Read it before closing the session — the same read that
reports the failure carries the reason.
Chats
Every conversation you have with a project’s agent through the API is kept as a chat, and it outlives the session that had it. Chats from any API client (an app, a script, a terminal) share one list per project. Chats started in the web app are not in this list. A new session starts in a fresh chat;session.chatId names it. Nothing is
saved until the first message is sent, so a session that never sends one leaves
no chat behind.
null clears it, and the chat stays untitled. A
title is trimmed and may be up to 200 characters. A fresh chat can’t be renamed
until something has been sent in it; renaming one returns CHAT_EMPTY.
A run keeps going after you switch away from its chat, so one session can have
several chats working at once. Read a chat’s messages to follow its run, or
switch back to carry on in it. Closing the session stops every run it has going.
You don’t have to switch to work in another chat. Pass chatId when sending a
message, stopping, or waiting, and the call goes to that chat while the session
stays in its own. Leave it out and the call goes to the current chat. A session
read lists every chat this session has a run in under agent.chats; the other
agent fields describe the current chat.
CHAT_NOT_FOUND.
A chat belongs to one session at a time. Switching into a chat that another of
your sessions is in, or left a run going in, takes it over. That session’s run
there is stopped, and if it was in the chat it moves to a fresh one.
takenOverFrom in the response lists the sessions it was taken from. Deleting
a chat stops any run in it first, and a session that was in it moves to a fresh
chat.
Watching and taking over a chat in the web app
Your API chats also appear in the Davinci web app, where you can watch a session work in one and take it over. Taking a chat over in the web app stops the session’s run there. The session still knows the chat, but sending or stopping in it answers409 CHAT_TAKEN_OVER until a session switches back into it with
switchChat, which takes it back from the web app.
While a run started in the web app is going in a chat, a session cannot switch
into it or send to it; those calls answer 409 CHAT_IN_USE and change nothing.
Try again once the run ends. A session never stops a run someone started in the
web app.
A run that finished in a chat the session has left drops off agent.chats
about five minutes after it ended, and a session keeps at most four idle runs in
chats it has left. The conversation itself is kept, and sending to the chat
again resumes it.