Custom Actions - Genie Helper

Action Runner allows the AI agent to execute pre-built flows by emitting [ACTION:slug:{"params"}] tags in chat responses. The system intercepts these tags, executes the flow steps, and streams status updates back to the user.

How It Works

AI emits action tag — Model outputs [ACTION:slug:{"params"}] in its prose
Interceptor strips tag — Action-runner plugin removes tag from visible chat
Flow execution — System fetches flow from Directus action_flows collection
Status streaming — Each step streams status back to chat interface
Results logged — Execution logged in agent_audits collection

Flow Storage

Flows are stored in the Directus action_flows collection:

Field	Type	Description
`slug`	string	Unique identifier (used in ACTION tag)
`name`	string	Human-readable name
`description`	text	What the flow does
`steps`	JSON	Array of step definitions
`active`	boolean	Enable/disable flow

Built-in Action Flows

Slug	Purpose
`scout-analyze`	Scrape URL + AI analysis
`taxonomy-tag`	Auto-classify content with 6-concept taxonomy
`post-create`	Draft platform-specific social post
`message-generate`	Fan engagement message
`memory-recall`	Search stored data + summarize
`media-process`	Queue media job (watermark, teaser, compress)

Step Types

The Action Runner supports 14+ step types. Each step can reference previous step results using variable interpolation.

Directus Steps

`directus_read`

Read items from a Directus collection.

{
  "type": "directus_read",
  "result_key": "user_data",
  "config": {
    "collection": "user_personas",
    "filter": {"user_id": {"_eq": "$input.user_id"}},
    "fields": "id,onboarding_state,brand_colors",
    "limit": 1
  }
}

Config options:

collection (required) — Collection name
filter — Filter object (Directus query syntax)
fields — Comma-separated field names
limit — Max items to return
sort — Sort field (-field for descending)
id — Read single item by ID

`directus_write`

Create a new item in a collection.

{
  "type": "directus_write",
  "result_key": "new_post",
  "config": {
    "collection": "scheduled_posts",
    "item": {
      "creator_profile_id": "$input.profile_id",
      "platform": "onlyfans",
      "caption": "$input.caption",
      "scheduled_time": "$input.scheduled_time",
      "status": "pending"
    }
  }
}

`directus_update`

Update an existing item.

{
  "type": "directus_update",
  "result_key": "updated",
  "config": {
    "collection": "creator_profiles",
    "id": "$input.profile_id",
    "item": {
      "last_scraped": "$context.timestamp"
    }
  }
}

`directus_delete`

Delete an item.

{
  "type": "directus_delete",
  "result_key": "deleted",
  "config": {
    "collection": "scheduled_posts",
    "id": "$input.post_id"
  }
}

`directus_search`

Full-text search across a collection.

{
  "type": "directus_search",
  "result_key": "search_results",
  "config": {
    "collection": "scraped_media",
    "query": "$input.search_term",
    "fields": "id,caption,engagement_rate",
    "limit": 10
  }
}

`directus_trigger`

Trigger a Directus Flow.

{
  "type": "directus_trigger",
  "result_key": "flow_result",
  "config": {
    "flow_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "payload": {
      "user_id": "$input.user_id",
      "action": "send_notification"
    }
  }
}

Stagehand Steps (Browser Automation)

`stagehand_start`

Start a new browser session.

{
  "type": "stagehand_start",
  "result_key": "session",
  "config": {}
}

Returns: { sessionId: "xyz123" }

`stagehand_navigate`

Navigate to a URL.

{
  "type": "stagehand_navigate",
  "result_key": "nav_result",
  "config": {
    "sessionId": "$session.sessionId",
    "url": "$input.target_url"
  }
}

`stagehand_extract`

Extract data from current page using AI.

{
  "type": "stagehand_extract",
  "result_key": "page_data",
  "config": {
    "sessionId": "$session.sessionId",
    "instruction": "Extract all post titles and engagement metrics",
    "schema": {
      "posts": {
        "type": "array",
        "items": {
          "title": "string",
          "likes": "number",
          "comments": "number"
        }
      }
    }
  }
}

`stagehand_act`

Perform an action on the page (click, type, etc.).

{
  "type": "stagehand_act",
  "result_key": "action_result",
  "config": {
    "sessionId": "$session.sessionId",
    "action": "Click the login button"
  }
}

`stagehand_close`

Close browser session.

{
  "type": "stagehand_close",
  "result_key": "closed",
  "config": {
    "sessionId": "$session.sessionId"
  }
}

`stagehand_cookie_login`

Start session with stored platform cookies (bypasses login).

{
  "type": "stagehand_cookie_login",
  "result_key": "auth_session",
  "config": {
    "creator_profile_id": "$input.profile_id",
    "platform": "onlyfans",
    "url": "https://onlyfans.com/my/subscribers"
  }
}

Fetches decrypted cookies from platform_sessions, injects them, and navigates to target URL.

`stagehand_extract_cached`

Extract with 10-minute cache (reduces browser calls).

{
  "type": "stagehand_extract_cached",
  "result_key": "cached_data",
  "config": {
    "sessionId": "$session.sessionId",
    "url": "https://example.com",
    "instruction": "Extract pricing table",
    "ttl_ms": 600000
  }
}

Ollama Steps (AI Generation)

`ollama_generate`

Generate completion (single-turn, no history).

{
  "type": "ollama_generate",
  "result_key": "caption",
  "config": {
    "model": "dolphin-mistral:7b",
    "prompt": "Write a flirty caption for this photo: $input.photo_description",
    "system": "You are an OnlyFans content strategist. Be playful and engaging.",
    "options": {
      "temperature": 0.9,
      "top_p": 0.95
    }
  }
}

`ollama_chat`

Multi-turn chat with message history.

{
  "type": "ollama_chat",
  "result_key": "response",
  "config": {
    "model": "qwen-2.5:latest",
    "messages": [
      {"role": "user", "content": "$input.user_message"}
    ],
    "system": "You are a helpful assistant."
  }
}

Taxonomy Steps

`taxonomy_terms_read`

Read taxonomy terms with caching.

{
  "type": "taxonomy_terms_read",
  "result_key": "terms",
  "config": {
    "super_concept": "aesthetic",
    "platform": "onlyfans",
    "limit": 20
  }
}

`taxonomy_invalidate`

Bust taxonomy cache after writes.

{
  "type": "taxonomy_invalidate",
  "result_key": "invalidated",
  "config": {}
}

Queue Steps

`bullmq_enqueue`

Enqueue a BullMQ job.

{
  "type": "bullmq_enqueue",
  "result_key": "job",
  "config": {
    "queue": "media-jobs",
    "job": {
      "id": "$input.job_id",
      "type": "apply_watermark",
      "media_id": "$input.media_id",
      "watermark_text": "© 2026"
    }
  }
}

Generic HTTP

`http_request`

Make arbitrary HTTP request.

{
  "type": "http_request",
  "result_key": "api_response",
  "config": {
    "url": "https://api.example.com/webhook",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer $input.token"
    },
    "body": {
      "event": "post_created",
      "data": "$new_post"
    }
  }
}

Variable Interpolation

Steps can reference data from:

$input.field — Parameters from ACTION tag
$steps[N].field — Result from step N (0-indexed)
$result_key.field — Result from step with given result_key
$context.field — Context data (user info, workspace, timestamp)

Example flow:

{
  "slug": "post-creator",
  "name": "Create Scheduled Post",
  "steps": [
    {
      "type": "ollama_generate",
      "result_key": "caption",
      "config": {
        "model": "dolphin-mistral:7b",
        "prompt": "Write caption for: $input.description"
      }
    },
    {
      "type": "directus_write",
      "result_key": "post",
      "config": {
        "collection": "scheduled_posts",
        "item": {
          "caption": "$caption.response",
          "platform": "$input.platform",
          "scheduled_time": "$input.time"
        }
      }
    }
  ]
}

Creating a New Action Flow

Design the flow — Map out steps and data flow
Create in Directus — Add to action_flows collection
Set slug — Unique identifier (e.g., analytics-report)
Define steps — JSON array of step definitions
Test execution — Trigger from AI chat: [ACTION:analytics-report:{"period":"7d"}]
Check audit log — Review in agent_audits collection

Execution Timeouts

Per-step timeout: 120 seconds
Steps exceeding timeout are aborted
Flow execution stops on first failed step
Partial results available in error response

Error Handling

Failed steps return error details:

{
  "success": false,
  "slug": "post-creator",
  "error": "Step 2 (directus_write) failed: Collection not found",
  "results": {
    "caption": { "response": "Check out this new content!" }
  },
  "failedStep": 1
}

All executions logged to agent_audits with full error details.

Implementation Files

server/utils/actionRunner/index.js — Flow executor (server/utils/actionRunner/index.js:1)
server/utils/actionRunner/stepExecutors.js — Step type implementations (server/utils/actionRunner/stepExecutors.js:1)

Usage

Administration

Development

​How It Works

​Flow Storage

​Built-in Action Flows

​Step Types

​Directus Steps

​directus_read

​directus_write

​directus_update

​directus_delete

​directus_search

​directus_trigger

​Stagehand Steps (Browser Automation)

​stagehand_start

​stagehand_navigate

​stagehand_extract

​stagehand_act

​stagehand_close

​stagehand_cookie_login

​stagehand_extract_cached

​Ollama Steps (AI Generation)

​ollama_generate

​ollama_chat

​Taxonomy Steps

​taxonomy_terms_read

​taxonomy_invalidate

​Queue Steps

​bullmq_enqueue

​Generic HTTP

​http_request

​Variable Interpolation

​Creating a New Action Flow

​Execution Timeouts

​Error Handling

​Implementation Files

​Next Steps

Project Structure

Extending MCP

Build docs developers (and LLMs) love