Concepts
Convoy decides who can do what, with which tools, in which order, when — and what happens next.
One station, every door, the same rules: our agent is just one client among others.
| in the sentence | primitive |
|---|---|
| who | access: identity, profiles, sub-identities |
| can | policies |
| do what, with which tools | capabilities: skills and their actions |
| in which order | journeys: playbooks |
| when | what opens: an incoming event, an automation, the intent recognised by the model |
| and what happens next | what follows: emitted events, deliveries, automations |
Then, around these rules:
- the station carries them once, for every agent;
- its channels are the doors through which agents reach it: MCP, WebMCP, the API;
- the agents are its clients: Claude, ChatGPT, a company's agent, and ours;
- the portals are where our agent meets people: widget, PWA, Teams, Slack, WhatsApp.
A channel connects an agent to the station; a portal connects a person to our agent.
The words
| word | what it is |
|---|---|
| station | a deployment: APIs + config, reachable through its channels. Versioned: staging, then production. |
| organisation | the client. It owns its stations, its directory, its keys. |
| user | the one the station serves: the customer (product), the employee (process). Profiles and permissions apply to them and to their agents. |
| admin | the one who builds and runs the station: the product builder (product), the IT admin (process). They act in the console, never in a room. |
owner (owner) | the user the room belongs to, once their identity is verified. The person the room is about is concerned (concerns). |
| identifier | a piece of data that identifies the room: phone, email, customer_id… It is declared when the person typed it (it stays in their room), verified when a provider proved it (it finds their other rooms). |
| identity provider | a mechanism Convoy prepares and the station configures: otp, oidc (Okta, Auth0, Keycloak, Entra ID), assertion. It says which data it verifies (verifies:). |
| global | what applies to the whole station: language, currency of all price fields, format, time zone. |
| agent | the agent Convoy deploys: its voice, its instructions, its portals. A client of the station, like an external agent. |
| channel | a door of the station for agents: MCP, WebMCP, the API. The same rules behind each one. |
| portal | where our agent talks: web (widget, PWA), teams, slack, whatsapp. Each one says how it proves who is talking. |
| action | what a skill proposes: "buy this item", "refund €72". In the config, an action is called an item ($item). An action reads or writes. |
| kind | a category of actions, recognised by a condition on their fields. A kind can be presented, chosen and executed differently, and declare the fields the person fills for each of its lines. |
| profile | a category of actors, recognised by a condition on the identity. A profile can be served differently, on the same points as a kind. |
| skill | a capability: it meets a need by proposing actions. It says how to get them (invoke), classify them (kinds), present them (present), reserve them (select) and execute them (submit). |
| selection | the room's order of actions: the reserved writes, and the traces of the reads. |
| guard | a policy evaluated before an action is reserved (or read). |
| playbook | a set of tasks that leads to an outcome. It enforces their order, adds guards, and ends with its submit. An order that sends the lines of several tasks in one request is declared once, on that submit. |
| sub-playbook | a task that is itself a playbook, with its own submit. The parent receives its result already executed. |
| submit | the execution of the reserved writes, in order: a call that reads another's output runs after it; otherwise the skills' calls, then the playbook's. It closes the playbook. |
| automation | an actor that starts, reminds or notifies on an event. It never writes to a tool and never submits. |
| policy | any restriction, wherever it applies. Type rule (deterministic, budgets included) or smart (a model and a threshold: it can ask for a human, never authorise). |
| event | a fact: incoming (from a tool, from another station), internal to Core, or emitted by the station. It is not refused; it is delivered. |
| outbound | the delivery of emitted facts to an external system. It decides nothing. |
| budget | a rule policy that caps several actions: an amount or a count, per scope and per period. |
| consumption | what the station costs the tenant (journeys, model calls, deliveries). It is read and billed; it is not a policy. |
| inbox | where the station asks a person to decide, with a deadline and an escalation. It is not a portal. |
| room | the space of a person (or a team) with the station. The current journey belongs to the room: several people, several sessions, several days. |
| test | a behaviour promised by the station, replayed without a model. True or false; a failure blocks the station's version. |
| eval | what our agent does with a request, played several times with its model. A rate; a failure blocks the agent's version. |
| log | what was decided, by whom, on what, with which rules. It can be replayed. |
The life cycle of an action
An action placed in the selection has a state. Internal events carry the same names:
action.pending, action.reserved, action.executed…
| action | life | at submit |
|---|---|---|
| a write | proposed → pending (on a person or a service) → reserved → executed · refused · waiting on a parent | executed, in order |
| a read | read → replaced · expired | never replayed; carried in the receipt |
A read leaves a trace because the person who submits must see what the action rests on ("Invoice INV-2291 verified · €120" above "Refund €120"). A trace does not count in the total. It is replaced, never deleted.
A refusal does not move the journey back: the action returns to proposed, and the plan is recomputed.