diff --git a/cookbook/tools/built-in.mdx b/cookbook/tools/built-in.mdx index bc507dbcf..e5348db30 100644 --- a/cookbook/tools/built-in.mdx +++ b/cookbook/tools/built-in.mdx @@ -145,6 +145,7 @@ agent.print_response("Send a message to #general saying 'Hello from AI!'") | Trello | `from agno.tools.trello import TrelloTools` | Kanban boards | | Linear | `from agno.tools.linear import LinearTools` | Issue tracking | | Jira | `from agno.tools.jira import JiraTools` | Project management | +| Salesforce | `from agno.tools.salesforce import SalesforceTools` | CRM records, SOQL, SOSL | | ClickUp | `from agno.tools.clickup import ClickUpTools` | Work management | | Confluence | `from agno.tools.confluence import ConfluenceTools` | Documentation | | Cal.com | `from agno.tools.calcom import CalComTools` | Scheduling | diff --git a/docs.json b/docs.json index 2cfed6b39..405914f35 100644 --- a/docs.json +++ b/docs.json @@ -2061,6 +2061,7 @@ "tools/toolkits/others/reasoning", "tools/toolkits/others/replicate", "tools/toolkits/others/resend", + "tools/toolkits/others/salesforce", "tools/toolkits/others/spotify", "tools/toolkits/others/shopify", "tools/toolkits/others/todoist", @@ -6621,6 +6622,7 @@ "examples/tools/parallel-tools", "examples/tools/python-function-as-tool", "examples/tools/python-tools", + "examples/tools/salesforce-tools", "examples/tools/shell-tools", "examples/tools/shopify-tools", "examples/tools/sleep-tools", diff --git a/examples/tools/salesforce-tools.mdx b/examples/tools/salesforce-tools.mdx new file mode 100644 index 000000000..63e2ffdd1 --- /dev/null +++ b/examples/tools/salesforce-tools.mdx @@ -0,0 +1,95 @@ +--- +title: "Salesforce" +description: "Use Salesforce CRM with Agno agents to query, create, and manage records." +--- + +## Prerequisites + +```shell +uv pip install -U simple-salesforce +``` + +```shell +export SALESFORCE_USERNAME="you@example.com" +export SALESFORCE_PASSWORD="your-password" +export SALESFORCE_SECURITY_TOKEN="token-from-email" +export SALESFORCE_DOMAIN="login" +``` + +## Example + +```python cookbook/91_tools/salesforce_tools.py +from agno.agent import Agent +from agno.models.openai import OpenAIChat +from agno.tools.salesforce import SalesforceTools + +# Read-only agent (default) +read_only_agent = Agent( + name="Salesforce Explorer", + model=OpenAIChat(id="gpt-4o"), + tools=[SalesforceTools()], + instructions=[ + "Use describe_object to understand available fields before building queries.", + "Use SOQL for precise structured queries, SOSL for full-text search across objects.", + ], + markdown=True, +) + +# Full CRM agent with write operations enabled +full_crm_agent = Agent( + name="Salesforce CRM Agent", + model=OpenAIChat(id="gpt-4o"), + tools=[ + SalesforceTools( + enable_create_record=True, + enable_update_record=True, + enable_delete_record=True, + ) + ], + instructions=[ + "Always use describe_object to check required fields before creating records.", + "Confirm with the user before deleting any records.", + ], + markdown=True, +) + +if __name__ == "__main__": + # Explore available objects + read_only_agent.print_response( + "List the queryable Salesforce objects in this org", + stream=True, + ) + + # Query accounts + read_only_agent.print_response( + "Find the top 5 accounts by name using SOQL", + stream=True, + ) + + # Describe an object's schema + read_only_agent.print_response( + "Describe the Contact object. What fields are required for creating a new contact?", + stream=True, + ) + + # Search across objects + read_only_agent.print_response( + "Search for anything related to 'United' across all objects", + stream=True, + ) +``` + +## Run the Example + +```bash +git clone https://github.com/agno-agi/agno.git +cd agno/cookbook/91_tools + +# Create and activate virtual environment +./scripts/demo_setup.sh +source .venvs/demo/bin/activate + +python salesforce_tools.py +``` + +For details, see [Salesforce Tools cookbook](https://github.com/agno-agi/agno/blob/main/cookbook/91_tools/salesforce_tools.py). diff --git a/tools/toolkits/others/salesforce.mdx b/tools/toolkits/others/salesforce.mdx new file mode 100644 index 000000000..8d5d81a5f --- /dev/null +++ b/tools/toolkits/others/salesforce.mdx @@ -0,0 +1,113 @@ +--- +title: Salesforce +description: "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 `simple-salesforce` library and set your Salesforce credentials. + +```shell +uv pip install -U simple-salesforce +``` + +**Username / Password auth** (most common): + +```shell +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 +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 +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 +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]` | `"login"` | Salesforce login domain. Falls back to `SALESFORCE_DOMAIN` env var. 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. | + +## 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](/tools/selecting-tools). + +## 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)