Skip to navigation
Plugin Building Masterclass

Plugin Building Masterclass

Build a Moveworks plugin from the downstream API through launch, testing, and operation.
View as Markdown

A plugin is a deployable capability that the Moveworks AI assistant can select or a system event can start. You build it from small, reusable modules: connectors, actions, typed data contracts, orchestration, and a trigger.

This masterclass teaches the complete architecture. You will learn where each module begins and ends, what data it can access, what the reasoning engine can see, and when to use deterministic logic instead of model instructions.

What You Will Build

The hands-on path uses the PurpleSuite Community API to build one continuing capability: Manage Product Feature Requests. Every chapter adds a working asset, from the connector and HTTP actions through slots, mappings, orchestration, publication, and testing.

Keep the same PurpleSuite instance and assets as you progress. Each chapter includes a Build Along section with a concrete checkpoint, so the concepts immediately become a working plugin.

The One-Picture Mental Model

Choose a trigger, then select a stage to see what changes and what stays reusable.

One modular assembly

Each outer layer plugs into a stable contract around the reusable core.

Moveworks capabilityOutside → inside
Slots and user contextInput mapper
Compound actionActionConnector
Outside Moveworks
External system API
Owns permissions, endpoints, and the API response.
Return path
API response → Output mapper → Reasoning engine
1. Start: Conversational plugin
Modules
Conversational plugin
Receives
User request
Hands off
Slots and user context
Modular rule: Swap this outer module when the capability needs a different trigger.

The architecture follows one rule:

Use the reasoning engine for language, intent, and conversation. Use typed inputs, mappings, DSL, policies, and code for business rules that must behave predictably.

The two sides work together:

Probabilistic layerDeterministic layer
Selects the most relevant conversational pluginConstrains which APIs and operations can run
Infers slot values from natural languageValidates collected values with DSL
Asks follow-up questionsMaps exact values into typed action inputs
Presents useful resultsFilters, renames, and structures action outputs
Chooses the next conversational stepExecutes backend sequences in compound actions

The Running PurpleSuite Trace

Every chapter uses the same live record and call sequence. Select a stage to see the Agent Studio asset that owns it, the exact PurpleSuite operation, and the data passed to the next module.

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.

The Building Blocks

A plugin packages a capability for deployment. A conversational plugin uses a user utterance as its trigger. A plugin with a system trigger, often called an ambient agent, uses a webhook or schedule.

A connector represents one external system’s base URL and authentication configuration. Build it from the downstream system’s account and permission model, then reuse it across compatible HTTP actions.

An action is one reusable executable operation. An HTTP action represents one HTTP request. Script, built-in, LLM, and compound actions provide other execution patterns.

A compound action coordinates uninterrupted backend work behind one action boundary. Its intermediate steps remain internal; its return value becomes the contract for the caller.

A conversation process coordinates user-facing work. It collects slots, applies policies, invokes actions through activities, and decides when to ask, confirm, or display information.

Slots are typed values collected during a conversation. Resolvers translate natural-language selections into allowed values or stable business objects such as a system ID.

Each execution scope exposes a specific set of runtime values. Input mappings, output mappings, and compound action returns move selected data across those boundaries.

Course Map

Complete the course in order the first time. Return to individual modules later as an architecture reference.

1. Design the Outcome and Trigger

Start from the business outcome, identify the execution identity, and choose a conversational or system trigger.

2. Configure the Connector

Translate the downstream system’s permission and authentication model into a reusable connection.

3. Build Focused Actions

Create single-purpose HTTP actions with typed inputs, test values, request fields, and concise response schemas.

4. Map Data and Context

Learn what data exists in each scope and when to use Mustache, Data Mapper, DSL, or Python.

5. Collect Slots and Resolve Values

Design typed conversational inputs, deterministic validation, inference policies, and static or dynamic resolvers.

6. Compose the Workflow

Separate user-facing orchestration from backend sequences and shape the output that crosses each boundary.

7. Publish and Trigger the Plugin

Package the capability, write retrieval metadata, configure launch access, and add conversational or system triggers.

8. PurpleSuite Build Reference

Review the completed architecture, compare every asset with the reference build, and finish any remaining checkpoints.

9. Test and Operate

Validate components, context boundaries, trigger behavior, permissions, failure paths, and production logs.

Before You Begin

You should have:

  • Access to Agent Studio with permission to create connectors, actions, processes, and plugins.
  • Access to the downstream system’s API documentation and an approved test account.
  • A PurpleSuite instance for the build-along exercises.
  • A non-production environment and test data for any write operation.
Protect Credentials and Production Data

Do not paste API tokens into plugin descriptions, slot descriptions, example utterances, URLs, or screenshots. Store credentials in a connector. Test mutations only against approved non-production data.

Continue

Start with Design the Outcome and Trigger.