Agent Builder: Technical Reference | CaveauAI by Blue Note Logic Inc.

Architecture

Agent Builder consists of a dedicated execution engine (FastAPI on an isolated server) proxied through the CaveauAI PHP platform on the production web server. The engine calls CaveauAI's existing search and chat APIs, which in turn route to the GPU inference cluster via the AI gateway.

Browser

Platform UI

Client

S1 PHP Proxy

Session & auth

Web Server

Agent Engine

FastAPI + SQLite

Pipeline Runner

GPU Cluster

S3 Gateway + Viper

Inference

Component breakdown

Component	Stack	Role
Platform UI	JavaScript (AJAX)	Agent management, run monitoring, template selection
PHP Proxy	PHP 8.4 (S1)	Session validation, bearer token injection, request forwarding
Agent Engine	Python / FastAPI + Uvicorn	Pipeline execution, scheduling (APScheduler), state management (SQLite WAL)
CaveauAI API	PHP (S1)	Corpus search, chat inference, document retrieval
AI Gateway	FastAPI (S3)	Model routing, GPU pool management, Ollama proxy
GPU Inference	Ollama on RTX 5090	LLM inference (qwen2.5:14b, dobetter-norge models)

Note: The Agent Engine runs on an isolated server with its own SQLite database. It communicates with CaveauAI via HTTPS API calls — no direct database access. This isolation means the engine can be independently scaled or replaced without affecting the core platform.

API Endpoints

All endpoints are accessed through the PHP proxy at ai.bluenotelogic.com/platform/ajax/agents_proxy.php. The proxy adds authentication and forwards to the engine. Direct engine access is not exposed publicly.

Method	Action	Description
GET	`list`	List all agents for the authenticated client
GET	`get`	Get a single agent by ID with full configuration
POST	`create`	Create a new agent from template or custom config
PUT	`update`	Update agent name, config, schedule, or enabled state
DELETE	`delete`	Delete an agent and all its run history
POST	`run`	Trigger a manual run (queued if concurrency limit reached)
GET	`runs`	List runs for an agent (paginated, newest first)
GET	`run_detail`	Get full run details including per-step input/output
POST	`schedule`	Update cron schedule and timezone for an agent
GET	`templates`	List available pipeline templates with step definitions
GET	`health`	Engine health check (returns status, version, uptime)

Authentication

The PHP proxy validates the client's CaveauAI session cookie and injects a Bearer token into the forwarded request. No API key management is required from the client side — authentication is session-based.

# Request flow Browser → POST /platform/ajax/agents_proxy.php?action=run&agent_id=5 → PHP validates session cookie → PHP adds Authorization: Bearer {engine_token} → POST https://agents.bluenotelogic.com/api/v1/agents/5/run → Engine validates token, executes pipeline → Response returned through proxy

Step Type Configuration

Each step in a pipeline has a type and a JSON configuration object. Steps execute sequentially — each step can access the output of all previous steps via template variables.

search

Queries the client's CaveauAI corpus via the platform search API. Returns ranked passages with citations.

{ "type": "search", "name": "gdpr_search", "config": { "query": "GDPR data processor obligations", "top_k": 10, "collection": null, "search_mode": "single" } }

Field	Type	Default	Description
`query`	string	—	Search query text (supports template variables)
`top_k`	int	10	Number of results to return
`collection`	string\|null	null	Specific Qdrant collection (null = default corpus)
`search_mode`	string	"single"	"single" or "iterate" (multi-topic)

chat

Sends a prompt to the AI model with optional context from previous steps. Uses the client's plan GPU model.

{ "type": "chat", "name": "analysis", "config": { "prompt": "Analyze these findings: {{steps.gdpr_search.output}}", "system_prompt": "You are a legal compliance analyst.", "temperature": 0.3, "max_tokens": 2000 } }

Field	Type	Default	Description
`prompt`	string	—	User prompt (supports template variables)
`system_prompt`	string	""	System instructions for the model
`temperature`	float	0.3	Sampling temperature (0.0 – 1.0)
`max_tokens`	int	2000	Maximum response tokens

transform

Reshapes or formats output locally without an API call. Useful for preparing email content or structured summaries.

{ "type": "transform", "name": "format_digest", "config": { "template": "## Research Findings\n\n{{steps.analysis.output}}", "format": "markdown" } }

notify_email

Sends formatted HTML email via the CaveauAI mail service. Styled in the Jazz Noir design language.

{ "type": "notify_email", "name": "send_digest", "config": { "to": ["legal@company.no", "cto@company.no"], "subject": "Weekly GDPR Brief — {{run.date}}", "body": "{{steps.format_digest.output}}" } }

notify_webhook

POSTs JSON payload to a public HTTPS endpoint. Includes SSRF protection.

{ "type": "notify_webhook", "name": "slack_post", "config": { "url": "https://hooks.slack.com/services/T.../B.../xxx", "method": "POST", "headers": { "Content-Type": "application/json" }, "body": { "text": "{{steps.analysis.output}}" } } }

Template Variables

Template variables use double-brace syntax and are resolved at execution time, just before each step runs.

Variable	Resolves To
`{{steps.<name>.output}}`	Full output from the named step
`{{steps.<name>.status}}`	Step status (completed, failed)
`{{inputs.question}}`	Agent's configured research topic / input query
`{{run.date}}`	Run start timestamp (ISO 8601)
`{{run.id}}`	Unique run identifier
`{{agent.name}}`	Agent display name
`{{agent.id}}`	Agent numeric ID

Resolution flow

Step 1 (search) → output stored as steps.gdpr_search.output ↓ Step 2 (chat) → prompt contains {{steps.gdpr_search.output}} → engine resolves variable → injects search results into prompt → output stored as steps.analysis.output ↓ Step 3 (email) → body contains {{steps.analysis.output}} → engine resolves variable → sends email with AI analysis

Tip: If a referenced step hasn't run yet or doesn't exist, the variable resolves to an empty string. Build your pipelines so each step only references steps above it in the sequence.

Security & Authentication

Authentication chain

Three-layer auth ensures no unauthenticated requests reach the engine:

Browser → PHP Proxy: CaveauAI session cookie validated against the platform database. Client must have agents_enabled = 1 on their plan.
PHP Proxy → Engine: Bearer token (agent_engine_token) injected by the proxy. Token is stored in server-side config, never exposed to the browser.
Engine → CaveauAI API: Engine uses a service-level API key to call search and chat endpoints on behalf of the client.

SSRF protection

Webhook URLs are validated before execution. The engine blocks requests to:

Private IP ranges (10.x, 172.16–31.x, 192.168.x, 127.x)
Link-local addresses (169.254.x)
Internal hostnames (localhost, *.internal)

Data encryption

Sensitive configuration values (API keys, webhook URLs with tokens) are encrypted at rest using Fernet symmetric encryption (AES-128-CBC + HMAC-SHA256). The encryption key is stored in the engine's environment, not in the database.

Important: Agent run output may contain sensitive business data from your corpus. Run history is stored in the engine's SQLite database and is only accessible to the authenticated client who owns the agent.

Quotas & Limits

Limit	Starter	Professional	Enterprise	Beta
Max agents	3	5	10	10
Runs / month	100	200	500	500
Concurrent runs	1	2	3	3
Max steps per agent	5	10	20	20
Step timeout	60s	120s	300s	300s
Min schedule interval	6 hours	1 hour	15 minutes	15 minutes
Run history retention	30 days	90 days	365 days	90 days

Note: Run counts are tracked per calendar month (UTC). The counter resets on the 1st of each month at 00:00 UTC.

Integration Examples

Slack webhook integration

Post agent output directly to a Slack channel using an incoming webhook URL:

{ "type": "notify_webhook", "name": "slack_alert", "config": { "url": "https://hooks.slack.com/services/T00000/B00000/xxxx", "method": "POST", "headers": { "Content-Type": "application/json" }, "body": { "blocks": [ { "type": "header", "text": { "type": "plain_text", "text": "{{agent.name}} — {{run.date}}" } }, { "type": "section", "text": { "type": "mrkdwn", "text": "{{steps.analysis.output}}" } } ] } } }

Scheduled GDPR monitoring

A compliance agent that runs every Monday morning Oslo time:

{ "name": "GDPR Weekly Monitor", "template": "compliance_monitor", "schedule_cron": "0 8 * * 1", "schedule_timezone": "Europe/Oslo", "config": { "topics": [ "GDPR data processor obligations", "AI Act compliance requirements", "employee personal data processing" ], "email_to": ["legal@company.no"], "depth": "standard" } }

Microsoft Teams webhook

Post structured cards to a Teams channel:

{ "type": "notify_webhook", "name": "teams_post", "config": { "url": "https://outlook.office.com/webhook/...", "method": "POST", "headers": { "Content-Type": "application/json" }, "body": { "@type": "MessageCard", "summary": "Agent Report", "themeColor": "C9A961", "title": "{{agent.name}} — Run Complete", "text": "{{steps.analysis.output}}" } } }

Ready to build?

Open the Agent Builder and create your first pipeline, or read the user guide for a step-by-step walkthrough.

Open Agent Builder User Guide Talk to an Architect

Agent Builder: Architecture & API