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}}" } } }

MCP Integration

Separate from Agent Builder's own pipeline-to-webhook integrations above, caveauAI implements the Model Context Protocol (MCP) — an open standard that lets AI assistants like Claude Desktop, Cursor, and VS Code query your corpora directly, as native tools inside your existing workflow.

Available tools

A full caveauAI tenant account has access to a larger tool set (memory, repo search, admin tools). The tools below are the ones relevant to corpus access via the Knowledge Exchange:

Tool	Purpose
`caveau_search`	Search across your entitled corpora with natural language. Returns ranked, cited passages.
`caveau_list_obligations`	Browse structured, admin-approved regulatory obligations (actor / action / deadline / penalty), each cited to source.
`caveau_compliance_check`	Paste in a policy document and check it against a regulation's obligations. Returns cited met / partial / gap verdicts for the most relevant obligations — a bounded, synchronous check, not exhaustive coverage.
`caveau_get_document`	Fetch a single document by id along with its chunked content.
`caveau_list_corpora`	List the corpora your token is entitled to query.

Knowledge Exchange: corpus-scoped access

Get MCP access scoped to a single corpus package — no full caveauAI account required:

Browse the available corpus packages on the Knowledge Exchange storefront.
Request access with just your email — no existing account needed.
You'll receive one email with your MCP endpoint and a Bearer token scoped to that package's corpus. The token is shown only in that email and can't be recovered afterward.
Paste the endpoint and token into your MCP client config below and start querying.

Tip: Every corpus package is currently free while we validate the product with early users — there's no charge today.

Claude Desktop configuration

Add to your claude_desktop_config.json, using the token from your Knowledge Exchange fulfillment email:

{ "mcpServers": { "caveau-ai": { "url": "https://mcp.caveauai.bluenotelogic.com/mcp", "headers": { "Authorization": "Bearer <your token from the fulfillment email>" } } } }

Cursor / VS Code configuration

Add to your project's .mcp.json:

{ "servers": { "caveau-ai": { "type": "http", "url": "https://mcp.caveauai.bluenotelogic.com/mcp", "headers": { "Authorization": "Bearer <your token from the fulfillment email>" } } } }

Example: checking a policy against a regulation

A caveau_compliance_check call and the kind of cited, evidence-based verdict it returns:

> caveau_compliance_check( regulation_document_id: 52996, // from caveau_list_obligations policy_text: "Our AI systems maintain automatic logging capabilities throughout their lifecycle..." ) EU Artificial Intelligence Act — 3/214 obligations checked met: 1 partial: 1 gap: 1 --- MET --- • Providers of high-risk AI systems: Ensure high-risk AI systems technically allow for automatic recording of events (logs). "The evidence explicitly states that AI systems maintain automatic logging capabilities throughout their lifecycle." (confidence 1.00) --- PARTIAL --- • Providers of high-risk AI systems: Ensure logging enables recording of events relevant for monitoring per Article 26(5). "Logging is mentioned but it's unclear whether it specifically covers Article 26(5)'s monitoring requirements." (confidence 0.60) Checked the 3 most relevant obligations of 214 total in this regulation — not exhaustive coverage.

Note: Knowledge Exchange tokens are scoped to the single corpus package you got access to. caveau_compliance_check is rate-limited to 20 calls per rolling 30 days per account, independent of your credit balance.

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