Workflows and AI Agents

Propeller supports embedded AI agents that can be triggered from the Sales Hub, Backoffice or any custom frontend. Agents connect to external workflow engines (such as n8n) via webhooks, so tenants and partners can build custom automations without modifying the core platform.

Each agent receives contextual data from the page it is embedded on (for example a complete order or quote payload) and returns a response that is displayed inline. This makes it possible to build anything from conversational sales assistants to one-click validation tools.

How it works

An agent is a configuration object that defines where in the UI it appears, how it is triggered and which webhook processes its requests. When a user interacts with an agent, Propeller sends the page context to the configured webhook and displays the response.

The agent API is served from a separate GraphQL endpoint from the core commerce API (products, orders, pricing, users). Agent operations are not available through the standard Propeller commerce schema.

There are three main components:

1. Agent configuration defines the agent's identity, trigger type, UI placement and webhook endpoint
2. Conversations handle the request/response lifecycle between the user and the webhook
3. Webhook integration is the external workflow that receives context and returns responses

Architecture

┌──────────────────────────────┐ ┌──────────────────────────────┐
│ Sales Hub / Backoffice       │ │ Custom Frontend              │
│                              │ │ (webshop, portal, app)       │
│ Built-in agent types:        │ │ Custom agent types:          │
│ SALES_HUB_ORDER_EDITOR       │ │ WEBSHOP_PRODUCT_DETAIL       │
│ BACKOFFICE_PRODUCTS          │ │ CUSTOMER_PORTAL_ORDERS       │
└──────────────┬───────────────┘ └───────────────┬──────────────┘
               │                                 │
               └────────────────┬────────────────┘
                                │
                                ▼
┌───────────────────────────────────────────────────────────────┐
│ Propeller Agent API (GraphQL)                                 │
│                                                               │
│ agentCreate / agents query                                    │
│ agentConversationCreate / agentMessageCreate                  │
└───────────────────────────────┬───────────────────────────────┘
                                │
                                │  POST with context payload
                                ▼
┌───────────────────────────────────────────────────────────────┐
│ External Webhook (n8n, custom API, LLM service)               │
│                                                               │
│ Receives context via requestMetadata.payload                  │
│ Returns responseMessage + optional responseMetadata           │
└───────────────────────────────────────────────────────────────┘

Key concepts

• Every agent invocation includes the complete page context so external workflows do not need to make round-trip API calls to understand what the user is looking at
• The webhook is fully external. Propeller provides the trigger mechanism and context delivery. The business logic lives in the tenant's or partner's workflow engine
• Agent types are freeform strings. Implementation partners can define custom types for any page in their webshop or portal and embed agents wherever needed
• Trigger type and interaction mode are independent, giving four valid combinations. A button can open a full conversation. A chat agent can be single-turn
• Agents return both a display message and optional structured metadata, so the UI can render rich results while also feeding data into further automations
• Webhook calls support HTTP Basic Auth and HMAC-SHA256 payload signature verification. Both are optional and can be used independently or together