> ## Documentation Index
> Fetch the complete documentation index at: https://benchgen.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Create an Action

> Step-by-step guide to adding a new Action to a Topic in Agentspace.

# How to Create an Action

This step‑by‑step guide shows how to add a new Action to one of your Topics.

> [!NOTE]
>
> **What Is an Action**
>
> An **Action** is the executable capability a Topic can invoke to move from intent → real outcome. Where a Topic defines scope, guardrails, and behavioral rules, an Action is the concrete tool (API call, workflow, computation, retrieval, mutation) that actually does work.
>
> Multiple Topics can reuse the same Action (e.g., a generic customer lookup). Likewise a single Topic may orchestrate several Actions in sequence. Designing Actions as modular, well‑named, side‑effect‑clear units keeps agents predictable, debuggable, and auditable.

> For deeper conceptual detail see: [What is an Action](https://benchgen.com/docs/agentspace/what-is-an-action.md)

### When to Create vs Reuse

**Create a new Action if:**

* Side effects or API contract differ (new endpoint, new verb, different auth).
* Required inputs / outputs diverge meaningfully from existing ones.
* You need isolated monitoring or rollout control.

**Reuse (or lightly extend) an existing Action if:**

* Only the calling Topic logic changes, not the underlying operation.
* A minor additional optional field covers the delta.

> [!TIP]
>
> If you find yourself adding conditional branching inside an Action description ("Sometimes updates, sometimes queries …"), you probably have multiple Actions intertwined—split them.

***

## How to Create an Action

1. **Open My Agents & Select an Agent**
   Go to your Left Menu and click **My Agents**. Then click the agent you want to add an action to (opens its details).

   ![Agent Details](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/choose-agent.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=551f605f1c88c7c643a9985474e639ac)

   Agent Details

2. **Open the Topics Tab**
   In the agent's left menu, click **Topics** to view existing Topics.

   ![Topic Management](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-01-topic-management.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=e6caf585279308650146aa49587171f6)

   Topic Management

3. **Open the Topic's Actions**
   Click the Topic name, then open **This Topic's Actions** to see any attached Actions.

   ![Edit Topic](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-02-click-edit-topic.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=225dda626e60941df71cad154ce34383)

   Edit Topic

4. **Create a New Action**
   This page lists the Actions attached to the selected Topic. To add an Action: click **+ Add Action** then click the **+ Create a New Action** and proceed to configure the Action.

   ![Create New Action](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-04-create-new-action.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=4942bd92d5492d0de3bf15018267f28f)

   Create New Action

***

## Create Your Own API Action

5. **Fill Action Details**
   Select **API** action and click to **Continue to Configure**. Complete fields in each block: Basic Info, Endpoint Configuration, Authentication, Query Params, Custom Headers, Input Parameters, Output Schema, Advanced Settings. Keep labels short and outputs lean.

   ![Configure Action Form](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-06-configure-action-form.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=61a1db0a4816568da9c4a678bc3a4cbc)

   Configure Action Form

   **Example (Get Product Details)**

   | Field | Example | Notes |
   | - | - | - |
   | Label | `Get Product Details` | Clear verb + object. |
   | Description | Call external API endpoints | Refine later with disambiguator (e.g., "Returns name, price, availability"). |
   | Base URL | `https://external-agent-.../testenvcloudlabs.cn` | Version / environment explicit. |
   | HTTP Method | `POST` | Matches service contract (use GET if retrieval only). |
   | Endpoint Path | `/getproduct` | No trailing slash duplication. |
   | Authentication | No Authentication (example) | Replace with real auth when secured. |
   | Query Parameters | (none) | Add only if filtering needed. |
   | Custom Headers | (none) | Insert `Accept: application/json` etc. if required. |
   | Input Parameters | `productId` (string, required) | Single required key. |
   | Output Schema | `productDetails` (string) | Replace with structured fields when mapping added. |
   | Timeout | `30` seconds | Tune to API latency. |
   | Retries | `0` | Increase only for idempotent calls. |
   | Error Handling | Throw Error | Fail fast for visibility. |
   | Response Mapping | (empty) | Add transform once response shape confirmed. |

6. **Test the API Action**
   Click **Test API**. Check assembled URL, method, headers, body, status code, and mapped outputs. Iterate until: correct status, expected latency, outputs populated, no secrets leaked.

   ![Test API](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-08-test-api.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=b2ab06c2964c5244f2812d14fa23e10f)

   Test API

   ![Test Success](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-09-test-success.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=c5583b3ae6a0bb019f427aeea5b4e859)

   Test Success

7. **Save the API Action**
   When satisfied, press **Save**.

   ![Save Action](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-10-save-action.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=98cc857224c45372bc21beb4ea2ba3d3)

   Save Action

8. **Validate in Chat**
   Use the right‑side chat. Trigger phrases that *should* invoke the Action plus a phrase that should route elsewhere. Adjust Description if mis‑selected.

***

## Use an Action Template

Leverage a pre-built template when your operation is common (lookup, list, status check) and you want speed + consistency.

1. **Access the Asset Library**
   Go to your Agent → **Topics** → open the relevant Topic → **This Topic's Actions** → click **Add from Asset Library**.

   ![Asset Library](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/clickassetsaction.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=ae98d717ad1bc7a21172481cb6d9223a)

   Asset Library

2. **Browse and Search Templates**
   Search or filter by keyword (product, order, quiz, invoice) to find relevant templates.

3. **Preview Template Details**
   Review the template's Label, Description, Inputs, Outputs, HTTP Method, Base URL/Path, Authentication, and Headers to ensure it matches your needs.

4. **Select and Apply Template**
   Click one **Template** to clone the action into your Topic.

   ![Asset Library](https://mintcdn.com/benchgen-8fc81371/2OCozHVviHUGu126/images/agentspace/action-11-asset-library.png?fit=max\&auto=format\&n=2OCozHVviHUGu126\&q=85\&s=fc3a77ed0bc7de9c09635834c6bf7a6a)

   Asset Library

5. **Customize Template Details**
   Modify ONLY what's required:
   * Ensure a unique label / API name (avoid collisions)
   * Update auth to your secret reference
   * Adjust Base URL / path placeholders
   * Remove unused params & outputs
   * Narrow the description (state one clear purpose)
   * Provide Example Input JSON if absent
   * Validate timeouts/retries for your API

6. **Test and Validate the Action**
   Click **Test API** to verify assembled URL, method, headers, body, status code, and mapped outputs. Then **Save** and validate in chat to confirm the agent calls the correct action.

> [!NOTE]
>
> **Testing Your Action**
>
> A passing test confirms: correct status code, expected response shape, and mapped output fields populated. If the test fails, check auth credentials, endpoint path, and input parameter formatting before retrying.

***

**Done!** You've created (or templated) an Action and hardened its definition.

## Next Steps

* Browse reusable templates → [Action Asset Library](https://benchgen.com/docs/agentspace/action-asset-library.md)
* Back to concepts → [What is an Action](https://benchgen.com/docs/agentspace/what-is-an-action.md)
* Back to topic guide → [How to Create a Topic](https://benchgen.com/docs/agentspace/how-to-create-topic.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.