AgentApps Flow
👤 admin · ⎋
Loading projects…
AgentApps v0.2.0
📁 Projects
🎨 Appearance
Fonts & colour themes — saved as default
Font
Colour Theme
📊 Model Logs
Token usage, response times and errors
Click ↻ to load logs
🔍 Execution Logs
Full trace — agents, tools, responses, errors
📈 Observability
Usage, models, projects and tool utilisation
Date range:
Click ↻ Refresh to load data
👥 User Management
Add users and assign project access
Loading…
Add New User
Username
Password (min 6 chars)
Role
Projects (comma-separated, blank = all)
🕓 Versions
Project versions
Loading...
Save current canvas as new version
🔗 Webhook & Automation
Configure incoming triggers and outgoing notifications for this project
⬇ Incoming Webhook — Trigger from External Systems
Endpoint URL
Bearer Token
API Key
Stored server-side with project. Never sent back to browser.
🔑 Token Management
Token label
✏️ Message Template — Shape what the agent receives
Template
Use `{{variable}}` placeholders — substituted before the agent runs.
Twilio variables: `{{message_body}}` `{{from_number}}` `{{sender_name}}` `{{to_number}}`
⬆ Outgoing Webhook — Push Result to External System
Post result to
Server POSTs `{project, message, response, elapsed, ts}` to this URL after each webhook run.
📋 Example cURL
Set a token above to see the example
⏰ Scheduler Trigger — Run flow on a time schedule Disabled
Schedule type
Every minutes (min 1)
At minute past each hour (0-59)
At time server local time
Every
server local time
Prompt Template
Available: `{{scheduled_at}}` `{{date}}` `{{time}}` `{{day}}` `{{project}}`
📧 Email Inbound Trigger — Run flow when email arrives Disabled
IMAP Host
Port 993 = SSL (recommended) · 143 = STARTTLS
Email Address
Password / App Password
Check every seconds (min 30)
Search emails
Only UNSEEN emails in this window are checked
Filter — From
Filter — Subject
Prompt Template
Use the + buttons above to insert email variables into your prompt. Available: `{{email_from}}` `{{email_subject}}` `{{email_body}}` `{{email_date}}`
Gmail: use an App Password (requires 2FA). Outlook: use your normal password or an app password.
🔁 API Poll Trigger — Run flow when external API matches condition Disabled
API URL
Method
Poll every sec (min 30)
Headers
Request Body
Trigger when
Contains
Prompt Template
Available: `{{api_response}}` `{{api_url}}` `{{polled_at}}` `{{change_detected}}`
🔧
AI Tool Creator
Describe a tool and get working Python code instantly
🔧 Describe any tool and I'll generate the Python code, register it, and add it to your palette.
Examples:
A tool that sends an email via SMTP A tool that queries a REST API with an API key A tool that reads and writes to a Google Sheet A tool that posts a message to Slack A tool that looks up a record in a database by ID
Uses API key from the model node · Shift+Enter for new line
🔧
Tool Name
ClassName
📖 AgentApps Flow Builder — Help
Learn how to build, connect, and run AI agent flows
🚀 Getting Started
🧩 Node Types
🔗 Connections
🔧 Custom Tools
📡 Webhooks
⚡ Triggers
🕓 Versioning
📊 Logs
🔑 Login & Auth

### 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

### Creating and using custom tools

#### Option A — AI Tool Creator (easiest)

1
Make sure a Model node with an API key is on the canvas
The AI creator uses your own API key to generate tool code.
2
Click 🔧 Create Tool in the header
Describe the tool in plain English, e.g. "A tool that sends a Slack message to a channel".
3
Tool is generated, registered & added to palette
Drag it from the sidebar. Click the node to fill in config fields (API keys, URLs etc.).

#### Option B — Import your own Python file

Click ⬆ Import Custom Tool in the sidebar. Paste your Python code — any class that extends `Tool` is detected automatically.

from agentapps import Tool API_KEY = "" # ← UPPERCASE = config field on node class MyTool(Tool): def __init__(self): super().__init__(name="my_tool", description="Does X") def execute(self, query: str) -> str: # your logic here return "result" def get_parameters(self): return {{"type":"object","properties":{{"query":{{"type":"string"}}}},"required":["query"]}} tool_instance = MyTool()
⚠️ UPPERCASE module-level constants become editable config fields on the canvas node. Never hardcode secrets in your source — use constants instead.

### 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.

## Drop components here

Drag from the sidebar · Click output ports to connect

⌨ Generated Python
▶
Playground
Test your flow by chatting with your configured agent.
Add an API key in the panel to enable live calls.
Enter to send · Shift+Enter for newline · No API key set
🔌 Now click an input port to connect — ESC to cancel