# Actions

**Actions** are the reusable building blocks you create to interact with third-party tools. They allow you to define exactly *what* you want to achieve and *how* the data should look when it returns to your system, regardless of the underlying API's complexity or user specific custom fields.

Once configured in the dashboard, Actions are invoked directly via our [API](/api-documentation/actions.md#post-v1-actions-run), providing a consistent interface for your application to communicate with external services.

### Intent & Normalization

The core power of an Action is **Data Normalization**. Instead of adapting your code to fit the unique response structures of dozens of different APIs, you define the output structure you need.

* [**Define the Intent**](/concepts/intent-and-context.md)**:** You describe the goal in natural language (e.g., "List all users" or "Get tickets from the 'Assets' project").
* [**Define the Schema**](/basics/structured-output.md)**:** You provide a JSON Schema representing the exact shape of the data you want to receive (output).
  * Optional input schema: Defining an input schema allows you to pass information to the action, e.g. `{ name: "John" }`  to search by name for an action "Find users by name"

The platform ensures that the data returned from the third-party service is transformed and mapped to fit your specific schema. This means your application always receives normalized, predictable data, whether it came from Google Workspace, Jira, or HubSpot.

### User Mappings

**User** **Mappings** define the integration(s) and executable logic that fulfills the Action.

You can mix and match mapping strategies within a single Action depending on the service:

#### 1. Default Mappings

For standardized services where the data structure is consistent across all organizations (such as **Google Workspace** or **Microsoft 365**), you can use a **Default Mapping**.

* **How it works:** You define the mapping logic once.
* **Benefit:** It automatically applies to every user that connects to that integration, requiring no per-user configuration.

#### 2. User-Specific Mappings

For highly customizable tools (such as **Jira** or **HubSpot**) where workflows vary between customers, the platform supports **User-Specific Mappings**.

* **How it works:** The system adapts the execution logic based on the specific user's configuration.
* **Example:** One customer might store IT assets in a Jira project named "IT," while another uses a specific label within a generic project.

**Interchangeability:** These strategies are interchangeable within a single Action. For example, your "List Users" Action can utilize a Default Mapping for your Google Workspace handling, while simultaneously using User-Specific Mappings for your HubSpot mappings to handle custom field variations.

### Execution Engine

Our execution model prioritizes reliability and performance by primarily executing code, and using AI agent based execution only when needed.

Each invocation of an action results in a [Run](/concepts/runs.md).

#### Agent Mode (Supervised)

When an Action is run for the first time or encounters unexpected errors, it operates in **Agent Mode**.

* **Role:** An AI Agent acts as an overseer.
* **Process:** The Agent supervises the execution of generated code step-by-step. It verifies that the API interaction is proceeding according to plan and can intervene dynamically if the code encounters unexpected behavior.

#### Code-Only Mode (Optimized)

Once the logic is established and verified, the Action automatically transitions to **Code-Only Mode**.

* **Role:** Pure code execution
* **Process:** The system executes code to achieve the intent without AI intervention for maximum speed.
* **Fallback:** If the code encounters an error (e.g., an API change or schema mismatch), the system automatically reverts to Agent Mode to diagnose the issue, heal the workflow, and update the code for future runs.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toolregistry.ai/basics/actions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.