AI Agents — Administrator Guide

Audience: System administrators, Agent Administrators, and AI Auditors. Use this document when: You configure LLM providers, model configurations, tools, agents, versions, permissions, document intelligence, audit, or AI settings. Canonical for: AI configuration, publishing, permissions, audit, and settings. Related: AI Agents Index, End User Guide, Custom Template Guide, Report Design Recommendations, Document Processing.

This guide is the canonical reference for the enezaagents app. It describes the screens under the Agents menu and the settings that control the AI subsystem.

Roles and permissions

AI access is controlled by the framework's role-based access control. A user needs both the AI permission and the normal model or module permission.

AI action codes registered by the app:

A non-built-in agent is also checked against action.enezaagents.agent.<agent_code> and every permission in the agent's Required Permissions field. Confirm that the matching grant exists in your RBAC configuration before rollout. Built-in agents check their required permissions. Contextual and default agents are available without the per-agent action grant.

Setup order

Configure the subsystem in this order. Each step depends on the previous one.

1. Create an LLM Provider under Agents › LLM Providers.
2. Create a Model Configuration under Agents › Model Configurations.
3. Review or create Tools under Agents › Tools.
4. Create an Agent under Agents › Agents.
5. Create a draft Agent Version with instructions and a model configuration.
6. Attach tools and sub-agents to the version.
7. Publish the agent from the agent detail screen.
8. Verify availability for the intended users and pages.
9. Optionally configure Document Schemas and Document Templates.

Do not skip the model configuration step. An agent version without a usable model configuration cannot run.

LLM Provider

Open Agents › LLM Providers and create or edit a provider.

API key resolution order:

1. The environment variable named in API Key Environment Variable.
2. The encrypted key stored on the provider.
3. The standard environment variable for the provider type, such as OPENAI_API_KEY, DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY.

Never store a real key in documentation, source control, or a description field.

Model Configuration

Open Agents › Model Configurations and create or edit a model.

ai_seed_models can create common provider and model defaults. ai_set_default_model can mark a shared provider and model as the default and repoint shared agent versions to it.

Tools

Open Agents › Tools. Built-in tools are seeded by the app. Developer and REST tools are optional.

External tools are blocked by default. To allow DEVELOPER or REST_API tools, set AI_ALLOW_EXTERNAL_TOOLS=True in the project settings. A REST API tool also requires an endpoint URL.

Agents

Open Agents › Agents and create an agent.

Setting Application and Module helps the runtime record usage and helps users find the right agent. It does not by itself attach the agent to a page.

Agent Versions and publishing

Open an agent and create or edit its version. A version holds the runnable configuration.

Publishing rules:

• Only the latest published version is runnable.
• Publishing snapshots the working version's instructions, model configuration, output schema, required permissions, provider snapshot, tools, and sub-agents.
• Editing a draft does not change the running agent.
• Publishing again creates the next version number and marks it as latest.
• Archived versions are not runnable.
• A published snapshot is self-contained: later changes to a tool or sub-agent do not change the published version until you publish again.

Publish from the agent detail screen with the Publish action. Confirm the new version number and that the agent status is Published.

Tools and sub-agents on a version

Attach only the tools the agent needs. Each tool is also checked against the user's permissions and the tool's execution policy at run time.

Built-in agents

The framework provisions several built-in agents. ai_seed_tools ensures the Workspace Orchestrator, the Contextual Assistant, and the builder agents exist. The AI Workspace also ensures the orchestrator and builder agents when it loads.

Notes:

• dashboard_builder creates a dashboard draft only. It never publishes, edits, archives, or deletes an existing dashboard.
• report_builder creates a report draft or design recommendation only. It does not publish.
• The report designer is a page-specific mode of the report page assistant. It proposes changes to the saved report that is open; the user must apply them. See Report Design Recommendations.
• Built-in instructions and tools are code-managed. python manage.py ai_seed_tools can overwrite local edits to a built-in agent's instructions or tool list. Do not rely on local edits to built-in instructions.
• The Dashboard Builder uses seeded sample dashboards and dashboard report sources. If a module has no accessible dashboard report source, the agent cannot create a draft for that module.

For dashboard-builder behavior, tools, page contexts, and troubleshooting, see Dashboard Builder.

Document intelligence

Document intelligence parses record attachments and AI Workspace uploads, classifies them, extracts structured data against versioned schemas, analyses them against versioned templates, and records every operation as a document processing job with evidence.

Open Agents › Document Schemas and Agents › Document Templates to configure the definitions.

• Defining a schema or template only makes it eligible. A job must pass a code, a target model or category, or a pinned reference before it is used.
• Creating a row with an existing code assigns the next version. Mark older versions inactive to retire them.

For the field reference, selection rules, operation and tool behavior, job statuses, evidence, permissions, settings, and troubleshooting, see Document Processing.

Document jobs are recorded under Agents › AI Audit › Document Jobs and are read-only.

AI Audit and AI Insights

AI Audit

Open Agents › AI Audit.

Audit screens are read-only. AI activity models require the AI Auditor role for wider access. Normal users see only their own activity in normal screens.

AI Insights

Agents › AI Insights opens the module dashboard. Seeded dashboards:

Environment settings

These settings are read from the project environment or project settings. Defaults are shown where the framework defines one.

Management commands

Run these commands after installation or upgrade when the matching data is needed.

Worker queues

AI tasks are queued on the queue named by AI_TASK_QUEUE. The default is ai_tasks.

Confirm that at least one running background worker consumes that queue. If no worker consumes the AI queue, workspace tasks stay queued and document jobs do not complete.

The project task configuration includes these queues:

TASKS = {
    "default": {
        "BACKEND": "django_tasks_db.DatabaseBackend",
        "QUEUES": ["default", "workflow_tasks", "ai_tasks"],
    }
}

Security rules

• The language model is never an authorization authority.
• Every query uses the signed-in user's RBAC grants, entity scope, and record scope.
• The AI does not execute arbitrary SQL, arbitrary Python, or arbitrary ORM field paths from model output.
• System-managed fields, workflow status fields, audit fields, and entity fields are not writable by AI proposals.
• Proposed changes require confirmation and are revalidated when applied.
• API keys and sensitive fields are redacted from audit and user-facing output.
• Document text, tables, OCR output, and retrieved web content are untrusted data, not instructions.
• The AI must not create users, invite users, change roles, change privileges, or change administrator flags.
• The AI must not name inaccessible applications or models, or confirm that restricted data exists.
• The AI must not reveal another user's activity or attribution.

Troubleshooting

A note on testing

Per project rules, the developer or agent does not run or claim test results. The user is solely responsible for all testing and validation of the configuration described in this guide.