> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```shell theme={null}
uv pip install -U simple-salesforce openai
```

```shell theme={null}
export OPENAI_API_KEY="your_openai_api_key_here"
```

**Username / Password auth** (most common):

```shell theme={null}
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):

```python theme={null}
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.

```python cookbook/91_tools/salesforce_tools.py theme={null}
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:

```python theme={null}
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

| Parameter | Type | Default | Description |
| - | - | - | - |
| `username` | `Optional[str]` | `None` | Salesforce username. Falls back to `SALESFORCE_USERNAME` env var. |
| `password` | `Optional[str]` | `None` | Salesforce password. Falls back to `SALESFORCE_PASSWORD` env var. |
| `security_token` | `Optional[str]` | `None` | Salesforce security token. Falls back to `SALESFORCE_SECURITY_TOKEN` env var. |
| `domain` | `Optional[str]` | `None` | Salesforce login domain. Falls back to the `SALESFORCE_DOMAIN` env var, then `"login"`. Use `"test"` for sandboxes. |
| `instance_url` | `Optional[str]` | `None` | Salesforce instance URL for session-based auth. |
| `session_id` | `Optional[str]` | `None` | Session ID for session-based auth. |
| `max_records` | `int` | `200` | Maximum number of records to return from queries and listings. |
| `max_fields` | `int` | `100` | Maximum number of fields to return from `describe_object`. |
| `enable_list_objects` | `bool` | `True` | Enable the `list_objects` tool. |
| `enable_describe_object` | `bool` | `True` | Enable the `describe_object` tool. |
| `enable_get_record` | `bool` | `True` | Enable the `get_record` tool. |
| `enable_query` | `bool` | `True` | Enable the `query` tool. |
| `enable_search` | `bool` | `True` | Enable the `search` tool. |
| `enable_create_record` | `bool` | `False` | Enable the `create_record` tool. Off by default for safety. |
| `enable_update_record` | `bool` | `False` | Enable the `update_record` tool. Off by default for safety. |
| `enable_delete_record` | `bool` | `False` | Enable the `delete_record` tool. Off by default for safety. |
| `enable_get_report` | `bool` | `False` | Enable the `get_report` tool. |
| `all` | `bool` | `False` | Enable all tools including write operations. |
| `instructions` | `Optional[str]` | `None` | Custom toolkit instructions. Defaults to built-in SOQL and SOSL guidance. |
| `add_instructions` | `bool` | `True` | Pass the toolkit instructions to the agent. |

## Toolkit Functions

| Function | Description |
| - | - |
| `list_objects` | List all available Salesforce objects in the org with metadata (queryable, createable, etc). |
| `describe_object` | Get the schema for a Salesforce object including field names, types, picklist values, and reference relationships. Use before creating records. |
| `get_record` | Get a single record by its Salesforce ID. Optionally specify which fields to return. |
| `query` | Execute a SOQL query against Salesforce. Supports relationship queries and aggregates. |
| `search` | Execute a SOSL full-text search across Salesforce objects. Requires explicit `RETURNING` clause with object names and fields. |
| `create_record` | Create a new Salesforce record. Accepts a JSON string of field name-value pairs. |
| `update_record` | Update an existing Salesforce record by ID. Accepts a JSON string of fields to update. |
| `delete_record` | Delete a Salesforce record by ID. |
| `get_report` | Run 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](https://agno-v2.mintlify.site/tools/selecting-tools.md).

## Developer Resources

* [Source](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/salesforce.py)
* [Cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/salesforce_tools.py)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.