2471 Migration Guide 94434e6c

Migration Guide: Agentforce Builder UI → Agent Script DSL

This guide maps every concept from the Agentforce Builder UI (Setup > Agents) to its Agent Script DSL equivalent. Use it when converting existing agents from the visual builder to code.

Builder UI → Agent Script Mapping

What's New in Agent Script (No Builder UI Equivalent)

These capabilities exist ONLY in Agent Script — they cannot be configured through the Builder UI:

Side-by-Side: Simple Topic

Builder UI Configuration

Topic Name: Order Lookup
Classification: Handles customer order status inquiries

Instructions:
  1. Ask the customer for their order number
  2. Look up the order using the Get Order Details action
  3. Share the order status with the customer

Actions:
  - Get Order Details (Flow: Get_Order_Details)
    Input: order_id (Collect from user)
    Output: status, estimated_delivery

Agent Script Equivalent

topic order_lookup:
   description: "Handles customer order status inquiries"

   actions:
      get_order_details:
         description: "Retrieves order information by order ID"
         inputs:
            order_id: string
               description: "Customer's order number"
         outputs:
            status: string
               description: "Current order status"
            estimated_delivery: string
               description: "Estimated delivery date"
         target: "flow://Get_Order_Details"

   reasoning:
      instructions: ->
         # Post-action check (if order was already looked up)
         if @variables.order_status != "":
            | Your order status is: {!@variables.order_status}
            | Estimated delivery: {!@variables.estimated_delivery}

         | I can help you check your order status.
         | Please provide your order number.
      actions:
         lookup: @actions.get_order_details
            with order_id = ...
            set @variables.order_status = @outputs.status
            set @variables.estimated_delivery = @outputs.estimated_delivery

Key differences in the Agent Script version:

• Explicit action definition with typed inputs/outputs and target
• Post-action check pattern (at TOP of instructions) enables deterministic routing after the action completes
• Variable injection ({!@variables.X}) for dynamic text
• Slot-fill (...) replaces "Collect from user"

Side-by-Side: Verification Gate

Builder UI Configuration

Topic Name: Identity Verification
Classification: Verifies customer identity before accessing account

Instructions:
  1. Ask the customer for their email address
  2. Use the Verify Identity action to check their email
  3. If verified, route to the Account Management topic
  4. After 3 failed attempts, escalate to a human agent

Actions:
  - Verify Identity (Apex: VerifyIdentityAction)
    Input: email (Collect from user)
    Output: verified (boolean)
  - Go to Account Management (Topic Transition)
  - Escalate (Escalate to Agent)

Agent Script Equivalent

variables:
   customer_verified: mutable boolean = False
   failed_attempts: mutable number = 0

topic identity_verification:
   description: "Verifies customer identity before accessing account"

   actions:
      verify_identity:
         description: "Checks customer identity by email"
         inputs:
            email: string
               description: "Customer email address"
         outputs:
            verified: boolean
               description: "Whether identity was verified"
         target: "apex://VerifyIdentityAction"

   reasoning:
      instructions: ->
         # Gate: Too many failures → escalate
         if @variables.failed_attempts >= 3:
            | Too many failed attempts. Connecting you with a human agent.
            transition to @topic.escalation

         # Gate: Already verified → proceed
         if @variables.customer_verified == True:
            transition to @topic.account_management

         | Please provide your email address to verify your identity.
      actions:
         verify: @actions.verify_identity
            with email = ...
            set @variables.customer_verified = @outputs.verified
            if @outputs.verified == False:
               set @variables.failed_attempts = @variables.failed_attempts + 1
         go_account: @utils.transition to @topic.account_management
            description: "Proceed to account management"
            available when @variables.customer_verified == True
         escalate_now: @utils.escalate
            description: "Transfer to human agent"

Key differences in the Agent Script version:

• Deterministic gates at top of instructions (cannot be bypassed by LLM)
• Explicit failure counter with arithmetic
• available when guard ensures the "proceed" action is invisible until verified
• @utils.escalate replaces the UI "Escalate to Agent" button

Migration Checklist

When converting a Builder UI agent to Agent Script:

• Export current config: Document all topics, instructions, and actions from the UI
• Map each topic: Use the mapping table above to translate concepts
• Identify implicit logic: Builder UI often has implicit routing — make it explicit with if/else
• Add deterministic gates: Convert any "instruction-based" security to available when guards
• Define variables: Builder UI hides state management — declare all needed variables explicitly
• Set action targets: Ensure all Flows/Apex classes are deployed with correct API names
• Test incrementally: Validate each topic independently before combining
• Verify default_agent_user: Must be a valid Einstein Agent User in the target org

Common Migration Pitfalls

Last updated: 2026-02-12