# Invoke AgentForce Agent

## Overview

The **Invoke Agentforce Agent** interaction lets you send messages to an Agentforce agent directly from within an Avonni Dynamic Component. This provides a powerful way to integrate AI-powered assistance and intelligent automation into your user interface, enabling users to leverage agent capabilities without leaving the current page.

{% hint style="warning" %}

## Important

**Before you can use this interaction, you must first create and configure an Agentforce agent in Salesforce's Agent Builder.** This interaction is a connector between your Dynamic Component and an existing agent—it does not create or configure the agent itself
{% endhint %}

### What You Need Before Starting

1. **An Active Agentforce Agent**
   * Created in Salesforce Setup → Agent Builder
   * Fully configured with topics, actions, and instructions
   * Activated and ready to receive requests
   * Permissions are configured to access the data it needs
2. **The Agent's API Name**
   * Found in Agent Builder when viewing your agent's details
   * This is the unique identifier you'll use in the interaction configuration
   * Example: `Account_Summarizer_Agent` or `Customer_Service_Agent`

**Without an agent created in Agent Builder, this interaction will not function.** The interaction triggers an existing agent—all AI behavior, data access, and response logic must be configured in the agent itself.

### How Agent Builder and Dynamic Components Work Together

* **Agent Builder:** Where you define what the agent does, what data it can access, and how it responds
* **Dynamic Components:** Where you create the user interface that triggers the agent and displays its responses
* **This Interaction:** The bridge that connects user actions in your component to agent execution in Agent Builder

**New to Agentforce?** Learn how to create agents in [Salesforce Agent Builder Documentation](https://help.salesforce.com/). Once your agent is ready, return here to integrate it with your Dynamic Components.

### Supported Components

You can add the "Invoke Agentforce Agent" interaction to the following Avonni Dynamic Components:

* Button
* Button Group
* Button Menu
* Button Icon
* Data Table (Header Actions)
* List Item

{% hint style="warning" %}

## Important

The "Invoke Agentforce Agent" interaction is designed for programmatic agent invocations that run in the background. The agent processes your message and returns a response that you can capture and use within your Dynamic Component.
{% endhint %}

***

## How it Works

1. **User Action**: The user interacts with the component (e.g., clicks a button).
2. **Agent Invocation**: The "Invoke Agentforce Agent" interaction sends a message to the specified Agentforce agent.
3. **Data Passing (Optional)**: You can pass parameters to the agent to provide context or specific instructions.
4. **Agent Processing**: The agent processes the message using its configured topics, actions, and AI capabilities.
5. **Response Capture (Optional)**: The agent's response can be captured in a resource for use within your Dynamic Component.
6. **Post-Execution Actions (Optional)**: You can configure actions to occur after the agent responds (e.g., display a toast message on success or error).

***

## Configuration

The "Invoke Agentforce Agent" interaction connects a user action (such as clicking a button) to an Agentforce agent. When configured, it sends a message to the agent, optionally passes parameters for context, captures the agent's response, and handles success or error scenarios.

Add this interaction to any supported Avonni component through the component's properties panel under "Actions" or "Interactions." Select "Invoke Agentforce Agent" as the interaction type.

### **Agent API Name**

This identifies which Agentforce agent will process your request. Enter the API name of the agent you created in Agent Builder. This is the unique identifier that tells Salesforce which agent to invoke when the interaction triggers.

### **User Message**

This is the prompt or question you're sending to the agent. Think of it as the instruction you're giving to the AI. The message can be:

* **Static text:** A fixed message like "Summarize this account"
* **Dynamic with merge syntax:** Include variables from your component using `{!variableName}` notation. For example, `"Can you summarize this account {!combobox1.selectedItemSObject.Id}"` dynamically inserts the selected account ID into your message
* **Context-rich:** Combine static instructions with dynamic data to give the agent everything it needs

The agent receives this message and processes it according to its configured topics and actions.

### **Parameters** (Optional)

Parameters let you pass additional structured data to the agent beyond the user message. This is useful when your agent expects specific named inputs or when you need to provide context separately from the primary prompt.

For each parameter you add:

* **Name:** The parameter identifier your agent expects (defined in Agent Builder)
* **Value:** What you're passing - this can be a fixed value, a component attribute, or a resource variable

Use parameters when your agent needs structured inputs rather than just parsing a text message.

### **Response Resource Name**

This specifies where the interaction should store the agent's response. Enter the name of a text variable in your Dynamic Component. Once the agent responds, its answer is automatically saved to this variable, making it available for:

* Displaying text components
* Using formulas or conditional logic
* Triggering additional actions based on the content
* Passing to other interactions or flows

If you don't specify a resource, the agent still processes your request, but you won't be able to capture or display the response.

***

## Step-by-Step Example

**Summarizing Selected Accounts with Agentforce**

Let's build a practical example where users can select multiple accounts from a data table and get an AI-powered summary by clicking a button.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FaldGi6G6KrjbliuXVxrT%2F2025-10-26_20-30-03%20(1).gif?alt=media&#x26;token=7483ad08-af02-4c4a-8a0f-6056ebd1a387" alt=""><figcaption></figcaption></figure>

### Scenario Overview

You have an Avonni Data Table displaying a list of accounts in your Dynamic Component. Users can:

1. Check one or more accounts in the data table
2. Click a "Summarize Selected" button in the table's header actions
3. Receive an AI-generated summary of the selected accounts from an Agentforce agent

### Before You Start

**Prerequisites:**

* An Agentforce agent created and configured in Agent Builder
* An Avonni Data Table component displaying account records
* The data table is configured with row selection enabled (checkboxes visible)

### Setup Steps

{% stepper %}
{% step %}

#### **Prepare Your Data Table**

First, you'll set up the data table that displays your accounts and configure it to allow users to select records and trigger the agent. This creates the foundation for the interactive summarization feature.

1. **Add the Data Table**
   * Add an Avonni Data Table to your Dynamic Component
   * Configure it to display Account records
   * **API Name:** Note this (e.g., `Datatable1`) - you'll need it later to reference the selected rows
2. **Enable Row Selection**
   * In the data table properties, enable row selection (checkboxes)
   * This allows users to select multiple accounts they want to summarize
3. **Add a Header Action Button**
   * In the data table's **Header Actions** section
   * Add a button with a label like "Summarize Selected Accounts"
   * This button will trigger the agent invocation when clicked
     {% endstep %}

{% step %}

#### **Create a Variable to Store the Agent's Response**

Before invoking the agent, you need a place to store the response it returns. This variable will capture the AI-generated summary so you can display it to users or use it elsewhere in your component.

**Create a Text Variable**

* In your Dynamic Component resources
* **API Name:** `agentResponse` (or your preferred name)
* **Data Type:** Text
* This will store the summary returned by the agent

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FfrR3OntpI59InYebgZ8v%2F2025-10-26_20-33-08.png?alt=media&#x26;token=5f6d92fd-bdb7-4185-bfd3-0198f2adbe60" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### **Configure the "Invoke Agentforce Agent" Interaction**

Now configure what happens when users click the "Summarize Selected Accounts" button.

1. **Select Your Header Action Button**
   * Click on the button you created in Step 1
2. **Add an Interaction**
   * In the button's properties, add a new action/interaction
   * Select **"Invoke Agentforce Agent"**
3. **Configure the Agent Settings** Fill in the following fields in the interaction configuration: **Agent API Name** Enter the API name of your agent from Agent Builder. Example: `Account_Summarizer_Agent` To find your agent's API name: Go to Agent Builder → Select your agent → Copy the API Name from the agent details

**User Message:** This is the prompt you're sending to the agent. Copy and paste the template below, then customize as needed:

```
   System:
   You are a Salesforce-savvy sales analyst. Be concise and structured.

   User:
   Summarize the following Salesforce Accounts selected by the user.
   Include: # of accounts, total ARR/Annual Revenue (if present), top industries, common products, notable white space, and a 5-bullet executive summary.

   Records Ids:
   {!Datatable1.selectedRowsKeyValue}
```

**Important:** Replace `Datatable1` with your actual data table's API Name.

**What this does:**

* `{!Datatable1.selectedRowsKeyValue}` dynamically inserts the IDs of all accounts the user selected
* The agent receives these IDs and can query Salesforce for the full account details.

**Response Resource Name**

Enter: `agentResponse`

This is the variable name you created in Step 2. The agent's summary will be stored here.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FjxY4HMUvJQemVxxDY2nO%2F2025-10-26_20-34-10.png?alt=media&#x26;token=fb7a25c9-7f32-49a5-8110-7011506f7b2a" alt="" width="375"><figcaption></figcaption></figure>

***

{% endstep %}

{% step %}

#### **Display the Agent's Response**

Now that the agent interaction is configured and will store its response in the `agentResponse` variable, you need to show this summary to users. We'll add a component that displays the agent's response and only appears after the agent has returned results.

1. **Add a Display Component**
   * Add a component to show the summary (e.g., **Profile Card**, **Display Text**, or **Rich Text** component)
   * Place it in a visible location on your Dynamic Component canvas
2. **Configure the Component Content**
   * In the component's properties, find the field for displaying text content
   * Set the value to `{!agentResponse}`
   * This will display whatever the agent returns
3. **Set Component Visibility** (Optional but recommended)
   * Select your display component
   * Find [**Set Component Visibility**](https://docs.avonnicomponents.com/dynamic-components/getting-started/understanding-the-essentials/component-visibility) in the properties panel
   * Create a condition so the component only appears when there's a response to show:

```
   {!agentResponse} IS NOT NULL
```

**What this does:** The component stays hidden until the agent returns a response. Once `agentResponse` contains data, the component automatically appears with the summary.

**What you've accomplished:** Users will now see the AI-generated summary appear on screen after clicking the "Summarize Selected Accounts" button. The summary component remains hidden until there's actually content to display, keeping your interface clean
{% endstep %}
{% endstepper %}

***

### Important Considerations

* **Agent Configuration**: Ensure your Agentforce agent is correctly configured with the necessary topics, actions, and permissions to handle your requests.
* **Message Format**: Structure your user message clearly to help the agent understand the intent. Include relevant context using merge syntax.
* **Parameter Names**: If using parameters, ensure the parameter names match what your agent expects.
* **Response Handling**: Plan how you'll use the agent's response—whether to display it to users, update records, or trigger additional actions.
* **Error Handling**: Use the "On Error" action to handle any errors that might occur during agent invocation gracefully.
* **Performance**: Agent invocations may take a few seconds to process. Consider adding loading indicators or informative messages to manage user expectations.

***

### In Summary

The "Invoke Agentforce Agent" interaction is a valuable feature for adding AI-powered intelligence to your Dynamic Components. Configuration settings include specifying the agent to invoke, crafting the user message with dynamic context, passing parameters, capturing the response, and defining success and error actions
