Build your first AI agent flow
1
Add a Model node
Drag Model from the left sidebar onto the canvas. Click the node to set your provider (OpenAI / Gemini / Grok), model ID (e.g. gpt-4o), and paste your API key.
2
Add an Agent node
Drag Agent onto the canvas. Click it to set the agent's Name, Role, and Instructions — be specific about what the agent should do.
3
Connect Model → Agent
Hover over the Model node until the purple connection dot appears on its right edge. Drag from that dot to the model port on the Agent node's left edge.
4
Add tools (optional)
Drag a Tool node (Search, Web, Calculator) and connect its right port to the Agent's tools port. The agent will automatically decide when to use it.
5
Run the flow
Type your message in the chat panel at the bottom and press Enter. The agent will respond using its model and tools. Watch tool calls appear in real-time if Show Tool Calls is enabled.
💡 Save your work: Use the project name field in the header and click 💾 Save. Projects are stored on the server and survive restarts.
Available node types
🤖 Model
The LLM brain. Supports OpenAI (GPT-4o), Gemini, Grok, Azure OpenAI, and Local models (Ollama, LM Studio, Jan, GPT4All). Set provider, model ID, API key, and temperature.
👤 Agent
An AI agent with a role and instructions. Runs tasks using its model and tools. Core of every flow.
👥 Team
A group of agents that collaborate. Set mode: coordinate (manager routes tasks), collaborate (agents work together).
🔧 Tool
Built-in capabilities: Search (DuckDuckGo), Web (fetch URLs), Calculator, Think (reasoning scratchpad), Scraper (extract structured data from web pages).
📋 Table Query
Read and write platform tables. Agents can insert rows, select with filters, update, and delete. Connect to an Agent's tools port. Specify which table in the node config.
✅ Approval Gate
Pauses execution and waits for a human to approve or reject before continuing. Shows in the Portal bell notification. Set approvers, timeout, and custom message.
🧠 RAG
Retrieval-Augmented Generation. Index a set of documents (PDF, text, URLs) and let the agent query them semantically. Connect to Agent tools port.
💬 Prompt
A message template sent as the initial input. Use {{variable}} placeholders filled by webhook/trigger data.
🔌 Custom Tool
Your own Python tool class. Import via the ⬆ Import button, or generate one with 🔧 Create Tool.
Local Models (Ollama, LM Studio etc.)
Select Local as provider, choose your server (Ollama port 11434, LM Studio port 1234, Jan port 1337), then click Load Models to pull the available model list. No API key needed.
Azure OpenAI
Select Azure as provider. Enter your Azure endpoint (e.g. https://myresource.openai.azure.com), deployment name, API key, and API version.
Multi-model flows
You can use different models for different agents — just add multiple Model nodes and connect each one to the relevant agent.
How to connect nodes
Hover a node to reveal its connection ports (colored dots). Drag from an output port to an input port. Only compatible ports can connect.
Valid connections
- Model → Agent — connect via the
model port
- Model → Team — connect via the
model port
- Tool → Agent — connect via the
tools port
- Tool → Team — connect via the
tools port
- Agent → Team — connect via the
agents port
Deleting connections
Right-click any connection line to delete it. Or delete a node (click it → press Delete / Backspace) to remove all its connections.
💡 A Model node can connect to multiple agents — they share the same LLM provider but each has its own instructions.
Minimum valid flow
Model ──model──▶ Agent
Full team flow
Model ──model──▶ Agent 1 ──agents──▶ Team
Model ──model──▶ Agent 2 ──agents──▶ Team
Tool ──tools──▶ Agent 1
Model ──model──▶ Team
Triggering flows via webhook
Webhooks let external services (WhatsApp, Slack, Zapier, etc.) trigger your flow automatically by sending an HTTP request.
1
Open the Webhooks panel
Click the ☰ menu → 🔗 Webhooks. Each project has its own webhook URL.
2
Copy your webhook URL
https://your-server/webhook/<project-name>?token=<token>
Use HTTPS for external services — run with --ssl-self-signed or behind a reverse proxy.
3
Set a message template (optional)
Use {{variable}} placeholders that map to fields in the incoming request body. For example, a Twilio request provides {{Body}}, {{From}}, {{To}}.
4
Set an outgoing URL (optional)
If set, the agent's response is POSTed back to this URL as JSON — useful for reply webhooks.
💡 Webhook routes are always public and bypass login — this is intentional so external services can reach them without a session cookie.
Login & authentication
Where is my password?
There are three ways to set the UI password:
1
Auto-generated (default)
If you started without specifying a password, one is auto-generated and printed in the terminal:
🔑 Auto-generated password: xK9mP2nQvR4sT7uW
2
CLI flag
agentapps-flow --password mysecretpassword
3
Environment variable (recommended for servers)
AGENTAPPS_PASSWORD=mypass agentapps-flow
Session & sign out
- Sessions last 7 days — you won't be asked to log in again on the same browser.
- Click ⎋ Sign out in the top-right to end your session immediately.
- Restarting the server clears all active sessions.
💡 Webhook URLs are always public and don't require login. Only the Flow Builder UI and API routes are password-protected.
🔒 HTTPS & SSL Certificates
By default the server runs on HTTP. For production use or when accepting webhooks from external services, run with HTTPS using one of three options:
1
Self-signed certificate (quickest)
Auto-generates a certificate — no setup required:
agentapps-flow --ssl-self-signed
Note: Browsers will show a security warning on first visit. Click "Advanced → Proceed" to continue. External services like Twilio require a trusted cert instead.
2
Your own certificate (recommended for production)
Provide your own cert and key files:
agentapps-flow --ssl-cert cert.pem --ssl-key key.pem
Use a cert from Let's Encrypt (free) or your own CA. Both files must be provided together.
3
Reverse proxy (nginx / Caddy)
Run agentapps-flow on HTTP locally and terminate SSL at the proxy:
agentapps-flow --port 7860
Then configure nginx or Caddy to proxy https://yourdomain.com → http://localhost:7860. This is the most robust option for public servers.
Get a free certificate with Let's Encrypt
- Install certbot:
sudo apt install certbot
- Generate cert:
sudo certbot certonly --standalone -d yourdomain.com
- Certs saved to:
/etc/letsencrypt/live/yourdomain.com/
- Run:
agentapps-flow --ssl-cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem --ssl-key /etc/letsencrypt/live/yourdomain.com/privkey.pem
- Certs expire every 90 days — renew with
sudo certbot renew
Standard HTTPS port
To run on port 443 (standard HTTPS) combine with --port:
agentapps-flow --port 443 --ssl-cert cert.pem --ssl-key key.pem
💡 For Twilio, Zapier, or any service that requires a valid HTTPS URL for webhooks, use Let's Encrypt or a reverse proxy — self-signed certs will be rejected.
Automation Triggers
Triggers let your flows run automatically — no manual input needed. Configure them via ☰ File → Webhooks & Automation.
⏰ Scheduler Trigger
Run a flow on a time schedule — every N minutes, hourly, daily, or weekly.
- Pick a schedule type and configure the time/interval.
- Write a Prompt Template — use
{{date}}, {{time}}, {{day}}, {{scheduled_at}}, {{project}}.
- Toggle Active to start. Toggle off to pause.
- Use ▶ Run Now to test immediately.
💡 Example: run daily at 09:00 with prompt "Today is {{day}} {{date}}. Generate the morning report."
📧 Email Inbound Trigger
Run a flow whenever a new email arrives in your inbox.
- Enter your IMAP host, email address and app password (Gmail requires an App Password with 2FA).
- Set Search emails — limits to today / last 2 / 7 / 30 days. Never scans your full inbox.
- Optional From / Subject filters — only trigger for matching emails.
- Write a Prompt Template using
{{email_from}}, {{email_subject}}, {{email_body}}, {{email_date}}.
💡 Gmail: go to myaccount.google.com/apppasswords to generate an app password.
🔁 API Poll Trigger
Periodically call an external API and trigger the flow when a condition is met.
- Set the API URL, method, headers (one per line as
Key: Value), and optional request body.
- Choose a trigger condition:
- Always — trigger on every poll.
- Response changes — only when response differs from last poll.
- Contains text — only when response body contains your string.
- JSON field equals — e.g.
status==pending or data.count==0.
- Use Prompt Template variables:
{{api_response}}, {{api_url}}, {{polled_at}}, {{change_detected}}.
- Use ▶ Run Now to test — shows a response preview in the status line.
💡 Use "Contains" condition to monitor a queue endpoint and only trigger when "new_item" appears in the response.
🔗 Webhook (Incoming)
Trigger a flow via HTTP POST from any external system — Zapier, n8n, Jira, Twilio, Slack, etc.
- Generate a Bearer Token in Token Management.
- POST to
/webhook/<project-name> with Authorization: Bearer <token>.
- Use a Message Template to shape what the agent receives — supports
{{variable}} substitution from the request body.
- Twilio variables are auto-mapped:
{{message_body}}, {{from_number}}, {{sender_name}}.
Project Versioning
Versions let you snapshot your flow at any point, test different configurations in Playground, revert if something breaks, and mark a stable release as published.
How to create a version
1
Open the Projects panel
Click ☰ File → Load or use the project name in the header to open the Projects panel.
2
Click the 🕓 button
Each project row has a 🕓 icon. Click it to open the Version panel for that project.
3
Save a version
Type a version name (e.g. v1, stable, release-2.0) and an optional label, then click + Save Version. The current canvas is snapshotted.
Version actions
- ▶ Set Active — loads that version's nodes into the canvas. Playground runs against whatever is on the canvas.
- ↩ Revert — copies the version back into the Working Copy. Your current canvas is overwritten (save a version first if needed).
- 📢 Publish — marks a version as the released/stable build. Shown as a badge in the Projects panel.
- 🗑 Delete — permanently removes a version snapshot.
Working Copy vs Versions
The Working Copy is what you always edit — it's the live canvas. Versions are read-only snapshots. Editing the canvas always modifies the Working Copy, never a saved version.
💡 The Playground always runs whatever is on the canvas. If a version is active, its nodes are loaded into the canvas when you open the project.
Logs & Observability
Access all logging and monitoring features from ⚙ Settings.
📊 Model Logs
Records every agent LLM call — tokens, timing, status, response preview. Also auto-populated into the model_logs platform table for SQL querying and reporting.
- Filter by date, trigger, status, project.
- Click any row to expand the full response or error.
- Download as CSV respecting current filters.
- Stats bar shows totals: runs, errors, estimated tokens, avg duration.
- Stored as daily JSONL files at
~/.agentapps/logs/YYYY-MM-DD.jsonl.
💡 The model_logs platform table is always kept in sync — query it from reports, agents, or SQL Server.
🔍 Execution Logs
Full per-execution trace — every agent start, tool call, tool result, and error in order. Also auto-populated into the execution_logs platform table.
- List view shows: project, trigger, status, duration, message preview, event count.
- Click a row to open the Timeline view — timestamped events with icons.
- Filter by trigger, status, project. Delete individual or all executions.
- Download as CSV (metadata only — use Timeline for full detail).
- Max 200 execution files kept — oldest pruned automatically.
📈 Observability Dashboard
Charts and summaries across all your runs.
- Select date range: last 7 / 30 / 90 days.
- Summary cards: total runs, success rate, avg response time, estimated tokens, projects, models.
- Charts: Runs over time, top projects, trigger breakdown, models in use, tool utilisation.
- Download as PDF — charts are captured as images.
💡 Observability reads existing log files on demand — zero background processing, zero extra API calls.
Platform Tables
Platform Tables are structured data stores built into AgentApps. Agents read and write them via the Table Query tool. Access from Tables in the header.
Creating a table
1
Click Tables in the header
Opens the Platform Tables view. Click + New Table. Table Name is required (letters, numbers, underscores only).
2
Add columns
Switch to the Columns tab. System columns (id, created_at, updated_at, tags) are automatic. Add your own with name and type (text, number, datetime, boolean).
3
Connect Table Query tool to an agent
Drag a Table Query node onto the canvas, set the target table, and connect it to your Agent's tools port.
Table operations agents can perform
- insert — add a new row with any fields
- select — query rows with optional filters
- update — modify existing rows by id
- delete — remove rows by id
Pagination
Tables show 30 rows per page. Use the Prev / Next buttons at the bottom. Refresh icon reloads current page data without a full browser refresh.
System tables (read-only)
These tables are auto-populated and cannot be deleted:
- model_logs — every LLM call
- execution_logs — every agent run
- project_summary — all project configs
- user_registry — all users (no passwords)
- trigger_registry — all configured triggers
- approval_logs — all approval requests
- report_registry — all reports
Table Relations
Click Relations in the Tables left panel to define relationships between tables (1:1, 1:N, N:N). Relations are descriptive metadata — useful for reports, agents, and SQL joins. No enforcement.
Export
Click Export CSV in the table header to download all rows as a CSV file.
💡 Multi-row delete: check the checkbox on multiple rows, then click the Delete Selected (N) button that appears.
Reports
Reports let you build dashboards and data views from platform tables. Publish them to the Portal so users can see live data without accessing the builder.
Creating a report
1
Click Reports in the header → New Report
Give it a name and select the source table. One table per report.
2
Add widgets
Click + Add Widget. Choose from: Table (data grid), Bar Chart, Line Chart, Pie/Donut Chart, Metric (single KPI number), Text (rich text block).
3
Configure each widget
Select the widget, then use the right panel to set columns, filters, grouping, chart type, colours, and row limits. For charts, type column names comma-separated in the Columns field.
4
Save & Publish
Click Save — a green confirmation flashes on the button. Toggle Published to make the report visible in the Portal.
Widget types
- Table — paginated data grid with search and column filters
- Bar / Line Chart — set X axis and Y columns (comma-separated)
- Pie / Donut — group by a column, count or sum values
- Metric — shows a single aggregated value (count, sum, avg)
- Text — rich text block for headings and notes
💡 Reports refresh live from the platform table every time they're opened in the Portal — always showing current data.
The Portal
The Portal is the end-user interface — a clean, chat-based view where users interact with agents, see trigger executions, view reports, and approve requests. It opens automatically after login.
What the Portal shows
- New Chat — start a manual conversation with any agent you have access to
- Trigger sessions — conversations started by email, webhook, scheduler, or API poll triggers (shown with an icon)
- Pending Approvals — bell icon with count; tap to review and approve/reject
- Recent Runs — list of recent trigger executions with status
- Reports — published reports are shown in the left panel
- What I can do — agent capabilities summary
Live streaming
When a trigger fires, the Portal shows a pulsing dot on the session. Click it to watch the agent's reasoning and tool calls stream in real-time.
Themes
The Portal supports the same themes as the builder — Dark, Light, Dark Blue, etc. Users can switch theme from their profile.
Portal vs Builder
- Builder — for admins and editors. Build flows, manage tables, configure triggers.
- Portal — for all users. Chat with agents, view results, approve requests.
💡 Viewers can only access the Portal — they cannot see the builder, tables, or settings.
Database / SQL Server
AgentApps stores all data as JSON files by default. Optionally connect a SQL Server (or Azure SQL) database to sync all platform table data for reporting, analytics, and integration.
Connecting SQL Server
1
Open Settings → Database
Admin only. Change provider from JSON Files to SQL Server / Azure SQL.
2
Fill in connection details
Server, Database name, Driver (ODBC 17 or 18), Authentication (SQL auth or Azure AD). The database must already exist.
3
Test Connection
Click Test Connection — shows latency and table count if successful.
4
Save & Migrate
Click Save. Then click Migrate JSON → SQL Server to copy existing data. JSON files are kept as backup.
How sync works
- JSON files are always written first — they are the source of truth
- SQL Server is a secondary sync — if it fails, JSON is safe
- Tables created in platform → SQL table created immediately
- Columns added/deleted →
ALTER TABLE runs automatically
- Rows added/updated/deleted → synced via MERGE + DELETE
Required SQL permissions
ALTER ROLE db_ddladmin ADD MEMBER agentapps_user;
ALTER ROLE db_datawriter ADD MEMBER agentapps_user;
ALTER ROLE db_datareader ADD MEMBER agentapps_user;
Reverse proxy / HTTPS setup
If running behind Nginx or Cloudflare, set the environment variable AGENTAPPS_HTTPS=1 before starting to enable secure cookies without needing a local SSL cert.
💡 Without SQL Server configured, AgentApps works exactly as before — JSON files only, nothing changes.
User Management
Manage who can access AgentApps and what they can do. Admin only. Open from ⚙ Settings → Manage Users.
Roles
- admin — full access: builder, tables, settings, user management, all projects
- editor — can build flows, run agents, manage tables and triggers
- viewer — Portal only: can chat with agents and view reports. Cannot access builder.
Creating a user
Click Add New User in the Users tab. Fill in username, password (min 6 chars), role, and optionally: title, department, manager, and assigned projects. Projects left blank means access to all projects.
Profile fields
- Title — job title (e.g. Finance Manager)
- Department — team or department
- Manager — their manager (selected from existing users)
- Groups — assign to one or more groups
Password reset
Select a user → scroll to Password Reset section → enter new password and confirm → click Save Changes. Leave blank to keep current password.
Groups
Groups organise users for easier management. Switch to the Groups tab to create groups and add members. Groups are descriptive — they don't change permissions directly, but are visible in the user_registry platform table for agents to query.
user_registry table
All users are automatically synced to the user_registry read-only platform table. Agents can query it via table_query. Password hashes are never included.
💡 The built-in admin account uses the server password set via --password or AGENTAPPS_PASSWORD. It cannot be deleted or modified here.