Android Integration Guidelines for Agentforce Mobile SDK

This guide provides the steps to integrate the Agentforce Mobile SDK with your native Android application using Jetpack Compose.

Android Studio: Android Studio Meerkat 2024.3.1 or newer.
Android Gradle Plugin: Version 8.9.1.
Kotlin: Version 1.9.22 or higher.
Minimum SDK Version: API level 29 (Android 10) or higher.
Jetpack Compose: The SDK's UI components are built with Compose. Your project must be configured to use it.

Configure your top-level settings.gradle.kts file as shown:

In your app-level build.gradle.kts file, add the dependencies for the integration path you choose. The agentforcesdk artifact is for the Full UI experience, while agentforce-service is for the Headless approach.

Download the latest release artifacts from the AgentforceMobileService-Android Releases
Unzip the downloaded artifacts and place the AAR files in the libs directory of your project
The libs directory should be located at the same level as your app's build.gradle.kts file

After adding the dependencies, sync your project with the Gradle files.

The Agentforce Mobile SDK is designed for flexibility and delegates several core responsibilities to the host application. This is achieved through a set of protocols that your application must implement. This approach allows the SDK to remain lean and lets you use your existing application architecture for handling common tasks. You will need to create concrete implementations for the following:

AgentforceAuthCredentialProviding: Supplies the SDK with the authentication token (e.g., OAuth 2.0 access token) required to communicate securely with Salesforce APIs.
AgentforceInstrumentation: A handler for the SDK to emit instrumentation and telemetry data into your app's analytics system.

This approach is the fastest way to get a complete, out-of-the-box chat interface running in your app. The AgentforceClient manages the session and provides a AgentforceLauncherContainer Composable that presents the chat UI.

The AgentforceConfiguration object holds the essential settings for connecting to your agent. You'll need to use the builder pattern to create the configuration.

The configuration requires several mandatory components:

authCredentialProvider: Your implementation of AgentforceAuthCredentialProvider
salesforceDomain: Your Salesforce instance URL
agentId: The ID of your configured agent
network: Your implementation of the Network interface
logger: Your implementation of the Logger interface
navigation: Your implementation of the Navigation interface

Optional components include:

instrumentationHandler: For analytics and telemetry
viewProvider: For customizing UI components
featureFlagSettings: For enabling/disabling specific features
isVoiceModeEnabled: For voice interaction capabilities
cameraUriProvider: For handling image uploads
onboardingManager: For managing user onboarding
voiceManaging: For voice interaction management
readbackManaging: For text-to-speech capabilities
delegate: For UI customization
connectionInfo: For connection settings
dataProvider: For custom data sources
user: For user information
permission: For permission handling

Instantiate AgentforceClient and add the AgentforceLauncherContainer to your Composable UI.

Create and retain an instance of AgentforceClient. It's best to hold this in a lifecycle-aware component, like a ViewModel, to ensure the conversation state persists across configuration changes.

Use the AgentforceLauncherContainer Composable in your screen. It displays a Floating Action Button (FAB) that, when tapped, presents the full chat container.

Once you have initialized the AgentforceClient, you can start a conversation with an agent using the startAgentforceConversation method.

Both approaches start a conversation and provide access to an AgentforceConversation object, which represents a single conversation with an agent. You can use this session/conversation to interact with the agent and manage the conversation state.

To display the chat UI, you can use the AgentforceConversationContainer Composable. This Composable provides the complete chat interface that you can integrate into your app.

First, create an AgentforceConversation object:

Then use the AgentforceConversationContainer Composable:

The AgentforceConversationContainer Composable takes the following parameters:

conversation: The AgentforceConversation object that you created
onClose: A lambda that will be called when the user closes the chat view

You can also use the AgentforceLauncherContainer for a floating action button approach:

This section covers the basic use cases for integrating the Agentforce Mobile SDK into your Android app.

To send a message to the agent programmatically, you can use a method like sendUtterance on your AgentforceConversation object:

To receive messages from the agent, you can use the conversationManager property on the AgentforceConversation object and its sendMessage method which returns a ReceiveChannel<AgentforceComponent>:

To handle UI events, you can implement the AgentforceUIDelegate interface. This interface has the following methods:

modifyUtteranceBeforeSending(utterance: AgentforceUtterance): This method is called before an utterance is sent to the agent. It allows you to modify the utterance before it is sent.
didSendUtterance(utterance: AgentforceUtterance): This method is called after an utterance has been sent to the agent.
userDidSwitchAgents(newConversation: AgentforceConversation): This method is called when the user switches to a different agent.

This approach is for developers who want to build a completely custom UI or run agent interactions in the background. The AgentforceService handles the communication and state, emitting events via Kotlin Flows that your app uses to update its own UI or trigger logic.

Use the AgentforceServiceProvider to create an AgentforceService instance for a specific agent.

Start a session by calling startSession() and then use sendMessageAndStartStreaming() to send messages and receive streaming responses. You'll need to handle the streaming responses in your UI.

The session flow works as follows:

Call startSession() to initialize a new session with the agent
The session response includes a sessionId and any initial messages
Use sendMessageAndStartStreaming() to send messages and receive streaming responses
Process the streaming responses in your UI, handling different message types:
- progressindicator: Shows that the agent is processing
- inform: Contains information or responses from the agent
- inquire: Contains questions or requests from the agent
Use cancelCurrentStreaming() to stop any ongoing streaming when needed

This section covers advanced configuration and customization options for the Agentforce Mobile SDK.

The AgentforceViewProvider interface allows you to provide your own custom views for the different components that are displayed in the chat interface. This is useful if you want to replace the default implementation of a component with your own.

To provide your own views, you must create a class that implements the AgentforceViewProvider interface and implement the following methods:

canHandle(definition: String): This method should return true if you want to provide a custom view for the given component definition, and false otherwise.
GetView(modifier: Modifier, view: AgentforceComponent): This method should return your custom Composable for the given component. The view parameter contains the component data and definition.

Here is an example of how you can provide a custom view for the AF_RICH_TEXT component:

Once you have created your custom view provider, you can register it with a ViewProviderService and pass it to the AgentforceConfiguration when you initialize it:

The Agentforce SDK provides a detailed instrumentation framework for monitoring performance and usage. To receive instrumentation events, you can provide an implementation of the AgentforceInstrumentationHandler interface in your AgentforceConfiguration.

Include the instrumentation handler in your configuration: