Orchestrate Adk Agent

IBM WatsonX Orchestrate ADK Salesforce Agent

An example Salesforce agent built with IBM watsonx Orchestrate ADK that provides powerful tools to interact with your Salesforce org using the simple-salesforce Python library.

NOTE: This is just a example implementation to help you get started with orchestrate adk and create agents/tools/connections. The salesforce tools added here are NOT meant for deployment purpose. Please take this only as example implementation

Getting Started

Prerequisites

• Python 3.8+
• IBM watsonx Orchestrate ADK
• Salesforce account with API access

Installation

git clone https://github.com/IBM/orchestrate-adk-agent.git
cd orchestrate-adk-agent
pip install -r requirements.txt
cp .env.template .env
# Fill in your Salesforce credentials in .env

> Note: Make scripts executable if needed: > > ``bash > chmod +x import_agent.sh setup_connection.sh check_connection.sh test_agent.sh > ``

Repository Structure

• agents/: Agent configuration files
• tools/: Python tools for Salesforce operations
• connections/: Connection configuration files
• requirements.txt: Python dependencies
• .env.template: Environment variable template
• import_agent.sh, import_tools.sh, setup_connection.sh, check_connection.sh, test_agent.sh: Shell scripts for quick setup and testing

Shell Scripts

• import_agent.sh: Imports the agent into Orchestrate.

``bash ./import_agent.sh ``

• import_tools.sh: Imports the tools into Orchestrate.

``bash ./import_tools.sh ``

• setup_connection.sh: Sets up Salesforce connection.

``bash ./setup_connection.sh ``

• check_connection.sh: Checks connection status.

``bash ./check_connection.sh ``

• test_agent.sh: Runs agent tests.

``bash ./test_agent.sh ``

Each script prints helpful messages and checks for required environment variables. If you encounter errors, ensure your .env file is configured and the scripts have execute permissions.

MCP Server Integration (Tavily)

This project includes integration with MCP (Model Context Protocol) servers to extend the agent's capabilities. The Tavily MCP server provides AI-powered web search and research capabilities.

> Documentation: For more information on MCP toolkits, see the IBM WatsonX Orchestrate Toolkits Documentation

Prerequisites

• Node.js installed (for npx command)
• Tavily API key (included in the setup script or provide your own)

MCP Server Files

• toolkits/tavily_mcp.yaml: MCP toolkit configuration file
• import_mcp_toolkit.sh: Import MCP toolkit via CLI command
• import_mcp_from_file.sh: Import MCP toolkit from YAML file
• remove_mcp_toolkit.sh: Remove MCP toolkit

Quick Setup

1. Import the MCP toolkit:

./import_mcp_toolkit.sh

This script will:

• Create a tavily_creds connection for the API key
• Configure the connection for draft environment
• Import the Tavily MCP toolkit with all available tools

1. Alternative: Import from YAML file:

./import_mcp_from_file.sh

Available Tavily Tools

Once imported, the following tools are available:

| Tool | Description | | ---------------------------------- | ---------------------------------------------------- | | tavily_mcp_server:tavily-search | AI-powered web search for finding information online | | tavily_mcp_server:tavily-extract | Extract content from specific URLs | | tavily_mcp_server:tavily-crawl | Crawl websites to gather comprehensive information | | tavily_mcp_server:tavily-map | Map website structure and discover pages |

Using with the Salesforce Agent

The Salesforce agent is configured to use Tavily tools for:

• Researching companies, competitors, or industry trends
• Enriching Salesforce lead/contact data with external information
• Finding current news about accounts or prospects
• Discovering company websites, social profiles, or contact information
• Verifying or supplementing Salesforce data with web sources

Example Usage

"Research the company Acme Corp and find their latest news"
"Find the LinkedIn profile for John Doe at IBM"
"What are the latest industry trends in cloud computing?"
"Extract contact information from https://example.com/about"

Manual MCP Toolkit Import

You can also import an MCP toolkit manually using the CLI:

# Setup connection first
orchestrate connections add -a tavily_creds
orchestrate connections configure -a tavily_creds --env draft --type team --kind key_value
orchestrate connections set-credentials -a tavily_creds --env draft -e "TAVILY_API_KEY=your_api_key"

# Import the toolkit
orchestrate toolkits add \
    --kind mcp \
    --name tavily_mcp_server \
    --description "Tavily MCP Server for AI-powered web search" \
    --command '["npx", "-y", "tavily-mcp@latest"]' \
    --tools "*" \
    --app-id tavily_creds

Remove MCP Toolkit

To remove the Tavily MCP toolkit:

./remove_mcp_toolkit.sh

Listing Toolkits

To see all imported toolkits:

orchestrate toolkits list

MCP Server Integration (Atlassian Jira)

The Atlassian MCP server provides comprehensive Jira integration for issue tracking, project management, and agile workflows.

Prerequisites

• uv installed (for uvx command)
• Jira Personal Access Token

MCP Server Files

• toolkits/atlassian_mcp.yaml: MCP toolkit configuration file
• import_atlassian_mcp.sh: Import Atlassian MCP toolkit via CLI command
• import_atlassian_mcp_from_file.sh: Import Atlassian MCP toolkit from YAML file
• remove_atlassian_mcp.sh: Remove Atlassian MCP toolkit

Quick Setup

1. Import the Atlassian MCP toolkit:

./import_atlassian_mcp.sh

You will be prompted to enter:

• Your Jira username (email)
• Your Jira Personal Access Token

The Jira URL (https://jsw.ibm.com) is pre-configured in the script.

1. Alternative: Import from YAML file:

./import_atlassian_mcp_from_file.sh

Available Atlassian Jira Tools

Once imported, the following tools are available:

Issue Management

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_get_issue | Get details of a specific Jira issue | | atlassian_mcp_server:jira_search | Search Jira issues using JQL | | atlassian_mcp_server:jira_create_issue | Create a new Jira issue | | atlassian_mcp_server:jira_update_issue | Update an existing Jira issue | | atlassian_mcp_server:jira_delete_issue | Delete a Jira issue | | atlassian_mcp_server:jira_batch_create_issues | Create multiple issues in batch |

Status & Transitions

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_transition_issue | Transition issue to a new status | | atlassian_mcp_server:jira_get_transitions | Get available status transitions |

Comments & Worklogs

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_add_comment | Add a comment to an issue | | atlassian_mcp_server:jira_add_worklog | Add a worklog entry | | atlassian_mcp_server:jira_get_worklog | Get worklog entries for an issue |

Projects & Versions

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_get_all_projects | Get all accessible Jira projects | | atlassian_mcp_server:jira_get_project_issues | Get all issues for a project | | atlassian_mcp_server:jira_get_project_versions | Get all fix versions for a project | | atlassian_mcp_server:jira_create_version | Create a new fix version | | atlassian_mcp_server:jira_batch_create_versions | Batch create multiple versions |

Agile & Sprints

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_get_agile_boards | Get agile boards by name, project, or type | | atlassian_mcp_server:jira_get_board_issues | Get issues linked to a board | | atlassian_mcp_server:jira_get_sprints_from_board | Get sprints from a board | | atlassian_mcp_server:jira_get_sprint_issues | Get issues from a sprint | | atlassian_mcp_server:jira_create_sprint | Create a new sprint | | atlassian_mcp_server:jira_update_sprint | Update a sprint |

Issue Linking

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_create_issue_link | Create a link between two issues | | atlassian_mcp_server:jira_remove_issue_link | Remove a link between issues | | atlassian_mcp_server:jira_create_remote_issue_link | Create a remote/web link | | atlassian_mcp_server:jira_get_link_types | Get available link types | | atlassian_mcp_server:jira_link_to_epic | Link an issue to an epic |

Utilities

| Tool | Description | |------|-------------| | atlassian_mcp_server:jira_get_user_profile | Get user profile information | | atlassian_mcp_server:jira_download_attachments | Download attachments from an issue | | atlassian_mcp_server:jira_search_fields | Search Jira fields by keyword | | atlassian_mcp_server:jira_batch_get_changelogs | Get changelogs for multiple issues |

Using with the Salesforce Agent

The Salesforce agent is configured to use Atlassian Jira tools for:

• Querying and searching Jira issues
• Creating, updating, and deleting tickets
• Managing sprints and agile boards
• Tracking project progress
• Linking CRM data (Salesforce) with issue tracking (Jira)
• Adding comments and worklogs
• Managing project versions

Example Usage

"Get details of Jira issue PROJ-123"
"Search for all open bugs in project MYPROJ"
"Create a new bug in project MYPROJ with title 'Login issue'"
"Add a comment to issue PROJ-456"
"Show me all sprints for board 123"
"Transition issue PROJ-789 to 'In Progress'"
"Get all projects I have access to"
"Link issue PROJ-100 to epic PROJ-50"

Manual Atlassian MCP Toolkit Import

You can also import the Atlassian MCP toolkit manually using the CLI:

# Setup connection first
orchestrate connections add -a atlassian_creds
orchestrate connections configure -a atlassian_creds --env draft --type team --kind key_value
orchestrate connections set-credentials -a atlassian_creds --env draft \
    -e "JIRA_USERNAME=your_email@example.com" \
    -e "JIRA_PERSONAL_TOKEN=your_token"

# Import the toolkit
orchestrate toolkits add \
    --kind mcp \
    --name atlassian_mcp_server \
    --description "Atlassian MCP Server for Jira integration" \
    --command '["uvx", "mcp-atlassian", "--jira-url=https://jsw.ibm.com", "--jira-username=${JIRA_USERNAME}", "--jira-personal-token=${JIRA_PERSONAL_TOKEN}"]' \
    --tools "*" \
    --app-id atlassian_creds

Remove Atlassian MCP Toolkit

To remove the Atlassian MCP toolkit:

./remove_atlassian_mcp.sh

Features

Core Capabilities

• SOQL Queries: Execute complex Salesforce Object Query Language queries
• SOSL Searches: Search across multiple Salesforce objects
• CRUD Operations: Create, Read, Update, Delete records
• Bulk Operations: Handle multiple records efficiently
• Metadata Access: Describe objects, fields, and org structure
• User Information: Get current user and org details

Supported Operations

• Query records with filtering, sorting, and relationships
• Search across multiple objects simultaneously
• Create new records with validation
• Update existing records with change tracking
• Delete records with confirmation
• Upsert records using external IDs
• Bulk create multiple records
• Get record counts with filtering
• Retrieve recent records
• Access object metadata and field definitions

Installation

1. Clone or create the agent directory structure:

salesforce_agent/
├── agents/
│   └── salesforce_agent.yaml
├── tools/
│   └── salesforce_tools.py
├── connections/
│   └── salesforce_connection.yaml
├── requirements.txt
├── .env.template
├── import_agent.sh
├── setup_connection.sh
├── check_connection.sh
└── README.md

1. Install dependencies:

pip install -r requirements.txt

1. Configure credentials (choose one method):

Method 1: Orchestrate Connections (Recommended)

Use the built-in script to set up the connection:

./setup_connection.sh

This will:

• Import the connection configuration
• Prompt you for your Salesforce credentials
• Store them securely in orchestrate
• Associate the connection with your tools

Method 2: Environment Variables (.env file)

Copy .env.template to .env and configure:

# For production org
SF_USERNAME=your_username@company.com
SF_PASSWORD=your_password
SF_SECURITY_TOKEN=your_security_token
SF_DOMAIN=login

# For sandbox org
SF_USERNAME=your_username@company.com.sandbox
SF_PASSWORD=your_password
SF_SECURITY_TOKEN=your_security_token
SF_DOMAIN=test

Quick Start

1. Import the agent:

./import_agent.sh

1. Import the tools:

./import_tools.sh

1. Set up your Salesforce connection:

./setup_connection.sh

1. Check connection status:

./check_connection.sh

1. Test the agent:

./test_agent.sh

Connection Management

Using Orchestrate Connections (Recommended)

The agent uses orchestrate's connection management system to securely store and access credentials:

• Connection ID: salesforce_creds
• Connection Type: key_value
• Required Keys:
• SF_USERNAME: Your Salesforce username
• SF_PASSWORD: Your Salesforce password
• SF_SECURITY_TOKEN: Your security token
• SF_DOMAIN: login for production, test for sandbox

Credential Hierarchy

The tools check for credentials in this order:

1. Orchestrate connections (salesforce_creds)
2. Environment variables (.env file)
3. System environment variables

Tools Reference

Query and Search Tools

salesforce_query

Execute SOQL queries against Salesforce.

# Example: Get all accounts with more than 100 employees
query = "SELECT Id, Name, NumberOfEmployees FROM Account WHERE NumberOfEmployees > 100"

salesforce_search

Execute SOSL searches across multiple objects.

# Example: Search for "Acme" across all searchable objects
search_term = "Acme"

Record Management Tools

salesforce_create_record

Create new records in Salesforce.

# Example: Create a new contact
object_type = "Contact"
record_data = '{"LastName": "Doe", "FirstName": "John", "Email": "john.doe@example.com"}'

salesforce_update_record

Update existing records.

# Example: Update account phone number
object_type = "Account"
record_id = "001XXXXXXXXXXXXXXX"
record_data = '{"Phone": "+1-555-123-4567"}'

salesforce_delete_record

Delete records from Salesforce.

# Example: Delete a lead
object_type = "Lead"
record_id = "00QXXXXXXXXXXXXXXX"

salesforce_get_record

Retrieve specific records by ID.

# Example: Get account details
object_type = "Account"
record_id = "001XXXXXXXXXXXXXXX"

Bulk Operations

salesforce_bulk_create

Create multiple records using Bulk API.

# Example: Create multiple contacts
object_type = "Contact"
records_data = '[
    {"LastName": "Smith", "Email": "smith@example.com"},
    {"LastName": "Jones", "Email": "jones@example.com"}
]'

salesforce_upsert_record

Insert or update records using external IDs.

# Example: Upsert contact using custom external ID
object_type = "Contact"
external_id_field = "External_ID__c"
external_id_value = "EXT-001"
record_data = '{"LastName": "Wilson", "Email": "wilson@example.com"}'

Metadata and Information Tools

salesforce_describe_object

Get metadata for Salesforce objects.

# Example: Describe the Account object
object_type = "Account"

salesforce_list_objects

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IBM
• Source: IBM/orchestrate-adk-agent
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.