Workflows · Cogtrix

A workflow in Cogtrix bundles a system prompt, an active toolset, a knowledge base, and an entry trigger into a single named unit. The agent auto-detects which workflow applies to an incoming message and routes accordingly.

Workflows are the layer that lets one Cogtrix instance act as multiple specialised assistants — one for customer support, one for code review, one for scheduling — without restarting or rerouting at the infrastructure level.

Anatomy

A workflow is defined as a record in the assistant database with these fields:

Field	Purpose
`name`	Unique identifier. Used in API + CLI references.
`system_prompt`	Replaces the default system prompt for this workflow.
`tool_list`	Comma-separated tool names that are pinned active in this workflow.
`knowledge_base_ids`	Linked RAG document collections — searched on every turn.
`triggers`	Auto-detection rules — keywords, regex, or contact tags.
`binding_channels`	Which assistant channels (Telegram, WhatsApp, web) route to this workflow.

Creating a workflow

Use the REST API:

curl -X POST http://localhost:8000/api/v1/assistant/workflows \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support-tier1",
       "system_prompt": "You are a friendly tier-1 support agent…",
       "tool_list": "web_search,knowledge_search",
       "knowledge_base_ids": ["faq-2026", "product-docs"],
       "triggers": {
         "keywords": ["billing", "subscription", "refund"]
       }
     }'

Or, via the Web UI: Assistant → Workflows → New.

Auto-detection

When a message arrives on a bound channel, the assistant scores each workflow’s triggers against the message content. The highest-scoring workflow wins. If no workflow matches, the default config-level system prompt and tool set apply.

You can force a specific workflow by including its name in the message metadata or by binding a contact directly to a workflow.

Inspecting the active workflow

In an interactive session, the active workflow appears in /info. In API responses, the session record includes active_workflow_id.

Knowledge base attachment

A workflow’s knowledge_base_ids controls which RAG document collections get queried on every turn. This is how you keep “support documents” out of a “developer assistant” workflow’s recall pool.

See RAG / knowledge base for ingesting documents into a knowledge base.

Binding to channels

Channels (WhatsApp, Telegram, web chat) bind to workflows via the binding-channels REST endpoint. A single channel can support multiple workflows; the trigger system decides which one each message activates.

Limits

Maximum ~50 workflows per instance before classification latency becomes noticeable.
system_prompt should fit within the model’s context window minus working memory budget.
tool_list is pinned — workflows cannot dynamically load tools via /tools load. To make a tool available in a workflow, add it to tool_list.

→ REST API: assistant/workflows/* — every workflow endpoint.