# Actions

> Source: `src/content/docs/actors/actions.mdx`
> Canonical URL: https://rivet.dev/docs/actors/actions
> Description: Actions are how your backend, frontend, or other actors can communicate with actors.

---
Actions are very lightweight. They can be called thousands of times per second safely. Actions are executed via HTTP requests or via WebSockets if [using `.connect()`](/docs/actors/connections).

For advanced use cases that require direct access to HTTP requests or WebSocket connections, see [raw HTTP and WebSocket handling](/docs/actors/fetch-and-websocket-handler).

By default, actions run in parallel. If you need advanced control over concurrency, use [queues](/docs/actors/queues).

## Writing Actions

Actions are defined in the `actions` object when creating an actor:

Each action receives a context object (commonly named `c`) as its first parameter, which provides access to state, connections, and other utilities. Additional parameters follow after that.

## Calling Actions

Actions can be called in different ways depending on your use case:

### Frontend (createClient)

Learn more about [communicating with actors from the frontend](/docs/actors/communicating-between-actors).

### Backend (registry.handler)

Learn more about [communicating with actors from the backend](/docs/actors/communicating-between-actors).

### Actor-to-Actor (c.client())

Learn more about [communicating between actors](/docs/actors/communicating-between-actors).

Calling actions from the client are async and require an `await`, even if the action itself is not async.

### Type Safety

The actor client includes type safety out of the box. When you use `createClient<typeof registry>()`, TypeScript automatically infers action parameter and return types:

## Error Handling

Actors provide robust error handling out of the box for actions.

### User Errors

`UserError` can be used to return rich error data to the client. You can provide:

-   A human-readable message
-   A machine-readable code that's useful for matching errors in a try-catch (optional)
-   A metadata object for providing richer error context (optional)

For example:

### Internal Errors

All other errors will return an error with the code `internal_error` to the client. This helps keep your application secure, as errors can sometimes expose sensitive information.

## Schema Validation

If passing data to an actor from the frontend, use a library like [Zod](https://zod.dev/) to validate input data.

For example, to validate action parameters:

## Streaming Data

Actions have a single return value. To stream realtime data in response to an action, use [events](/docs/actors/events).

## Canceling Long-Running Actions

For operations that should be cancelable on-demand, create your own `AbortController`. Chain it with `c.abortSignal` so actor shutdown also cancels the operation.

See [Actor Shutdown Abort Signal](/docs/actors/lifecycle#actor-shutdown-abort-signal) for automatically canceling operations when the actor stops.

## Using `ActionContext` Externally

When writing complex logic for actions, you may want to extract parts of your implementation into separate helper functions. When doing this, you'll need a way to properly type the context parameter.

Rivet provides the `ActionContextOf` utility type for exactly this purpose:

See [types](/docs/actors/types) for more details on using `ActionContextOf` and other utility types.

## Debugging

- `GET /inspector/rpcs` lists all available actions on an actor.
- `POST /inspector/action/:name` executes an action with JSON args and returns output.
- In non-dev mode, inspector endpoints require authorization.

## API Reference

- [`Actions`](/typedoc/interfaces/rivetkit.mod.Actions.html) - Interface for defining actions
- [`ActionContext`](/typedoc/interfaces/rivetkit.mod.ActionContext.html) - Context available in action handlers
- [`ActorDefinition`](/typedoc/interfaces/rivetkit.mod.ActorDefinition.html) - Interface for defining actors with actions
- [`ActorHandle`](/typedoc/types/rivetkit.client_mod.ActorHandle.html) - Handle for calling actions from client
- [`ActorActionFunction`](/typedoc/types/rivetkit.client_mod.ActorActionFunction.html) - Type for action functions

_Source doc path: /docs/actors/actions_