Skip to main content
An agent runs inside a project session. Create a session, send it a prompt, and poll the session until the agent reaches a terminal state.

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:
Each entry’s 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

The model key is checked against the account’s current choices. An unavailable key is rejected with 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:
The built-in persona comes first, followed by the branch’s own personas. The list reads the running project, so it includes uncommitted edits. 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:
The persona applies to that prompt and every later one in the session. Omitting 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.
Over HTTP, 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.
A prompt’s images never change, so a fetched image can be cached.

When a run ends

Waiting returns the run’s terminal state. A terminal state is not necessarily a good one: when status 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.
A chat is titled from its opening message. Renaming it sets a title that is kept as the conversation goes on; 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.
Sending to a chat in your list that this session has no run in claims it for this session, the same way switching into it would, but leaves the session’s current chat where it is. Stopping only reaches chats this session has; naming any other chat returns 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 answers 409 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.