Action Runner

The Action Runner plugin intercepts special [ACTION:slug:{"params"}] tags emitted by the LLM in chat responses, strips them from the visible message, executes the corresponding flow, and streams status updates back to the user.

Why Action Runner?

Problem: Qwen-2.5 (and many uncensored models) struggle with reliable tool calling in AnythingLLM’s agent mode. Function calls often fail, get malformed, or hallucinate parameters. Solution: Instead of relying on native tool calling, the model emits structured text tags that trigger pre-built flows. The Action Runner plugin intercepts these tags, validates parameters, and executes multi-step workflows using a declarative JSON format.

How It Works

1. Model Emission

The model outputs a special tag in its prose:

I'll analyze that URL for you.

[ACTION:scout-analyze:{"url":"https://example.com"}]

Let me know if you need anything else.

2. Interception

The action-runner plugin:

Detects the [ACTION:slug:{params}] pattern
Strips it from the visible chat response
Parses the slug and JSON parameters
Looks up the flow definition in action_flows collection

3. Execution

The plugin executes the flow’s steps sequentially:

Each step is one of 14 available step types
Steps can use variables from previous steps via {{step_name.field}}
Execution status is streamed back to the chat UI
Results are logged to agent_audits (success/error/miss)

4. Logging

Every ACTION execution is logged to the agent_audits collection:

success: Flow completed without errors
error: Flow failed (with error message)
miss: Slug not found in action_flows

Available Actions

Slug	Purpose	Typical Use Case
`scout-analyze`	Scrape URL + AI analysis	”Analyze this creator’s OnlyFans profile”
`taxonomy-tag`	Auto-classify content with 6-concept taxonomy	”Tag this image with relevant categories”
`post-create`	Draft platform-specific social post	”Write a caption for this photo”
`message-generate`	Fan engagement message	”Draft a reply to this fan’s DM”
`memory-recall`	Search stored data + summarize	”What were my best-performing posts last month?”
`media-process`	Queue media job (watermark, teaser, compress)	“Watermark all photos in this upload”

Flow Definition Format

Flows are stored in the action_flows Directus collection with this structure:

{
  "slug": "scout-analyze",
  "name": "Scout & Analyze URL",
  "description": "Scrape a URL and run AI analysis",
  "steps": [
    {
      "type": "stagehand",
      "name": "scrape",
      "action": "extract",
      "params": {
        "url": "{{params.url}}",
        "instruction": "Extract all text content and metadata"
      }
    },
    {
      "type": "ollama",
      "name": "analyze",
      "model": "qwen-2.5:latest",
      "prompt": "Analyze this content: {{scrape.content}}"
    },
    {
      "type": "directus",
      "name": "save",
      "operation": "create-item",
      "collection": "scout_reports",
      "data": {
        "url": "{{params.url}}",
        "analysis": "{{analyze.response}}"
      }
    }
  ]
}

Step Types

The Action Runner supports 14 step types:

MCP Tool Steps

Type	Description
`directus`	Execute any Directus MCP tool (17 tools available)
`ollama`	Execute Ollama generate/chat (3 tools available)
`stagehand`	Execute Stagehand browser action (9 tools available)

Utility Steps

Type	Description
`http`	Make HTTP request (GET/POST/PATCH/DELETE)
`transform`	Transform data with JSONPath or template
`condition`	Conditional branching (if/else)
`loop`	Iterate over arrays
`delay`	Wait for specified milliseconds
`parallel`	Execute multiple steps concurrently
`error`	Throw an error (for validation)
`log`	Log message to console
`return`	Return early from flow with value
`script`	Execute custom JavaScript (sandboxed)
`wait-for`	Poll a condition until true or timeout

Variable Interpolation

Steps can reference variables from:

{{params.fieldName}} — Input parameters from the ACTION tag
{{stepName.field}} — Output from previous steps
{{env.VARIABLE}} — Environment variables
{{user.id}} — Current user context

Example:

{
  "type": "directus",
  "name": "create_job",
  "operation": "create-item",
  "collection": "media_jobs",
  "data": {
    "user_id": "{{user.id}}",
    "operation": "{{params.operation}}",
    "media_id": "{{params.media_id}}"
  }
}

System Prompt Integration

The GENIE_SYSTEM_PROMPT includes instructions for emitting ACTION tags:

When the user requests an operation, you can trigger it by outputting:

[ACTION:slug:{"param1":"value1","param2":"value2"}]

Available actions:
- scout-analyze: {"url": "https://..."}
- taxonomy-tag: {"media_id": "uuid"}
- post-create: {"media_id": "uuid", "platform": "onlyfans"}
- message-generate: {"fan_id": "uuid", "context": "..."}
- memory-recall: {"query": "..."}
- media-process: {"operation": "watermark", "media_id": "uuid"}

The tag will be hidden from the user. Mention the action in your prose.

Error Handling

Flow Not Found

If the slug doesn’t exist in action_flows, the runner logs a miss to agent_audits and returns an error message to the chat.

Step Failure

If a step throws an error:

Execution halts immediately
Error is logged to agent_audits with full stack trace
User sees a friendly error message in chat

Tier Limits

If a step triggers a tier-gated operation (e.g. create-item on media_jobs), the Directus MCP server checks quotas and throws a tier_limit: error that propagates to the user.

Implementation Details

Plugin Location

server/utils/actionRunner/

Key Files

index.js — Main plugin entrypoint and tag interceptor
executor.js — Flow step executor
steps/ — Individual step type implementations

Integration Points

Chat stream: Intercepts SSE stream from AnythingLLM
Agent audits: Logs every execution to Directus
MCP servers: Reuses existing MCP tool connections

Compared to Native Tool Calling

Aspect	Native Tool Calling	Action Runner
Model requirements	Reliable function calling support	Any model that can output text tags
Flexibility	Single-step tool execution	Multi-step workflows with variables
Error recovery	Limited retry logic	Custom error handling per step
Observability	Basic logging	Full audit trail in Directus
Tier gating	Manual implementation	Built into Directus MCP tools
Complexity	Simple, fast	More complex, slower (multi-step)

When to use Action Runner: Complex workflows, unreliable tool-calling models, need for audit trails When to use native tools: Simple single-step operations, models with good function calling (GPT-4, Claude)

MCP Servers — The 29 tools available in flow steps
Ollama Models — Models that emit ACTION tags
Collection: action_flows — Flow definitions (slug → steps JSON)
Collection: agent_audits — Execution logs (success/error/miss)

Get Started

Deployment

Core Features

AI & Automation

Integrations

Why Action Runner?

How It Works

1. Model Emission

2. Interception

3. Execution

4. Logging

Available Actions

Flow Definition Format

Step Types

MCP Tool Steps

Utility Steps

Variable Interpolation

System Prompt Integration

Error Handling

Flow Not Found

Step Failure

Tier Limits

Implementation Details

Plugin Location

Key Files

Integration Points

Compared to Native Tool Calling

Build docs developers (and LLMs) love

Get Started

Deployment

Core Features

AI & Automation

Integrations

​Why Action Runner?

​How It Works

​1. Model Emission

​2. Interception

​3. Execution

​4. Logging

​Available Actions

​Flow Definition Format

​Step Types

​MCP Tool Steps

​Utility Steps

​Variable Interpolation

​System Prompt Integration

​Error Handling

​Flow Not Found

​Step Failure

​Tier Limits

​Implementation Details

​Plugin Location

​Key Files

​Integration Points

​Compared to Native Tool Calling

​Related

Build docs developers (and LLMs) love

Why Action Runner?

How It Works

1. Model Emission

2. Interception

3. Execution

4. Logging

Available Actions

Flow Definition Format

Step Types

MCP Tool Steps

Utility Steps

Variable Interpolation

System Prompt Integration

Error Handling

Flow Not Found

Step Failure

Tier Limits

Implementation Details

Plugin Location

Key Files

Integration Points

Compared to Native Tool Calling

Related