Skip to content
SubsidiaDevelopers Get an API keyAPI key

Agents

Create, read, update and delete the agents (personas) of a workspace through the API.

An agent is a persona that lives in a workspace: a name, a role, a character, a mission and a system prompt. Once it exists you can talk to it (Agent chat), give it memory (Agent memory), link it to your own HTTP tools (Tools), link it to knowledge sources (Knowledge sources), put it around a table with other agents (Conversations), or call it by name from any OpenAI or Anthropic client through the Gateway with the model address agent:<slug> (Model addressing).

This page covers the persona itself and the four endpoints that manage it. Everything is scoped to the workspace of your API key: another workspace's agents are indistinguishable from missing ones.

The persona model

Six text fields are required to create an agent. They are not decoration: each one is injected into the prompt the model sees, in a different place and with a different effect. The API returns the full row, including a few fields that only the console edits.

FieldTypeSet through the APIWhat it does
idstringNo, generatedStable identifier. Use it in every path (/v1/agents/:id/...).
namestringRequiredHow the agent is named in answers, in debates and in the roster other agents see when they consult a colleague. Keep it short and unique inside the workspace.
rolestringRequiredA job title in a few words ("Contrôle de gestion"). Shown next to the name in every surface and read by the auto-pick router of Agent chat.
personalitystringRequiredThe character: tone, temperament, habits of speech. This is what makes an answer sound like the agent and not like a generic assistant.
missionstringRequiredWhat the agent is for, in one specific sentence. It is the boundary other agents read before consulting this one and the line the agent quotes when it declines an off-topic question. Also read by the auto-pick router.
decisionStylestringRequiredHow it reasons and chooses: cautious, contrarian, evidence-first, speed-first. It shapes disagreements in debates.
systemPromptstringRequiredFree-form instructions appended to the persona: domain rules, output conventions, things to never do.
isDevilsAdvocatebooleanOptional, default falseMarks a contrarian persona. Debates always seat one devil's advocate per workspace; agents flagged this way are not drawn as regular debaters (see Conversations).
expertise, outOfScopestring[]No, console onlyThe subjects inside the mission, and the subjects to decline and hand off. Returned as empty arrays for agents created through the API. Postes use them heavily.
collectionScope, checkliststring[]No, console onlyA poste's dossier scope and control list. See Postes.
isSharedbooleanNoWhether the agent's global memories are shared across the workspace.
createdAtISO dateNoCreation time. Lists are ordered by it, oldest first.

Design tips

  • One agent, one job. A precise mission beats a long prompt. "Check that every figure is backed by a document of the file" gives the router, the colleagues and the agent itself something to hold on to; "Help with finance" gives them nothing.
  • Put character in personality and decisionStyle, rules in systemPrompt. Character fields are weighed on every answer; the system prompt is where you write constraints ("never quote a figure without its source", "answer in the language of the question").
  • Do not write output formats into the prompt. Ask for structure per call with responseFormat (Agent chat); the prompt stays reusable.
  • Keep facts out of the prompt. Documents belong in Knowledge sources linked to the agent, where they are retrieved, cited and signed into the proof. Per-call data belongs in the context array of the chat request.
  • Give the workspace a contrarian. A debate with only agreeable personas converges in one round. One agent with decisionStyle "contrarian" earns its seat.
  • Test with a fixed question set. Change one field at a time and replay the same three or four questions; persona behaviour moves more than people expect.

Authentication and scopes

Send the key as Authorization: Bearer sk_live_... or x-api-key: sk_live_... (Authentication). A key issued without capability scopes (a legacy key) reaches every route. A restricted key, one that carries a capability scope such as engine, reaches the agent routes only if it also carries the agents scope; otherwise the answer is a 403 scope_denied. A key with the readonly scope can list and read agents but cannot create, change or delete them (403 read_only_key).

Endpoints

GET/v1/agents

List the agents of the workspace.

API key (Bearer or x-api-key)agents

Returns every agent of the workspace, oldest first, with all persona fields. The list includes the workspace's devil's advocate once a debate has created it, and any installed poste. Filter on the client side if you only want conversational personas (postes have empty personality and decisionStyle).

Request examples

curl https://api.subsidia.protypa.fr/v1/agents \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

An object with an agents array.

Example response
{ "agents": [
{
  "id": "cm2k8x1ab0001qz0f7h3d9t4e",
  "userId": "cm1u0a0000000qz0fowner001",
  "workspaceId": "cm1w0b0000000qz0fworksp01",
  "name": "Claire",
  "role": "Contrôle de gestion",
  "personality": "Precise, calm, allergic to round numbers nobody can source.",
  "mission": "Check that every figure in a client file is backed by a document of that file.",
  "expertise": [],
  "outOfScope": [],
  "decisionStyle": "Evidence first: never concludes without a cited piece.",
  "collectionScope": [],
  "checklist": [],
  "systemPrompt": "You are Claire, a management controller. Answer in the language of the question...",
  "isDevilsAdvocate": false,
  "isShared": false,
  "createdAt": "2026-10-09T08:15:42.118Z"
}
] }

Errors

  • 401No key, invalid, revoked or expired key.
  • 403scope_deniedA restricted key without the agents scope.

POST/v1/agents

Create an agent.

API key (Bearer or x-api-key)agents

Creates a persona in the workspace of the key. The six text fields are all required and must be non-empty. The agent is usable immediately: chat with it, link tools, link knowledge sources.

Request body

  • namestringrequired
    Display name of the agent.
  • rolestringrequired
    Job title in a few words.
  • personalitystringrequired
    Tone and temperament.
  • missionstringrequired
    What the agent is for, in one sentence.
  • decisionStylestringrequired
    How the agent reasons and decides.
  • systemPromptstringrequired
    Additional instructions and rules.
  • isDevilsAdvocatebooleandefault false
    Mark the persona as a contrarian.

Request examples

curl https://api.subsidia.protypa.fr/v1/agents \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claire",
    "role": "Contrôle de gestion",
    "personality": "Precise, calm, allergic to round numbers nobody can source.",
    "mission": "Check that every figure in a client file is backed by a document of that file.",
    "decisionStyle": "Evidence first: never concludes without a cited piece.",
    "systemPrompt": "You are Claire, a management controller. Answer in the language of the question."
  }'

Responses

The created agent.

Example response
{ "agent": {
  "id": "cm2k8x1ab0001qz0f7h3d9t4e",
  "userId": "cm1u0a0000000qz0fowner001",
  "workspaceId": "cm1w0b0000000qz0fworksp01",
  "name": "Claire",
  "role": "Contrôle de gestion",
  "personality": "Precise, calm, allergic to round numbers nobody can source.",
  "mission": "Check that every figure in a client file is backed by a document of that file.",
  "expertise": [],
  "outOfScope": [],
  "decisionStyle": "Evidence first: never concludes without a cited piece.",
  "collectionScope": [],
  "checklist": [],
  "systemPrompt": "You are Claire, a management controller. Answer in the language of the question...",
  "isDevilsAdvocate": false,
  "isShared": false,
  "createdAt": "2026-10-09T08:15:42.118Z"
} }

Errors

  • 400A required field is missing or an empty string.
  • 403read_only_keyThe key carries the readonly scope.
  • 403scope_deniedA restricted key without the agents scope.

PUT/v1/agents/:id

Update an agent.

API key (Bearer or x-api-key)agents

Partial update despite the verb: send only the fields you want to change. Omitted fields (or fields sent as null) keep their value. Unlike creation, update does not validate emptiness: an empty string is stored as is, so do not send one unless you mean it. In particular, emptying both personality and decisionStyle turns the agent into a poste, which can no longer be chatted with.

Path parameters

  • idstringrequired
    The agent id.

Request body

  • namestring
    New display name.
  • rolestring
    New role.
  • personalitystring
    New personality.
  • missionstring
    New mission.
  • decisionStylestring
    New decision style.
  • systemPromptstring
    New system prompt.
  • isDevilsAdvocateboolean
    Toggle the contrarian flag.

Request examples

curl -X PUT https://api.subsidia.protypa.fr/v1/agents/cm2k8x1ab0001qz0f7h3d9t4e \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mission": "Check every figure of a client file against its documents, and say which one is missing."}'

Responses

The updated agent.

Example response
{ "agent": {
  "id": "cm2k8x1ab0001qz0f7h3d9t4e",
  "userId": "cm1u0a0000000qz0fowner001",
  "workspaceId": "cm1w0b0000000qz0fworksp01",
  "name": "Claire",
  "role": "Contrôle de gestion",
  "personality": "Precise, calm, allergic to round numbers nobody can source.",
  "mission": "Check that every figure in a client file is backed by a document of that file.",
  "expertise": [],
  "outOfScope": [],
  "decisionStyle": "Evidence first: never concludes without a cited piece.",
  "collectionScope": [],
  "checklist": [],
  "systemPrompt": "You are Claire, a management controller. Answer in the language of the question...",
  "isDevilsAdvocate": false,
  "isShared": false,
  "createdAt": "2026-10-09T08:15:42.118Z"
} }

Errors

  • 404Unknown id, or the agent belongs to another workspace.
  • 403read_only_keyThe key carries the readonly scope.

DELETE/v1/agents/:id

Delete an agent and its memories.

API key (Bearer or x-api-key)agents

Deletes the persona and every memory attached to it. This cannot be undone. Chat sessions that the agent took part in are kept (they are workspace conversations), but the agent can no longer answer in them.

Path parameters

  • idstringrequired
    The agent id.

Request examples

curl -X DELETE https://api.subsidia.protypa.fr/v1/agents/$AGENT_ID \
  -H "Authorization: Bearer $SUBSIDIA_API_KEY"

Responses

Deleted. No body.

Errors

  • 404Unknown id, or the agent belongs to another workspace.
  • 403read_only_keyThe key carries the readonly scope.

What to do next

Talk to the agent
One-to-one chat, streaming, structured answers, citations.
Give it memory
Read what it remembers and seed facts it should know.
Connect your systems
Register an HTTP endpoint as a tool the agent can call.
Use it from any client
Call it as agent:<slug> through the Gateway.

Related

Agent chat
Talk to one agent, or let Subsidia pick the best-fit agent: multi-turn sessions, knowledge citations, tool calls, structured JSON and a server-sent event stream.
Agent memory
What an agent remembers across conversations: how memories are written, ranked, deduplicated and labelled by provenance, and how to read, seed and delete them.
Tools
Register an HTTP endpoint of yours as a tool an agent can call during a chat, with a signed request, a JSON schema for its arguments and a JSON answer.
Sessions
Chat sessions keep the history of a conversation with an agent: create one, continue it, list and replay it.
Postes
Run a poste (a job-role agent such as the Auditeur de pièces) on one dossier and get a structured verdict, RAS or a list of findings, each tied to a piece.