Claude Tool-Use API for Salesforce: No Abstraction Layers

// lib/salesforce.ts
import axios from 'axios'
 
interface SalesforceAuth {
  accessToken: string
  instanceUrl: string
}
 
export async function getSalesforceToken(): Promise<SalesforceAuth> {
  const params = new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: process.env.SF_CLIENT_ID!,
    client_secret: process.env.SF_CLIENT_SECRET!,
  })
 
  const res = await axios.post(
    `${process.env.SF_LOGIN_URL}/services/oauth2/token`,
    params.toString(),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
  )
 
  return {
    accessToken: res.data.access_token,
    instanceUrl: res.data.instance_url,
  }
}
 
export async function querySalesforce(soql: string, auth: SalesforceAuth) {
  const res = await axios.get(
    `${auth.instanceUrl}/services/data/v64.0/query`,
    {
      params: { q: soql },
      headers: { Authorization: `Bearer ${auth.accessToken}` },
    }
  )
  return res.data
}
 
export async function createRecord(
  objectType: string,
  fields: Record<string, unknown>,
  auth: SalesforceAuth
) {
  const res = await axios.post(
    `${auth.instanceUrl}/services/data/v64.0/sobjects/${objectType}`,
    fields,
    { headers: { Authorization: `Bearer ${auth.accessToken}`, 'Content-Type': 'application/json' } }
  )
  return res.data
}

// lib/agent-tools.ts
import Anthropic from '@anthropic-ai/sdk'
 
export const salesforceTools: Anthropic.Tool[] = [
  {
    name: 'query_salesforce',
    description: `Execute a SOQL query against Salesforce and return the results.
Use this when the user asks about existing records, relationships, or data in Salesforce.
Always use SELECT with specific fields — never SELECT *.
Limit results to 50 unless the user asks for more.`,
    input_schema: {
      type: 'object',
      properties: {
        soql: {
          type: 'string',
          description: 'The SOQL query to execute. Must be valid SOQL syntax.',
        },
      },
      required: ['soql'],
    },
  },
  {
    name: 'create_record',
    description: `Create a new record in Salesforce.
Use this only when the user explicitly asks to create something.
Confirm the object type and required fields before calling.`,
    input_schema: {
      type: 'object',
      properties: {
        object_type: {
          type: 'string',
          description: 'Salesforce object API name (e.g., Account, Opportunity, Contact)',
        },
        fields: {
          type: 'object',
          description: 'Key-value pairs of field API names and their values',
        },
      },
      required: ['object_type', 'fields'],
    },
  },
  {
    name: 'describe_object',
    description: `Get the field list and metadata for a Salesforce object.
Use this when you need to know what fields are available on an object before querying or creating records.`,
    input_schema: {
      type: 'object',
      properties: {
        object_name: { type: 'string', description: 'API name of the Salesforce object' },
      },
      required: ['object_name'],
    },
  },
]

// lib/agent.ts
import Anthropic from '@anthropic-ai/sdk'
import { getSalesforceToken, querySalesforce, createRecord } from './salesforce'
import { salesforceTools } from './agent-tools'
import axios from 'axios'
 
const client = new Anthropic()
 
async function executeTool(
  toolName: string,
  toolInput: Record<string, unknown>,
  auth: Awaited<ReturnType<typeof getSalesforceToken>>
): Promise<string> {
  if (toolName === 'query_salesforce') {
    const result = await querySalesforce(toolInput.soql as string, auth)
    return JSON.stringify(result.records ?? result, null, 2)
  }
 
  if (toolName === 'create_record') {
    const result = await createRecord(
      toolInput.object_type as string,
      toolInput.fields as Record<string, unknown>,
      auth
    )
    return JSON.stringify(result, null, 2)
  }
 
  if (toolName === 'describe_object') {
    const res = await axios.get(
      `${auth.instanceUrl}/services/data/v64.0/sobjects/${toolInput.object_name}/describe`,
      { headers: { Authorization: `Bearer ${auth.accessToken}` } }
    )
    // Return just field names + types to keep context lean
    const fields = res.data.fields.map((f: { name: string; type: string; label: string }) => ({
      name: f.name,
      type: f.type,
      label: f.label,
    }))
    return JSON.stringify(fields, null, 2)
  }
 
  return 'Unknown tool'
}
 
export async function runAgent(userMessage: string): Promise<string> {
  const auth = await getSalesforceToken()
  const messages: Anthropic.MessageParam[] = [
    { role: 'user', content: userMessage }
  ]
 
  const systemPrompt = `You are a Salesforce assistant with read and write access to the org.
When answering questions about records, always query Salesforce — never make up data.
When creating records, confirm what you're about to create before doing it.
Be concise. Format numbers and dates in a human-readable way.`
 
  while (true) {
    const response = await client.messages.create({
      model: 'claude-sonnet-4-7',
      max_tokens: 4096,
      system: systemPrompt,
      tools: salesforceTools,
      messages,
    })
 
    // Add assistant's response to message history
    messages.push({ role: 'assistant', content: response.content })
 
    // If no more tool calls, return the final text response
    if (response.stop_reason === 'end_turn') {
      const textBlock = response.content.find((b) => b.type === 'text')
      return textBlock?.type === 'text' ? textBlock.text : 'Done.'
    }
 
    // Process all tool calls in this response
    const toolResults: Anthropic.ToolResultBlockParam[] = []
 
    for (const block of response.content) {
      if (block.type !== 'tool_use') continue
 
      console.log(`→ Tool call: ${block.name}`, block.input)
      const result = await executeTool(block.name, block.input as Record<string, unknown>, auth)
      console.log(`← Result preview:`, result.slice(0, 200))
 
      toolResults.push({
        type: 'tool_result',
        tool_use_id: block.id,
        content: result,
      })
    }
 
    messages.push({ role: 'user', content: toolResults })
  }
}

// index.ts
import { runAgent } from './lib/agent'
 
async function main() {
  const queries = [
    "What are the 5 most recent opportunities closing this quarter?",
    "How many open cases does Acme Corp have right now?",
    "Create a task for John Smith to follow up on the Q3 renewal, due next Friday.",
  ]
 
  for (const query of queries) {
    console.log(`\nUser: ${query}`)
    const result = await runAgent(query)
    console.log(`Agent: ${result}`)
  }
}
 
main().catch(console.error)

// lib/agent-production.ts
const MAX_TURNS = 10
const MAX_RETRIES = 3
const RETRY_DELAY_MS = 1000
 
async function withRetry<T>(fn: () => Promise<T>, retries = MAX_RETRIES): Promise<T> {
  for (let attempt = 0; attempt < retries; attempt++) {
    try {
      return await fn()
    } catch (err: unknown) {
      const isRateLimit = err instanceof Error && err.message.includes('rate_limit')
      const isLast = attempt === retries - 1
      if (isLast || !isRateLimit) throw err
      const backoff = RETRY_DELAY_MS * Math.pow(2, attempt)
      console.warn(`Rate limited — retrying in ${backoff}ms (attempt ${attempt + 1}/${retries})`)
      await new Promise(r => setTimeout(r, backoff))
    }
  }
  throw new Error('Max retries exceeded')
}
 
export async function runAgentSafe(userMessage: string): Promise<string> {
  const auth = await getSalesforceToken()
  const messages: Anthropic.MessageParam[] = [{ role: 'user', content: userMessage }]
  let turns = 0
 
  while (turns < MAX_TURNS) {
    turns++
 
    const response = await withRetry(() =>
      client.messages.create({
        model: 'claude-sonnet-4-7',
        max_tokens: 4096,
        system: systemPrompt,
        tools: salesforceTools,
        messages,
      })
    )
 
    messages.push({ role: 'assistant', content: response.content })
 
    if (response.stop_reason === 'end_turn') {
      const textBlock = response.content.find((b) => b.type === 'text')
      return textBlock?.type === 'text' ? textBlock.text : 'Done.'
    }
 
    if (response.stop_reason === 'max_tokens') {
      return 'Agent response was truncated — try a more specific question or reduce result set.'
    }
 
    const toolResults: Anthropic.ToolResultBlockParam[] = []
 
    for (const block of response.content) {
      if (block.type !== 'tool_use') continue
 
      let result: string
      try {
        result = await executeTool(block.name, block.input as Record<string, unknown>, auth)
      } catch (err: unknown) {
        // Return the error as a tool result — Claude can reason over failures
        result = JSON.stringify({
          error: true,
          message: err instanceof Error ? err.message : String(err),
        })
      }
 
      toolResults.push({ type: 'tool_result', tool_use_id: block.id, content: result })
    }
 
    messages.push({ role: 'user', content: toolResults })
  }
 
  return 'Agent exceeded maximum turns — possible loop detected. Check tool definitions.'
}

// In executeTool, before returning to Claude:
function summarizeQueryResult(result: Record<string, unknown>): string {
  const records = (result.records ?? []) as Record<string, unknown>[]
 
  if (records.length === 0) return 'No records found.'
 
  // Return count + first 5 records only
  const preview = records.slice(0, 5)
  const summary = `Found ${records.length} record(s). Showing first ${preview.length}:\n`
  return summary + JSON.stringify(preview, null, 2)
}