For the complete documentation index, see llms.txt. Every page is also served as Markdown at its URL followed by .md.

standards
Agent conversationsAgents

Agent conversations

Read long agent conversations, navigate older messages, and reopen Artifacts.


An agent conversation opens on its most recent messages. Scroll upward to load older messages. The reader's position stays anchored while an older page arrives; a new reply follows the scroll only when the reader is already near the latest message. The transcript renders the rows in view, so a long conversation does not mount every message at once.

The inspector lists records, documents, and every published Artifact revision for the session, including entries from messages that have not been loaded into the transcript yet. Opening an Artifact reads its stored revision; loading or unloading transcript rows does not remove its content. If the inspector cannot load its resource list, it shows a retry action instead of an incomplete list.

Linked records. An Artifact can be linked to any record. A person links it from the Artifact's Details; the agent links it when it publishes, to the records the agent names or, when it names none, to the conversation's target records. Linking adds to the links already there. A link changes no one's access to the Artifact: it keeps its own visibility.

Copying an assistant answer includes all of its messages, even when the beginning sits on an older page. The conversation loads the missing part on demand before copying.

Where a new conversation opens

New chat and its shortcut (⌘O, or Ctrl+O on Windows and Linux) open a new conversation in the side panel by default, so the page you were on stays in view. To have every new conversation open fullscreen instead, choose Settings › Preferences › New conversations › Fullscreen. The choice is saved on your profile in this workspace, so it follows you to every device; each workspace keeps its own.

Either way, a conversation already open keeps its own place: the expand and reduce controls in its header move that one conversation between the panel and fullscreen. On a page that is already a conversation, a new conversation always opens fullscreen in its place.

The header's ••• menu also opens the conversation in a new tab and moves it to the trash, as its menu in the sidebar does. A routine's run keeps its shorter menu.

Turns and phases

A conversation advances in turns. A turn starts when the agent reads what is waiting for it — your message, a decided approval, the reports of the agents it waited for — and ends when the agent stops writing. Each turn ends with one outcome:

OutcomeMeaning
completedThe agent finished its answer, or reached a wait (see below).
failedThe turn stopped on an error, such as a spent budget or a model that kept failing.
cancelledSomeone stopped it.

What the agent says to you depends on the conversation's display. In Details, its text is its reply and the conversation shows every step in order: its reasoning, its tool steps, its text, and any message it sends with send. In Chat, it speaks only through send, and the conversation shows only what it sends, with its questions and approval cards. A message sent with send can carry stored files: attachments, up to 10 document:<id> or file:<id> the agent may share (it can edit their drive). They show under the message, join the decision when the message lands in Décisions, and are uploaded to linked Slack threads. A file it cannot see refuses the send with REFERENCE_NOT_FOUND, one it can only read with FORBIDDEN, and nothing is sent.

Between turns, a session is in one of three phases:

PhaseMeaning
idleNo turn runs and nothing is awaited. The next message starts a turn.
runningA turn runs.
parkedNo turn runs, but the session still holds open approvals or awaits the agents it started. parkedOn says which: human or agents (human wins when both hold).

A session has no end state. Its state carries the phase, parkedOn when parked, and the last turn's outcome; a failed or cancelled conversation is an idle one whose last turn failed or was cancelled, and it accepts the next message like any other.

Every wait ends the turn. A step that asks a question with send, asks for approvals, or starts agents or sends them a follow-up with wait: true, ends the turn as completed, and the session parks. Answering is not a continuation of that turn: once every question and approval of the batch is answered or decided, or every awaited agent has reported, a new turn starts and reads the answers from the conversation. A run's question or approval left unanswered for 24 hours expires and the agent sees "no answer" in the turn that follows; a question in a conversation never expires, since the person is there. A routine run that waits stays paused and the answer resumes that same run.

A message sent while the session is parked starts a turn at once, unless the wait locked the conversation. The open questions and approvals stay open: the agent sees them as still pending in that turn, and a decision that arrives meanwhile waits for the turn to end, then starts its own. When a turn ends and something is still awaited, the session parks again.

A wait can lock the conversation. An agent that asks with send and lock: true, or that writes to an agent it started with wait: true and lock: true, locks the conversation until that wait resolves; the parked session's state carries locked: true. While it is locked, a person's message, in the app or in Slack, yours included, is kept but starts no turn and answers no question: the question is answered on its card or in Decisions. A message from another agent or an automation still starts a turn. Editing a message answers 403 STATE_GATE. The answer, its expiry, the awaited agent's report, a Stop or archiving the conversation lifts the lock, and the turn that follows reads the messages kept meanwhile. In the Standards app the composer shows what the agent wrote when it locked the conversation and takes no text until then; Stop stays available.

A message sent while a turn runs waits; the agent reads it at its next step, or in the next turn. A turn acts for one person at a time: the waiting messages read together are those sent by the same person as the oldest one, and a message from someone else starts its own turn. If the server running a turn stops, the turn resumes by itself from its last completed step; a turn that cannot be resumed ends failed.

A message carries its sender's timezone. POST /agents/sessions/:id/messages takes an optional timezone, an IANA name such as Europe/Paris; the Standards app sends the browser's. A conversation's turn is dated in the zone of the latest message that carried one, and the agent states dates and times in it. A zone the server does not recognise is ignored. Without one, and always for runs, schedules and triggers, the agent works in UTC.

A message can name the record it is sent from. The same route takes an optional attachedRecordId, a record UUID; the Standards app sends it from a record's page or peek. The agent reads that record's card after those of the records the message mentions (see Skills and memories). A record the sender cannot read brings no card.

Chat and Details

A conversation has one of two displays, set on the conversation so everyone who reads it sees the same thing. Details, which every conversation starts with, shows everything the agent writes and does, and its text is its reply. Chat shows only what the agent sends with send, its questions and approval cards, and the agent speaks only through send. It then reads like a messaging app: your messages in bubbles on the right, the agent's on the left, the messages of each of its turns under one time, and three animated dots while it works, which never name what it is doing. Chat is what a person reached outside Standards receives: a linked Slack thread, or the person an external agent works for. The change applies from the agent's next turn; the display follows at once. In the Standards app the display menu under the composer, on the right of the model, chooses Chat or Details, as does ⌥⌘F (Ctrl+Alt+F off Mac) anywhere in the conversation; the work mode (Architect, Manual, Auto) sits on the left of the same row. Over the API the display is the session's focus field, true for Chat: PATCH /agents/sessions/:id/focus with { "focus": true } answers the session. It needs the right to use the conversation's agent; a conversation you cannot see answers 404. A conversation started from a Slack thread starts in Chat.

In either display, a request that means going through several records or writing a document opens with one short line saying what the agent is starting on, a message of its own in Chat; the answer follows once the work is done. A quick answer, or a request the agent must ask about first, has none.

In either display, a message the agent sends that names files it stored in Standards for your request (a chart it made, an email's attachments it saved) must carry them as attachments, so you see them with it; a message that names them without attaching them is refused, and the agent sends it again with the files. A file it only copied into its sandbox to read is not one of them.

Acting on a session

Every action on a session is a request to the agent, answered with an outcome rather than with the session:

OutcomeMeaning
{ "status": "accepted", "seq": "…" }The agent will act on it. created: false means an identical earlier request already answered it.
{ "status": "withdrawn", "messageId": "…" }The message you stopped was still waiting: it was taken back and never read.
{ "status": "no_active_turn" }The turn you named is no longer current. Nothing changed.

DELETE /agents/sessions/:id stops a conversation. Its body names what you are stopping: { "turnId": "…" }, the running turn you observed on the stream (turn.started), or, for a Stop pressed before the turn started, { "clientMessageId": "…" }, the id of the message you sent. A message that is still waiting is withdrawn; one a turn already read stops that turn. A Stop on a parked session, naming its last turn, cancels the waits: the open approvals close, the awaited agents are stopped, and the session becomes idle with outcome cancelled. A request that names nothing, or a turn that has since ended, answers no_active_turn. PATCH /agents/runs/:id/cancel stops a run's current turn and answers the same outcome.

The other actions answer an outcome too:

  • PATCH /agents/sessions/:id/agent-read asks the running turn to read the waiting messages at its next step.
  • POST /agents/sessions/:id/compact folds the older history into a summary once no turn runs. The fold's result arrives on the stream as compact.completed, not in the response.
  • PATCH /agents/sessions/:id/messages/:messageId replaces a past message and everything after it, and answers { outcome, clientMessageId }, the id under which the corrected message is written. A session with a running turn answers 409 with AGENT_INVALID_STATE: stop it first. A conversation run by a harness (Claude Code, Codex or Cursor, see Environments) refuses edits the same way.
  • POST /agents/sessions/:sessionId/approvals/:approvalId decides an approval and answers { message, outcome? }. The agent resumes on its own once the whole batch is decided.
  • POST /agents/sessions/:sessionId/requests/:requestId/answer answers the agent's questions, requestId being the id of its send call with questions, and answers { message }. See Answering the agent's questions.
  • POST /decisions/:decisionId/answer answers a decision from Decisions: an agent's questions ({ "kind": "answers", … }), an approval ({ "kind": "approval", "approved": true }) or a design review ({ "kind": "review", "outcome": "approved" }). It goes through the same path as the chat card and answers the decision as you now see it. See Decisions.

An interrupted turn needs no action from the client: the former resume endpoint is gone.

Forking a conversation

POST /agents/sessions/:id/fork copies a conversation into a new one and answers the new session. The copy is a conversation of its own: its own messages, turns, approvals and title, starting as "<title> (fork)". The original keeps running untouched, even when you fork it mid-turn. Send an optional client id (a UUID) to make a retry return the same fork instead of copying twice.

The fork holds every message the original had persisted when you forked it, in the same order. A message still waiting to be read is left out. A tool call that had no result yet (a step still running, an approval or a question still open) is closed in the copy with a fixed note saying its outcome stays with the original, so the fork never runs or decides it. The fork keeps the original's agent or configuration, model choices and approval mode.

Every session carries its lineage: forkedFromSessionId, the conversation it was copied from, and forkedAtMessageId, that conversation's last message in the copy. Both are absent on an ordinary session. forkedFromSessionId is cleared when the original is deleted; the fork itself is never touched. The Standards app nests a fork under its original in the conversation list. Only the person who started a conversation sees its Fork action, in the conversation's menu or as /fork in its composer.

StatusMeaning
403You did not start this conversation (only its creator can fork it), or it is a subagent or an autonomous run (SCHEMA_STATE_GATE).
409The conversation is run by a harness (AGENT_INVALID_STATE), which refuses forks as it refuses edits.
404The conversation does not exist, or you cannot see it.

Send an aside with the fork, { "question": "…", "answer": "…" }, to append an aside exchange (see below) after the copy: the question as your message, the answer as the agent's, both marked as an aside so the agent reads them as one, with no turn started. A blank aside question answers 400.

Sharing a conversation

The person who started a conversation can show it to named members with Share in its header menu, or through GET, PUT and DELETE /agents/sessions/:id/access[/:actorId]. The only role is reader, only the creator shares, and only a root conversation: a sub-agent's conversation answers 403 SCHEMA_STATE_GATE. Each person who receives it gets an access.granted notification that opens it. Sharing shows what is in the conversation, including everything the AI displayed in it: records, documents and screenshots it read out.

A reader sees the conversation as it stands, read-only: its line reads "name's conversation · read-only" where the composer would be. They cannot send, approve, answer, stop or archive. Because a reader gets no live stream, the view refreshes when the window regains focus and every 10 seconds while the conversation is working. Continue in my conversation forks it into a conversation of the reader's own (see Forking a conversation). The fork copies only what the reader could see: no hidden recall context, and no stamp of the creator's authority. A routine's run can be forked the same way.

Revoking a person closes their reading at their next request and tells their client to drop the conversation; a view already open may keep its last state briefly. Deleting a conversation deletes its shares. Artifacts a conversation produced follow their own visibility, not the conversation's.

Reading other members' conversations

A member who holds the supervision permission, owner by default, reads every member's conversations, read-only: messages, a run's input, output and error, the plan and screenshots. They never read the configuration of a private agent, nor a run's resolved system prompt. Members are not told; the audit is.

Reading a conversation that only supervision lets you reach writes the audit entry agent_session.supervised_read (reader, conversation, person), whatever is read: the conversation, its messages or history, its overview, its plan, a screenshot, a run's content, or a fork of it, through the app or the API. One entry stands for every such read of the same conversation by the same person for 10 minutes, so the view's refreshes do not multiply it. Listing conversations writes nothing. A supervisor has no live stream either: the view refreshes like a reader's.

Filtering by provenance

GET /agents/sessions takes provenance:

  • mine, the default: conversations you started.
  • shared: conversations shared with you.
  • team: every member's conversations; 403 without supervision. actorId narrows it to one person; with any other provenance it answers 400.

shared and team rows are root conversations. Each carries readThrough: true, the person it belongs to, and the agent's name and icon, never its configuration. cursor is an opaque keyset cursor, valid with orderBy=lastActivity; combined with offset it answers 400.

In the app the history and the sidebar's Conversations section have a Show filter (Mine, Shared with me, and Whole team for supervisors) next to Status. In the history picker, typing @ picks a person to narrow Whole team. An agent's or a routine's activity panel has the same filter, restricted to that agent or routine.

Asking an aside

POST /agents/sessions/:id/aside asks a side question about a conversation without adding it to the conversation. The body is { "question": "…", "exchanges": [ … ] }, exchanges being the previous asides of your view as { question, answer } pairs, at most 20; the server keeps none. The answer streams back as text/plain. The agent answers from the conversation as it stands, including while a turn runs, and uses no tool. Nothing is written: no message, no turn, no memory, no notification. The model call is billed like any other, and an answer is kept short (about 4,000 tokens at most). Only the person who started the conversation can ask an aside about it. In the Standards app, type /aside followed by your question; the answer shows above the composer, and Continue as a conversation forks the conversation with the aside appended.

StatusMeaning
400The question is blank or too long, or more than 20 exchanges were sent.
403You did not start this conversation (only the person who started it may ask an aside), you cannot start a turn in it, or it has no turn yet to ask about (SCHEMA_STATE_GATE), as a conversation on an environment never has.
404The conversation does not exist, or you cannot see it.

A refusal answers its JSON error before any answer text is sent. An answer that fails once it has started is cut off, so reading the response fails rather than ending as if the answer were complete.

Background subagents

A subagent started without wait runs in the background and reports back only if it fails: its failure wakes the agent that started it, which tells you, and never relaunches it on its own. One that completes says nothing; start it with wait: true to be told its result.

Forked subagents

An agent that spawns a subagent chooses its context. "fresh", the default, starts the subagent from its mission alone. "fork" starts it from a copy of the conversation so far, with the agent's own instructions, tools and model, followed by the mission: use it when a fresh subagent would need too much background, or to try several approaches from the same point. A forked subagent reuses the conversation's prompt cache, so it costs far less than briefing a fresh one with the same context. It cannot ask the person questions, change the todo plan, load more tools or spawn subagents, and it runs only the tools the agent still holds, so it holds no permission the conversation lacks: a web search the model provider runs itself is left out when the agent no longer holds it. Only its final report reaches the conversation that spawned it. A fork cannot name another model.

Architect build roles

In architect mode the conversation's agent can spawn subagents and message them, always by role: a spawn with no role is refused there (VALIDATION_FAILED), and a role is refused outside architect mode.

The roles:

  • scout: reads the workspace and the request, and returns a brief.
  • builder: builds one object's fields and views. It takes an objectName, and no other role does.
  • The five reviewers: practicality, extensibility, fit, consistency and integrity.

The role fixes what the subagent holds:

  • Tools. The scout holds only the reading verbs (read, search, query). A reviewer holds those, plus get_architect_draft, to review the folded draft. A builder holds the reading verbs, plus get_architect_draft and draft_schema. No other tool is mounted, whatever the conversation's grants: no writing verb, no discard_architect_draft, no request_work_mode.

  • Starting point. A role subagent starts in architect mode, from its role's instructions followed by the mission, and never as a fork. A reviewer's or a builder's first message also carries the build's brief and your why-, process- and compose- answers, as stored in metadata.architectBuild.

  • Report. The scout replies with one JSON brief: reuse, conventions, volumes and ambiguities. A reviewer replies with a JSON array of findings, each { severity, target, problem, fix }, where severity is blocking, to fix or noted and target names an object or object.attribute.

  • Name. Its session is named by its role's key, such as builder:contacts, whatever label the agent passed. The app shows each role by a name in your language, composed from the stored role:

    RoleEnglishFrench
    scoutScoutÉclaireur
    builderBuilder · objectBâtisseur · object
    practicalityEveryday userUsager
    extensibilityPlannerUrbaniste
    fitClientCommanditaire
    consistencyArchivistArchiviste
    integrityEngineerIngénieur

    A builder's object is named by its label, plural when it has one: Bâtisseur · Contacts.

  • Draft. Every subagent of an architect build writes the conversation's own draft, so you follow one build. It never publishes it, and it cannot discard it (FORBIDDEN).

  • Scope. A builder writes inside its own object only. An operation on another object, on the object itself (add_object, update_object, remove_object), on a relation attribute or on a page is refused whole, and nothing is appended: stillMissing reads Outside your scope: object "contacts" only.. The object and its relations are the conversation's agent's.

  • Parallel builders. The guard a builder reads from get_architect_draft covers its own object's targets, and each draft_schema result returns the next one. Builders writing different objects at the same time never conflict. A target of its object that the builder did not see when it read, created or changed since by someone else, still conflicts. Another object its content only reads, such as the one a collection lists, never makes it conflict.

The role is kept on the subagent's session as metadata.architectRole, for example { "role": "builder", "objectName": "contacts" }.

In the sidebar, the build's subagents are listed under the open conversation, in the order they were dispatched, each with its status. The five reviewers of one review are grouped under Review board (French: Comité de relecture), which folds them. While a subagent runs, its row says what it is doing, such as Construit les champs et les vues de Contacts. Clicking a subagent opens it beside the conversation. Any other subagent stays out of the sidebar.

The build sequence

A build whose plan creates 3 or more objects runs these steps, in order:

  1. The scout reads the workspace and the request.
  2. The agent asks you why you need the workspace, how the work runs today and what you want to see daily: question ids start with why-, process- and compose-. It asks only what changes the plan, never what your request already says, and never asks again a batch you skipped.
  3. It writes the plan as its todo list.
  4. The five reviewers review the plan together, and the agent amends it from their blocking and to fix findings.
  5. It asks you to validate the plan (below).
  6. It creates every object, then dispatches one builder per object, in parallel.
  7. It adds the relations itself.
  8. It fixes what the draft still lacks or what would refuse its publication, then the five reviewers review the folded draft.
  9. It fixes their blocking and to fix findings and reports, listing the noted ones.

A smaller build is made by the agent alone, after at most one batch of questions.

Validating a large build's plan

A build whose todo list has 3 or more objects todos waits for you before it creates anything. The agent shows you its plan as a question with the id plan-validate. Until you choose its validate option, or skip the question, every draft_schema batch that creates an object is refused: nothing is written, and stillMissing[0] reads Ask the person to validate the plan first. Answering anything else sends the agent back to amend the plan and ask again: Ajuster with text, or a message you type instead, is applied as written. Ajuster alone makes the agent ask you what to change first. A new build of the same conversation waits for its own validation.

The build keeps its context on the conversation's session, as metadata.architectBuild:

  • brief: the scout's report;
  • answers: your answers to the questions whose id starts with why-, process- or compose-, and to plan-validate;
  • costBaselineUsd: what the conversation had cost when the build's plan was written;
  • planValidatedAt: when you validated the plan.

Dispatching a new build's scout clears the previous build's brief, answers and planValidatedAt, so none of them reaches the new build. Each field has its own writer. A change to the session's other metadata, such as its title, leaves this context as it is.

The plan's card shows what the build cost: the conversation's cost now, its subagents included, minus costBaselineUsd. A conversation that spent $0.40 before a build costing $1.10 shows Build cost · $1.10, not $1.50.

Answering the agent's questions

An agent asks questions with send and questions. The call stays open in the message as a card until it is answered, and the session parks on it. The questions go to the person the conversation acts for, or to the people the call names in to, and any of them answers. to can only name people who can write in the conversation: naming anyone else refuses the call, and the agent is told so in the same turn. Whoever answers, the turn that follows acts for the person the conversation acts for, never with the answerer's rights; the call's result names who answered (answeredBy). Send the card's answer to POST /agents/sessions/:sessionId/requests/:requestId/answer:

{ "skipped": false, "answers": { "target": "publish_default", "scopes": ["read", "audit only"] } }

Each answer is a string, or a list of strings for a multi-select question. A value the question did not offer is your free-text answer ("Other"), at most one per question, unless the question allows none. A chosen option can carry a precision in notes, by question id then option value ({ "notes": { "target": { "publish_default": "after legal review" } } }): the call's result gives it on that answer as note, or as notes by value on a multi-select, and a precision on an option not chosen is dropped. In the Standards app it is the « Préciser » button on the chosen option. An option the agent marks « (Recommended) » is shown as recommended and stands chosen when the card opens. A question you walked past is left out of answers, and the call's result names it in unanswered (its id and text) so the agent knows to ask it again; a skip names none. The answer becomes the call's result, with each chosen option's label, the response carries the updated message, and the agent continues in a new turn as soon as none runs; a conversation waiting on an approval reads it when it resumes, one waiting on other agents when they report. A Stop after that leaves the answer for your next message.

StatusMeaning
403The questions were not asked of you.
400An answer names a question the call did not ask, has the wrong shape, or a value the question does not accept.
404No open question has this id: it does not exist, the conversation was stopped, or you answered it by writing a message. Also returned when you can no longer see the conversation.

Answering again answers the same message and changes nothing. Writing a message instead of using the card also answers the question when you are one of the people it was asked of: the agent is told you wrote instead and reads your message, and for a recipient other than the person the conversation acts for, the answer is recorded as theirs. Anyone else's message leaves the question open, and so does any message while the question locked the conversation.

Decisions

Each question the agent sends in a conversation is also one decision in Décisions, for the person the conversation acts for, or for the people its to names. The call takes, besides its questions:

InputWhat it is
titleThe decision's title in the list, at most 120 characters. The first question by default.
whyWhy the agent asks, one sentence of at most 200 characters.
changeWhat answering will make possible, written in the future (« Cette décision permettra… »): one sentence of at most 200 characters.
attachmentsStored files to look at before answering: document:<id> or file:<id>. A file the recipient cannot open is left out.
linksRecords the decision is about: record:<id>. A record the recipient cannot see is left out.
toWho should answer, as actor ids: people who may write the conversation, or, in a routine's run, any active person of the workspace. The answer still acts with the rights of the person the conversation acts for.

A why or a change over 200 characters is refused, and no decision is raised. Every decision of a conversation shares its thread, session:<id>, so a second question stacks under the first. Answering it in Décisions, on the chat card, or by writing a message all complete it the same way: the decision records the answer, who gave it and its effect (relaunched <agent>, relaunched Standards for a conversation without an agent), and the agent continues in one new turn. A request a Stop closes (the running turn's, or a parked conversation's approvals) withdraws its decision.

Tool approvals and design reviews are decisions too, of kind approval and review, for the person who started the conversation. An approval, or a routine run's question, that expires after 24 hours leaves its decision expired, with its expiry in payload.expiresAt; Décisions shows it as an « expire dans » badge.

People decisions

A person raises a decision for colleagues with POST /decisions:

{
  "title": "Budget Q4",
  "why": "Le devis dépasse l'enveloppe",
  "question": { "text": "On valide 40 k€ ?", "options": [{ "label": "Oui" }, { "label": "Non" }], "freeText": false },
  "recipients": ["<actor id>"],
  "links": ["record:<id>"],
  "attachments": ["document:<id>"]
}
FieldWhat it is
titleAt most 120 characters.
why, changeOne sentence each, at most 200 characters.
questionOne question, answered by one of two options or more, in free text (freeText: true), or both.
recipientsThe people who answer, as actor ids: active members only.
linksRecords the decision is about, record:<id>.
attachmentsDocuments to look at, document:<id> or file:<id>.
followUpOfA decision of the thread this one continues.

The decision is open for each recipient and stacks in its own thread, decision:<id>. A recipient answers it with POST /decisions/:decisionId/answer ({ "kind": "answers", ... }, the same answer as an agent's card); the answer, who gave it and when are recorded, and no agent runs.

StatusMeaning
400No recipient, no question, a question with neither two options nor free text, or a recipient who is not an active person.
403You can read an attached document but not share it: you need write access to its drive.
404A linked record or an attached document you cannot see.

Each recipient reads the attached documents' files with GET /decisions/:decisionId/attachments, even on a drive they cannot open, until the decision is withdrawn. Only the sender withdraws it, with POST /decisions/:decisionId/withdraw: every open row is withdrawn and the attachments read 404 from then on. A recipient who is not the sender gets 403, anyone else 404, and a decision already answered gets STATE_GATE.

decisions.list shows a linked record only to a recipient who can see it, labelled with its name, a linked conversation only to one who can read it, and a document with its title; anything else is left out of links. Each item names its sender (person, agent or system).

« Transformer en décision » (POST /decisions/:recipientId/transform) turns one of your « Pour toi » items that a person sent (a mention, an assignment, a share) into a question for yourself, linked to its record, its text as the why, and marks the item read. A routine's report or a notice an agent sent is refused with 400.

A mention or an assignment raises a toast and, while unread, a dot on Décisions: decisions.counts returns it as unread, beside open, the number of decisions waiting for you. A share or a routine's report raises neither.

Reading decisions

An agent reads what a person decided through its read and search verbs, with the decision kind. It sees only the decisions the person it acts for received or sent. search with kinds: ["decision"] lists them newest first, with or without a query; link narrows to those about a record (record:<object>:<id>) or a conversation (session:<id>), and state to open, answered, withdrawn, expired or info. Each hit carries data.state and, once answered, data.answer, data.answeredBy and data.completedAt. read decision:<id> returns the decision with its questions, answer, answerer and links; a decision the person cannot see reads as missing. Neither verb answers a decision.

{ "kinds": ["decision"], "link": "record:issue:6290", "state": "answered" }

Listing sessions

GET /agents/sessions lists the sessions you can see. It filters on phase (idle, running or parked) and on outcome, the last turn's (completed, failed or cancelled), alongside q, definitionId, mode, parentSessionId, rootSessionId, limit, offset and includeArchived. The query is strict: any other parameter, the former status filter included, answers 400 with SCHEMA_VALIDATION_FAILED instead of an unfiltered list.

The model a new conversation starts on

A conversation not bound to an agent starts on your personal default: Auto, or the model you last chose in the conversation's model menu. Choosing Auto there makes Auto your default; choosing a model makes that model your default. It is your chat.default preference: GET /users/me/preferences reads it, and PUT /users/me/preferences/chat.default sets it directly, with { "value": { "routing": "auto" } } for Auto or { "value": { "model": { "provider": "anthropic", "model": "claude-sonnet-5.5" } } } for a model. A model the catalogue has since retired reads as its closest live model. A conversation bound to an agent starts on that agent's configuration instead.

Attaching an HTML file

An .html or .xhtml file attaches to a message like a Markdown or JavaScript file: the agent reads it as text, so a page or a template can be handed over from the chat. A file over 10 KB reaches the agent as its first lines, with the whole file under /workspace/attachments. Opening the attachment shows the page with its scripts disabled; it is never served as a live page.

Attaching an image

A JPEG, PNG, GIF or WebP image attaches to a message and the agent sees it, up to 3.75 MB (5 MB once encoded, the most every model provider accepts). Any other image (an SVG, a HEIC, a BMP, a TIFF, an AVIF) and any larger one reaches the agent only as a file under /workspace/attachments, where an agent with a sandbox can convert or measure it; an agent without one is told it cannot open the file. Such an image never breaks the conversation: no model is handed a picture it would refuse.

Attaching a voice memo

A voice memo — an .m4a, .mp3, .wav, .ogg, .webm or .flac, up to 50 MB — attaches to a message like any file. The agent reads its transcript, so every model takes it and none needs to hear audio. The transcript is made once and kept on the file: later turns reuse it, and the transcription counts toward your workspace's AI usage like any other model call. The memo itself also stays in the agent's files, under /workspace/attachments. A memo that cannot be transcribed, or one over 20 MB, reaches the agent only as that file.

Following an architect conversation

In architect mode, the agent's changes appear as a draft while the conversation runs. The page follows the object, view, or tab the agent is changing. An activity bubble shows the current change and stays visible while the agent prepares the next one. Every change the agent commits is followed, even while the draft's preview is still loading or behind: each one arrives with where it can be seen. A change the page cannot open yet waits and is shown once it can; it is dropped only when it leaves the draft. If you navigate manually, automatic following pauses so the page stays where you chose.

The bubble beside the agent's cursor says what the change does, in one line such as Ajoute l'attribut Statut à Contact. Above it is the sentence the agent gave the batch of changes it is writing. Below it is the turn's progress, <shown> / <committed>: the number of changes shown so far, out of those the agent has committed this turn. The right-hand number grows while the agent writes. When the agent has build todos, the progress starts with the one it is on, for example Vues · Fiche Contact · 3 / 155. While following is paused, a button in the draft's strip counts what arrived since the pause, Reprendre · 12 nouvelles étapes: beside the change count in the strip above the composer of the conversation that wrote the draft, and on the line under the change count in the architect panel's. Clicking it resumes following on the most important change of the agent's latest batch. With neither strip on screen, the same button floats at the bottom of the page instead. The architect panel shows the build's progress beside the draft's change count, Plan · 4 / 8.

When several builders write the draft in parallel, each one has its own cursor. The page follows one builder: by default the one working on the plan's first unfinished fields or views todo. Its cursor's bubble names it above the change, for example Bâtisseur · Contacts. Every other builder still at work appears as a chip in its own colour, grouped at the top right of the page: Bâtisseur · Entreprises, with Cliquer pour suivre below. Clicking a chip follows that builder, and the page shows its latest change at once. The other builders' changes still count in the turn's progress. A builder that finished leaves the chips. When the agent writes alone, there is a single cursor and no builder label.

When the agent adds a sample record, its draft record opens in a read-only detail page. You can inspect its tabs before publishing the draft.

A change to an object's record view, or to one of its attributes, opens that object's record page: the draft's sample record first, otherwise its first existing record. An object with neither, such as one the draft has just created, opens on a preview record at /~/<object>/_preview. It is empty and read-only, marked as a draft preview, and stores nothing. While the object's record view has no form of its own, the preview shows every attribute of the object in a plain form, so you see the fields arrive as the agent adds them. The sample and schema changes become permanent only when you choose to publish.

A publish applies the whole draft or nothing. When it is refused, nothing is applied, the draft stays as it was, and the refusal is kept on it: its code, the object, attribute, view or page it names, and the last change of the draft that touched it. A failure that is not a refusal of the draft is kept as its code alone, INTERNAL, with no server text. GET /schema/draft/last-publication (schemaDraft.lastPublication, same session parameter as the draft) answers how your last publish ended, published or refused, whichever is later, or null before any. A publish waits up to two minutes for its answer. When the answer is lost (a timeout or a dropped connection), the app reads that outcome instead of reporting a failure, so a publish the server applied shows as published.

The tab you published from then goes to what was built: the list of the first object the draft created, or the page it created when it created no object. A draft that created neither leaves you where you are. When the publish is refused, the tab goes to what was refused and the architect panel opens on it, saying why. Anyone else viewing the draft stays where they are and reads the outcome in the strip.

A publish is also refused when someone published a change to an object, attribute or view the draft touches after the draft read it. The draft strip then lists each one with what changed on it: its old and new label, modified, or removed. You choose: Publish over applies the draft on top of those changes, or Cancel keeps the draft as it is. Over the API, the refusal is 409 DRAFT_REVISION_CONFLICT and its details.changes lists { key, kind, label, relabelled?, removed?, seen }. Publishing over sends accept, each change's key mapped to its seen, with the next publish. A target changed again since that refusal is refused once more, so you never publish over a change you were not shown.

The conversation whose draft you published is told how it ended. A refusal writes Publish refused on <target>: <reason>. into the conversation and wakes the agent, so it can correct the draft with draft_schema; publishing stays yours. A success writes Published: <n> operations., which the agent reads on its next turn without being woken for it. That text is the agent's: the conversation shows you the outcome in your language, what was published or what was refused and why, without the instruction to the agent. The row's metadata.publication carries it, { outcome: "published", operations } or { outcome: "refused", target?, reason?, code? }, and readArchitectPublication from @standards/schema reads it. A refusal whose code the app words, such as DRAFT_REVISION_CONFLICT, shows its reason in your language; any other keeps the server's words, which name what was refused. A draft you composed outside any conversation tells no one.

Asking for access

In a conversation you are actually at — never a spawned child, a trigger run, or a schedule run — the AI can ask you for access it lacks instead of guessing. It shows a card with up to five items, each either:

  • a catalog MCP server, with the reason it wants it. Connecting opens the consent in a new tab or a popup; the chat itself never navigates away. Before you click, the row states whether the connection will be private to you or shared with the workspace — shared when the AI asked for the whole workspace (scope: "workspace") or the target agent is a workspace agent, private otherwise. Unless the AI asked for the workspace, the row stays inactive until that agent is known. When the connection is to be shared, only a connection shared with the workspace counts as connected: your private one never answers it. Connecting needs the same permission as adding a connector in settings; without it, the card is refused, whatever the AI asked. A connector you removed can be asked for again the same way.
  • GitHub or Slack, installed for the whole workspace. Connect goes straight to the provider's own install and comes back to the conversation; the row reads connected once the workspace has it, whoever installed it. When GitHub finds no account of yours free to bind, it opens the GitHub App's install directly instead of asking you to choose. Installing needs the same permission as adding a connector in settings.
  • an API key, saved as an environment variable. The AI tells you exactly what to create and with which rights, and links to the page to create it. You choose whether the key belongs to the conversation's agent or to the whole workspace; an agent-layer key overrides a workspace-layer key of the same name. The row states who ends up able to use it: only you, every member who uses this agent, or every member and their routines.

Each item targets the conversation's agent by default. It can instead name another agent you can edit, with agentId — for example the routine the AI is building for you in Architect mode — so the connection or the key lands where that agent can use it. A card never asks twice for the same key or the same connector.

The value you type goes straight to the environment-variable store. It never enters the chat, a tool result, or the model — the AI only ever learns what is now stored or connected, read back from real state, never what you typed. If a key already exists at the layer the AI would ask for, it is never asked again: the AI can see key names when it may read environment variables, never their values.

The card is also a decision in Décisions, titled Configurer <first item>, for the conversation's authority. Continuing from there or from the chat closes the card with what is really stored or connected, completes the decision, and starts the AI's next turn. A connected account whose sync breaks (its sign-in is refused, or it stops syncing) hands its owner a Reconnecter <provider> decision, which names the account when it is an address (a Gmail, Outlook or calendar account). Reconnecter offers that account first at the provider's sign-in; for a shared mailbox, which cannot sign in, you sign in as the account it was added from. The decision completes on its own once the account works again, after a reconnect or a successful sync.

API history window

GET /agents/sessions/:id/messages?history=1 returns the newest 30 messages in chronological order with hasMore and an opaque nextCursor. Pass before=<nextCursor> to get the preceding page. An optional limit accepts 1–100. The cursor is exclusive and remains stable when another message is added. A request without history=1 retains the existing array response for clients that use the original endpoint.

The history page also returns committedSeq, the position in the session's event log that its messages already reflect. Each user message carries waiting: true while no turn has read it yet.

GET /agents/sessions lists conversations newest-created first. Pass orderBy=lastActivity to order them by the latest message either side wrote (creation when there is none), as the conversation history does; renames, read stamps and archives never move a conversation in that order. Page with limit and offset.

Following a conversation live

GET /agents/sessions/:id/stream?after=<committedSeq> streams the session's event log as server-sent events. Each event is one frame, id: <seq>, event: event, with the event as JSON data. The stream first replays every event after the cursor, then sends a control frame event: control with {"control":"up-to-date"} followed by {"control":"inbox"}, then follows the session live. The response opens with retry: 1000, the reconnect delay. When the agent writes its todo list during a turn, a todo-plan.updated event carries the plan as written, as data.plan. In Architect mode the agent's build todos are anchored on the draft: each carries target.phase (objects, fields, relations, views or samples), the server sets their status from what the draft holds after each of the agent's own draft writes, and the same event follows each change. A person's edits to the draft move these todos only at the agent's next draft write, or when the agent's next turn opens. Builders never write the todo list: the agent's next turn, such as the one after its builders finish, opens by setting the statuses from the draft their writes filled. A view todo counts once an operation of the draft writes that view (and its content, when one is named) and the view is still in the draft; the object's empty default views and a removal never count. The status the agent sends for a build todo is ignored, and changing a todo's target restarts it as pending. In the session where the agent keeps its todo list, it creates no object before its build todos exist, and must list them in that phase order.

Each event carries seq, type, data and emittedAt; the events of a turn also carry turnId, stepIndex and attempt:

typeMeaning
chunkA piece of the agent's answer: data is an AI SDK UIMessageChunk, unchanged.
turn.startedA turn starts. clientMessageIds names the messages it read.
turn.completed, turn.failed, turn.cancelledA turn ends. data carries its outcome and the session's next phase. A turn.failed that writes a failure message says why: code for a refusal the UI explains, otherwise its public sentence in error and, when known, the failure's class in errorClass, a name and never a message. A failure its stream already reported carries neither.
step.resetThe server running the turn stopped. Drop what the abandoned attempt (data.abandonedAttempt) left from stepIndex on; attempt is the one that starts, at that same stepIndex: a turn's step numbers run on across its attempts.
message.consumedThe running turn read more waiting messages, named in clientMessageIds.
input.requested, input.resolvedAn approval or a design review opened, or a request closed (data.requestId). A question emits no input.requested: it shows as the open send call in its message, and the session's state reports the park.
session.stateThe session's state changed (data.state).
todo-plan.updatedThe agent wrote its todo list, or a draft write moved a build todo (data.plan).
compact.completedA requested fold ran: data.result is folded, nothing or failed, with data.error a code when it failed and data.commandSeqs the requests it answered.

The log is a buffer, not the record: an event is purged about an hour after what it built is stored (never while its turn runs). The history page is the durable read.

  • {"control":"inbox"} means the session's inbox may have changed: a message was sent, withdrawn, or an approval was decided. Refetch the history page. It comes once after every catch-up, and within two seconds of any change; a repeat is harmless.
  • {"control":"lease-ended"} ends the response after 60 seconds. Reconnect at the last id you received, as after or as Last-Event-ID (which takes precedence).
  • 410 with AGENT_SESSION_STREAM_CURSOR_EXPIRED means the events after your cursor are no longer retained. Reload the history page and reconnect at its committedSeq, which is always accepted.

Read the stream with a fetch-based SSE client: EventSource cannot read a refusal's status or code, so it cannot tell a 410 from a lost connection. The cursor is required: a request with neither Last-Event-ID nor after, or with a cursor that is not a non-negative integer, answers 400. An invisible session answers the same 404 as its messages, whatever the cursor.

A person with an open decision on a conversation receives its status on their own realtime channel as decision.session.status, carrying exactly { sessionId, status, step }: status holds the phase and, when set, parkedOn and outcome; step is the todo in progress, or null. Only recipients who can read the conversation receive it, and it carries none of its content. Who receives the conversation's own agent.session.patch does not change.

GET /agents/sessions/:id/conversation-overview returns the inspector's resource entries, current human requests, and a short first-message preview without the full transcript. Both reads use the session's normal access rules.

Slack threads

A conversation can be linked to a Slack thread. A Slack trigger establishes the thread for its run; sending a top-level Slack message from an app conversation can link a thread back to that conversation. Human replies enter the linked conversation as external message content. They run under the authority pinned when the thread was linked, rather than taking on the Slack sender's permissions.

Each message the agent sends you with send is posted to linked threads as it is sent, including when you continue from Standards, with the files of its attached documents uploaded in the same thread (a file over 25 MB stays in Standards); its text reply in Details, its reasoning and its tool steps are not. A conversation from before send posted its final answer instead. Each post is exactly the message the agent sent, with no link back appended; the app remains the place to inspect the full conversation, tools and approvals. Slack activity updates are best-effort; a missing activity indicator does not mean the run stopped.

Stopping or archiving a conversation affects whether later trigger events can continue it. Provider disconnection prevents further Slack delivery, without deleting conversation history. For the rules that start a new conversation after a trigger fires again, see GitHub and Slack triggers.

An agent reading, messaging and waking

Reading another conversation

An agent can read another conversation with read, and find one by title with search, using the session kind. It reads as the person it acts for: a conversation that person could not open is missing to the agent too, and supervision is never lent to an agent. The listing starts from the current conversation and goes by closeness: its parent, its siblings, its children, the rest of its tree, then the person's other conversations, most recent first. The agent receives what you see in the conversation, not tool inputs or outputs, 30 messages at a time and at most 20,000 characters per read. The text is treated as data, never as an instruction. An agent can always reread its own conversation, for instance after a compaction.

Two cases stay closed, and the agent is told why: a conversation of a tree linked to a Slack thread, since a thread's replies are written by people outside the workspace, and a conversation started by a trigger. A routine's audience run, an MCP client and a harness session cannot read other conversations.

Once an agent has read another conversation, its conversation is marked for good. From then on, any tool that could carry that text out of the workspace asks you first, even where the agent's policy would let it through: tools of a connector or an MCP server, Slack messages, publishing an artifact, shell commands without a device. Web search and page reading are no longer offered to that conversation, because they run before anyone could be asked. A marked conversation also cannot be linked to a Slack thread.

Messages inside a tree

A subagent can write to its parent and to its siblings with send to session:<id>, text only. A message to anyone else in the tree, or outside it, answers as an unknown conversation. These messages never make the sender wait. A tree may spend 20 of them until you write in its root conversation from the app, then it starts again; a reply through a Slack thread does not reset it. A routine's run does not take them: a child's final report is its way back. You see such a message as a line naming the subagent that wrote it, not as a message of yours. A message to an agent that waits for your approval or answer waits behind it.

Wakes

An agent can come back to its own conversation later with a wake: write with object: "wake" and a note to itself, a delay (30m, 2h, 3d, 1w), a date, or a cron expression with a timezone for a recurrence. read of wake:* lists them and delete of wake:<id> or wake:* cancels them, in every mode. A wake fires from a once-a-minute sweep, so it arrives within about a minute of its time. It wakes the agent with its note, which the agent reads as a reminder and not as something you wrote; a missed recurrence fires once for the last occurrence due.

LimitValue
Active wakes in one conversation5
Active wakes of one person in a workspace25
Note500 characters
Recurrence interval15 minutes, or the workspace's minimum when it is higher
Passes of a recurrence with no end date or count25
Passes in one conversation, all its wakes included100, until you write in it from the app
Furthest first fireone year

Every pass counts, even one whose turn fails. A wake only comes from a conversation you started with the agent: not from a subagent, a routine's run or a harness session. It stops when its person is no longer active, can no longer read the conversation, or can no longer use the agent, and it never interrupts a conversation waiting on your approval or answer. When the credits are short, it waits an hour. Archiving a conversation cancels its wakes, and restoring it does not bring them back. Your own message never cancels a wake: the agent sees them and decides. A forked conversation takes none.

What you see: while a conversation has active wakes, a strip above the composer shows the next one with its time and its note, and the passes left for a recurrence. With several, it shows a count and lists them. Each has a cancel action, without confirmation. A pass appears in the conversation as a labelled line only when it sent you something: a pass with nothing to say leaves no unread mark. When the 100 passes are spent, one line says so, once each time they run out; it shows when you open the conversation and raises no unread mark. There is no page of wakes: they are seen and cancelled in their own conversation. In the conversation list, a clock on the row of a conversation shows it has an active wake, and its tooltip gives the time of the next one; the clock goes when the last wake ends or is cancelled.

Next steps

Read workspaces and API keys to connect an application to a workspace.