Build an AI Agent

An AI Agent is an application that talks to a language model. It receives messages, reasons about them, calls tools (like reading data or triggering actions), and responds. Under the hood, it is a standard RootCX Application with one extra configuration file: agent.json.

It inherits everything a regular application has -- Authentication, RBAC, Audit Logs -- plus session memory, supervision policies, and streaming responses.

Create an Agent with Forge

Open the AI Forge in Studio. Describe your agent, its purpose, and what tools it should access.

Example prompt:

"Create a customer support agent. It should be polite and concise. Give it read access to the Orders app and the ability to send Slack notifications. Enable session memory."

The Forge generates everything: the agent.json configuration, a Markdown system prompt, the manifest with permission keys, and the backend logic.

What Gets Generated

After the Forge builds your agent, review the key files:

• agent.json -- configures the agent's name, system prompt path, memory settings, turn limits, and supervision policies.
• agent/system.md -- the instructions your agent follows. Plain Markdown, editable at any time.
• manifest.json -- declares the agent's entities, permission keys, and actions.
• backend/index.ts -- the LLM invocation logic.

agent.json

This is the file that turns a regular application into an AI Agent:

{
  "name": "Support Agent",
  "description": "Handles customer queries about orders and shipping",
  "systemPrompt": "./agent/system.md",
  "memory": { "enabled": true },
  "limits": {
    "maxTurns": 20,
    "maxContextTokens": 100000,
    "keepRecentMessages": 10
  },
  "supervision": {
    "mode": "supervised",
    "policies": [
      {
        "action": "mutate",
        "entity": "orders",
        "requires": "approval"
      }
    ]
  }
}

Tools and RBAC

Your agent uses the platform's built-in tools, governed by the same RBAC policies as human users:

• query_data -- read records from any entity across any app.
• mutate_data -- create, update, or delete records.
• describe_app -- inspect the data model of an app.
• list_apps -- discover all installed applications.
• list_integrations -- browse available integrations and their actions.
• browser -- control a real browser (navigate, click, type, snapshot).

Each tool is gated by RBAC. If the agent lacks a permission, the Core blocks the call instantly. No hallucinated calls can bypass this.

Session Memory

When memory is enabled, the agent retains conversation history across messages within a session. A user can ask follow-up questions without repeating context.

Supervision

Supervision controls how much freedom the agent has before acting:

In supervised mode, you define granular policies per action or entity. For example, allow the agent to query freely but require approval before modifying order records.

When approval is required, the agent pauses, an approval request appears in Studio, and a human approves or rejects. The agent then resumes or adapts.

Deploy and Test

Hit Run (F5). The Core installs the manifest, syncs the schema, and starts the backend -- same flow as any application. The agent gets its own system identity with deterministic RBAC permissions.

Test it by sending a message and observing the streamed response in Studio.

Full agent.json Example

{
  "name": "Finance Agent",
  "description": "Automates invoice processing and payment reconciliation",
  "systemPrompt": "./agent/system.md",
  "memory": { "enabled": true },
  "limits": {
    "maxTurns": 15,
    "maxContextTokens": 100000,
    "keepRecentMessages": 10
  },
  "supervision": {
    "mode": "supervised",
    "policies": [
      { "action": "mutate", "entity": "invoices", "requires": "approval" },
      { "action": "mutate", "rateLimit": { "max": 20, "window": "1h" } },
      { "action": "query", "rateLimit": { "max": 200, "window": "1h" } },
      { "action": "*", "rateLimit": { "max": 500, "window": "1d" } }
    ]
  }
}

This configuration:

• Enables session memory with context compaction at 100k tokens.
• Caps reasoning at 15 turns per invocation.
• Requires human approval before mutating invoices.
• Rate-limits mutations to 20/hour and queries to 200/hour.
• Hard caps total tool usage at 500 calls/day.

Next Steps

• Build an Application -- understand the foundation every agent inherits.
• RBAC -- how to assign permissions to your agent's role.
• For developers: REST API for the invoke and approval endpoints.