- Notifications
You must be signed in to change notification settings - Fork1
License
salesforce/AgentforceMobileSDK-Android
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
The Agentforce Mobile SDK empowers you to integrate Salesforce's feature-rich, trusted AI platform directly into your native iOS and Android mobile applications. By leveraging the Agentforce Mobile SDK, you can deliver cutting-edge, intelligent, and conversational AI experiences to your mobile users, enhancing engagement and providing seamless access to information and actions.
Agentforce is Salesforce's platform for building and deploying trusted AI agents. These agents can understand user requests, access relevant data, perform actions across Salesforce and external systems, and generate helpful, conversational responses. The Agentforce Mobile SDK acts as the bridge, allowing your mobile app to communicate directly with these sophisticated agents, bringing the power of generative AI and automated workflows to your users' fingertips.
Integrating the Agentforce Mobile SDK into your app offers several key advantages. It allows you to deliver advanced AI experiences that go beyond simple chatbots, providing users with truly agentic capabilities for complex task completion, personalized interactions, and access to generative AI features within your app's context.
The SDK offers flexible integration options to suit your needs:
- Full UI Experience: Get up and running quickly by using the SDK's pre-built, customizable chat interface. This provides a rich, out-of-the-box conversational experience supporting text, voice, and multimodal inputs with minimal coding effort.
- Headless Integration: For ultimate control, use the headless SDK to power your own custom user interface or to drive automated, agent-led processes in the background. You manage the conversational state and UI, while Agentforce handles the complex AI logic. For more information go toAgentforceService
We suggest starting with the Full UI Experience unless you need more granular control over the interface.
- Networking: A robust networking layer for handling both communication with the Agentforce platform and streaming responses.
- Conversational Intelligence: Sophisticated Natural Language Understanding (NLU) to process user requests via text or voice.
- Salesforce Actions: Execute actions within Salesforce, such as creating records, updating fields, and running Apex classes, directly from the conversation.
- Customizable UI: When using the Full UI experience, you can customize the appearance of the chat interface to match your app's branding.
- Extensible Service Protocols: The SDK defines a set of protocols for core services like navigation, caching, and logging, which you implement using your app's native infrastructure.
Before you begin integrating the Agentforce Mobile SDK, you must first configure an agent within your Salesforce organization.
- Create and Configure an Agent: You will need to build and configure an agent using the tools available in your Salesforce org. This includes defining its capabilities, persona, and connecting it to any necessary Salesforce data or actions.
- Obtain Agent and Org IDs: Once configured, you will need to retrieve the
Agent IDand theSalesforce Org ID. These unique identifiers are required to initialize the SDK and route requests to the correct agent in the correct organization.- You can find the Agent ID in the URL of the Agent Details page. When you select your agent from Setup, use the 18-character ID at the end of the URL. For example, when viewing this URL,
https://mydomain.salesforce.com/lightning/setup/EinsteinCopilot/0XxSB000000IPCr0AO/edit, the agent ID is0XxSB000000IPCr0AO. - You can find the Org ID from the Company Information page in Setup.
- You can find the Agent ID in the URL of the Agent Details page. When you select your agent from Setup, use the 18-character ID at the end of the URL. For example, when viewing this URL,
More documentation on configuring your orgs for Agentforce are available atdeveloper.salesforce.com
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 (interfaces) 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 interfaces:
AgentforceSDK Interfaces:
- 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.
Salesforce Mobile Interfaces:
These are described in more detail inSalesforce Mobile Interfaces
- SalesforceNetwork.Network: Provides the SDK with the ability to make authenticated network calls to Salesforce. Your implementation will handle the underlying networking logic, leveraging your app's existing network stack, and will be responsible for attaching the necessary authentication tokens to each request.
- SalesforceNavigation.Navigation: Handles navigation requests from the agent. For example, if the agent provides a link to a specific record, this interface allows your app to intercept that request and navigate the user to the appropriate screen within your native application.
- SalesforceLogging.Logger: Allows the SDK to pipe its internal logs into your application's logging system for easier debugging and monitoring.
By implementing these interfaces, you provide the "scaffolding" that the Agentforce SDK builds upon, ensuring seamless integration with your app's existing ecosystem.
This guide provides the steps to integrate the Agentforce Mobile SDK into 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.
In your top-levelsettings.gradle.kts file, add the Salesforce Maven URL:
// settings.gradle.ktsdependencyResolutionManagement { repositories { google() mavenCentral() maven { url= uri("https://jitpack.io") } maven { url= uri("https://opensource.salesforce.com/AgentforceMobileSDK-Android/agentforce-sdk-repository") } maven { url= uri("https://s3.amazonaws.com/salesforce-async-messaging-experimental/public/android") } }}
In your app-levelbuild.gradle.kts file, add the dependencies for the integration path you choose. Theagentforcesdk artifact is for the Full UI experience, whileagentforce-service is for the Headless approach.
plugins { id("com.android.application") id("kotlin-android") id("kotlin-kapt") id("kotlinx-serialization")}// app/build.gradle.ktsdependencies {// Agentforce SDK Dependencies api("com.salesforce.android.agentforcesdk:agentforce-sdk:14.0.0")}
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.
importcom.salesforce.android.mobile.interfaces.network.Networkimportcom.salesforce.android.mobile.interfaces.network.NetworkRequestimportcom.salesforce.android.mobile.interfaces.network.NetworkResponseimportkotlinx.coroutines.Dispatchersimportkotlinx.coroutines.withContextimportokhttp3.MediaType.Companion.toMediaTypeimportokhttp3.OkHttpClientimportokhttp3.Requestimportokhttp3.RequestBody.Companion.toRequestBodyclassMyAppNetwork(privatevalokHttpClient:OkHttpClient) : Network {overridesuspendfunperform(request:NetworkRequest):NetworkResponse {return withContext(Dispatchers.IO) {val okHttpRequest=Request.Builder().apply { url(request.path) request.headers.forEach { (key, value)-> addHeader(key, value) }when (request.method) {NetworkRequest.Method.POST-> {val mediaType= request.contentType?.toMediaType()?:"application/json".toMediaType() post(request.body?.toRequestBody(mediaType)) }NetworkRequest.Method.GET-> get()NetworkRequest.Method.PUT-> {val mediaType= request.contentType?.toMediaType()?:"application/json".toMediaType() put(request.body?.toRequestBody(mediaType)) }NetworkRequest.Method.DELETE-> delete()else->throwIllegalArgumentException("Unsupported HTTP method:${request.method}") } }.build()val response= okHttpClient.newCall(okHttpRequest).execute() response.use {// Properly close the responseNetworkResponse( body= it.body?.string()?.toByteArray(), statusCode= it.code, headers= it.headers.toMap() ) } } }}
importcom.salesforce.android.agentforceservice.AgentforceAuthCredentialProviderimportcom.salesforce.android.agentforceservice.AgentforceAuthCredentialsimportcom.salesforce.android.mobile.interfaces.logging.LoggerclassMyAppCredentialProvider(privatevaluserSession:UserSession,privatevallogger:Logger? =null) : AgentforceAuthCredentialProvider {overridefungetAuthCredentials():AgentforceAuthCredentials {returntry {val token= userSession.getAuthToken()if (token.isBlank()) { logger?.e("Auth token is empty")throwIllegalStateException("Authentication token is empty") }AgentforceAuthCredentials( authToken= token, orgId= userSession.getOrgId(), userId= userSession.getUserId() ) }catch (e:Exception) { logger?.e("Failed to fetch auth credentials", e)throwIllegalStateException("Failed to fetch authentication credentials", e) } }}
This approach is the fastest way to get a complete, out-of-the-box chat interface running in your app. TheAgentforceClient manages the session and provides aAgentforceLauncherContainer Composable that presents the chat UI.
TheAgentforceConfiguration object holds the essential settings for connecting to your agent. You'll need to use the builder pattern to create the configuration.
importcom.salesforce.android.agentforcesdkimpl.configuration.AgentforceConfigurationimportcom.salesforce.android.agentforceservice.AgentforceAuthCredentialProviderimportcom.salesforce.android.agentforceservice.AgentforceInstrumentationHandlerimportcom.salesforce.android.mobile.interfaces.logging.Loggerimportcom.salesforce.android.mobile.interfaces.network.Networkimportcom.salesforce.android.mobile.interfaces.navigation.Navigation// First, create your implementations of the required interfacesval authCredentialProvider=MyAppCredentialProvider(userSession)val network=MyAppNetwork(okHttpClient)val logger=MyAppLogger()// Your implementation of Loggerval navigation=MyAppNavigation()// Your implementation of Navigation// Then create the configuration using the builderval agentforceConfig=AgentforceConfiguration.builder(authCredentialProvider) .setSalesforceDomain("https://your-domain.my.salesforce.com") .setAgentId("YOUR_AGENT_ID") .setNetwork(network) .setLogger(logger) .setNavigation(navigation)// Optional configurations .setInstrumentationHandler(myInstrumentationHandler)// Optional: for analytics .setViewProvider(myViewProvider)// Optional: for custom UI components .build()
The configuration requires several mandatory components:
authCredentialProvider: Your implementation ofAgentforceAuthCredentialProvidersalesforceDomain: Your Salesforce instance URLagentId: The ID of your configured agentnetwork: Your implementation of the Network interfacelogger: Your implementation of the Logger interfacenavigation: Your implementation of the Navigation interface
Optional components include:
instrumentationHandler: For analytics and telemetryviewProvider: For customizing UI componentsfeatureFlagSettings: For enabling/disabling specific featuresisVoiceModeEnabled: For voice interaction capabilitiescameraUriProvider: For handling image uploadsonboardingManager: For managing user onboardingvoiceManaging: For voice interaction managementreadbackManaging: For text-to-speech capabilitiesdelegate: For UI customizationconnectionInfo: For connection settingsdataProvider: For custom data sourcesuser: For user informationpermission: For permission handling
InstantiateAgentforceClient and add theAgentforceLauncherContainer to your Composable UI.
Create and retain an instance ofAgentforceClient. It's best to hold this in a lifecycle-aware component, like aViewModel, to ensure the conversation state persists across configuration changes.
importandroidx.lifecycle.ViewModelimportcom.salesforce.android.agentforcesdkimpl.AgentforceClientimportcom.salesforce.android.agentforceservice.AgentforceServiceProviderclassMyViewModel :ViewModel() {// Retain the client in a ViewModelval agentforceClient:AgentforceClientinit {// Assume you have access to your config and interface implementationsval serviceProvider=AgentforceServiceProvider( network=MyAppNetwork(okHttpClient),// Your implementation credentialProvider=MyAppCredentialProvider(userSession)// Your implementation// Pass optional implementations here (logger, delegate, etc.) ) agentforceClient=AgentforceClient( configuration= agentforceConfig,// Your config from the previous step serviceProvider= serviceProvider ) }}
Use theAgentforceLauncherContainer Composable in your screen. It displays a Floating Action Button (FAB) that, when tapped, presents the full chat container.
importandroidx.compose.runtime.Composableimportcom.salesforce.android.agentforcesdk.ui.AgentforceLauncherContainerimportandroidx.lifecycle.viewmodel.compose.viewModel@ComposablefunMyScreen(viewModel:MyViewModel = viewModel()) {// ... Your existing screen content (e.g., inside a Scaffold)// Add the Agentforce LauncherAgentforceLauncherContainer(client= viewModel.agentforceClient)}
Once you have initialized theAgentforceClient, you can start a conversation with an agent using thestartAgentforceConversation method.
// Start the conversationagentforceClient.startAgentforceConversation()// Option 1: Get the conversation session using fetchAgentforceSessionval session= agentforceClient.fetchAgentforceSession(YOUR_AGENT_ID)// Option 2: Create a new AgentforceConversation objectval conversation=AgentforceConversation( configuration= configuration, conversationService= agentforceClient.conversationService)
Both approaches start a conversation and provide access to anAgentforceConversation 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 theAgentforceConversationContainer Composable. This Composable provides the complete chat interface that you can integrate into your app.
First, create anAgentforceConversation object:
// Create the conversation objectval conversation=AgentforceConversation( configuration= configuration, conversationService= agentforceClient.conversationService)
Then use theAgentforceConversationContainer Composable:
importandroidx.compose.runtime.Composableimportcom.salesforce.android.agentforcesdkimpl.AgentforceConversation@ComposablefunMyChatScreen(conversation:AgentforceConversation,agentforceClient:AgentforceClient) { agentforceClient.AgentforceConversationContainer( conversation= conversation, onClose= {// Handle chat view close } )}
TheAgentforceConversationContainer Composable takes the following parameters:
conversation: TheAgentforceConversationobject that you createdonClose: A lambda that will be called when the user closes the chat view
You can also use theAgentforceLauncherContainer for a floating action button approach:
@ComposablefunMyScreen() {// Your existing screen content// Add the Agentforce Launcher (FAB)AgentforceLauncherContainer(client= agentforceClient)}
To send a message to the agent programmatically, you can use a method likesendUtterance on yourAgentforceConversation object:
// Example: Sending a message with an optional attachmentconversation.sendUtterance( utterance="Hello, world!", attachment=null// or provide an AgentforceAttachment object)
To receive messages from the agent, you can use theconversationManager property on theAgentforceConversation object and itssendMessage method which returns aReceiveChannel<AgentforceComponent>:
// Example: Using conversationManager to send and receive messagesval responseChannel= conversation.conversationManager.sendMessage( inputRepresentation=ConversationInputRepresentation("Hello, world!"), agentforceAttachment=null,// Optional attachment file=null// Optional file)
To handle UI events, you can implement theAgentforceUIDelegate 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.
classYourActivity :AgentforceUIDelegate {overridesuspendfunmodifyUtteranceBeforeSending(utterance:AgentforceUtterance):AgentforceUtterance {// Modify the utterance if neededreturn utterance }overridefundidSendUtterance(utterance:AgentforceUtterance) {// Handle sent utterance }overridefunuserDidSwitchAgents(newConversation:AgentforceConversation) {// Handle agent switch }}
This approach is for developers who want to build a completely custom UI or run agent interactions in the background. TheAgentforceService handles the communication and state, emitting events via Kotlin Flows that your app uses to update its own UI or trigger logic.
Use theAgentforceServiceProvider to create anAgentforceService instance for a specific agent.
importcom.salesforce.android.agentforceservice.AgentforceServiceProviderimportcom.salesforce.android.agentforceservice.AgentforceServiceimportcom.salesforce.android.agentforceservice.AgentforceServerSentEventsimportcom.salesforce.android.mobile.interfaces.logging.Loggerimportcom.salesforce.android.mobile.interfaces.network.Networkimportjava.util.Locale// Create the service provider with required dependenciesval serviceProvider=AgentforceServiceProvider( configurationLocale=Locale.getDefault(),// Optional: Your app's locale domain="https://your-domain.my.salesforce.com",// Your Salesforce domain network=MyAppNetwork(okHttpClient),// Your Network implementation credentialProvider=MyAppCredentialProvider(userSession),// Your credential provider instrumentationHandler= myInstrumentationHandler,// Optional: For analytics logger= myLogger// Optional: For logging)// Get the service for your specific agentval agentId="YOUR_AGENT_ID"val agentforceService:AgentforceService= serviceProvider.getAgentforceService(agentId)
Start a session by callingstartSession() and then usesendMessageAndStartStreaming() to send messages and receive streaming responses. You'll need to handle the streaming responses in your UI.
importandroidx.lifecycle.ViewModelimportandroidx.lifecycle.viewModelScopeimportcom.salesforce.android.agentforceservice.AgentforceServiceimportcom.salesforce.android.agentforceservice.conversationservice.data.AgentforceResponseimportcom.salesforce.android.agentforceservice.conversationservice.data.StreamingCapabilitiesimportcom.salesforce.android.agentforceservice.conversationservice.data.StreamingRequestimportcom.salesforce.android.agentforceservice.conversationservice.data.ChunkTypeimportkotlinx.coroutines.flow.MutableStateFlowimportkotlinx.coroutines.flow.asStateFlowimportkotlinx.coroutines.launchclassChatViewModel(privatevalagentforceService:AgentforceService) : ViewModel() {privatevar currentSessionId:String?=nullprivateval_messages=MutableStateFlow<List<ChatMessage>>(emptyList())val messages=_messages.asStateFlow()funstartSession() { viewModelScope.launch {try {// Configure streaming capabilitiesval streamingCapabilities=StreamingCapabilities( chunkTypes=mutableListOf(ChunkType.TEXT.type).apply {if (AgentforceClient.agentforceFeatureFlagSettings.enableLightningTypeStreaming) { add(ChunkType.LIGHTNING.type) } } )// Start the sessionval session= agentforceService.startSession(streamingCapabilities) currentSessionId= session.sessionId// Handle initial messages if any session.messages.forEach { message-> processMessage(message) } }catch (e:Exception) {// Handle session start error } } }funsendMessage(text:String) {val sessionId= currentSessionId?:return viewModelScope.launch {try {// Create streaming requestval streamingRequest=StreamingRequest( message= text,// Add any additional request parameters )// Send message and start streamingval responseChannel= agentforceService.sendMessageAndStartStreaming( sessionId= sessionId, inputRepresentation= streamingRequest )// Process streaming responsesfor (responsein responseChannel) { processMessage(response.message) } }catch (e:Exception) {// Handle message sending error } } }privatefunprocessMessage(message:AgentforceMessage) {// Process different message typeswhen (message.type) {"progressindicator"-> {// Handle progress indicator }"inform"-> {// Handle informational message }"inquire"-> {// Handle inquiry message }// Handle other message types... } }overridefunonCleared() {super.onCleared()// Cancel any ongoing streaming agentforceService.cancelCurrentStreaming() }}
The session flow works as follows:
- Call
startSession()to initialize a new session with the agent - The session response includes a
sessionIdand 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 processinginform: Contains information or responses from the agentinquire: Contains questions or requests from the agent
- Use
cancelCurrentStreaming()to stop any ongoing streaming when needed
TheAgentforceViewProvider 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 theAgentforceViewProvider interface and implement the following methods:
canHandle(definition: String): This method should returntrueif you want to provide a custom view for the given component definition, andfalseotherwise.GetView(modifier: Modifier, view: AgentforceComponent): This method should return your custom Composable for the given component. Theviewparameter contains the component data and definition.
Here is an example of how you can provide a custom view for theAF_RICH_TEXT component:
importandroidx.compose.runtime.Composableimportandroidx.compose.ui.Modifierimportandroidx.compose.ui.text.font.FontWeightimportandroidx.compose.ui.unit.spimportcom.salesforce.android.agentforcesdk.components.models.AgentforceComponentimportcom.salesforce.android.agentforcesdk.components.models.AgentforceViewProviderclassCustomViewProvider :AgentforceViewProvider {overridefuncanHandle(definition:String):Boolean {return definition=="AF_RICH_TEXT" } @ComposableoverridefunGetView(modifier:Modifier,view:AgentforceComponent) {// Access component data from the view parameterval value= view.data["value"]as?String?:"" androidx.compose.material3.Text( text= value, fontSize=16.sp, fontWeight=FontWeight.Normal, modifier= modifier ) }}
Once you have created your custom view provider, you can register it with aViewProviderService and pass it to theAgentforceConfiguration when you initialize it:
// Create and register your view providerval viewProviderService=DemoViewProviderServiceImpl()viewProviderService.register(CustomViewProvider())val agentforceConfig=AgentforceConfiguration.builder(authCredentialProvider) .setSalesforceDomain("https://your-domain.my.salesforce.com") .setAgentId("YOUR_AGENT_ID") .setNetwork(network) .setLogger(logger) .setNavigation(navigation) .setViewProvider(viewProviderService)// Add your view provider service .build()
The Agentforce SDK provides a detailed instrumentation framework for monitoring performance and usage. To receive instrumentation events, you can provide an implementation of theAgentforceInstrumentationHandler interface in yourAgentforceConfiguration.
importcom.salesforce.android.agentforceservice.AgentforceInstrumentationHandlerimportcom.salesforce.android.agentforceservice.AgentforceInstrumentationEventimportcom.salesforce.android.mobile.interfaces.logging.LoggerclassMyInstrumentationHandler(privatevallogger:Logger? =null) : AgentforceInstrumentationHandler {overridefunrecordEvent(event:AgentforceInstrumentationEvent) {// Handle instrumentation events logger?.d("Instrumentation event:$event")// You can send events to your analytics service here// For example, using Firebase Analytics, Mixpanel, etc.when (event) {isAgentforceInstrumentationEvent.MessageSent-> {// Track message sent events logger?.d("Message sent:${event.messageType}") }isAgentforceInstrumentationEvent.MessageReceived-> {// Track message received events logger?.d("Message received:${event.messageType}") }isAgentforceInstrumentationEvent.SessionStarted-> {// Track session start events logger?.d("Session started:${event.sessionId}") }isAgentforceInstrumentationEvent.SessionEnded-> {// Track session end events logger?.d("Session ended:${event.sessionId}") }isAgentforceInstrumentationEvent.Error-> {// Track error events logger?.e("Agentforce error:${event.error}") }else-> {// Handle other event types logger?.d("Other event:$event") } } }}
Include the instrumentation handler in your configuration:
val agentforceConfig=AgentforceConfiguration.builder(authCredentialProvider) .setSalesforceDomain("https://your-domain.my.salesforce.com") .setAgentId("YOUR_AGENT_ID") .setNetwork(network) .setLogger(logger) .setNavigation(navigation) .setInstrumentationHandler(MyInstrumentationHandler(logger))// Add your instrumentation handler .build()
For additional documentation, examples, and support:
SeeCONTRIBUTING.md
This project is licensed under the terms specified in theLICENSE.txt file.
About
Resources
License
Code of conduct
Contributing
Security policy
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.