> This page is for Agent Studio.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.moveworks.com/_mcp/server.

# Design the Outcome and Trigger

Strong plugins start with a business outcome and a real downstream contract, not with a blank process canvas.

## Step 1: Write the Outcome as a Contract

Describe the outcome in one sentence:

> Given **these inputs**, perform **this operation** in **this system**, then return **this result**.

For example:

> Given an employee and leave type, retrieve the employee's current balance from the HR system, then return the available, used, and scheduled amounts.

This sentence becomes the architecture boundary. If it contains several independent outcomes, split it into reusable actions or separate plugins.

## Step 2: Start in the Downstream System

Before opening Agent Studio, confirm:

#### Find the supported API operation

Record the HTTP method, base URL, endpoint path, required headers, query parameters, request body, response schema, pagination, and error responses.

#### Choose the execution identity

Decide whether requests represent a shared application or service account, or each consenting user.

#### Grant the minimum permissions

Configure the account, OAuth application, scopes, roles, allowlists, and test data required by the operation.

#### Define failure behavior

Decide how to handle missing records, invalid inputs, authorization failures, rate limits, timeouts, and partial completion.

> **Identity Model Before Authentication Mechanism**
>
> First choose **who the downstream system should believe is calling**: a shared application identity or a delegated user identity. Then choose a mechanism the provider supports, such as API key, OAuth, JWT bearer, or Basic authentication.

## Step 3: Choose the Trigger

The trigger determines the runtime context and the body your plugin can execute.

#### User Utterance

Use a **conversational plugin** when a user asks for the capability and the assistant may need to collect, confirm, or present information.

Typical body: a **conversation process** containing slots and action activities.

Examples:

* "Check my PTO balance."
* "Transfer this opportunity to Priya."
* "Order a monitor for my new hire."

#### Webhook

Use a **plugin with a webhook system trigger** when an external event should start work.

Typical body: an HTTP action or compound action.

Examples:

* An expense report enters review.
* An incident becomes critical.
* A candidate reaches the offer stage.

#### Schedule

Use a **plugin with a scheduled system trigger** when a clock should start work.

Typical body: an HTTP action or compound action.

Examples:

* Audit purchase requests every morning.
* Send a weekly risk digest.
* Find overdue tasks every two hours.

> **One Trigger Paradigm per Plugin**
>
> Create separate plugin wrappers when the same reusable actions support both conversation and system events. This keeps retrieval, launch behavior, logs, and runtime context clear.

## Step 4: Decide Where Conversation Is Required

Use a new conversational step only when the assistant must:

* Collect a value from the user.
* Resolve an ambiguous business object.
* Apply a user-facing confirmation or policy.
* Branch based on user input.
* Display information before continuing.

Keep steps together in a compound action when they:

* Run without user input between calls.
* Transform or validate backend data.
* Implement retries, loops, or deterministic control flow.
* Should expose one compact result instead of several intermediate responses.

This separation prevents integration plumbing from consuming conversational context.

## Step 5: Sketch the Data Contract

Create a short contract for every boundary:

| Boundary                  | Define                                                  |
| ------------------------- | ------------------------------------------------------- |
| Trigger → body            | Event payload, schedule body, or conversation slots     |
| Process → action          | Typed input arguments and input mapping                 |
| Action → process          | Response schema and output mapping                      |
| Compound action → caller  | Explicit `return.output_mapper`                         |
| Plugin → reasoning engine | Title, description, examples, and useful runtime output |

## Build Along: Plan the PurpleSuite Capability

Use the PurpleSuite Community API for one continuing build. At this stage, create the design record rather than an Agent Studio asset.

#### Write the outcome

Given a feature request selected by the user and a supported target status, update that request in PurpleSuite and return its name and new status.

#### Choose the conversational trigger

Use a conversational plugin because the assistant must resolve a feature request, collect a target status, and confirm the write.

#### Record the API operations

Use `GET /api/purple-suite/community/feature_requests` to find candidates, `GET /api/purple-suite/community/feature_requests/{id}` to verify one record, and `PATCH /api/purple-suite/community/feature_requests/{id}` to update it.

#### Set the deterministic boundary

Constrain the target status to an approved list, preserve the selected record ID, confirm the write, and expose only the final business result.

Your checkpoint is a short design record with these decisions:

| Decision            | PurpleSuite build                                    |
| ------------------- | ---------------------------------------------------- |
| Capability name     | `Manage Product Feature Requests`                    |
| Execution identity  | Shared PurpleSuite instance credential               |
| Trigger             | User utterance                                       |
| Conversation needed | Record selection, status selection, and confirmation |
| Reusable operations | List, retrieve, and update feature requests          |
| Final output        | Request name and current status                      |

## Architecture Worksheet

#### Outcome

What business state should change or what information should the user receive?

#### Downstream Contract

Which API operation is authoritative? What permissions, request fields, and error responses does it define?

#### Execution Identity

Does the provider see a shared service identity or the consenting user?

#### Trigger

Does a user utterance, webhook, or schedule start the capability?

#### Conversation Boundary

At which exact points must the assistant collect, confirm, decide, or display?

#### Deterministic Boundary

Which validations, business rules, transformations, and control flow must not depend on model interpretation?

## Deep Dives

* [Assistants, Agents, and Plugins](/agent-studio/core-concepts/assistants-agents-plugins)
* [Building a Conversational Plugin](/agent-studio/guides/architecture/building-a-conversational-plugin)
* [Ambient Agents](/agent-studio/core-concepts/ambient-agents)
* [System Triggers](/agent-studio/system-triggers)
* [The Golden Rule](/agent-studio/guides/best-practices/the-golden-rule)

Next, [configure the connector](/agent-studio/guides/plugin-building-masterclass/configure-the-connector).