# Actions

Capabilities you define once in the ledger, such as tools, skills, agents, and MCP servers, and run from triggers, calls, sessions, or outside agents, with every run recorded.

An **action** is a capability defined in your Twisp tenant, independently of what invokes it. Its definition says what it does: a handler `kind` and its `config`, the schemas of what it accepts and returns, the tools and skills it may use, and the `policies` that bound what it can touch. How it runs is a separate choice. The same action can run when a record changes, on a schedule, when a client or another action calls it, as a turn of a long-running session, or when an agent outside Twisp asks for it.

Every run of every action is an **execution**: a durable record of what ran, on what input, under which exact version, with what result, and what it called.

## The kinds

An action's `kind` selects its handler. How it runs depends on what else the definition holds: event or schedule triggers make it run on its own, a `tool` block makes it callable, and a `session` gives it durable identity across runs. Every action has at least one trigger, a `tool` block, kind `skill`, or kind `mcp`.

| What you build   | What it is                                                                                | Use it when                                                                                    | Concepts                                                    | Reference                                      |
| ---------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------- |
| Triggered action | Any action with event or schedule triggers.                                               | Work must follow a ledger change, or run at set times, and you need a record that it happened. | [Triggers and Executions](https://www.twisp.com/docs/actions/triggers-and-executions.md) | [Actions](https://www.twisp.com/docs/reference/actions/actions.md#triggers) |
| Tool             | Kind `tool`: a Starlark program behind a typed input and output.                          | Clients, agents, or other tools need one well-defined operation, run atomically.               | [Tools](https://www.twisp.com/docs/actions/tools.md)                                     | [Tools](https://www.twisp.com/docs/reference/actions/tools.md)              |
| Skill            | Kind `skill`: instructions, examples, and the tools a procedure uses.                     | Agents need guidance for a task that is shared, versioned, and loaded only when needed.        | [Skills](https://www.twisp.com/docs/actions/skills.md)                                   | [Skills](https://www.twisp.com/docs/reference/actions/skills.md)            |
| Model            | Kind `model`, built in: typed questions to a provider's model, such as `typesafe_jev`.    | A decision needs a judgment over text or records, returned as typed answers code can act on.   | [Models](https://www.twisp.com/docs/actions/models.md)                                   | [Models](https://www.twisp.com/docs/reference/actions/models.md)            |
| Agent            | Kind `agent`: a model in a loop over its declared tools and skills.                       | The work needs reasoning across steps, and every step must be bounded and recorded.            | [Agents](https://www.twisp.com/docs/actions/agents.md)                                   | [Agents](https://www.twisp.com/docs/reference/actions/agents.md)            |
| MCP server       | Kind `mcp`: an endpoint offering chosen tools and skills over the Model Context Protocol. | Agents you run outside Twisp need to act on the ledger.                                        | [MCP Servers](https://www.twisp.com/docs/actions/mcp-servers.md)                         | [MCP Servers](https://www.twisp.com/docs/reference/actions/mcp.md)          |

The kinds are not exclusive roles. A tool can also have triggers, so the same program runs for events and for calls. An agent can have triggers and a `tool` block, so it runs for events and other agents can call it. An agent with a session runs through its session instead; a callable agent has none.

## How the pieces compose

Actions are built from one another by name:

- **Tools call tools.** A tool declares the tools it calls, and each call is a child execution. A call and everything beneath it commits or rolls back as one unit. See [Tools](https://www.twisp.com/docs/actions/tools.md).
- **Agents use tools and skills.** An agent can call only the tools it declares and load only the skills it declares, plus the tools a loaded skill makes available. Its model decides which to use; the definition decides what is possible. See [Agents](https://www.twisp.com/docs/actions/agents.md) and [Skills](https://www.twisp.com/docs/actions/skills.md).
- **Models are tools.** Twisp ships each model, and every tenant can call one like any tool. A Starlark tool can wrap a model so a judgment and the writes it leads to commit together. See [Models](https://www.twisp.com/docs/actions/models.md).
- **MCP servers offer tools to outside agents.** A server lists the tools and skills an external agent may use, and each request is an execution of the server, recorded like the work of an agent Twisp runs. See [MCP Servers](https://www.twisp.com/docs/actions/mcp-servers.md).
- **Sessions give actions durable identity.** A session ties a stream of events, schedule firings, and calls to one subject, such as one account, with its own input, state, history, and end. An agent with a session works in turns and can remember across them. See [Sessions](https://www.twisp.com/docs/actions/sessions.md) and [Memory](https://www.twisp.com/docs/actions/memory.md).

## Executions

An execution is the universal record. A matching event, a schedule firing, a client's call or start, a session turn, a nested call, a skill load, and a request to an MCP server each produce one. It records its status, the exact action version, its input, every invocation and its output or error, and its full history. Calls and starts link executions into trees, and `lineage` walks them, so any piece of work can be followed to everything it caused. See [Triggers and Executions](https://www.twisp.com/docs/actions/triggers-and-executions.md#executions-as-records).

Because every run is recorded with its input and version, a recorded agent turn or MCP request can be [replayed](https://www.twisp.com/docs/actions/preview-and-replay.md) against a changed version, and an agent can run in preview mode, doing everything it would do while committing none of its business writes.

## Versions and publication

Every write to an action creates a new version, and the action keeps them all. Writes take effect asynchronously: a new or changed definition is `pending` until it is published. An event is matched against the version published when it committed; a call names the version it runs, and a start runs the current version unless it names one. Each execution is pinned to the version it ran, so editing an action never changes work already recorded.

References between actions choose how they follow change. A reference with a `version` always uses exactly that version; one without uses the latest version, resolved when each execution starts, and the execution records the version it used. See [Publication status](https://www.twisp.com/docs/reference/actions/actions.md#publication-status) and [Versions](https://www.twisp.com/docs/reference/actions/tools.md#versions).

## The policy chain

Each action runs as its own principal with its own `policies`, and every operation a tool or agent performs is checked against a chain of policy lists: the client that started the work, then the MCP server, for a request made through one, then the agent, if one is on the call stack, then each tool from the first call down to the one performing the operation. Every layer must allow the operation, so each layer can only narrow what the layers above it allow. Declaring a tool never grants its caller anything, a tool can do only what its callers can, and an agent's policies bound everything it can reach through any tool. See [Policy chain](https://www.twisp.com/docs/reference/actions/actions.md#policy-chain) and [Authority and Audit](https://www.twisp.com/docs/actions/authority-and-audit.md).

## In this section

- [Triggers and Executions](https://www.twisp.com/docs/actions/triggers-and-executions.md): Run work when records change or on a schedule, and operate the executions that record it.
- [Tools](https://www.twisp.com/docs/actions/tools.md): Typed, versioned programs that are called in your transaction or started to run on their own.
- [Writing Starlark](https://www.twisp.com/docs/actions/starlark.md): Write, test, and debug the Starlark programs behind tools.
- [Native Tools](https://www.twisp.com/docs/actions/native-tools.md): The tools Twisp provides, and when to use each.
- [Skills](https://www.twisp.com/docs/actions/skills.md): Reusable guidance and the tools its procedure uses, loaded by agents when needed.
- [Models](https://www.twisp.com/docs/actions/models.md): Typed answers to typed questions from a built-in model.
- [Agents](https://www.twisp.com/docs/actions/agents.md): A model in a loop over declared tools and skills, bounded by its policies and fully recorded.
- [Sessions](https://www.twisp.com/docs/actions/sessions.md): Durable identity across events, schedules, and calls, with turns, approvals, and an end.
- [Memory](https://www.twisp.com/docs/actions/memory.md): What agents keep between turns and sessions, and how they search it.
- [MCP Servers](https://www.twisp.com/docs/actions/mcp-servers.md): Offer your tools and skills to agents running outside Twisp.
- [Preview and Replay](https://www.twisp.com/docs/actions/preview-and-replay.md): Run agents without committing, and rerun recorded work against a changed version.
- [Authority and Audit](https://www.twisp.com/docs/actions/authority-and-audit.md): Who may do what through an action, and how to trace any decision back to its evidence.