AI Workflows and Agents

Introduction to Flow

The Flow platform is powered by the Vizra ADK (Agent Development Kit), an open-source framework for building AI agents in Laravel. WebPal integrates this directly into the document management and content management environment, so AI agents can:

• Read, write, and manage your documents
• Look up and update user accounts
• Query external systems (PipeDrive CRM, GitHub, Zabbix monitoring, etc.)
• Trigger automatically when events happen (file changes, incoming emails)
• Run complex multi-step workflows in the background

Accessing the Flow Section

Click Flow in the top navigation bar. The Flow section has a three-panel layout:

Chat Interface

Starting a Conversation

The AI chat appears in the right panel throughout WebPal — on the Dashboard, in the Documents section, and in the Flow section. The same chat context can be used across all sections.

1. Type your message in the input box at the bottom of the right panel.
2. Press Enter to send.
3. The AI responds in real time, streaming the response token by token.

Choosing an Agent

The chat agent selector (dropdown above the input) lets you choose which AI agent to converse with. Different agents have different specialisations and tools. The default agent is typically the DocAgent, which is optimised for document management tasks.

Chat Contexts

A context is a persistent chat session that remembers prior conversation history. Contexts are shown in the context dropdown (or tab) above the chat input.

• Each context maintains its own conversation history.
• Switching contexts switches the agent's working history — the AI starts fresh with the new context.
• Contexts can be associated with a specific document or folder (the AI's "working context").
• Use Ctrl+Up / Ctrl+Down to navigate through previously sent messages in the current context.

Context Reset

To start a fresh conversation without creating a new context, you can insert a context reset marker — a visual divider in the chat history that tells the AI to ignore everything above it. This reduces token usage and improves response relevance.

Document Context

The AI agent is context-aware: when you navigate to a document or folder in the Documents section, the agent automatically knows what you're looking at. You can then ask questions like "summarise this document" or "find similar files" without specifying which document you mean.

When you add a document to the context (click "Add to context" or similar), it appears as a context item. Removing it clears it from the agent's working context.

File Attachments in Chat

You can attach files to your chat messages:

• Drag and drop files onto the chat input area.
• Ctrl+V to paste files or images from your clipboard.
• Click the attachment icon to browse for files.

Uploaded files are stored in your Document Manager under a designated folder (attached-documents/ or attached-images/). Images are automatically provided to the AI for visual analysis. Other documents are referenced and read on demand.

Status Indicators

While the AI is processing, status indicators show you what it's doing:

• Thinking… — the AI is formulating a response
• Calling {tool_name} — the AI is invoking a tool (fetching data, reading a document, etc.)

A Stop button is available to cancel an in-progress response.

Prompt History

Use Ctrl+Up and Ctrl+Down to navigate through messages you have previously sent in the current context. This works like a terminal command history.

Built-in Agents

WebPal ships with a set of pre-configured agents. Each has a specific role and set of tools.

Interactive Agents

These agents are available in the chat agent selector:

Background / Workflow Agents

These agents run automatically in response to events and do not appear in the chat selector:

Document Agent (DocAgent)

The DocAgent is the primary AI assistant for document management tasks.

Capabilities

• Browse documents — list the contents of any folder you have access to
• Read documents — read the text content of documents
• Search — search for files by name or content
• Edit documents — modify the content of Markdown, text, and HTML files
• Create documents — create new files
• Move and copy — move or copy files between folders
• Convert documents — convert files between formats (PDF, DOCX, Markdown, HTML) using pandoc, LibreOffice, or Chromium
• Navigate — navigate the WebPal UI to a specific file or folder
• Share documents — find recipients and create document shares

Example Prompts

Summarise the document I'm currently viewing.

Find all PDFs in the Marketing folder created in the last 30 days.

Convert this Markdown document to a Word file and save it to the Reports folder.

Create a new document called "Q2 Summary" in the Reports folder with the following content: [...]

Move all files in the Inbox folder to the Archive/2026 folder.

Share the file "Project Proposal.pdf" with alice@example.com and give her download permissions.

Real-Time Editing (EditorAgent)

The EditorAgent goes further than the DocAgent by streaming edits directly into your open CKEditor document as they are generated, so you can watch the changes appear in real time.

Example:

Rewrite this document in a more formal tone.

Add an executive summary at the beginning.

Insert a table of contents after the first heading.

The Flow Dashboard

Navigate to Flow → Dashboard to see an operational overview of the AI platform.

Dashboard Metrics

• Total sessions — all AI chat sessions
• Active now — sessions currently processing
• Sessions today — sessions started today
• Unique users — distinct users who have used AI today
• Agents — total number of registered agents
• Tools — total number of available tools

A 14-day bar chart shows session volume over the past two weeks.

A status breakdown donut chart shows the proportion of sessions in each state (active, completed, failed, idle).

A top-10 agents table shows which agents are used most frequently.

History Tab

The History tab shows a paginated list of all recent agent conversations with their status, agent name, user, and timestamps. Click any entry to view the full conversation.

Agent Detail Panel

When you select an agent in the left panel of Flow, the centre panel shows:

Diagram Tab

A Mermaid diagram showing the agent's state machine — how it flows from receiving a prompt, to reasoning, to calling tools, to responding. Workflow agents show their pipeline steps, fork/join logic, and error paths.

Activity Tab

Recent sessions for this agent with status indicators and timestamps.

Prompt Tab

The agent's system prompt displayed in a Monaco editor. Administrators can edit the system prompt directly in the browser and save changes. This allows you to customise agent behaviour without writing PHP code.

Info Panel

Shows the agent's:

• Tool list — with links to each tool's parameter specification
• Event triggers — which events cause this agent to run automatically
• Sub-agents — other agents this agent can delegate to
• Session count — how many times it has been used
• Metadata — who created it, when it was last modified

Agent Creator

The AgentCreator allows authorised users to build new custom AI agents through conversation — no PHP coding required.

Creating a Custom Agent

Start a chat with the AgentCreator agent and describe what you want:

I need an agent that can:
- Read our weekly sales report from the Reports folder
- Summarise it
- Post the summary to our Slack channel

It should run every Monday morning when a new report is uploaded.

The AgentCreator will:

1. Ask clarifying questions about what the agent should do.
2. Suggest appropriate tools from the available tool library.
3. Set up any event triggers (e.g., "trigger when a file is uploaded to the Reports folder").
4. Generate the agent class and prompt template.
5. Make the new agent immediately available — no server restart required.

What AgentCreator Can Build

• Interactive agents — conversational agents you can chat with
• Background agents — agents that run automatically without user interaction
• Workflow agents — multi-step pipelines that chain other agents
• Event-triggered agents — agents that fire when specific events happen

Modifying an Existing Agent

Ask AgentCreator to modify an agent:

Update the SalesReportAgent to also email the summary to the sales team.

Deleting an Agent

Delete the SalesReportAgent.

Event-Triggered Agents

Event-triggered agents run automatically when specific things happen in WebPal — no user interaction required.

Available Triggers

File Changed

Fires when a document is created, updated, deleted, moved, or renamed.

Configuration options:

• Watch a specific document (by ID)
• Watch all files in a folder matching a pattern (e.g., *.pdf in the Reports folder)
• Filter by action type (created, updated, deleted, moved, renamed)

Example: "Run the ReportSummaryAgent whenever a PDF is added to the /Reports folder."

Folder Content Changed

Fires for every ancestor folder when any descendant changes. Use this when you want to react to any change anywhere within a folder tree.

Incoming Email Received

Fires when an email arrives via procmail integration or mailbox monitoring.

Configuration:

• Filter by sender email (partial match)
• Filter by recipient email (partial match)
• Non-admin users must include a recipient_contains filter matching their own email address

Example: "Run the MeetingSummaryAgent whenever an email is received at meetings@example.com."

How Triggered Agents Work

When a trigger fires:

1. WebPal checks all registered triggers to see which agents should run.
2. Matching agents are queued and executed in the background.
3. The agent runs as a configured "run as" user, respecting that user's permissions.
4. On completion, a toast notification is pushed to the requesting user's browser.

Workflow Agents

Workflow agents orchestrate multiple AI agents into a coordinated pipeline. They are ideal for complex, multi-step processes.

Example: Meeting Summary Workflow

This built-in workflow demonstrates the capability:

Trigger: An email arrives at the configured meetings mailbox.

Step 1 (sequential): The SummarizeEmail agent:

• Reads the incoming email
• Generates a structured Markdown summary
• Saves it to a configured folder in the Document Manager

Step 2 (parallel — both run simultaneously):

• The NotificationSlack agent posts the summary to Slack
• The NotificationEmail agent sends the summary by email

If Step 1 fails, the workflow aborts. If a notification step fails, the workflow completes with a "partial success" status (rather than failing entirely).

Workflow Execution Logging

All workflow runs are logged with:

• Start and end timestamps
• Per-step results
• Error messages (if any step failed)
• Overall status: completed, partial_success, or failed

Agent Session Management

Viewing Active Sessions

The Flow Dashboard shows currently active sessions. Each session card shows:

• Agent name
• Status (running, completed, failed)
• User
• Start time
• Process ID (for background agents)

Terminating a Session

If an agent is stuck or taking too long, click Terminate on its session card. The underlying process is killed and the session is marked as failed.

Admin Session Management

Administrators can view all sessions across all users at /admin/agent-sessions. Filter by agent, status, date, or user. Click a session to see the full message history including token usage and tool calls.

Per-User Credentials

Some AI tools require API keys for external services. Rather than sharing API keys globally, each user can store their own credentials.

Setting Up Credentials

1. Click your avatar and select Settings.
2. Navigate to Credentials.
3. Click Add Credential.
4. Select the service (e.g., PipeDrive, GitHub, Time Tracker).
5. Enter your API key or token.
6. Click Save.

Credentials are encrypted and stored per-user. When you use a tool that requires a credential, it is automatically retrieved and used — you do not need to provide it again in the chat.

Supported Credential Types

• PipeDrive — API token for CRM integration
• GitHub — Personal access token for repository management
• Time Tracker — API token for time entry submission
• Zabbix — API token for infrastructure monitoring

Available Tools

The AI agents have access to a rich library of tools. You can browse them in the Flow section left panel under Tools.

Document Tools

Filesystem Tools (Sandboxed)

Agents have access to a sandboxed scratch directory for multi-step file operations:

User Management Tools

GitHub Tools

PipeDrive CRM Tools

Communication Tools

Time Tracking

Memory Tools (Vizra ADK Built-in)

LLM Models and Streaming

WebPal supports multiple AI providers and models. The model used by an agent is configured in the agent's class or by the administrator.

Supported Models (Examples)

Real-Time Streaming

Responses from most agents stream token-by-token to your browser. You see the response being written in real time rather than waiting for the complete response. This makes interactions feel faster and more natural.

Token Usage

Token counts (input and output) are recorded for every conversation and available in:

• The Flow page session detail view
• The agent:chats CLI command output
• Admin download (JSON export) of conversation history

Agent Export and Import

Custom agents can be exported and imported between WebPal installations.

Exporting an Agent

php artisan agent:export my_custom_agent
# Creates my_custom_agent.zip in storage/app/agent-exports/ by default

php artisan agent:export my_custom_agent --output=/path/to/backup/

The export includes:

• The agent PHP class file
• The agent's prompt template
• Metadata (name, description, triggers)

Importing an Agent

php artisan agent:import my_custom_agent.zip

# Preview what will be imported without making changes
php artisan agent:import my_custom_agent.zip --dry-run

# Overwrite an existing agent with the same name
php artisan agent:import my_custom_agent.zip --overwrite

Agent Evaluation (Developer/Admin Feature)

For administrators and developers who want to validate agent behaviour:

WebPal includes an agent evaluation framework where you can define test scenarios (inputs and expected behaviours) and run them automatically. An LLM-as-judge evaluates whether the responses meet the defined criteria.

Run evaluations:

# Run all evaluations
php artisan vizra:run:eval

# Run a specific evaluation
php artisan vizra:run:eval CustomerSupportEvaluation

# Output results to a file
php artisan vizra:run:eval --output=results.json

This is particularly useful for regression testing after modifying an agent's prompt or tools.