Salesforce

Query, create, update, and manage Salesforce CRM records with SOQL, SOSL, and the REST API.

SalesforceTools enable an Agent to interact with Salesforce CRM. Query records with SOQL, search with SOSL, manage objects, and run reports.

Read-only by default. Write operations (create, update, delete) require explicit opt-in.

Prerequisites

Install the dependencies and set your Salesforce and OpenAI credentials.

uv pip install -U agno simple-salesforce openai
export OPENAI_API_KEY="your_openai_api_key_here"

Username / Password auth (most common):

export SALESFORCE_USERNAME="you@example.com"
export SALESFORCE_PASSWORD="your-password"
export SALESFORCE_SECURITY_TOKEN="token-from-email"
export SALESFORCE_DOMAIN="login"

To get your security token: Log into Salesforce > click your avatar (top right) > Settings > "Reset My Security Token".

Session / Instance URL auth (when SOAP login is disabled):

from agno.tools.salesforce import SalesforceTools

SalesforceTools(
    instance_url="https://your-org.my.salesforce.com",
    session_id="your-session-id",
)

Example

A read-only agent that explores Salesforce objects, runs SOQL queries, and searches across the org.

cookbook/91_tools/salesforce_tools.py
from agno.agent import Agent
from agno.tools.salesforce import SalesforceTools

agent = Agent(tools=[SalesforceTools()])
agent.print_response("Find the top 5 accounts by name", stream=True)

Enable write operations for full CRM management:

from agno.agent import Agent
from agno.tools.salesforce import SalesforceTools

agent = Agent(
    tools=[
        SalesforceTools(
            enable_create_record=True,
            enable_update_record=True,
            enable_delete_record=True,
        )
    ],
)
agent.print_response(
    "Create a new lead: Jane Doe, CTO at Acme Corp, email jane@acme.com",
    stream=True,
)

Toolkit Params

ParameterTypeDefaultDescription
usernameOptional[str]NoneSalesforce username. Falls back to SALESFORCE_USERNAME env var.
passwordOptional[str]NoneSalesforce password. Falls back to SALESFORCE_PASSWORD env var.
security_tokenOptional[str]NoneSalesforce security token. Falls back to SALESFORCE_SECURITY_TOKEN env var.
domainOptional[str]NoneSalesforce login domain. Falls back to the SALESFORCE_DOMAIN env var, then "login". Use "test" for sandboxes.
instance_urlOptional[str]NoneSalesforce instance URL for session-based auth.
session_idOptional[str]NoneSession ID for session-based auth.
max_recordsint200Maximum number of records to return from queries and listings.
max_fieldsint100Maximum number of fields to return from describe_object.
enable_list_objectsboolTrueEnable the list_objects tool.
enable_describe_objectboolTrueEnable the describe_object tool.
enable_get_recordboolTrueEnable the get_record tool.
enable_queryboolTrueEnable the query tool.
enable_searchboolTrueEnable the search tool.
enable_create_recordboolFalseEnable the create_record tool. Off by default for safety.
enable_update_recordboolFalseEnable the update_record tool. Off by default for safety.
enable_delete_recordboolFalseEnable the delete_record tool. Off by default for safety.
enable_get_reportboolFalseEnable the get_report tool.
allboolFalseEnable all tools including write operations.
instructionsOptional[str]NoneCustom toolkit instructions. Defaults to built-in SOQL and SOSL guidance.
add_instructionsboolTrueIntended instruction toggle; current adapter does not forward it to the base Toolkit. See limitation below.

Toolkit Functions

FunctionDescription
list_objectsList all available Salesforce objects in the org with metadata (queryable, createable, etc).
describe_objectGet the schema for a Salesforce object including field names, types, picklist values, and reference relationships. Use before creating records.
get_recordGet a single record by its Salesforce ID. Optionally specify which fields to return.
queryExecute a SOQL query against Salesforce. Supports relationship queries and aggregates.
searchExecute a SOSL full-text search across Salesforce objects. Requires explicit RETURNING clause with object names and fields.
create_recordCreate a new Salesforce record. Accepts a JSON string of field name-value pairs.
update_recordUpdate an existing Salesforce record by ID. Accepts a JSON string of fields to update.
delete_recordDelete a Salesforce record by ID.
get_reportRun a Salesforce report by report ID and return the results.

You can use include_tools or exclude_tools to modify the list of tools the agent has access to. See selecting tools.

Agent instructions

The current adapter populates its instruction text but does not enable the base Toolkit's instruction-injection flag. Put the guidance directly on your Agent until that forwarding is fixed:

agent = Agent(
    tools=[SalesforceTools()],
    instructions=[
        "Use describe_object to inspect available objects and fields before querying.",
        "Use explicit object names and fields in SOSL RETURNING clauses.",
    ],
)

This is a continuation of the imports and credentials above. Read/write tool opt-ins operate independently of this instruction limitation.

Developer Resources