Appearance
Agent Management
The AI module lets an authenticated agency manage reusable agent definitions that drive chats, RAG behavior, and token budgets.
Controller Surface
The controller-defined routes are:
GET /agentPOST /agentPUT /agent/:idDELETE /agent/:id
AIModule is not mounted yet, so these routes are documented from source and are not currently live in the running API.
Create and Update Rules
POSTrequiresname,role,internalNameId,visibility,brain, andinstructions.brainrequires one primarymodeland at least one supported language.instructionsrequires asystemPrompt,personality, andwritingStyle; the rule arrays are optional and normalize to empty arrays in the command layer.internalNameIdmust be unique per agency. Duplicate creates returnAI.AGENT_ALREADY_EXISTS.PUTsupports partial updates, includingisEnabled, brain config, instructions config, knowledge config, and limits config.- The update command deliberately ignores
knowledge.embeddingModelchanges even though the entity supports them, because changing embeddings would invalidate the existing vector collection.
Read Behavior
GET /agentcurrently forces a public projection by passingpublicVersion=true.- The public list response omits sensitive internals such as the full system prompt, knowledge config, and limits config.
POSTandPUTreturn the full agent DTO, including nested configs, stats,agencyId, andorgId.
Default Configuration on Create
When a new agent is created, the command only supplies the explicit brain and instruction payloads. The entity creates the remaining config automatically:
- knowledge config is created but starts with
isEnabled=false - Qdrant collection name becomes
agent-<agentId> - token limits default to unlimited (
0) budgets executionLimitActiondefaults toblock_next
Delete Semantics
Agent removal is intentionally two-mode:
- If the agent has already processed messages,
DELETEdoes not remove it. The command disables the agent and returns{ action: 'disabled' }. - If the agent has never been used,
DELETEremoves the agent row, deletes related knowledge documents, and publishes cleanup for the Qdrant collection and stored file keys.
This behavior prevents historical usage from suddenly pointing at a missing agent definition.
Structured Error Contract
| Code | HTTP | Meaning |
|---|---|---|
AI.AGENT_ALREADY_EXISTS | 409 | The same internalNameId already exists for the agency. |
AI.AGENT_NOT_FOUND | 404 | The requested agent id does not exist. |
AI.UNEXPECTED_ERROR | 500 | Persistence or other unexpected infrastructure failure. |
Notes
- The list query reads public agents by agency today. The internal
AgentByOrgquery exists in source but is not used by the controller. - The controller file also owns the streamed chat entrypoint
POST /agent/:id/chat, but that execution path is documented separately in Chat and Message Streaming.