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.