System Agents

System Agents

System agents are packaged, stateless agents used to inject system-level instructions and tools without requiring a direct agentId.

Purpose

• Provide reusable, managed behavior for specific object types or workflows.
• Allow clients to request agent context from Dialogue Script instead of passing agentId.
• Keep system agent assets global, versioned, and deployable via packages.

How System Agents Resolve

1. Dialogue Script includes <include type="system" name="rooms__AIModel__c" /> in the systemMessage.
2. POSTAIResponse extracts the tag, records the system agent key, and replaces the tag with the resolved prompt block.
3. Managed package keys (Namespace__Object__c) are resolved via the registry to a pkg:{uuid}.
4. The package is loaded and MetaPackage.models.get(0) becomes the system agent.
5. A synthetic agent id sys:{key} is used, and the system agent tools are attached to the model request.

Prompt Block Composition

The system agent prompt block replaces the tag inline and includes:

• AIAgent.systemPrompt when present.
• AIPrompt entries where isSystem=true and isActive=true.
• Tool include tags for every AISkill, for example: <include type="skill" primitive="query_sobjects" name="query_sobjects" />

Multi-turn Behavior

• Dialogue.systemAgentKey is persisted on init.
• Subsequent turns rehydrate system agent context without resending the tag.
• Transcripts record the system agent package id when available.

DevOps: Registry Maintenance

• Registry location: src/main/resources/agents/system/registry.csv
• CSV header: system_agent,pkg_id
• Each row maps a system agent key to a package id, e.g. rooms__AIModel__c,pkg:{uuid}
• Required default row: default,pkg:{uuid}. Used when a key is missing; fallback usage is logged via Ops.
• Update workflow:
  • Upload the system agent package via POSTPackage to obtain pkg:{uuid}
  • Add or update the row in registry.csv
  • Update the default row when rotating the fallback agent
  • Run mvn -Denv=dev -Dtest=SystemAgentRegistry_Tests test to validate parsing

Legacy Keys

Non-managed keys are legacy and may be removed. Prefer managed package keys with registry entries.