1. Architecting Plugins

Why Proper Architecture Matters

Building plugins in Agent Studio at scale, think of hundreds deployed enterprise-wide, demands thoughtful design. Poor architecture risks silos (isolated components that don't share), security gaps (leaky data flows), and brittle plugins (ones that break under load or changes). In contrast, solid architecture drives reusability (e.g., a shared HR connector across plugins), streamlines maintenance, and helps the Agentic Reasoning Engine better interpret your high-level specs for reliable, context-aware behaviors. This approach, rooted in the platform's design philosophy, lets you focus on what your plugin achieves (e.g., seamless PTO checks) rather than low-level details like LLM tuning.

Walk through a simple 5-step flow to architect any plugin. Using a bottom-up approach, starting with purpose and building to launch to your users.

Recommended 5-step Flow

1. Define Plugin Purpose
2. Define Core Components
3. Build Your Process/Flow
4. Configure The Triggers
5. Link the Flow and Launch

flowchart TD
    A[Define Purpose<br>e.g., PTO Check] --> B[Core Components<br>Actions + Inputs]
    B --> C[Build Process<br>Chain Logic]
    C --> D[Set Trigger<br>Conversational or System]
    D --> E[Link & Launch<br>]
    style A fill:#e1f5fe
    style E fill:#c8e6c9

This sequence empowers quick prototyping while ensuring robust, reusable results.

1.1 Define Plugin Purpose

Start here to ground your plugin in real value. Outline the business problem it solves, who it serves, and the desired user experience. This step ensures your design aligns with outcomes, not just tech. Focus on the end-to-end flow: how users (or systems) interact and what success looks like.

Key Questions to Answer

• Business Problem: What gap does this plugin fill? (For example, manual PTO checks wasting HR time.)
• End Users: Who benefits? (For example, employees querying balances; managers approving requests.)
• UX Journey: What flow feels natural? Consider if it's a quick response or guided steps. Map it in the Chat Designer.

Example: PTO Balance Checker (Reactive Flow)

For a conversational plugin, map a simple query like: "Do I have enough PTO to take off a week in November?" The assistant fetches the balance and responds: "You have 12 days left. Yes, that's enough for a week off in November."

flowchart TD
    A[User Query] --> B[Assistant: Fetch Balance<br>via HR API]
    B --> C[Calculate Availability<br>e.g., 12 days > 5 needed]
    C --> D[Response]
    style A fill:#fff3e0
    style D fill:#e8f5e8

Example: PTO Approval (Proactive Flow)

For an ambient plugin, trigger on HR events (e.g., new request submitted). Run in background, then notify for approval.

flowchart TD
    A[Event Trigger:<br>HR Request Submitted] --> B[Background: Validate Policy<br>& Fetch Approver]
    B --> C[Notify Approver:<br>]
    C --> D{Approve/Deny?}
    D -->|Approve| E[Update Systems<br>]
    D -->|Deny| F[Notify Requester<br>]
    style A fill:#f3e5f5
    style E fill:#e8f5e8
    style F fill:#ffebee

Example: Unmoderated Ambient Agent Sync (No Human-in-the-Loop)

For fully unmoderated ambient agent plugins (e.g., nightly PTO accrual sync), no notifications needed, just ensure it runs silently and logs outcomes for audits.

flowchart TD
    A[Scheduled Trigger:<br>Nightly Cron Job] --> B[Background: Fetch Accruals<br>from HR API]
    B --> C[Update Database<br>e.g., Add 1.5 days per employee]
    C --> D[Log Success/Failure]
    style A fill:#f3e5f5
    style D fill:#e8f5e8

📘

Tips

Keep it outcome-focused

• For user-involved flows, prioritize natural presentation (e.g., summaries over raw data).
• For ambient agents with human touchpoints, emphasize clear notifications and CTAs (e.g., approve buttons).
• For unmoderated ambient agents, align on silent efficiencies like reduced manual syncs, with logging for monitoring.

Sucess Criteria

• UX journey sketched in Chat Designer (3-5 steps visualized).
• Agent type identified: Conversational (user-driven) or Ambient (background/event-driven).
• 1-2 sentence purpose statement written (e.g., "Solves PTO queries for employees via instant checks").
• End users and business problem documented (e.g., "Employees save 10 min/query; HR reduces emails").

Now that you understand the UX and purpose, it's time to think about the components needed to build the plugin.

1.2 Define Core Components

With your plugin's purpose clear, identify and prototype the building blocks. This bottom-up approach starts with connections and actions, then layers on orchestration, inputs, and trigger prep. It promotes reusability and aligns with the platform's component-based design.

Follow this sequence to define and test your components:

1. Check or Create Connectors: Review if an existing connector fits. If not, build a custom one to authenticate and handle system access. This ensures secure, reusable links to external services.
2. Identify APIs and Build HTTP Actions: List required endpoints (e.g., GET /pto-balance). Verify the system exposes them with the right permissions. Create HTTP Actions to call these and test each for success (e.g., 200 OK response with sample data).
3. Plan Orchestration Layer: Choose based on agent type from Step 1: Conversational Processfor user-driven flows or Compound Action for system-driven. Map how actions connect: Are they sequential with dependencies (e.g., Action 1 fetches employee ID from query, Action 2 uses it to pull PTO data)? Or independent (e.g., parallel checks for vacation vs. sick time)?
4. Configure Inputs: For conversational agents, add slots to collect user data mid-flow (e.g., prompt "Vacation or sick PTO?" to set a filter). For ambient agents, map inputs from event payloads (e.g., webhook sends employee ID and request details).
5. Prep Plugin Trigger Type:Build on Step 1's decision:
   1. Conversational: for user queries.
   2. System: You can specify the type of trigger: webhook (real-time pushes), scheduled (e.g., daily syncs), or polling (periodic checks for changes in an external system).

PTO Example

For a conversation PTO lookup plugin:

• Connector: Workday
• Actions: HTTP Action for GET /pto-balance/{user_id}?type={pto_type}
• Orchestration: Conversational Process
• Inputs: Slot pto_type for "vacation/sick" pto type
• Trigger: Conversational

flowchart TD
    A[Connectors<br>Check/Create] --> B[HTTP Actions<br>Map APIs & Test 200 OK]
    B --> C[Orchestration Plan<br>Conversational or Compound Action?]
    C --> D[Inputs<br>Slots for User Data<br>Input Arguments for System Data]
    D --> E[Triggers<br>Conversational vs. System]
    style A fill:#e1f5fe
    style E fill:#c8e6c9

📘

Tips

• Prototype one action at a time to catch API gaps early.
• Create connectors that are reusable across plugins, making sure actions are also generic but dynamic

Success Criteria

• Connectors ready
• HTTP Actions created and tested individually
• Inputs identified
• Orchestration type identified

Your components are now solid Lego blocks. Next assemble them into a cohesive process or flow.

1.3 Build Your Process / Flow

Now that your components are prototyped, orchestrate them into a cohesive process. This layer adds the logic that drives your plugin, whether you have single action for simple use cases or a sequenced flow of steps for complex use cases.

Core Build Patterns

Add your actions to the flow in the order you expect the calls to go. Start small, a lone action suffices for straightforward tasks like a direct PTO fetch. For complex cases, chain them together and add decision logic.

In conversational processes, you chain activities and decision blocks together. Add action activities to fetch, content activities for polished outputs , decision policies for if-then paths, and early exits/continue blocks to control the execution of the process.

Compound actions mirror the functionalities of a conversational process but is built-in with more capabilities such as the ability to loop through a batch of sequential requests or run through multiple actions in parallel.

Hybrid Calls

While conversational processes and compound actions get executed in different context-layers, you are still able to call them from each other. Call a compound from a conversational process via an action activity (treat it as any action). Or, from compound, use the notify expression to send a message to user allowing them to kick off a conversational flow.

For example, when a finance system generates an approval request, it can trigger a powerful automated workflow. First, a webhook is sent to a compound action that notifies the manager. The manager receives an interactive message with a button that launches a conversational process. This allows them to instantly view the request's details, discuss it if necessary, and then approve or reject it directly within the conversation.

Build Sequence

flowchart TD
    A[Choose Type:<br>Conversational or Compound] --> B[Add Actions<br>Single or Chain together]
    B --> C[Layer Controls<br>Decisions, Loops]
    C --> D[Add Hybrids if Needed<br>e.g., Notify Expression]
    style A fill:#e1f5fe

Success criteria

• Orchestration created (conversational or compound) with integrated actions.
• Controls applied minimally (e.g., decisions/loops as needed).

Your process will now drive the plugin, now we have to set the corresponding triggers that will spark the plugin into action.

1.4 Configure The Triggers

With your orchestration layer built, define how the plugin activates. Triggers bridge your flow to real-world events, ensuring it runs at the right moment. Based on your plugin's purpose and agent type, conversational for user queries or ambient for background tasks. Select the type that matches your plugin's journey, reactive for on-demand or proactive for automated.

Conversational Triggers (User-Driven)

For conversational processes, choose the "conversational" trigger type. Agent Studio auto-generates example utterances (e.g., "Check my PTO balance") based on your plugin's name and description. Refine these to cover natural variations. Tip: Set a clear name/description early.

System Triggers (Event-Driven)

For compound actions or background flows, select "system" trigger. Pick from two subtypes:

• Webhooks: Ideal for real-time external events (e.g., HR system pushes a new PTO request). Create a listener in Agent Studio and link it to your plugin, and add filters for events your plugin cares about. Filters route relevant payloads to your plugin while sharing the listener across other plugins.
• Schedules: For periodic runs from Agent Studio. Choose:
  • Cron: For custom patterns (e.g., every Friday at 5 PM).
  • Interval: For repeats (e.g., every 6 hours).
  • Calendar: For one-offs (e.g., end-of-month on the 30th at 10 AM).

PTO Example

• Conversational: Utterances like "How much PTO do I have?" trigger the plugin to fetch PTO balance information.
• Ambient webhook: HR event "request-approved" filters to update user calendars when a PTO request is approved.

Build Sequence

flowchart TD
    A[From Step 1: Agent Type?] --> B{Conversational<br>User-Driven?}
    B -->|Yes| C[Select Conversational<br>Refine Auto-Utterances]
    B -->|No| D[System Trigger<br>Webhook or Schedule?]
    D -->|Real-Time External| E[Webhook: Create Listener<br>Add Filters]
    D -->|Periodic Internal| F[Schedule: Cron/Interval/Calendar<br>Set Cadence]
    C --> G[Attach Process & Test]
    E --> G
    F --> G
    style A fill:#e1f5fe
    style G fill:#c8e6c9

Triggers now activate your plugin. Let's now link your flow to the plugin

1.5 Link the Flow and Launch

Your plugin is nearly ready, now link the orchestrated process from Step 1.3 to the trigger from Step 1.4. This final assembly wraps your components into a production-ready plugin. Set launch rules like permissions or scopes to control access of who can trigger the plugin.

Linking for Conversational Triggers

Select the conversational trigger type and attach your conversational process as the body. The platform handles the rest: User utterances from Step 1.4 cue the plugin to execute the flow.

Linking for System Triggers

Choose the system trigger type and set your compound action as the body. Here, add an input mapping to pass specific webhook fields that your flow cares about. This empowers precise data passthrough without overload. For schedules, mapping is optional since no external payload arrives.

📘

Note: Security for Ambient Agents

Ambient agents run in the background and are not constrained by launch rules for user permissions.

PTO Example

• Conversational: Body = PTO Process
• System Webhook: Map requestId from payload to compound action for approval update

Build Sequence

flowchart TD
    A[From Step 4: Trigger Type?] --> B{Conversational?}
    B -->|Yes| C[Attach Process as Body<br>No Mapping Needed]
    B -->|No| D[System: Attach Compound as Body<br>Map Webhook Fields via Mapper]
    C --> E[Set Launch Rules<br>e.g., Permissions, Scopes]
    D --> E
    E --> F[Validate & Publish<br>Simulate Full Run]
    style A fill:#e1f5fe
    style F fill:#c8e6c9

Success criteria

• Process attached as plugin body (conversational or compound).
• Input mapping configured for system triggers (if webhook).
• Launch rules set

This completes the architectural blueprint for your plugin. The modular design promotes reusability, allowing easy adaptation for similar plugin use cases.

2. Naming Conventions and Patterns

All resource names in Agent Studio must adhere to these foundational guidelines to ensure compatibility, searchability, and collaboration across workspaces.

Global Rules Summary

• Start with a letter (a-z, A-Z).
• Contain only letters (a-z, A-Z) and numbers (0-9).
• Use underscores (_) instead of spaces or hyphens.
• Maximum length of 64 characters.
• No special characters (e.g., @, #, $, %) allowed.

Core Rules

The standard format for most resources follows a Camel_Snake_Case structure: [system optional]_Verb_Noun_[Type]. The system prefix (e.g., "Salesforce") is optional but recommended for integrations. This format promotes clarity and reusability.

• Casing and Structure: Use PascalCase (capitalized words) separated by underscores for Camel_Snake_Case, ensuring each word is descriptive (e.g., Verb for action, Noun for resource).
• Prefixes and Suffixes: Personal prefix for ownership (e.g., "John_Doe"); optional system for context; type suffix (e.g., "_Action", "_Connector") for categorization.

Examples Across Components

This subsection illustrates the Camel_Snake_Case format across key components, with propagation notes for how names flow (e.g., from Action to Process).

Common Pitfalls

• Overly Generic Names: Vague terms like Get_Data_Action hinder searches; fix with specifics (e.g., Salesforce_Get_User_Pto_Action).
• Missing Suffixes: Omitting "_Action" or "_Process" confuses categorization; fix by always appending type for quick identification in libraries.