agentforce-sdk

Salesforce AgentForce SDK

A Python SDK for creating, managing, and deploying AI agents and prompt templates in Salesforce.

Introduction

The Salesforce AgentForce SDK provides a programmatic interface to Salesforce's Agent infrastructure, allowing developers to define and interact with agents using Python code. It also includes tools for generating and managing prompt templates with Salesforce field mappings.

Installation

pip install agentforce-sdk

Dependencies

The SDK has several dependencies that will be installed automatically, including:

• requests: For HTTP requests to Salesforce APIs
• simple-salesforce: For Salesforce authentication and API access
• aiohttp: For asynchronous HTTP operations, especially in deployment tools
• jsonschema: For validating agent and template configurations
• python-dotenv: For environment variable management
• openai: For LLM API integration

If you encounter import errors when using deployment features, ensure that aiohttp is properly installed:

pip install aiohttp>=3.8.0

Features

• Create and manage AI agents in Salesforce
• Generate and manage prompt templates with Salesforce field mappings
• Support for various Salesforce field types and relationships
• Automatic Apex class generation for related data queries
• Template tuning for different LLM models
• Multiple formats for defining agents (JSON, nested directory, modular directory)
• MCP server for HTTP-based integration

Documentation

Comprehensive documentation for the SDK is available in the docs directory:

• API Documentation: Detailed documentation for all SDK components, classes, and methods.
• JSON Schemas: JSON schemas for validating agent definitions in various formats.

Examples

Prompt Template Examples

The SDK provides several examples demonstrating prompt template functionality:

• Basic Template Generation: Generate a prompt template with Salesforce field mappings
• Template with Apex Actions: Create a template that includes Apex invocable actions
• Template Tuning: Tune an existing template for different LLM models
• Template Deployment: Deploy a prompt template to Salesforce

Basic Template Generation

The examples/generate_prompt_template_example.py script demonstrates how to generate a prompt template with Salesforce field mappings:

python examples/generate_prompt_template_example.py \
  --username your_username \
  --password your_password \
  --security-token your_security_token \
  --output_dir templates \
  --model gpt-4

This will:

1. Connect to your Salesforce org
2. Generate a prompt template with appropriate field mappings
3. Save the template and any generated Apex classes to the specified output directory

Template with Apex Actions

The examples/generate_template_with_apex_example.py script shows how to create a template that includes Apex invocable actions:

python examples/generate_template_with_apex_example.py \
  --username your_username \
  --password your_password \
  --security-token your_security_token \
  --output_dir templates \
  --model gpt-4

This example demonstrates:

1. Creating a template for account opportunity analysis
2. Including Apex invocable actions for data manipulation
3. Generating necessary Apex classes for the actions
4. Saving the complete template with action mappings

Template Tuning

The examples/tune_prompt_template_example.py script demonstrates how to tune an existing template for different LLM models:

python examples/tune_prompt_template_example.py \
  --username your_username \
  --password your_password \
  --security-token your_security_token \
  --template-path templates/my_template.json \
  --output_dir tuned_templates \
  --model gpt-4

This example shows how to:

1. Load an existing template
2. Optimize it for specific LLM models
3. Add explicit instructions and validation rules
4. Save the enhanced template

Template Deployment

The examples/deploy_prompt_template_example.py script shows how to deploy a template to Salesforce:

python examples/deploy_prompt_template_example.py \
  --username your_username \
  --password your_password \
  --security-token your_security_token \
  --template-path templates/my_template.json \
  --validate-only

This example demonstrates:

1. Loading a template from a JSON file
2. Validating the template before deployment
3. Deploying the template and associated components
4. Monitoring deployment status and handling errors

Arguments

Common arguments across examples:

• --username: Your Salesforce username (required)
• --password: Your Salesforce password (required)
• --security-token: Your Salesforce security token (optional)
• --output_dir: Directory to save generated files (default varies by example)
• --model: Model to use for generation/tuning (default: 'gpt-4')

Example-specific arguments:

• --template-path: Path to an existing template JSON file (for tuning and deployment)
• --validate-only: Only validate the deployment without actually deploying (deployment example)
• --description: Additional context for template tuning (tuning example)

Output

The examples generate various outputs depending on their function:

• Template JSON files with field mappings
• Generated Apex classes for actions and queries
• Deployment status and validation results
• Detailed logs of operations performed

Agent Examples

The examples directory contains additional sample code for agent functionality:

• Creating an agent programmatically
• Creating an agent from a JSON file
• Creating an agent from a nested directory
• Creating an agent from a modular directory
• Creating an agent from a description
• Creating an agent with user-specified metadata
• Creating Apex classes
• Running an agent
• Exporting an agent
• Using the MCP server

Quick Start

from agent_sdk import Agentforce
from agent_sdk.core.auth import BasicAuth
from agent_sdk.utils.prompt_templates.prompt_template_utils import PromptTemplateUtils

# Initialize authentication
auth = BasicAuth(username="your_username", password="your_password")

# Initialize the client
client = Agentforce(auth=auth)

# Generate a prompt template
prompt_utils = PromptTemplateUtils(client.sf)
template = prompt_utils.generate_prompt_template(
    name="Account Health Analysis",
    description="Generate a health analysis for an account",
    output_dir="templates",
    model="gpt-4"
)

print(f"Template saved to: {template}")

Project Structure

agent-sdk/
├── agent_sdk/
│   ├── core/
│   │   ├── agentforce.py
│   │   ├── auth.py
│   │   ├── base.py
│   │   └── prompt_template_utils.py
│   └── models/
│       ├── agent.py
│       └── prompt_template.py
├── examples/
│   ├── generate_prompt_template_example.py
│   └── [other examples]
└── README.md

Development

You'll require poetry >= 2.0 for dependency management. To install it, follow the instructions on their website.

To contribute to the project:

1. Clone the repository
2. Create a virtual environment and install dependencies: poetry install
3. Run tests: pytest

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.