User Guide
Agent Builder: Getting Started
Create multi-step AI pipelines, run them against your corpus, and deliver findings by email or webhook. This guide walks you through every step.
Getting Started
Agent Builder lets you chain CaveauAI's AI tools — corpus search, LLM chat, data transforms, email, and webhooks — into automated multi-step pipelines. Define a workflow once, then run it manually or on a cron schedule. Every run produces a full audit trail with per-step output you can review.
Prerequisites
- A CaveauAI account on any plan (Starter, Professional, Enterprise, or Beta)
- At least one corpus with uploaded documents — the agent searches your data, not the internet
- A modern browser (Chrome, Firefox, Safari, or Edge)
Accessing Agent Builder
Log in to your CaveauAI dashboard at ai.bluenotelogic.com. In the left sidebar, click the Agents link (look for the sparkle icon).
Creating Your First Agent
The fastest way to get started is to pick a template. Templates are pre-configured pipelines you can customize.
Step by step
- Click the "New Agent" button in the top-right corner of the Agents page
- Enter a name for your agent (e.g., "GDPR Weekly Brief")
- Select a template from the dropdown:
- Research Assistant — search + analyze + email (best for getting started)
- Compliance Monitor — multi-topic search + analysis + email alerts
- Document Processor — search + analyze + email or webhook
- Custom — blank canvas, add steps manually
- Configure the template-specific fields (see table below)
- Click "Create Agent"
Configuration fields
| Field | Required | Description |
|---|---|---|
| Name | Yes | A descriptive label for your agent |
| Template | Yes | Determines the step pipeline (Research, Compliance, Document, Custom) |
| Research topic | Yes | The search query sent to your corpus (e.g., "GDPR data processor obligations") |
| Depth | No | Research Assistant only: quick (1 pass), standard (2 passes), deep (3 passes) |
| Email recipients | No | Comma-separated email addresses for the digest delivery step |
| Webhook URL | No | HTTPS endpoint for webhook delivery step (must be a public URL) |
Template depth comparison
| Depth | Steps | Search Passes | Typical Duration |
|---|---|---|---|
| Quick | 2 (search + chat) | 1 | 2–5 seconds |
| Standard | 4 (search + chat + transform + email) | 2 | 5–15 seconds |
| Deep | 5 (search ×3 + chat + transform + email) | 3 | 15–45 seconds |
Running an Agent
Once your agent is created, trigger a run manually to see it in action.
Manual run
- On the Agents page, find your agent in the list
- Click the "Run Now" button
- Watch the status badge change: pending → running → completed
- Click the run row to expand the per-step details
Real example: GDPR Research Bot
This is an actual test run against the Norwegian Legal Intelligence corpus (280,000+ document chunks covering employment law, GDPR, and AI regulation):
Step 1 — Search: The corpus search returns 10 ranked passages from the NLI corpus. Results include excerpts from EU AI Act provisions, Norwegian personopplysningsloven (Personal Data Act) sections, and employment law guidance. Each result carries a relevance score and source citation.
Step 2 — Chat: The AI model receives the search results and the analysis prompt. It produces a structured response identifying key obligations:
The entire 2-step quick pipeline completed in 2.1 seconds. Deep mode (3 search passes + analysis + transform + email) typically takes 15–45 seconds depending on corpus size.
Understanding Results
Each run produces a detailed record you can inspect down to the individual step level.
Run states
| Status | Meaning |
|---|---|
| pending | Run is queued and waiting for an execution slot (max 3 concurrent runs) |
| running | Pipeline is actively executing steps in sequence |
| completed | All steps finished successfully; results are available |
| failed | A step encountered an error; check step details for the specific failure |
Per-step output
Click into a completed run to see the breakdown for each step:
- input_data — what was sent to this step (query text, prompt, template variables)
- output_data — what the step produced (search results, AI response, formatted content)
- duration_ms — execution time for this step in milliseconds
- api_calls — number of external API calls made (search, chat, email, webhook)
For search steps, the output includes results_count and relevance scores for each passage. For chat steps, you get the full AI response text, the model used, and source citations derived from the search context.
Scheduling
Instead of running agents manually, set a cron schedule so they execute automatically at fixed intervals.
Setting up a schedule
- Open your agent's detail view (click the agent name)
- In the Schedule section, enter a cron expression
- Select a timezone (e.g., Europe/Oslo)
- Click "Update Agent" to save
Cron expression examples
Cron format: minute hour day-of-month month day-of-week
Minimum intervals by plan
| Plan | Minimum Schedule Interval |
|---|---|
| Starter | Every 6 hours |
| Professional | Every 1 hour |
| Enterprise | Every 15 minutes |
| Beta | Every 15 minutes |
Advanced: Custom Pipelines
When templates don't fit your use case, select "Custom" as the template type and build your pipeline from scratch. You can chain any combination of the five step types in any order.
Template variable syntax
Steps can reference the output of previous steps using double-brace template variables:
Variables are resolved at execution time. If a referenced step hasn't run yet or doesn't exist, the variable resolves to an empty string.
Example: Weekly Competitive Intelligence Brief
A 4-step custom pipeline that searches your market intelligence corpus, identifies threats, formats an executive summary, and posts it to Slack:
| # | Step Name | Type | Configuration |
|---|---|---|---|
| 1 | market_search | search | Query: "competitive product launches and market shifts" |
| 2 | threat_analysis | chat | Prompt: "Analyze these findings and identify the top 3 competitive threats: {{steps.market_search.output}}" |
| 3 | exec_summary | transform | Template: format as executive briefing with bullet points |
| 4 | slack_post | webhook | URL: https://hooks.slack.com/services/T.../B.../xxx, payload: {{steps.exec_summary.output}} |
Troubleshooting
Common issues and how to resolve them:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Run stuck on pending | 3 concurrent runs already active | Wait for a running agent to finish, or cancel an existing run |
| Search step returns no results | Corpus is empty or query doesn't match any documents | Check your corpus has uploaded documents; try a broader search query |
| Email not received | Spam filter or incorrect address | Check spam/junk folder; verify the email address in agent config |
| Webhook step fails | Target URL unreachable or returned error | Verify the endpoint is public and accepts POST; check step output for HTTP status |
| Chat step produces empty output | Model timeout or no context provided | Ensure the search step ran first and produced results; retry the run |
| Schedule not firing | Invalid cron expression or engine offline | Validate cron syntax; check the health indicator on the Agents page |
Need help?
If you're stuck or have questions about configuring an agent for your specific use case, reach out. We can help design the right pipeline for your workflow.