Skip to content

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 /agent
  • POST /agent
  • PUT /agent/:id
  • DELETE /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

  • POST requires name, role, internalNameId, visibility, brain, and instructions.
  • brain requires one primary model and at least one supported language.
  • instructions requires a systemPrompt, personality, and writingStyle; the rule arrays are optional and normalize to empty arrays in the command layer.
  • internalNameId must be unique per agency. Duplicate creates return AI.AGENT_ALREADY_EXISTS.
  • PUT supports partial updates, including isEnabled, brain config, instructions config, knowledge config, and limits config.
  • The update command deliberately ignores knowledge.embeddingModel changes even though the entity supports them, because changing embeddings would invalidate the existing vector collection.

Read Behavior

  • GET /agent currently forces a public projection by passing publicVersion=true.
  • The public list response omits sensitive internals such as the full system prompt, knowledge config, and limits config.
  • POST and PUT return the full agent DTO, including nested configs, stats, agencyId, and orgId.

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
  • executionLimitAction defaults to block_next

Delete Semantics

Agent removal is intentionally two-mode:

  • If the agent has already processed messages, DELETE does not remove it. The command disables the agent and returns { action: 'disabled' }.
  • If the agent has never been used, DELETE removes 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

CodeHTTPMeaning
AI.AGENT_ALREADY_EXISTS409The same internalNameId already exists for the agency.
AI.AGENT_NOT_FOUND404The requested agent id does not exist.
AI.UNEXPECTED_ERROR500Persistence or other unexpected infrastructure failure.

Notes

  • The list query reads public agents by agency today. The internal AgentByOrg query 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.