Getting Started

Complete guide to deploying and configuring your first AI agent.

10 min read
TL;DR

Fastest way: Run cci flow run dev_org --org dev with CumulusCI

Manual setup: Clone repo, deploy with SF CLI, create Named Credential, create LLM Config, create Agent, add Capabilities, add chat component, test!

Table of contents

  1. Prerequisites
  2. Step 1: Deploy the Framework
    1. Option 1: CumulusCI (Recommended for Scratch Orgs)
    2. Option 2: Salesforce CLI (Manual Setup)
  3. Step 2: Configure Named Credentials
    1. For OpenAI
    2. For Claude (Anthropic)
    3. For Gemini (Google)
  4. Step 3: Create LLM Configuration
    1. Available Provider Adapters
  5. Step 4: Create Your First Agent
  6. Step 5: Add Capabilities
    1. Example: Search Contacts
    2. Example: Create Task
  7. Step 6: Add Chat Component to a Page
  8. Step 7: Test Your Agent
  9. Next Steps

Prerequisites

💡 Tip

We recommend starting with a Sandbox org for initial setup and testing.

Before you begin, ensure you have:

Step 1: Deploy the Framework

CumulusCI provides the fastest way to get started with a fully configured scratch org.

# Clone the repository
git clone https://github.com/iamsonal/aiAgentStudio.git
cd aiAgentStudio

# Run the dev_org flow
cci flow run dev_org --org dev

This single command performs all of the following:

Step What it does
Deploy Framework Deploys all Apex classes, LWCs, objects, and metadata from force-app
Deploy Seed Data Deploys utility classes from seed-data folder
Assign Permission Sets Assigns AIAgentStudioConfigurator and AIAgentStudioEndUser
Enable Knowledge Enables Knowledge user and assigns KnowledgeDemo permission set
Create Sample Data Runs AgentTestDataFactory.createComprehensiveShowcase() to create sample agents and test data
Setup Connected App Configures a Connected App for API access

After the flow completes, open your scratch org:

cci org browser dev

You’ll have working sample agents ready to test. Explore the seed-data folder and AgentTestDataFactory class to see what gets created.

Option 2: Salesforce CLI (Manual Setup)

For existing orgs or when you need more control over the deployment:

# Clone the repository
git clone https://github.com/iamsonal/aiAgentStudio.git
cd aiAgentStudio

# Authenticate to your org
sf org login web -a your-org-alias

# Deploy the framework
sf project deploy start -d force-app/main/default -o your-org-alias

Step 2: Configure Named Credentials

⚠️ Security Note

Never commit API keys to source control. Named Credentials keep your keys secure and separate from your code.

Named Credentials securely store your AI provider API keys.

For OpenAI

  1. Go to Setup → Named Credentials → New
  2. Configure:
    • Label: OpenAI API
    • Name: OpenAI_API
    • URL: https://api.openai.com
    • Identity Type: Named Principal
    • Authentication Protocol: Custom
  3. Add External Credential with your API key as a header:
    • Header Name: Authorization
    • Header Value: Bearer YOUR_API_KEY

For Claude (Anthropic)

  1. Go to Setup → Named Credentials → New
  2. Configure:
    • Label: Claude API
    • Name: Claude_API
    • URL: https://api.anthropic.com
  3. Add header:
    • Header Name: x-api-key
    • Header Value: YOUR_API_KEY

For Gemini (Google)

  1. Go to Setup → Named Credentials → New
  2. Configure:
    • Label: Gemini API
    • Name: Gemini_API
    • URL: https://generativelanguage.googleapis.com
  3. Add your API key as a query parameter or header per Google’s requirements

Step 3: Create LLM Configuration

LLM Configurations define how to connect to your AI provider.

  1. Open App Launcher → LLM Configurations
  2. Click New
  3. Fill in the fields:
Field Value Description
Developer Name OpenAI_GPT4o Unique identifier
Named Credential OpenAI_API Your named credential
Provider Adapter Class OpenAIProviderAdapter Provider-specific adapter
Default Model gpt-4o-mini Model to use
Temperature 0.7 Creativity (0-1)
Max Tokens 4096 Maximum response length
Is Active ✓ Enable this configuration

Available Provider Adapters

Provider Adapter Class Models
OpenAI OpenAIProviderAdapter gpt-4o, gpt-4o-mini

Additional provider adapters are available in the addon package. You can also create your own by extending BaseProviderAdapter.

Step 4: Create Your First Agent

  1. Open App Launcher → AI Agent Definitions
  2. Click New
  3. Configure basic settings:
Field Value
Name Sales Assistant
Developer Name Sales_Assistant
Agent Type Conversational
LLM Configuration OpenAI_GPT4o
Is Active ✓
  1. Configure memory settings:
Field Value Description
Memory Strategy BufferWindow How to manage history
History Turn Limit 10 Conversations to remember
  1. Configure prompts:

Identity Prompt (Who the agent is):

You are a helpful Salesforce assistant for the sales team.
You help users find accounts, contacts, and opportunities.
You are professional, concise, and always confirm before making changes.

Instructions Prompt (How to behave):

- Always greet users warmly
- Ask clarifying questions when requests are ambiguous
- Confirm before creating or updating records
- Provide summaries of search results
- If you can't help, explain why and suggest alternatives

Step 5: Add Capabilities

📝 Note

Capabilities are the "tools" your agent can use. Start with read-only capabilities and add write capabilities once you're comfortable with the framework.

Capabilities define what actions your agent can perform.

Example: Search Contacts

  1. Open App Launcher → Agent Capabilities
  2. Click New
  3. Configure:
Field Value
Capability Name search_contacts
Description Search for contacts by name, email, or account. Use this when users ask to find contact information.
Implementation Type Standard
Standard Action Type GetRecordDetails
AI Agent Definition Sales Assistant
  1. Add Backend Configuration: 
    {
  "objectApiName": "Contact"
}
  2. Add Parameters (JSON Schema): 
    {
  "type": "object",
  "properties": {
 "firstName": {
   "type": "string",
   "description": "Contact's first name"
 },
 "lastName": {
   "type": "string",
   "description": "Contact's last name"
 },
 "email": {
   "type": "string",
   "description": "Contact's email address"
 },
 "accountName": {
   "type": "string",
   "description": "Name of the contact's account"
 }
  }
}

Example: Create Task

Field Value
Capability Name create_task
Description Create a follow-up task. Use when users want to schedule reminders or to-dos.
Implementation Type Standard
Standard Action Type CreateRecord
Requires Approval ✓

Backend Configuration:

{
  "objectApiName": "Task"
}

Parameters:

{
  "type": "object",
  "required": ["Subject"],
  "properties": {
    "Subject": {
      "type": "string",
      "description": "Task subject/title"
    },
    "Description": {
      "type": "string",
      "description": "Task details"
    },
    "ActivityDate": {
      "type": "string",
      "description": "Due date in YYYY-MM-DD format"
    },
    "Priority": {
      "type": "string",
      "enum": ["High", "Normal", "Low"],
      "description": "Task priority"
    }
  }
}

Step 6: Add Chat Component to a Page

  1. Go to Setup → Lightning App Builder
  2. Edit an existing page or create a new one
  3. Find aiAssistantChat in the components panel
  4. Drag it onto your page
  5. Configure the component:
    • Agent Developer Name: Sales_Assistant
  6. Save and Activate the page

Step 7: Test Your Agent

Open the page with your chat component and try these conversations:

You: Hi there!
Agent: Hello! I'm your Sales Assistant. How can I help you today?

You: Find contacts at Acme Corp
Agent: [Searches and returns contacts]

You: Create a task to follow up with John Smith next week
Agent: I'll create a follow-up task for John Smith. Here are the details:
       - Subject: Follow up with John Smith
       - Due Date: [next week]
       Should I proceed?

You: Yes
Agent: ✓ Task created successfully!

Next Steps

Now that you have a working agent, explore: