AI Agent Functionality

This document describes the current `ai_agent` implementation in automation runtime and UI.

1) Where it is implemented

- UI step builder: `application/views/automation.php` - Runtime dispatcher and AI logic: `include_file/automations_functions.php` - Action include file: `include_file/automations/actions/ai_agent.inc.php`

2) Step behavior

`ai_agent` behaves like a control step (similar to `if`):

- Calls Gemini Flash model with prompt + selected context. - Expects JSON response with `result` boolean and extra output fields. - If `result = false`, applies `extra_param.skip` to runtime skip list. - Any returned output fields are injected to runtime replacements as: - `{ai-<field_name>}`

Example:

- AI returns: `{"result": true, "message": "Hello"}` - Next steps can use: `{ai-message}`

3) UI fields

In `ai_agent` popup:

- `Prompt` (textarea) - `Result` (dynamic rows with `name` + `type`) - supported types in UI: `date`, `text`, `number`, `email`, `boolean` - `AI Context Sources` (dynamic rows) - `Customer data` - `Customer entries` - `Customer documents` - `Customer chat` - Delay/advance section is available like other actions.

Saved in `parameter` JSON:

{
  "prompt": "user prompt here",
  "result": [
    { "name": "message", "type": "text" }
  ],
  "context_sources": ["customer_data", "customer_chat"]
}

4) Context queries

When context sources are selected, runtime builds:

- `customer_data`: current customer data already in runtime. - `customer_documents`: `SELECT * FROM documents WHERE cus_id = ? ORDER BY id DESC` - `customer_entries`: `SELECT * FROM tabs WHERE cus_id = ? ORDER BY id DESC` - `customer_chat`: uses one of these hooks if exists: - `automation_ai_get_last_customer_messages($cus_id, 10)` - `get_last_customer_messages_for_ai($cus_id, 10)` - fallback: empty array

5) File support in prompt

If prompt contains full file paths (pdf/image/audio), runtime auto-detects and attaches them to Gemini request as inline data.

Detected extensions:

- pdf - png / jpg / jpeg / gif / webp - mp3 / wav / ogg / m4a

6) API / model

- API key source checks: - `$GLOBALS['public']` - `$GLOBALS['public_var']` - `GEMINI_API_KEY` env values - Model default: - `gemini-3.0-flash`

7) Practical examples

A) Reply from last customer chat

Prompt:

`answer to customer last message politly and save it in message`

Result schema:

- `message` (text)

Use in next `sendEmail` step:

- `{ai-message}`

B) Transcription from pushed file

Prompt:

`your job is to give transcription of last call in {file} and put it in transcript`

Result schema:

- `transcript` (text)

Use in next step (e.g. update custom field):

- `{ai-transcript}`

Note: placeholder key must match result field name exactly. If field is `transcription`, use `{ai-transcription}`.