Actions Reference
Actions, tools, skills, models, agents, sessions, memory, MCP servers, and the executions that record their work.
An action defines a capability, such as a tool, a skill, or an agent, independently of what invokes it. A CDC-triggered action adds CEL triggers over database change data capture (CDC) events to a handler and its execution settings; a trigger can instead run the action on a schedule. A tool is an action with a tool block, which makes it callable through invokeAction. A skill is an action of kind skill, which supplies reusable guidance. An agent is an action of kind agent, whose handler runs a model in a loop over its declared tools and skills; see Agents. An MCP server is an action of kind mcp, which offers its declared tools to agents running outside Twisp over the Model Context Protocol; see MCP Servers.
Every action has at least one trigger, a tool block, kind skill, or kind mcp. An execution is one durable run of an action, whether a matching event, a schedule, or a tool call started it. The execution records its status, current invocation, event or call input, handler output, and full history.
An invocation is one call to the action’s handler within an execution. A retry starts another invocation in the same execution. If a handler accepts work asynchronously, that invocation remains open until it completes or reaches its deadline.
All operations live under the actions field of Query and Mutation. Mutations inside one actions block run in document order within the request transaction.
Operations
| Query | Arguments | Returns |
|---|---|---|
action | id: UUID!, version: Int | The action, or null if id was never created. Omit version for the current record; pass one for an exact historical version. |
actions | where: ActionFilterInput, first: Int!, after: String | ActionConnection ordered by actionId. Without a filter this includes deleted actions. |
execution | id: UUID!, version: Int | The execution, or null if id was never created. |
executions | where: ActionExecutionFilterInput, sort: SortOrder, first: Int!, after: String | ActionExecutionConnection ordered by creation time, newest first unless sort: ASC. |
Sessions and agent memory have lookups and lists of their own. Everything else is reached from these records, as the rest of the API is: an action's executions, sessions, and memory; a session's history, inputs, and turns; a turn's execution; an execution's transcript, calls, and the records it used. Every identifier a record carries has a field beside it that reads the record it names. Action, ActionExecution, ActionSession, ActionSessionTurn, and ActionAgentMemory implement Node, so the top-level node(id) query reads any of them by id.
| Mutation | Arguments | Behavior |
|---|---|---|
invokeAction | id: UUID!, input: ActionInvokeInput! | Calls a tool synchronously in the request transaction and returns its execution. See Calling a tool. |
startAction | id: UUID!, input: ActionStartInput! | Queues a tool or callable agent to run on its own and returns its execution at once. See Starting a tool. |
createAction | id: UUID!, input: ActionDefinitionInput! | Creates the action and requests its publication. Omitted settings resolve to defaults. |
updateAction | id: UUID!, input: ActionUpdateInput! | Patches only the supplied settings and requests publication. |
deleteAction | id: UUID! | Soft-deletes the action and requests removal from matching. The action and its executions remain readable. |
validateAction | input: ActionDefinitionInput!, samples: [String!] | Resolves defaults and evaluates the triggers against sample events. Stores nothing. |
rerunExecution | id: UUID!, input: ActionRerunInput! | Creates a new execution for the same event from a terminal source. |
replayExecution | id: UUID!, input: ActionReplayInput! | Reruns a recorded agent turn or MCP request with another version, committing nothing. See Replays. |
cancelExecution | id: UUID! | Cancels an execution that has not finished. See Cancellation. |
Pages
Actions
Definitions, triggers, schedules, execution settings, publication, and policies.
Tools
Tool blocks, calling and starting tools, nested calls, native tools, versions, and the Starlark runtime.
Starlark
The Starlark runtime: language, globals, types, transactions, and limits.
Skills
Reusable guidance, the tools a skill makes available, and preloaded skills.
Models
Typed answers to typed questions from a built-in model.
Agents
The agent block, configuration, models, agent tools, turns, outcomes, and transcripts.
Sessions
Session roles, turns, the session clock, approvals, held turns, and tool sessions.
Memory and History
Agent memory scopes, extraction, search, pins, and session history.
Executions
Execution records, lineage, preview calls, payloads, reruns, replays, and cancellation.
MCP Servers
Offer tools to agents outside Twisp over the Model Context Protocol.
Limits and Errors
Every limit and error of the actions API.