agents

List this organization's agents. Each carries its live version (current_version_id, None until first published), the language and AI profile of that version (the draft's before the first publish), whether its calls are recorded, and when anything about it last changed.

The platform's own agents -- the Architect and the Analyst -- are left out unless include_platform is true; then they are included, each with platform set. Use it to name the agent behind a conversation or a line of consumption, never to offer an agent to choose.

Create an agent in the caller's organization. Use when a new agent has to exist at all; it is born usable — a draft on the organization's default AI profile, holding a graph with one node that is already its root.

It arrives as a draft speaking the organization's language and takes no traffic until a version is published; an organization with no AI profile to start it on is refused. Its calls are not recorded unless record_audio says so — the switch is the agent's own, is not versioned, and starts off. Creating an agent with record_audio on needs the recording feature, as moving the switch later does.

List which agents ground on which documents — the library's own read. Use when checking what would be affected by changing or removing a document, or showing a document's usages. Changes nothing.

It is here and not under /documents because it answers about agents. rag holds the documents and this module holds the attachment, and neither may import the other; putting the route on the side that owns the array is what keeps that from needing a protocol, a binding and a second copy of the shape to travel through them.

No document_id asks for every attachment this organization has, which is one request for a whole table of documents rather than one per row. Naming ids narrows it — what the delete confirmation asks about one document.

Fetch one version of an agent by its version id. Use when you need the exact content of a specific past or published version, not the current draft.

Change a draft's name, language, phrases, AI profile, documents, call behaviour switches and timings, or the tools the whole agent carries. Use when configuring a draft before it is published; use replace_draft_graph or the one-by-one graph operations for the node graph itself.

Only the fields sent change. The agent's own recording switch, record_audio, rides along here and is not part of any version: it takes effect on the next call rather than at the next publish; moving it to a different value needs the recording feature (a body that repeats its current value is no move). global_tool_ids are available in every node; pre_hook_tool_ids run once before the first word, to fetch what the agent should know (the caller's record, their last order) — the caller is looked up by putting a collection's get_ tool here with its identity field fixed to $ref:conversation.number (update_tool, fixed_parameters); post_hook_tool_ids run once after the conversation ends. A tool that belongs to one situation goes on that node with update_node instead, and work with several steps after a conversation is an automation on an interaction ended, since a hook takes one tool each. Graph edits go through the draft's graph_id.

Edits the draft only. The published version keeps taking traffic until publish_version. Refused with 403 for one of the platform's own agents (the Architect, the Analyst).

Write a draft's whole graph in one act — every node, every edge, the root and each node's tools — replacing whatever the draft's graph held before. Use this when the graph has been designed already and is being written down; use add_node, add_edge, update_node and set_root for one change to a graph that exists.

Nodes carry a key of your choosing (any short string, unique in the payload); edges and root name nodes by that key, so the whole graph is declared before any id exists. A node's name is what a person will see it called — give each node one when you write a graph; the model never reads it. The response returns the graph as stored and node_ids, each key mapped to the id its node was given — use those ids with the one-by-one operations afterwards. A node's tool_ids are instance ids exactly as update_node takes them.

Refused whole — nothing about the draft changes, and reasons names every problem at once — when two edges leaving one node share a label (compared trimmed and case-insensitively), when a tool name would be offered twice across the agent (the draft's global tools count), or when an edge or root names a key no node carries. A node with no edges, or no root at all, is unfinished and is accepted: a draft may be. Takes the draft's version id (get_draft); a published version is refused. Nothing takes traffic until publish_version. Refused with 403 for one of the platform's own agents.

Make this version the one that takes live traffic. Use when the draft is ready and should start answering real calls.

Refused if the version could not run: a graph with no root node, or one naming a root it does not contain; no AI profile named, or one this organization cannot use; two visible tools sharing a name; two edges leaving one node under the same label. The refusal names every reason, one per entry. Refused with 403 for one of the platform's own agents.

Read one agent of this organization: its live version, language, AI profile, recording switch and last change. The draft is read with GET /agents/{agent_id}/draft and the published history with GET /agents/{agent_id}/versions.

Delete an agent and every version of it, permanently. Use when the agent should stop existing altogether, not just stop taking traffic.

Refused while something still routes conversations to it; the refusal names what has to be unassigned first. Refused with 403 for one of the platform's own agents.

Duplicate an agent, graph and all, as a new draft. Use when starting a new agent from an existing one instead of from scratch.

The copy is independent of the original and takes no traffic until published. Refused with 403 for one of the platform's own agents (the Architect, the Analyst).

Fetch the agent's draft — the version to edit. Use when about to change an agent's configuration or graph, or when you need its graph_id.

Its graph_id is what the graph tools (add_node, add_edge, set_root) take.

Read one agent's frame of the map: the agent's card, what brings it conversations, what runs before, during and after them, the collections and documents it reads and writes, and the connections its tools use -- each with its owner and whether it is working. Parts you may not see are counted in hidden, never named. Give owner to see one recipe's parts, or only the organization's own. Give draft=true to draw the frame from the agent's draft -- the version being edited, which answers no conversation until published -- instead of its published version; version_id names the version drawn and frame.draft says the draft was drawn. Changes nothing.

List what publishing the draft would change, against the version that is live. Use when deciding whether a draft is ready to publish, or summarizing what a publish would do before doing it.

The same vocabulary a published version records. Empty means the draft says what the live version says; an agent that has never been published has no since to be pending against and answers 404.

List what sits in an agent's pre- and post-conversation slots outside its versions: each tool a recipe placed there, whose it is (owner) and whether it is on. Use it beside the draft's own hooks to say everything that runs before and after the agent's conversations. A placement runs from the next conversation without a publish and is changed only through the recipe that owns it.

Publish an earlier version again, making it live. Use when the current live version is wrong and an earlier one should take traffic instead.

The draft is left alone; this changes what answers, not what is being edited. Refused with 403 for one of the platform's own agents.

List an agent's versions, oldest first, with what changed and who changed it. Use when reviewing an agent's history or picking a version to inspect or restore.

Read the organization's map: its agents, the automations that run on their own, what brings conversations to each agent, its collections and each agent's documents, as folded cards with the lines between them -- and, for each agent and automation, the frame of what runs before, during and after it. Each card says who owns it (an installed recipe or the organization) and whether it is working. Parts you may not see are counted in hidden, never named. Give owner to see one recipe's parts, or only the organization's own. Changes nothing.