# Invoke AgentForce Agent

## Overview

The **Invoke Agentforce Agent** interaction lets you send messages to an Agentforce AI agent directly from a Dynamic Component — passing context, capturing the response, and acting on it, all without leaving the page.

{% hint style="warning" %}

#### **You need an agent before this works**

This interaction *connects to* an existing Agentforce agent — it does not create one. You must first build and configure your agent in [Salesforce Agentforce Studio](https://trailhead.salesforce.com/content/learn/modules/agent-builder-basics). Once it's ready, come back here to wire it into your component**.**
{% endhint %}

***

## How it Works

When a user triggers the interaction (e.g., by clicking a button), your component communicates with the agent and optionally captures the response. Here's the full sequence:

{% stepper %}
{% step %}

#### **User Action**

The user interacts with the Avonni Component (e.g., clicks a button).
{% endstep %}

{% step %}

#### **Agent Invocation**

The "Invoke Agentforce Agent" interaction sends a message to the specified Agentforce agent.
{% endstep %}

{% step %}

#### **Data Passing (Optional)**

You can pass parameters to the agent to provide context or specific instructions.
{% endstep %}

{% step %}

#### **Agent Processing**

The agent processes the message using its configured topics, actions, and AI capabilities.
{% endstep %}

{% step %}

#### **Response Capture (Optional)**

The agent's response can be captured in a resource for use within your Dynamic Component.
{% endstep %}

{% step %}

#### **Post-Execution Actions (Optional)**

You can configure actions to occur after the agent responds (e.g., display a toast message on success or error)
{% endstep %}
{% endstepper %}

The only required steps are the user action and the agent invocation. Capturing the response, passing parameters, and post-execution actions are all optional — add them when your use case needs them.

***

## Configuration

Four settings control how the interaction behaves. The first two are required; the rest are optional.

<details>

<summary>Agent API Name <mark style="background-color:orange;">(Required)</mark></summary>

The unique identifier for the Agentforce agent you want to invoke. Found in Agent Builder under your agent's details. This tells Salesforce exactly which agent should handle the request.

{% hint style="info" icon="lightbulb" %}

#### To find It

**Agentforce Studio → select your agent → copy the API Name** from the agent details panel.
{% endhint %}

</details>

<details>

<summary>User Message <mark style="background-color:orange;">(Required)</mark></summary>

The prompt you're sending to the agent — the instruction that tells it what to do. This can be static text, dynamic using merge syntax, or a combination of both. **Merge syntax is the key to making messages context-aware:** wrap any variable or component attribute in `{! }` to inject its live value into the message at runtime.

<table><thead><tr><th width="178.78125">Message Type</th><th></th></tr></thead><tbody><tr><td><strong>Static</strong></td><td>"Summarize this account"</td></tr><tr><td><strong>Merge Syntax</strong></td><td>"Summarize account <em>{!Datatable1.selectedRowsKeyValue}</em>"</td></tr><tr><td><strong>Combined</strong></td><td>"You are a sales analyst. Summarize accounts: <em>{!Datatable1.selectedRowsKeyValue}</em>. Include ARR, industry, and key insights."</td></tr></tbody></table>

</details>

<details>

<summary>Parameters <mark style="background-color:blue;">(Optional)</mark></summary>

Pass structured data to the agent as named key-value pairs — separate from the main user message. Use this when your agent is configured to expect specific named inputs in Agent Builder, or when you want to pass data in a structured format rather than embedding it in the message text.

{% hint style="info" icon="lightbulb" %}

#### Naming and Mapping Parameters

Each parameter needs a name (must match what your agent expects) and a value (a static value, a component attribute, or a resource variable).
{% endhint %}

</details>

<details>

<summary>Response Resource Name <mark style="background-color:blue;">(Optional)</mark></summary>

The name of a **Text Variable** in your component where the agent's response will be stored. Once the agent replies, its answer is automatically written to this variable — making it available to display in a text component, drive visibility rules, feed into formulas, or pass to other interactions.

{% hint style="warning" %}

#### Important

If you skip this attribute, the agent still runs — but you won't be able to display or use its response. Always set this if you intend to show the agent's output to users.
{% endhint %}

</details>

***

## 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="/files/0tvV8PD1voQNHqFXuD8h" 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

{% hint style="warning" icon="square-check" %}

#### Before You Start this tutorial

**You'll need**:&#x20;

* an agent created in Agentforce Studio
* an Avonni Data Table showing Account records
* row selection (checkboxes) enabled on the table
  {% endhint %}

### 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="/files/TSQF0NmX93uc5mH0oGq3" 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 Force Studio. 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="/files/bi8LnBMCOz5q2BqnEkR2" 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**](/dynamic-components/core-concepts/component-visibility.md) 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 when they click the "Summarize Selected Accounts" button. The summary component remains hidden until there's actually content to display, keeping your interface clean
{% endstep %}
{% endstepper %}

***

### Things to keep in mind

<table><thead><tr><th width="211.8515625">Topic</th><th>Guidance</th></tr></thead><tbody><tr><td><strong>Merge syntax</strong></td><td>Use <code>{!variableName}</code> anywhere in the User Message to inject live component data. Always test with real data to confirm the merge resolves correctly</td></tr><tr><td><strong>Parameter names</strong></td><td>Must exactly match the input variable names defined in your agent's Agent Builder configuration — case-sensitive</td></tr><tr><td><strong>Response timing</strong></td><td>Agent calls can take a few seconds. Add a loading indicator or informative message so users know processing is happening</td></tr><tr><td><strong>Error handling</strong></td><td>Configure an <strong>On Error</strong> action to show a toast or message if the agent invocation fails — don't leave users with a silent failure</td></tr><tr><td><strong>Agent permissions</strong></td><td>Ensure your agent has the necessary topics, actions, and Salesforce permissions to handle the request you're sending</td></tr><tr><td><strong>No response resource</strong></td><td>If you skip the Response Resource field, the agent still runs — but the response is discarded. Only skip it for fire-and-forget scenarios where you don't need to show the output</td></tr></tbody></table>

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.avonnicomponents.com/dynamic-components/component-builder/interactions/ai-and-automation/invoke-agentforce-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.