Configuration

Project structure, config files, and environment variables for the AUI Agent Builder CLI.

Project Structure

After running aui import-agent or aui agent --create, your project directory looks like this:

my-agent/
├── agent.aui.json              # Agent identity, objective, guardrails, tone
├── parameters.aui.json         # Data units (input/output definitions)
├── entities.aui.json           # Groups of related parameters (the ontology)
├── integrations.aui.json       # API, RAG, and MCP connections
├── rules.aui.json              # Global behavioral rules
├── tools/                      # Agent capabilities (one file per tool)
│   ├── product_search.aui.json
│   └── generative_ai.aui.json
├── scenarios/                  # Evaluation scenarios and scores
│   ├── scenarios.aui.json
│   ├── scenarios-scores.aui.json
│   └── intent/                 # Raw intent files, docs, sample data
├── traces/                     # Saved interaction traces (aui apollo trace)
├── GUIDE.md                    # Step-by-step building guide
├── .auirc                      # Project config (agent, version, account, env)
├── .aui-schema/                # JSON schemas for validation
│   └── aui.dschema.json
├── .vscode/
│   └── settings.json           # Schema autocomplete for VSCode/Cursor
└── .cursor/ · .claude/ · .opencode/   # Coding-agent skills (generated on import)

File Reference

File	Purpose
agent.aui.json	Core agent configuration — name, objective, personality, guardrails, tone of voice
parameters.aui.json	Defines data units the agent collects or outputs
entities.aui.json	Groups related parameters into logical entities (the agent’s ontology)
integrations.aui.json	External connections — APIs, RAG knowledge bases, MCP servers
rules.aui.json	Global behavioral rules that govern agent behavior
tools/*.aui.json	Individual tool definitions — each tool is a separate file
scenarios/	Evaluation scenarios and recorded scores (managed by aui scenarios)
GUIDE.md	Auto-generated step-by-step building guide
.auirc	Project-level config linking to your account, agent, and version
.aui-schema/	JSON schemas for local validation and editor autocomplete

VSCode and Cursor get automatic JSON schema autocomplete for .aui.json files via the .vscode/settings.json generated during import. Coding-agent skill folders (.cursor/, .claude/, .opencode/) are also generated so agents like Cursor and Claude Code understand how to build AUI agents. Skip them with --no-skills.

---

Session

Stored at ~/.aui/session.json after login. Contains:

• Auth token (JWT) and refresh token
• User info (ID, email, name)
• Organization ID and name
• Account ID and name
• Agent ID and name
• Environment and API URL
• Token expiry timestamp

Do not commit ~/.aui/ to version control. It contains authentication tokens and API keys.

---

Project Config (.auirc)

Created in your project directory by aui import-agent or aui agent --create. It links your local project to a specific agent and version on the AUI platform:

.auirc

{
  "agent_code": "my_agent",
  "agent_id": "abc123",
  "agent_management_id": "am_abc123",
  "version_id": "ver_abc123",
  "version_tag": "v3.2",
  "environment": "staging",
  "account_id": "...",
  "organization_id": "...",
  "network_category_id": "...",
  "network_api_key": "..."
}

Commands like push, pull, apollo, version, and scenarios read their target from .auirc. If your session is scoped to a different organization than the project, run aui sync-session (the CLI also does this automatically before most commands).

---

Environment Variables

Environment variables override file-based configuration. Useful for CI/CD pipelines.

Variable	Description
AUI_AUTH_TOKEN	Skip login — use this JWT directly
AUI_API_URL	Override API base URL
AUI_ENVIRONMENT	Set environment (staging, custom, production, eu-production)
AUI_ACCOUNT_ID	Account ID
AUI_ORGANIZATION_ID	Organization ID
AUI_AGENT_CODE	Agent code
AUI_KBM_API_KEY	RAG knowledge base API key
AUI_AGENT_TOOLS_API_KEY	Agent Settings API key
AUI_API_WORKFLOW_KEY	API Workflow key

# Example: run a command against production without switching env
AUI_ENVIRONMENT=production aui list-agents

---

Secure Key Files

Additional credentials are stored as secure files (mode 600) in ~/.aui/:

File	Purpose
~/.aui/kbm-key	RAG API key
~/.aui/agent-settings-key	Agent Settings API key
~/.aui/api-workflow-key	API Workflow key

Mock DB runtime and management keys are stored per-agent when you run aui mockdb provision. Inspect their prefixes (never the secrets) with aui mockdb keys.

---

Environments

AUI supports the following environments:

Environment	Description
staging	Development and testing
production	Live production environment (default)
eu-production	EU-hosted production
custom	Custom environment

Switch environments:

aui env staging
aui env production
aui env eu-production
aui env custom

The active environment is stored in ~/.aui/environment.

Next Steps

Command Reference

Full reference for all CLI commands.

Workflows

Common development workflows and patterns.