Build Focused Actions

An action is one reusable executable operation. An HTTP action represents one HTTP request. Other action types cover code, model work, platform capabilities, and backend composition.

Choose the Action Type

Do not model every action as an API call. Keep the name aligned with the operation it actually performs.

Step 1: Define Typed Input Arguments

Input arguments make an action reusable. Define the values the caller must provide without coupling the action to a specific conversation.

For a Get feature requests HTTP action:

For an Update feature request HTTP action:

Step 2: Configure One HTTP Operation

An HTTP action defines:

Build Along: Create the PurpleSuite Actions

Use the explorer to inspect the current Community API contract. It reads public catalog and OpenAPI metadata, then translates the selected operation into an Agent Studio action outline. It never requests credentials or executes the operation.

GET /api/purple-suite/community/feature_requests
$filter: currentStatus ne 'Planned'
$select: id,name,currentStatus,productArea
$top: 10

Create these three HTTP actions with the connector from the previous chapter:

Add X-Instance-ID as an action header for all three operations. For the update action, map a JSON body with only the field being changed:

{
  "currentStatus": "{{{new_status}}}"
}

Configure the list action with the query parameters used by the dynamic resolver:

Run the three actions in the same order the complete plugin uses:

1. Run List PurpleSuite feature requests and save one returned record’s id, name, and original currentStatus.
2. Run Get PurpleSuite feature request with that ID and verify the same record is returned.
3. Run Update PurpleSuite feature request with the ID and new_status: Planned.
4. Run the get action again and verify currentStatus is Planned.
5. Restore the original status when appropriate for your development instance.

Your checkpoint is three independently tested actions with stable, minimal response schemas.

Step 3: Place Variables Safely

HTTP actions can reference inputs and supported runtime values in the endpoint, headers, query parameters, body, and JWT claims.

{{query}}

Step 4: Use Runtime User Data Deliberately

In user-triggered execution, an HTTP action can reference supported user attributes through meta_info.user.

{{{meta_info.user.email_addr}}}

Use the bare meta_info.user.email_addr path only in Data Mapper or DSL contexts. Do not assume that user context exists in webhook or scheduled execution. Pass identity as an explicit input when backend work needs it.

Use meta_info.action_instance_id when the downstream API supports an idempotency key.

Step 5: Shape the Response Early

Every field you keep becomes part of a downstream contract. Prefer:

{
  "id": "FR-1042",
  "name": "Bulk edit requests",
  "current_status": "Planned",
  "product_area": "Admin"
}

Avoid passing:

{
  "raw_record": {
    "internal_metadata": {},
    "debug": {},
    "audit_history": [],
    "unused_fields": []
  }
}

There are three useful pruning boundaries:

1. The HTTP action Response Schema removes fields before returning to its caller.
2. A compound action’s return.output_mapper controls its final return.
3. A conversation action activity’s Output Mapping controls what enters the conversation process and reasoning context.

Step 6: Test the Action in Isolation

Provide example values for every input argument and test:

• A successful response.
• No matching data.
• Invalid and boundary values.
• Unauthorized and forbidden responses.
• Rate limiting and timeouts.
• Malformed downstream data.
• A repeated write with the same idempotency key.

The action editor uses the currently logged-in builder for user runtime attributes. This does not prove that every end user has the same downstream access.

Action Quality Checklist

• The name begins with a clear verb.
• The action performs one focused operation.
• Input arguments are typed and reusable.
• The endpoint path begins with /.
• The connector supplies secrets; descriptions and mappings do not.
• Request variables use the correct substitution or mapping method.
• The response schema includes only useful fields.
• Errors preserve enough detail for deterministic handling without exposing secrets.
• The action passes isolated tests before composition.

Deep Dives

• Actions
• HTTP Actions
• HTTP Action Data Bank
• Data Mapper in HTTP Actions
• Script Actions
• LLM Actions

Next, map data and context.