ExternalAPIIntegration Agent

Overview

Learn how to integrate external APIs and systems using Flow and Apex targets. This recipe demonstrates patterns for calling weather APIs, payment gateways, and shipping trackers.

Agent Flow

%%{init: {'theme':'neutral'}}%%
graph TD
    A[User Request] --> B[start_agent routes to api_integration]
    B --> C{User Intent?}
    C -->|Weather| D[fetch_weather Action]
    C -->|Payment| E[make_payment Action]
    C -->|Tracking| F[check_tracking Action]
    D --> G[Apex: WeatherService]
    E --> H[Apex: PaymentGatewayController]
    F --> I[Flow: TrackShipment]
    G --> J[Capture: temperature, humidity, conditions]
    H --> K[Capture: transactionId, status, success]
    I --> L[Capture: status, estimated_delivery]
    J --> M[Display Results]
    K --> M
    L --> M
    M --> N{More Requests?}
    N -->|Yes| C
    N -->|No| O[End]

Key Concepts

• Flow targets (flow://): Call external APIs via Salesforce Flows
• Apex targets (apex://): Call external APIs via Apex classes
• API response handling: Capture outputs from external calls
• Error tracking: Monitor API success/failure status
• Multiple integrations: Different services, different targets

How It Works

Apex-Based Integration (Weather)

actions:
   get_weather:
      description: "Fetch weather data from external API via Flow"
      inputs:
         cityName: string
      outputs:
         temperature: number
         conditions: string
         humidity: number
         success: boolean
         error_message: string
      target: "apex://WeatherService"

Apex-Based Integration (Payment)

actions:
   process_payment:
      description: "Process payment via external payment gateway using Apex"
      inputs:
         amount: number
         paymentToken: string
         currencyName: string
      outputs:
         transactionId: string
         status: string
         success: boolean
         errorMessage: string
      target: "apex://PaymentGatewayController"

Flow-Based Integration (Shipping)

actions:
   track_shipment:
      description: "Track shipment via external shipping API"
      inputs:
         tracking_number: string
         carrier: string
      outputs:
         status: object
         estimated_delivery: string
         success: boolean
      target: "flow://TrackShipment"

Using Actions in Reasoning

reasoning:
   instructions:->
      | Identify the action based on the user's request. You can:
        - Get weather
        - Process payment
        - Track shipment

      | If an action needs user input, prompt the user for the needed info before
        performing the action. For example:
        - Weather: need city name
        - Payment: need amount and payment token
        - Shipping: need tracking number

   actions:
      fetch_weather: @actions.get_weather
         with cityName= ...
         set @variables.temperature = @outputs.temperature
         set @variables.humidity = @outputs.humidity
         set @variables.conditions = @outputs.conditions
         set @variables.api_response_status = ""
         set @variables.api_error_message = ""

      make_payment: @actions.process_payment
         with amount=...
         with paymentToken=...
         with currencyName="USD"
         set @variables.transaction_id = @outputs.transactionId
         set @variables.api_response_status = @outputs.success
         set @variables.api_error_message = @outputs.errorMessage

      check_tracking: @actions.track_shipment
         with tracking_number=...
         with carrier="USPS"
         set @variables.shipment_status = @outputs.status
         set @variables.api_response_status = @outputs.success

Key Code Snippets

Variables for API State

variables:
   # API tracking
   api_request_id: mutable string = ""
   api_response_status: mutable string = ""
   api_error_message: mutable string = ""

   # Weather API example
   temperature: mutable string = ""
   humidity: mutable string = ""
   conditions: mutable string = ""

   # Payment API example
   transaction_id: mutable string = ""

   # Shipping API example
   shipment_status: mutable object = {}

Complete Action Definitions

actions:
   get_weather:
      description: "Fetch weather data from external API via Flow"
      inputs:
         cityName: string
      outputs:
         temperature: number
         conditions: string
         humidity: number
         success: boolean
         error_message: string
      target: "apex://WeatherService"

   process_payment:
      description: "Process payment via external payment gateway using Apex"
      inputs:
         amount: number
         paymentToken: string
         currencyName: string
      outputs:
         transactionId: string
         status: string
         success: boolean
         errorMessage: string
      target: "apex://PaymentGatewayController"

   track_shipment:
      description: "Track shipment via external shipping API"
      inputs:
         tracking_number: string
         carrier: string
      outputs:
         status: object
         estimated_delivery: string
         success: boolean
      target: "flow://TrackShipment"

Try It Out

Example: Weather Lookup

Agent: I can integrate with external APIs for weather, payments, and shipping!

User: What's the weather in San Francisco?

[Agent calls get_weather via Apex]
  - WeatherService.getWeather("San Francisco")
  - Returns: temperature=65, conditions="Partly Cloudy", humidity=72

Agent: Weather in San Francisco:
       🌤️ Partly Cloudy
       Temperature: 65°F
       Humidity: 72%

Example: Payment Processing

User: Process a payment of $50

Agent: I'll need a payment token to process this. Do you have one?

User: Yes, the token is PAY-TOKEN-123

[Agent calls process_payment via Apex]
  - PaymentGatewayController.process(50, "PAY-TOKEN-123", "USD")
  - Returns: transactionId="TXN-789", status="approved", success=true

Agent: ✅ Payment processed successfully!

       Transaction ID: TXN-789
       Amount: $50.00
       Status: Approved

Example: Shipment Tracking

User: Track my shipment 1Z999AA10123456784

[Agent calls track_shipment via Flow]
  - TrackShipment flow with tracking_number and carrier="USPS"
  - Returns: status object, estimated_delivery="2025-01-22"

Agent: 📦 Shipment Status:

       Tracking: 1Z999AA10123456784
       Status: In Transit
       Estimated Delivery: January 22, 2025

Integration Patterns

Pattern 1: Simple API Call

fetch_data: @actions.api_call
   with param=...
   set @variables.result = @outputs.data

Pattern 2: With Error Capture

fetch_data: @actions.api_call
   with param=...
   set @variables.result = @outputs.data
   set @variables.success = @outputs.success
   set @variables.error = @outputs.error_message

Pattern 3: Fixed Default Parameters

make_payment: @actions.process_payment
   with amount=...
   with paymentToken=...
   with currencyName="USD"  # Fixed default

Best Practices

✅ Always capture success status - Check if API call succeeded

✅ Store error messages - For user feedback

✅ Use appropriate targets - Flow for simple, Apex for complex

✅ Prompt for required inputs - Don't call APIs without needed data

❌ Don't assume success - Always verify response

❌ Don't expose raw errors - Show user-friendly messages

What's Next

• ErrorHandling: Build robust error handling
• MultiStepWorkflows: Chain multiple API calls
• ActionCallbacks: Process API results

Testing

Test Case 1: Successful API Call

• Provide valid inputs
• Verify API called correctly
• Check outputs captured

Test Case 2: API Error

• Trigger API failure
• Verify error captured
• Check graceful handling

Test Case 3: Missing Input

• Don't provide required input
• Verify agent prompts for it