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. Set provider, model ID, API key, and temperature. Every agent must have one connected.
👤 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).
💬 Prompt
A message template sent as the initial input. Use {{variable}} placeholders filled by webhook data.
🔌 Custom Tool
Your own Python tool class. Import via the ⬆ Import button, or generate one with 🔧 Create Tool.
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 call — tokens, timing, status, response preview.
- 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.
💡 No extra tokens are used — logs only record what the model already returned.
🔍 Execution Logs
Full per-execution trace — every agent start, tool call, tool result, and error in order.
- 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.
💡 Token streaming events are excluded from traces to keep files small — only meaningful events are recorded.
📈 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, donuts shown side by side.
💡 Observability reads existing log files on demand — zero background processing, zero extra API calls.