Agent chat

Agent chat is the endpoint family for conversations with a persona: the agent answers in character, remembers past sessions, reads the documents linked to it, calls your HTTP tools when it needs live data, and can ask a colleague for a second opinion. It is the right choice when your application is built around a specific agent. If you only want to point an existing OpenAI or Anthropic client at an agent, use the Gateway with the model name agent:<slug> instead.

There are two styles, each with a plain and a streamed form:

Use a developer API key (Authentication). On a restricted key, these routes need the agents scope alongside your capability scope; a readonly key is refused because chatting writes (history, memory). Each chat route is also limited to 30 calls per minute per client, and a key can carry its own per-minute limit and monthly ceiling (Rate limits and quotas).

Each turn is metered against the workspace allowance of questions on the model usage of the whole turn (retrieval, tool rounds and consultations included), and an exhausted allowance is a 402 before any model runs (Rate limits and quotas).

Every event is one line data: <json> followed by a blank line, where the JSON is { "type": "<name>", "data": <payload> }. A line starting with a colon (: ping) is a keep-alive comment, not an event: ignore it. The stream ends after done or error; the server then closes the connection, there is no [DONE] sentinel.

A client has to do four things: read the body incrementally, split it on blank lines, parse data: lines as JSON, and treat error as a failure. The examples below print tokens as they arrive, collect citations and tool calls, and return the final done result.

context lets your application hand the agent live data without storing it anywhere: the customer record on screen, today's figures, the form the user is filling in. Each item becomes a labelled section of the agent's prompt, sorted high priority first. It is used for this call only and is not saved to the session.

The agent can cite what it used. Items it relied on come back in contextUsed (streamed done event) with origin: "context", numbered after the document passages in knowledgeUsed, so a [3] in the answer may point to your data rather than to a document: do not offer to open it as a file. Provenance also applies to memory: a fact the agent saves from context is stored with provenance data (Agent memory).

When the call is served by an external model provider, personal data in the context is masked first and restored in the answer, like any other Subsidia call (Synapse).

With extraction, a separate pass reads your message (not the answer) and pulls out structured facts in the categories you name. They come back in extracted as { category, key, value, confidence } and, unless persist is false, are stored in the workspace's extracted data. It is a convenient way to turn free-text intake ("I'm Anne, I run a bakery in Lyon with 4 employees, I prefer email") into fields for your CRM in the same call that produces the reply.

Set responseFormat.type to json and describe what you want in fields (a map of field name to description) or as a free-form schema. The agent answers with a JSON object only. In the response, content is the JSON text and contentParsed is the parsed object; if the model's output was not valid JSON, contentParsed is absent and you should treat content as unparsed.

JSON mode changes how the turn behaves: the agent does not write memories, does not consult colleagues, and with options.reflection its reasoning is returned as a thoughts field inside the JSON instead of a separate pass. Validate the object on your side; the format is an instruction to the model, not a schema enforced by the server.

When retrieval is on, the agent reads passages from the knowledge sources linked to it (attach them with the agentIds field of POST /v1/knowledge-sources), within the access rules of the workspace. The retrieved passages are numbered 1..n in knowledgeUsed. In the answer, a claim backed by a passage is followed by its marker, for example [1]; markers that match no passage are removed before you see them.

Subsidia also marks provenance inside the text, and computes it itself instead of trusting the model: every marker the model wrote is removed, then each anchor an auditor would copy (a number, a date, an amount, a proper name) is checked against the retrieved passages. An anchor found in a passage that discusses the same subject is wrapped as U+27E6 anchor U+27E7 followed by its [n] (white square brackets, a verified claim); an anchor found nowhere is wrapped in U+27EC and U+27ED (white tortoise-shell brackets) and is the agent's own, not backed by your documents. Reasoning and opinion stay unmarked. If you display answers, either render these spans (a rail or underline is enough) or strip the delimiters; do not leave them in as plain text. A missing document is a reason to mark provenance, not to refuse, so the agent still answers when the base is silent.

The passages retrieved for a turn are committed to the proof certificate of the turn, so an auditor can check what the answer was grounded in (Proof certificates).

With consult on (the default), an agent can ask another agent of the workspace for a second opinion before it answers, through an internal tool called ask_colleague. Rules that matter for an integration:

• It is the colleague's judgment, inside its declared mission, that is consulted. The colleague answers from its persona and expertise alone, with no documents and no tools of its own, in at most about 400 tokens, and consultations never nest.
• At most two consultations per turn, among up to twelve other agents of the workspace. Postes are not colleagues.
• Consultations are visible: they stream as consult_start and consult_result events and come back in consultations in the done event, each with the question, the answer and the duration. Nothing happens off the record.
• It is disabled in JSON mode, and with consult: { "enabled": false }.

Write each agent's mission and outOfScope so that colleagues know what to ask whom (Agents).

If the agent has tools linked and tools.enabled is not false, the model may ask for one or more of them while preparing its answer. Subsidia calls your endpoint, reads the JSON you return, feeds it back to the model, and repeats for at most three rounds before the final answer. Each call is reported in toolCalls (toolName, arguments, result, success, error, durationMs) and streamed as tool_call and tool_result. A failing tool does not fail the turn: the agent receives the error and answers with what it has, and it is told never to claim an action it has no tool result for. Use tools.toolIds to narrow a turn to the tools relevant to the screen you are on.

Each turn is saved in its session (Sessions): your message and the agent's answer, with its metadata (sources, tool calls, tokens). The agent also recalls and may write long-term memory (Agent memory); the notes written during the turn are returned in memoriesSaved. To call an agent without memory, use the Gateway address agent:<slug>+nomemory.