> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/create-a-custom-action.md).

# Create a custom action

A custom action adds an operation that is not available in the standard action catalog. You define its inputs, outputs, and code. StackAI can generate an initial implementation from your instructions.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2Fm78Pb9S0aFCOZ9ieSKDd%2FG050.mp4?alt=media&token=f1d05668-43db-4493-99a9-cf9b8553a4ed>" %}

## Before you start

Have an authorized connection for the provider used by the action.

## Choose the provider

Open Settings → Custom Actions, select Create Action, and choose the provider.

![Action provider selection controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/FgXGCszaXWWycYs7c0on/assets/g050-g050-01-provider.png)

The provider determines the authenticated connections available to the action.

## Generate the action

Describe the operation, its inputs, and its expected outputs to the generation assistant.

![Custom action generation controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/futPfrnEg7hvd04vfdtS/assets/g050-g050-02-prompt.png)

State whether it reads or changes data and whether repeating it can cause additional effects.

Review the proposed operation and returned fields before selecting Accept.

![Custom action generation controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/JB6MjDBLryjMn8b8rQnj/assets/g050-g050-03-generated.png)

Inspect the generated configuration and code before using the action.

## Review the action settings

Open Edit Manually → General and review the provider, connection requirement, and behavior annotations.

![Custom action behavior settings](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/6gYJtA8eJqCALcjtlssO/assets/g050-g050-04-general.png)

Read-only, Destructive, and Idempotent must describe what the implementation actually does.

## Review inputs, outputs, and code

Open Schema and check input and output definitions.

![Custom action implementation review](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/D2AgroUsyirvr3bY1YA4/assets/g050-g050-05-schema.png)

Field names and data types must match the values the code accepts and returns.

Open Code and inspect the provider API request.

![Custom action implementation review](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/MNKpqSkzHIvBJ7EuLzdO/assets/g050-g050-06-code.png)

Use the authenticated provider connection rather than placing credentials directly in the implementation.

Review error handling and the mapping from the provider response into the output fields.

![Custom action implementation review](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/JzPVTnW3DBr1YJsgbHip/assets/g050-g050-07-mapping.png)

A count derived from a returned list may not represent every record in a paginated provider account.

## Run the action

Select an authorized provider connection.

![Custom action execution results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/gAm3RQcItpSRUcNUDG9j/assets/g050-g050-08-connection.png)

The action uses that account when it calls the provider.

Open Test Action and select Run Action.

![Custom action execution results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/MYtwCtBt8VLCSOny5J7m/assets/g050-g050-09-test.png)

Inspect the response status and records returned by the actual provider request.

Check that summary fields agree with the returned records.

![Custom action execution results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/ojgSwsTvHt30h0D03gyy/assets/g050-g050-10-result.png)

For example, a count of returned items should match the length of the corresponding array.

## Save the action

Select Create after reviewing the action's behavior and response.

![Saved custom action configuration](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/3BPXSFrZmMHIIcWUA0YX/assets/g050-g050-11-saved.png)

Confirm that the saved custom action appears under the intended provider for reuse.

## Important behavior

Read-only means the action does not change provider data. Destructive identifies an action that can remove or irreversibly change data. Idempotent means repeating the same request does not cause additional effects.

If the provider returns results in pages, handle pagination when the action needs a complete list. For GraphQL requests, inspect response errors as well as the HTTP status.

## Continue

* [Configure and test an action](https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/configure-and-test-an-action.md)
* [Give an agent tools](https://docs.stackai.com/guides-and-quickstarts/agent-builder-and-skills/give-an-agent-tools.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/using-tools-and-actions/create-a-custom-action.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
