Agentforce (Salesforce)

🚀 Agentforce Proxy Server Guide

This guide provides a comprehensive overview of the Agentforce proxy server, including environment variable configuration, GitHub push script usage, detailed setup steps, troubleshooting, and more.

🚀 Quick Start

Environment Variable Configuration

To configure environment variables, follow these steps:

1. Open the terminal.
2. Run the command: source ~/.bash_profile

GitHub Push Script Usage

To simplify the process of pushing changes to GitHub, we provide a convenient script. Follow these steps:

1. Give the script execution permissions:

   chmod +x github_push.sh
   

2. Execute the script:

   ./github_push.sh
   

The script will perform the following actions:

• Check if Git is installed on the system.
• Ensure that sensitive files (e.g., .env) are not pushed to GitHub (these files are added to .gitignore).
• Prompt the user to enter the GitHub repository URL.
• Initialize the Git repository or update the remote repository URL.
• Display the files to be committed for user confirmation.
• Automatically generate a commit message and push the changes.

📚 Documentation

Creating a Connected App

1. Log in to the Salesforce organization using an administrator account.
2. Go to Setup.
3. Enter "App Manager" in the quick search bar and click to enter.
4. Click New Connected App.
5. Fill in the basic information:
   • App Name: For example, "Agentforce MCP Integration".
   • API Name: Will be automatically filled.
   • Contact Email: Enter your email address.
6. Enable the OAuth settings option.
7. Set the callback URL to https://localhost/oauth/callback.
8. In Selected OAuth Scopes, add:
   • Manage user data (api).
   • Perform requests at any time (refresh_token, offline_access).
9. Click Save.
10. Record the Consumer Key (Client ID) on the connected app details page.
11. Click Show next to the Consumer Secret to obtain the client password.

Obtaining the Agent ID

1. Log in to the Salesforce organization.
2. Navigate to Einstein Agent Builder.
3. Select the agent to use.
4. Check the URL in the browser address bar, which is in the format https://your-salesforce-instance.lightning.force.com/lightning/r/Agent__c/0XxXXXXXXXXXXXXX/view.
5. Extract the 18-character ID (e.g., 0XxXXXXXXXXXXXXX) as the agent ID.

Obtaining the Salesforce My Domain URL

1. Log in to the Salesforce organization.
2. Go to Setup.
3. Enter "My Domain" in the quick search bar and click to enter.
4. Check the displayed domain name in the format DOMAIN-NAME.my.salesforce.com.
5. Use this URL (without the "https://" prefix) in the .env file.

Obtaining the Organization ID

1. Log in to the Salesforce organization.
2. Go to Setup.
3. Enter "Company Information" in the quick search bar and click to enter.
4. Check the "Organization ID" field, which is your Salesforce organization ID.
5. It will be a 15 or 18-character code.

⚠️ Important Notes

• The server automatically manages the sequence numbers of message exchanges.
• Each email address maintains authentication and session states.
• All API interactions are logged for debugging purposes.

💡 Troubleshooting

If you encounter issues, check the following:

1. Authentication failure: Confirm that the connected app settings are correct.
2. Agent ID retrieval error: Check the URL in Einstein Agent Builder.
3. Organization ID error: Verify in the Company Information page.
4. Callback URL issue: Ensure that the correct local callback address is set.

💻 Usage Examples

Configuration File Path Example

# Set the proxy server path
export AGENTFORCE_HOME=/path/to/agentforce-server

# Set the runtime environment
export ENV=development

# Start the server
$AGENTFORCE_HOME/bin/start.sh

Using the github_push.sh Script

1. Execute the command to give permissions:

   chmod +x github_push.sh
   

2. Run the script:

   ./github_push.sh
   

After entering the GitHub repository URL as prompted, the script will automatically handle the remaining steps.

📦 Installation

1. Environment Preparation

• Operating System: Linux/MacOS/Windows (Linux or MacOS is recommended).
• Java Version: JDK 8 or higher.
• Git Tool: It is recommended to install Git for Windows (if on Windows).

2. Installation Steps

Download the Source Code

git clone https://github.com/agentforce/server.git
cd server

Configure Environment Variables

Edit the ~/.bash_profile file and add the following content:

export AGENTFORCE_HOME=$(pwd)
source ~/.bash_profile

Install Dependencies

After entering the project directory, run:

mvn clean install

3. Running Guide

Start the Server

cd $AGENTFORCE_HOME/bin
./start.sh

Stop the Server

cd $AGENTFORCE_HOME/bin
./stop.sh

4. Other Tools Usage

Using the github_push.sh Script

This script helps push the local repository to GitHub, especially suitable for new project initialization.

Steps:

1. Add the script to the project root directory:

   wget https://raw.githubusercontent.com/agentforce/server/master/bin/github_push.sh
   

2. Give execution permissions and run:

   chmod +x github_push.sh
   ./github_push.sh
   

Parameter Explanation:

• The script does not require additional parameters and automatically detects Git configuration.
• After prompting for the repository URL, it automatically completes the push.

5. Frequently Asked Questions

Q: How to handle SSH connection issues?

A: Ensure that an SSH key has been generated locally and added to the SSH Keys settings on GitHub. Run the following command to test:

ssh -T git@github.com

Q: What if the push fails?

A: Check the network connection, confirm that the repository URL is correct, and then run the script again.

6. Complete Example

# Download the source code
git clone https://github.com/agentforce/server.git
cd server

# Configure environment variables
echo 'export AGENTFORCE_HOME=$(pwd)' >> ~/.bash_profile
source ~/.bash_profile

# Install dependencies
mvn clean install

# Start the server
cd $AGENTFORCE_HOME/bin
./start.sh

After running the above commands, you will successfully deploy and start the Agentforce proxy server.