# Set the graph conductor of a v2 avatar

URL: https://www.atmee.ai/docs/v2/api/reference/avatars/setAvatarConductor

`PUT /v1/avatars/{avatarId}/conductor`

Gives the avatar's conversations an agenda: a graph of steps, each
with the avatar's instructions while the conversation is in it, and
edges that say when it moves on. At the end of every turn a judge
model gives each condition (`when`) of the current step the
probability that it holds; edges without a condition share the
probability that none holds, by `weight`. The step then takes its
likeliest edge (or, marked `random`, draws one). A step without
edges is the end. An edge marked `speak`, taken after an avatar
turn, has the avatar go on under the next step without waiting for
the user (`speakAfterS` seconds later; absent, Causeur's default).

v2 avatars only: a v1 avatar is refused (`409 not_v2_avatar`). The
conductor runs on Causeur, the conversation runtime v2 sessions are
moving to; it has no effect on a session the behavior module runs.
It replaces any earlier conductor, and any conductor the avatar's
own config carries, and applies from the next session (a running
session keeps what it started with). Nothing is rebuilt or captured,
and the serving candidate stays. A session whose whole payload would
exceed Causeur's limit (262,144 characters, the avatar's persona and
config included) starts without the conductor.

The graph is checked before it is saved, with Causeur's own rules
and limits; a refusal names the field (`400 invalid_conductor`,
`/graph/nodes/2/edges/0/weight: ...`; a value of the wrong JSON type
is `422`). Limits: at most 100 nodes and 100 edges in all; node ids
`[a-z][a-z0-9_]{0,39}` and not `none`, unique; instructions at most
1000 characters; a condition at most 300; a weight above 0 and at
most 1000, and only on an edge without a condition (default 1); one
edge with a condition and one without per target at most; every
node reachable from `start`, every edge to a node of the graph, a
`speak` edge only into a step with instructions. Not accepted here:
`replan` steps (the graph runs as given), text holding a
`!<...>!` placeholder or starting with `supabase/`, and a graph over
150,000 characters of JSON (non-ASCII characters count as their
`\uXXXX` escapes), which leaves over 110,000 characters for the rest
of the session (a v2 avatar's own config is typically under 15,000).
Only `graph` and `speakAfterS` are accepted at the top level. The
request body may be up to 512 KiB.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | path | yes |  |

## Request body

- `application/json`: `ConductorRequest`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `graph` | `ConductorGraph` | yes | The steps of the conversation (`nodes`) and the one it starts in (`start`). Every node must be reachable from `start`. Only `start`, `nodes` and `reasoning` are accepted. |
| `speakAfterS` | number | no | Seconds after an avatar turn before the avatar speaks again along a `speak` edge, if the user has not taken the floor. 0.1 to 10; absent or null: Causeur's default (0.5 today). |

## Responses

| Status | Description | Schema |
| --- | --- | --- |
| `200` | Saved; returns the conductor. | `Conductor` |
| `400` | invalid_conductor (the message names the field and what it takes) \| invalid_body (also an unknown top-level field) \| a request body over 512 KiB | none |
| `401` | Missing or invalid credentials -- or a user token that is invalid, anonymous, or of a user who may act for no account (invalid_login) | none |
| `403` | insufficient_scope \| avatar_not_allowed \| account_not_allowed (a user token whose X-Account-Id names an account the user may not act for) \| v2_access_required (engine v2 is invite-only and this account has not been let in yet) | none |
| `404` | avatar_not_found | none |
| `409` | not_v2_avatar (a v1 avatar) \| account_ambiguous (a user token of several accounts without X-Account-Id) | none |
| `422` | Request body failed schema validation (a value of the wrong JSON type, an unknown top-level field, speakAfterS out of range). | none |

## `200` response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `avatarId` | string | yes |  |
| `graph` | `ConductorGraph` | yes | The steps of the conversation (`nodes`) and the one it starts in (`start`). Every node must be reachable from `start`. Only `start`, `nodes` and `reasoning` are accepted. |
| `speakAfterS` | number | no | As set; absent when it was not (Causeur's default applies, 0.5 today). |
| `nodes` | integer | yes | The graph's node count. |
| `edges` | integer | yes | The graph's edge count, all nodes together. |