# 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](https://www.twisp.com/docs/reference/cel.md) 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](https://www.twisp.com/docs/reference/actions/actions.md#schedule-triggers). 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](https://www.twisp.com/docs/reference/actions/agents.md). 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](https://www.twisp.com/docs/reference/actions/mcp.md). 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. > **Note:** > > New to actions? Start with the [concepts](https://www.twisp.com/docs/actions.md), which explain each kind of action and when to use it, then run the [tutorials](https://www.twisp.com/docs/tutorials/actions.md). 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](https://www.twisp.com/docs/reference/actions/sessions.md#inspecting-and-closing-sessions) and [agent memory](https://www.twisp.com/docs/reference/actions/memory.md#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](https://www.twisp.com/docs/reference/actions/tools.md#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](https://www.twisp.com/docs/reference/actions/tools.md#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](https://www.twisp.com/docs/reference/actions/executions.md#replays). | | `cancelExecution` | `id: UUID!` | Cancels an execution that has not finished. See [Cancellation](https://www.twisp.com/docs/reference/actions/executions.md#cancellation). | ## Pages - [Actions](https://www.twisp.com/docs/reference/actions/actions.md): Definitions, triggers, schedules, execution settings, publication, and policies. - [Tools](https://www.twisp.com/docs/reference/actions/tools.md): Tool blocks, calling and starting tools, nested calls, native tools, versions, and the Starlark runtime. - [Starlark](https://www.twisp.com/docs/reference/actions/starlark.md): The Starlark runtime: language, globals, types, transactions, and limits. - [Skills](https://www.twisp.com/docs/reference/actions/skills.md): Reusable guidance, the tools a skill makes available, and preloaded skills. - [Models](https://www.twisp.com/docs/reference/actions/models.md): Typed answers to typed questions from a built-in model. - [Agents](https://www.twisp.com/docs/reference/actions/agents.md): The agent block, configuration, models, agent tools, turns, outcomes, and transcripts. - [Sessions](https://www.twisp.com/docs/reference/actions/sessions.md): Session roles, turns, the session clock, approvals, held turns, and tool sessions. - [Memory and History](https://www.twisp.com/docs/reference/actions/memory.md): Agent memory scopes, extraction, search, pins, and session history. - [Executions](https://www.twisp.com/docs/reference/actions/executions.md): Execution records, lineage, preview calls, payloads, reruns, replays, and cancellation. - [MCP Servers](https://www.twisp.com/docs/reference/actions/mcp.md): Offer tools to agents outside Twisp over the Model Context Protocol. - [Limits and Errors](https://www.twisp.com/docs/reference/actions/limits-and-errors.md): Every limit and error of the actions API.