Repository files navigation

This tutorial explains how to deploy a Heroku application written in Python that can be used to build an Agentforce custom action, extending the capabilities of any Agentforce agent with the power of Heroku's fully managed, elastic compute services.

IN A HURRY? This application has already been deployed publicly and is available athttps://agentforce-tutorial-python-7894e9215571.herokuapp.com/, allowing you to skip straight toconfiguring Heroku-based actions in your Salesforce organization to try it out first.

Salesforce Org Requirements:

• Use aSalesforce Developer Edition org (not Trailhead Playground)
• Ensure you have access to Agentforce by searching forAgents in theSetup menu
• If needed, get a freeSalesforce Developer Edition org here
• Enable Einstein and Agentforce inEinstein Setup under theSetup menu

Network Requirements:

• Disable VPN connections during setup - they interfere with OAuth flows
• Ensure you have a stable internet connection for the authentication process

Regardless of how you access this app, you will need to complete or configure basic authentication. We have included this as a reminder that best practice is to always consider authentication for APIs, especially those involved in AI interactions like this. For APIs in general, it is typical to use JWT-based authentication. For the basic authentication setup here, the default username isheroku, and the password isagent.

WARNING: Carefully review your app authentication needs and requirements before deploying to production.

You can deploy this application to your Heroku account using the button below or manually via the CLI.

To proceed with a CLI deployment, install theHeroku CLI and log in with your Heroku account (orsign up). Then, execute the following CLI commands:

git clone https://github.com/heroku-examples/heroku-agentforce-tutorial-pythoncd heroku-agentforce-tutorial-pythonheroku create your-app-name# Choose a unique namegit push heroku main

Add Heroku AppLink addon:

heroku addons:create heroku-applink

Configure the application ID:

heroku config:set HEROKU_APP_ID="$(heroku apps:info --json| jq -r'.app.id')"

💡jq utility: If you don't have thejq utility, runheroku apps:info --json manually and extract the value from theapp.id field.

Add the Heroku AppLink Service Mesh buildpack:

heroku buildpacks:add https://github.com/heroku/heroku-buildpack-heroku-applink-service-mesh

Deploy the updated configuration:

git commit --allow-empty -m"Add AppLink configuration"git push heroku main

Important: Make sure you're using a Salesforce Developer Edition org and have disabled any VPN connections.

heroku salesforce:connect your-connection-name -a your-app-name --addon your-applink-addon-name

To find your addon name, run:heroku addons and look for theheroku-applink entry.

Example:

heroku salesforce:connect my-salesforce-org -a my-badge-app --addon applink-example-12345

heroku salesforce:publish api-spec.json --client-name BadgeService --connection-name your-connection-name --authorization-connected-app-name BadgeServiceConnectedApp --authorization-permission-set-name BadgeServicePermissions -a your-app-name --addon your-applink-addon-name

Verify the publication worked:

heroku salesforce:publications

You should see your connection listed with a "Connected" status.

VPN Interference:

• Problem: Connection fails with "Invalid record" or "UNTRUSTED_CALLER" errors
• Solution: Disable VPN connections during the setup process. VPNs interfere with OAuth flows.

Port Configuration Issues:

• Problem: App crashes with "Address already in use" errors in logs
• Solution: The app is already configured to use port 3000 when AppLink service mesh is enabled. If you modify the port logic, ensure it uses port 3000 whenHEROKU_APPLINK_TOKEN environment variable is present.

Connection Timeout:

• Problem: Browser shows successful authentication but CLI shows timeout
• Solution: This is normal behavior. Checkheroku salesforce:publications to verify the connection worked.

Explicit Parameters Required:

• Problem: Commands fail with ambiguous errors
• Solution: Always specify explicit app and addon parameters:

  heroku salesforce:connect connection-name -a your-app-name --addon your-addon-name

API Spec File Missing:

• Problem: "The API spec file path api-spec.json doesn't exist"
• Solution: Ensure you have theapi-spec.json file in your project directory. It should be created automatically, but if missing, it describes your/process endpoint.

If you continue to experience issues:

1. Checkheroku logs --tail for application errors
2. Verify your Salesforce org has Agentforce enabled
3. Ensure all config variables are set:heroku config
4. Check connection status:heroku salesforce:publications

To use Heroku AppLink features with the CLI, you need to install the AppLink plugin:

heroku plugins:install @heroku-cli/plugin-applink

This plugin provides the necessary commands for working with AppLink add-ons and Salesforce connections.

Alternative: Environment Variable Workaround

If you encounter errors referencing the old add-on nameheroku-integration, you can also set the following environment variable:

export HEROKU_INTEGRATION_ADDON=heroku-applink

For permanent setup, add this to your shell profile:

• macOS/Linux: Addexport HEROKU_INTEGRATION_ADDON=heroku-applink to your~/.zshrc or~/.bashrc
• Windows: Set the environment variable in your system settings

After installing the plugin or setting the environment variable, you can successfully run:

heroku addons:create heroku-applink -a your-app-nameheroku salesforce:connect your-org -a your-app-name

Although you cannot integrate this app with Agentforce until you deploy it, you can still develop and test your action’s inputs and outputs locally, using the built-inSwagger UI. Once you are satisfied with your changes, refer to the deployment and configuration steps above.

git clone https://github.com/heroku-examples/heroku-agentforce-tutorial-pythoncd heroku-agentforce-tutorial-pythonpython -m venv venvsource venv/bin/activatepip install -r requirements.txtpython app.py

Once the application is running, navigate to the URL below, click theTry it Out button, and complete the basic authentication as covered above.

http://127.0.0.1:5000