Skip to navigation
Plugin Building MasterclassEnd-to-End Course

Design the Outcome and Trigger

Define the business outcome, execution identity, API contract, and trigger before creating assets.
View as Markdown

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:

1

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.

2

Choose the execution identity

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

3

Grant the minimum permissions

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

4

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.

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.”
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:

BoundaryDefine
Trigger → bodyEvent payload, schedule body, or conversation slots
Process → actionTyped input arguments and input mapping
Action → processResponse schema and output mapping
Compound action → callerExplicit return.output_mapper
Plugin → reasoning engineTitle, 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.

PurpleSuite end-to-end call trace

Follow one live feature request through the same three API calls and Agent Studio contracts in every chapter.

Shared connector
https://marketplace.moveworks.com
Every API action
Connector adds Bearer PAT. Action adds X-Instance-ID.
Design the complete contract
Start with the user outcome, identify the three API calls, and define the final response before creating assets.
User requestConversationConversational plugin
Move <a live feature request name> to Planned.
Receives
Natural-language intent
Returns
Selected plugin and conversation process
How it fits
The title, description, and triggering examples retrieve the capability. They do not contain an API record ID.
Successful run: actual API call ledger
1GET/api/purple-suite/community/feature_requestsDynamic resolver retrieves live candidates
2PATCH/api/purple-suite/community/feature_requests/{id}Compound action updates the selected record
3GET/api/purple-suite/community/feature_requests/{id}Compound action verifies the stored result
Use a record returned by your own PurpleSuite instance. Save its original status before the write and restore it after mutation testing when appropriate.
1

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.

2

Choose the conversational trigger

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

3

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.

4

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:

DecisionPurpleSuite build
Capability nameManage Product Feature Requests
Execution identityShared PurpleSuite instance credential
TriggerUser utterance
Conversation neededRecord selection, status selection, and confirmation
Reusable operationsList, retrieve, and update feature requests
Final outputRequest name and current status

Architecture Worksheet

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

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

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

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

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

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

Deep Dives

Next, configure the connector.