> ## Documentation Index
> Fetch the complete documentation index at: https://docs.davinci-app.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Select an available model and send work to a session's agent

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:

```typescript theme={null}
const available = await client.agentModels.list();
console.log(available.defaultModel);
```

```python theme={null}
available = client.agent_models.list()
print(available.default_model)
```

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

```typescript theme={null}
await client.sessions.with(projectId, async (session) => {
  await session.sendMessage({
    message: 'Add a mounting bracket',
    model: 'anthropic:claude-opus-5',
    modelOptions: {
      effort: 'high',
      speed: 'fast',
    },
    webSearch: true,
  });
  await session.waitUntilDone();
});
```

```python theme={null}
with client.sessions.create(project_id) as session:
    session.send_message(
        "Add a mounting bracket",
        model="anthropic:claude-opus-5",
        model_options={
            "effort": "high",
            "speed": "fast",
        },
        web_search=True,
    )
    session.wait_until_done()
```

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](https://docs.davinci-app.com/pages/editor/agent/persona.md) 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:

```typescript theme={null}
const { personas, defaultPersonaId } = await client.projects.listPersonas(projectId);
```

```python theme={null}
result = client.projects.list_personas(project_id)
print(result.default_persona_id)
```

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:

```typescript theme={null}
await session.sendMessage({ message: 'Review the bracket', persona: 'reviewer' });
```

```python theme={null}
session.send_message("Review the bracket", persona="reviewer")
```

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.

```typescript theme={null}
import { readFile } from 'node:fs/promises';

await session.sendMessage({
  message: 'Model a bracket that matches this sketch',
  images: [{ mimeType: 'image/jpeg', bytes: await readFile('sketch.jpg') }],
});
```

```python theme={null}
session.send_message(
    "Model a bracket that matches this sketch",
    images=["sketch.jpg"],
)
```

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`.

```typescript theme={null}
const transcript = await client.chats.messages(projectId, chatId);
for (const entry of transcript.messages) {
  for (const image of entry.images ?? []) {
    const { mimeType, bytes } = await client.chats.messageImage(
      projectId, chatId, entry.messageId!, image.index,
    );
  }
}
```

```python theme={null}
transcript = client.chats.messages(project_id, chat_id)
for entry in transcript.messages:
    for image in entry.images or []:
        picture = client.chats.message_image(
            project_id, chat_id, entry.message_id, image.index
        )
```

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.

```typescript theme={null}
const state = await session.waitUntilDone();
if (state.status === 'failed') {
  console.error(state.error?.message, state.error?.category);
}
```

```python theme={null}
state = session.wait_until_done()
if state.status == "failed":
    print(state.error.message, state.error.category)
```

## 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.

```typescript theme={null}
const { chats } = await client.chats.list(projectId);
for (const chat of chats) console.log(chat.id, chat.title, chat.messageCount);

// Read a chat without a session.
const transcript = await client.chats.messages(projectId, chats[0].id, { limit: 50 });

// Continue it from a session, or start over in a fresh one.
await session.switchChat(chats[0].id);
await session.switchChat(null);

// Rename it, or clear the title with null.
await client.chats.rename(projectId, chats[0].id, 'Bracket redesign');

await client.chats.delete(projectId, chats[0].id);
```

```python theme={null}
chats = client.chats.list(project_id).chats
for chat in chats:
    print(chat.id, chat.title, chat.message_count)

transcript = client.chats.messages(project_id, chats[0].id, limit=50)

session.switch_chat(chats[0].id)
session.switch_chat(None)

client.chats.rename(project_id, chats[0].id, "Bracket redesign")

client.chats.delete(project_id, chats[0].id)
```

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.

```typescript theme={null}
await session.sendMessage({ message: 'Redo the bracket', chatId: otherChatId });
const state = await session.waitUntilDone({ chatId: otherChatId });

const { chats } = await session.status();
await session.stop({ chatId: otherChatId });
```

```python theme={null}
session.send_message("Redo the bracket", chat_id=other_chat_id)
state = session.wait_until_done(chat_id=other_chat_id)

chats = session.status().chats
session.stop(chat_id=other_chat_id)
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.