Salesforce Agentforce는 기업용 AI를 수동적인 챗봇에서 자율적으로 판단하고 작업을 수행하는 자율형 에이전트(Autonomous Agents)로 진화시키고 있습니다. 실제 엔터프라이즈 환경에서 에이전트는 지식 기반 문서 검색에 기반한 단순 응답을 넘어, 고객의 의도를 정확히 파악하고 사내 전문 도구를 호출하며 실시간 트랜잭션을 실행한 뒤 결과를 평가하여 다음 업무 단계를 결정해야 합니다.
기본 제공되는 표준 액션(Standard Actions)은 이메일 초안 작성이나 레코드 요약과 같은 일상적인 CRM 작업에 집중되어 있습니다. 그러나 엔터프라이즈 실무에서는 독자적인 비즈니스 규칙 적용, 레거시 시스템을 아우르는 다단계 트랜잭션, 실시간 외부 데이터 연동이 필수적입니다. Salesforce 개발자와 엔터프라이즈 아키텍트는 다음 세 가지 핵심 기술 요소를 활용하여 **커스텀 액션(Custom Actions)**을 구축함으로써 Agentforce의 기능을 확장해야 합니다.
- Invocable Apex 메서드: 복잡한 계산, 정밀한 유효성 검사, 대량 데이터 처리 및 결정론적 실행이 필요한 프로그래밍 로직.
- 헤드리스 자동 실행 플로우(Autolaunched Flow): 관리자나 로우코드 개발자가 빠르게 유지보수할 수 있는 표준 CRM CRUD 및 승인 워크플로.
- External Services 및 API Catalog 기반 MuleSoft API: SAP, Oracle 등의 핵심 ERP, 결제 게이트웨이 및 사외 마이크로서비스를 에이전트 런타임에 직접 연결하는 엔터프라이즈 통합 브리지.
본 가이드에서는 세 가지 액션 유형의 아키텍처 원리, 단계별 구현 방법, 컨텍스트 엔지니어링(Context Engineering) 모범 사례 및 보안 거버넌스 전략을 상세히 설명합니다.
1. 핵심 아키텍처: Atlas 추론 엔진이 액션을 이해하고 실행하는 원리
오류와 환각(Hallucination) 없는 안정적인 액션을 구축하려면 먼저 Agentforce의 핵심 두뇌인 **Atlas 추론 엔진(Atlas Reasoning Engine)**의 작동 메커니즘을 이해해야 합니다.
[ 사용자 상호작용 / 옴니채널 접점 ]
│
▼
[ Atlas 추론 엔진 ]
(ReAct: 추론 - 행동 - 관찰)
│
┌───────────┼───────────┐
▼ ▼ ▼
[ 토픽 분류 식별 ] │ [ 비즈니스 가드레일 및 컨텍스트 ]
│ │
└─────┬─────┘
▼
[ 액션 / 도구 선택 ]
│
┌─────────┼─────────┐
▼ ▼ ▼
[ Apex ] [ Flow ] [ MuleSoft / API ]
│ │ │
└─────────┼─────────┘
▼
[ 실행 결과 구조화 출력 관찰 ]
│
▼
[ 최종 응답 생성 또는 후속 액션 연계 ]
ReAct 패턴과 컨텍스트 엔지니어링
Atlas 엔진은 Reason-Act-Observe(추론-행동-관찰) 루프를 기반으로 동작합니다.
- 추론(Reason): 사용자의 대화 입력이나 이벤트를 분석하고, 설정된 토픽(Topics) 범위 내에서 의도를 충족할 수 있는 전용 도구(액션)를 결정합니다.
- 행동(Act): 대화 컨텍스트에서 필요한 매개변수를 추출하여 액션의 입력 스키마에 매핑한 뒤 실행을 트리거합니다.
- 관찰(Observe): 액션이 반환한 구조화된 출력 데이터를 검토하여 목표가 달성되었는지 평가하고, 후속 액션을 호출할지 자연어 응답을 반환할지 결정합니다.
전통적인 프로그래밍에서는 엄격한 타입과 직접적인 메서드 호출을 통해 모듈이 연결되지만, 자율형 에이전트 환경에서는 메타데이터가 곧 프롬프트입니다. 대규모 언어 모델은 Apex 클래스의 내부 코드를 직접 분석하지 못하며, 액션의 label, description, 입력 매개변수 주석 및 자연어 액션 지침(Action Instructions)을 해석하여 동작합니다. 모호한 설명은 도구 오작동과 매개변수 누락을 유발하며, 명확하고 구체적인 설명만이 결정론적이고 안정적인 실행을 보장합니다.
2. Invocable Apex를 커스텀 액션으로 구축 및 노출
복잡한 알고리즘 계산, 다중 객체 트랜잭션, 정밀한 보안 검증이 필요한 경우 Invocable Apex가 가장 이상적인 선택지입니다.
1단계: Invocable Apex 클래스 구현
Agentforce는 @InvocableMethod 주석을 통해 Apex 메서드를 식별합니다. 메서드는 public 또는 global 정적(static) 메서드여야 하며, 입력 래퍼 객체 리스트(List)를 인수로 받아 출력 래퍼 객체 리스트(List)를 반환해야 합니다.
다음은 고객 주문 취소 로직을 구현한 엔터프라이즈급 Apex 예제입니다.
public with sharing class OrderCancellationService {
// 입력 래퍼 클래스: 에이전트가 필요로 하는 입력 매개변수 정의
public class OrderCancellationRequest {
@InvocableVariable(
label = 'Order Number'
description = '취소할 주문의 고유 식별 번호 (예: ORD-10023).'
required = true
)
public String orderNumber;
@InvocableVariable(
label = 'Cancellation Reason'
description = '고객이 제시한 주문 취소 사유.'
required = false
)
public String reason;
}
// 출력 래퍼 클래스: Atlas 추론 엔진에 반환할 구조화된 결과
public class OrderCancellationResult {
@InvocableVariable(
label = 'Is Success'
description = '주문 취소가 성공적으로 완료되었는지를 나타내는 불리언 값.'
)
public Boolean isSuccess;
@InvocableVariable(
label = 'Cancellation Reference Code'
description = '취소 확정 후 발급된 감사 추적용 참조 코드.'
)
public String referenceCode;
@InvocableVariable(
label = 'Status Message'
description = '처리 결과 안내 또는 상세 오류 원인 설명.'
)
public String message;
}
@InvocableMethod(
label = 'Cancel Customer Order'
description = '대기 중인 고객 주문을 취소하고 감사 코드를 발급합니다. 주문 상태가 Pending 또는 Processing이며 고객이 명시적으로 취소를 요청한 경우에만 실행하십시오.'
category = 'Order Management'
)
public static List<OrderCancellationResult> cancelOrders(List<OrderCancellationRequest> requests) {
List<OrderCancellationResult> results = new List<OrderCancellationResult>();
for (OrderCancellationRequest req : requests) {
OrderCancellationResult res = new OrderCancellationResult();
try {
// 사용자 모드 보안 검증 적용
List<Order> orders = [
SELECT Id, Status, TotalAmount
FROM Order
WHERE OrderNumber = :req.orderNumber
WITH USER_MODE
LIMIT 1
];
if (orders.isEmpty()) {
res.isSuccess = false;
res.message = '해당 주문 번호와 일치하는 활성 주문을 찾을 수 없습니다: ' + req.orderNumber;
results.add(res);
continue;
}
Order targetOrder = orders[0];
if (targetOrder.Status == 'Activated' || targetOrder.Status == 'Completed') {
res.isSuccess = false;
res.message = '주문 ' + req.orderNumber + '는 이미 배송되었거나 완료되어 자동 취소할 수 없습니다.';
results.add(res);
continue;
}
targetOrder.Status = 'Cancelled';
targetOrder.Description = 'Agentforce를 통해 취소됨. 사유: ' + (req.reason != null ? req.reason : '미지정');
Database.SaveResult sr = Database.update(targetOrder, AccessLevel.USER_MODE);
if (sr.isSuccess()) {
res.isSuccess = true;
res.referenceCode = 'CAN-' + System.currentTimeMillis();
res.message = '주문이 성공적으로 취소되었습니다.';
} else {
res.isSuccess = false;
res.message = '데이터베이스 레코드 업데이트에 실패했습니다.';
}
} catch (Exception ex) {
res.isSuccess = false;
res.message = '주문 취소 처리 중 내부 오류가 발생했습니다: ' + ex.getMessage();
}
results.add(res);
}
return results;
}
}
Apex 개발 모범 사례
- 단일 책임 원칙 준수: 조회, 결제 취소, 재고 복구, 배송 중단을 하나의 거대한 만능 클래스(God Class)에 몰아넣지 마십시오. 액션을 원자적 단위로 세분화해야 Atlas 엔진이 필요한 순서대로 도구를 조합하여 추론할 수 있습니다.
- 예외 발생 대신 구조화된 오류 반환: 처리되지 않은 Exception이 런타임에 발생하면 에이전트 대화가 중단됩니다.
try-catch로 예외를 포착하여isSuccess = false와 원인이 명시된message를 반환하면 에이전트가 고객에게 상황을 설명하거나 누락된 정보를 재질문할 수 있습니다. - 사용자 모드 보안 강제:
with sharing을 선언하고 SOQL에서WITH USER_MODE, DML에서AccessLevel.USER_MODE를 사용하여 에이전트 실행 사용자의 권한 범위를 엄격히 준수하십시오.
2단계: Setup에서 에이전트 액션 등록
- Salesforce **설정(Setup)**에서 빠른 찾기에
Agent를 입력하고 Agentforce Assets(또는 Agent Actions)를 선택합니다. - **New Agent Action(새 에이전트 액션)**을 클릭합니다.
- **Reference Action Type(참조 액션 유형)**으로 Apex를 선택합니다.
- 배포된 클래스
OrderCancellationService와 메서드Cancel Customer Order를 선택합니다. - 코드 주석에서 자동 로드된 라벨과 파라미터 설명을 확인합니다.
- **Action Instructions(액션 지침)**에 호출 조건(예: “인증된 고객이 명시적으로 주문 취소를 요청할 때만 실행할 것. 주문 번호가 누락된 경우 반드시 먼저 되물을 것”)을 명시합니다.
- 저장합니다.
3. 헤드리스 Flow를 커스텀 액션으로 구축 및 노출
표준 CRM 레코드 변경, 기존 승인 프로세스 연동 및 선언적 비즈니스 로직 재사용의 경우 Autolaunched Flow가 뛰어난 개발 민첩성을 제공합니다.
플로우 유형 제한
Agentforce는 **트리거가 없는 자동 실행 플로우(Autolaunched Flow - No Trigger)**만 호출할 수 있습니다. 화면 플로우(Screen Flow)는 사용자 화면 UI 렌더링이 필요하고, 레코드 트리거 플로우는 DB 이벤트에 반응하므로 에이전트 액션으로 직접 등록할 수 없습니다. 헤드리스 플로우만이 에이전트 요청-응답 모델에 완벽히 부합합니다.
[ 사용자 발화: "배송지 주소를 서울시 테헤란로 123으로 변경해 줘" ]
│
▼
[ Agentforce 액션 플래너 ]
│
(파라미터 추출: orderId, streetAddress, city)
│
▼
[ Autolaunched Flow: 주문 배송지 주소 변경 ]
┌─────────────────────────┐
│ Get Records: 주문 조회 │
├─────────────────────────┤
│ Decision: 배송 완료 여부 │
├─────────────────────────┤
│ Update Records: 주소 변경│
└─────────────────────────┘
│
(출력 변수: isUpdated = True, confirmationMsg)
│
▼
[ Atlas 최종 자연어 응답 생성 ]
플로우 구성 단계
- 플로우 생성: Flow Builder를 열고 **Autolaunched Flow (No Trigger)**를 선택합니다.
- 입력 변수 정의:
- 텍스트 변수
var_orderId를 생성하고 **입력에 사용 가능(Available for input)**을 선택합니다. - **Description(설명)**에 *“대상 주문 레코드의 18자리 Salesforce Record ID”*를 명시합니다.
- 필요한 추가 입력 변수(
var_streetAddress등)를 생성하고 상세 설명을 추가합니다.
- 텍스트 변수
- 출력 변수 정의:
- 불리언 변수
var_isUpdated를 생성하고 **출력에 사용 가능(Available for output)**을 선택합니다. 설명: “주소 업데이트가 성공적으로 커밋되면 True”. - 텍스트 변수
var_statusMessage를 생성하여 출력 가능으로 설정합니다.
- 불리언 변수
- 선언적 로직 구현:
- Get Records로 주문 조회.
- Decision으로 주소 변경 가능 상태인지 검증.
- 조건 충족 시 Update Records로 새 주소 반영.
- Assignment로 출력 변수 값 지정.
- 저장 및 활성화: 플로우를
Agent_Update_Order_Address로 저장하고 활성화합니다.
3단계: 플로우 액션 등록
- Setup > Agentforce Assets > New Agent Action으로 이동합니다.
- Reference Action Type으로 Flow를 선택합니다.
Agent_Update_Order_Address플로우를 선택합니다.- 열려 있는 입출력 변수의 설명이 LLM이 이해하기 쉬운 자연어로 기술되어 있는지 검토합니다.
- 액션 지침을 작성하고 저장합니다.
4. External Services 및 API Catalog를 통한 MuleSoft API 노출
기업용 에이전트는 SAP, Oracle과 같은 기간계 ERP, 외부 물류 시스템, 결제 허브와 실시간 연동해야 하는 경우가 많습니다. MuleSoft는 엔터프라이즈 통합을 관장하며, Salesforce는 **External Services(외부 서비스)**와 **API Catalog(API 카탈로그)**를 통해 해당 API를 에이전트 액션으로 자동 매핑합니다.
두 가지 통합 방식 비교
| 연동 방식 | 기술 메커니즘 | 최적 사용 시나리오 |
|---|---|---|
| MuleSoft for Agentforce: Topic Center 및 API Catalog 동기화 | Anypoint Platform Topic Center에서 사양을 정의하고 Salesforce API Catalog로 동기화 | 중앙 API 조직이 Anypoint Platform 거버넌스를 주도하는 대규모 엔터프라이즈. |
| External Services for MuleSoft 직접 가져오기 | Named Credentials와 OpenAPI 3.0/2.0 규격을 통해 직접 액션 생성 | 점대점 연동, 특정 시스템 API를 Flow 및 에이전트에 빠르게 연결해야 하는 경우. |
[ 기간계 ERP / SAP / 외부 데이터베이스 ]
│
▼
[ MuleSoft Anypoint Platform ]
(System, Process, Experience APIs)
│
(Topic Center 관리 / OAS 3.0 사양)
│
▼
[ Salesforce Anypoint 연결 및 동기화 ]
│
┌────────────┴────────────┐
▼ ▼
[ Named Credentials ] [ Salesforce API Catalog ]
(인증 및 자격 증명) (엔터프라이즈 API 검색)
│ │
└────────────┬────────────┘
▼
[ External Services ]
(Invocable 액션 자동 생성)
│
▼
[ Agentforce 커스텀 액션 라이브러리 ]
1단계: AI 친화적인 OpenAPI 사양(OAS) 설계
Atlas 엔진은 OpenAPI 문서를 해석하여 경로 매개변수와 요청 본문을 파악합니다. 에이전트용 API는 다음 원칙을 준수해야 합니다.
- 모든 필드에 명확한 설명 제공: 경로 변수, 쿼리 파라미터 및 JSON 속성에 구체적인
description을 기재합니다. - 스키마 단순화: 다형성(
oneOf,anyOf)이나 지나치게 깊은 중첩 구조를 피하고 평탄화된 데이터 스키마를 구성하여 매개변수 추출 오류를 줄입니다. - 의미 있는 HTTP 상태 코드 및 오류 바디: 200 응답뿐만 아니라 400, 404, 500 오류 시에도 사유가 명시된 JSON 응답을 반환하도록 정의합니다.
재고 조회 API의 OpenAPI 3.0 사양 예제:
openapi: 3.0.3
info:
title: Enterprise Warehouse API
version: 1.0.0
description: 물류창고 실시간 재고 조회 서비스.
paths:
/inventory/{sku}:
get:
summary: 상품 SKU 기준 물류창고 가용 재고 조회
description: 제품 SKU 코드를 기반으로 각 창고의 가용 재고 수량, 출고 가능 여부 및 재입고 리드타임을 반환합니다.
operationId: getInventoryBySku
parameters:
- name: sku
in: path
required: true
description: 제품 고유 식별 코드 (예: PROD-WIDGET-99).
schema:
type: string
responses:
'200':
description: 재고 조회 성공
content:
application/json:
schema:
type: object
properties:
sku:
type: string
description: 조회된 제품 SKU 코드.
quantityOnHand:
type: integer
description: 물류창고 실물 재고 수량.
isAvailableToShip:
type: boolean
description: 즉시 출고 가능 여부.
warehouseRegion:
type: string
description: 담당 물류 허브 권역.
'404':
description: 재고 목록에서 해당 SKU를 찾을 수 없음
2단계: Salesforce 동기화 및 액션 생성
- Anypoint 플랫폼 연결: Salesforce 설정의 Anypoint Platform Setup에서 조직 ID와 클라이언트 자격 증명으로 연결을 구성합니다.
- API 카탈로그 동기화: MuleSoft Topic Center 또는 Exchange에서 대상 API에
sf-api-catalog태그를 부여하고, Salesforce의 API Catalog 화면에서 필요한 엔드포인트를 액션으로 활성화합니다. - Named Credentials 구성: OAuth 2.0 기반의 지정된 자격 증명을 설정하여 아웃바운드 호출의 보안을 확보합니다.
- 에이전트 액션 생성: Agentforce Assets에서 External Service 유형으로 액션을 생성하고 해당 작업을 연결합니다.
5. Agentforce Builder에서 토픽 구성 및 액션 배치
구축된 커스텀 액션은 Agentforce Builder 내의 **토픽(Topics)**에 할당되어야만 런타임에 에이전트가 식별하고 실행할 수 있습니다. 토픽은 업무 도메인을 분리하고 도구 사용 범위를 제어하는 핵심 경계선입니다.
[ 자율형 에이전트: 고객 서비스 전담 에이전트 ]
│
┌───────────────┴───────────────┐
▼ ▼
[ 토픽: 주문 물류 및 변경 ] [ 토픽: 반품 및 기술 지원 ]
(업무 범위 및 라우팅) (업무 범위 및 라우팅)
│
┌───┴───────────────────────────────┐
▼ ▼
[ 액션: 주문 상태 조회 ] [ 액션: 주문 취소 실행 ]
(Autolaunched Flow) (Invocable Apex)
토픽 할당 절차
- Setup에서 Agentforce Builder를 실행하고 대상 에이전트를 편집 모드로 엽니다.
- 기존 토픽을 선택하거나 New Topic을 생성합니다(예: Order Logistics and Changes).
- **Topic Classification Description(토픽 분류 설명)**에 어떤 고객 질문이 이 토픽에 해당하는지 명확히 기술합니다.
- 토픽의 Actions 탭에서 Add Action을 클릭하여 등록된 Apex, Flow, MuleSoft 액션을 추가합니다.
고품질 토픽 및 액션 지침 작성
자연어 지침(Instructions)은 에이전트의 의사결정을 이끄는 핵심 가이드라인입니다.
### 토픽 지침: Order Logistics and Changes
- 주문 배송 추적, 상태 문의, 배송지 주소 변경 및 주문 취소 요청을 지원합니다.
- 주문을 취소하기 전에 반드시 현재 상태를 확인하고 고객에게 취소 의사를 재확인하십시오.
- 이미 배송이 완료되어 취소가 불가한 경우, 정중히 사유를 안내하고 반품 절차를 제시하십시오.
### 액션 지침: Cancel Customer Order
- 고객이 주문 번호를 명확히 제공하고 취소 확인 질문에 동의한 경우에만 실행하십시오.
- 주문 번호가 누락된 경우 "취소하시려는 주문 번호를 알려주시겠습니까?"라고 되물으십시오.
- 실행 완료 후 반환된 취소 감사 코드(referenceCode)를 고객에게 반드시 안내하십시오.
Human-in-the-Loop(사전 확인 절차)
데이터 레코드 변경, 결제 처리, 취소 등 비가역적인 액션의 경우 설정에서 **Require Confirmation(확인 요구)**을 활성화하십시오. 이를 통해 에이전트는 백엔드 로직을 실행하기 전 "ORD-10023 주문을 정말 취소하시겠습니까? 이 작업은 되돌릴 수 없습니다"와 같은 확인 대화를 거치도록 강제할 수 있습니다.
6. 기술 선정 아키텍처 비교 매트릭스
요구사항에 맞춰 최적의 기술을 선택하면 개발 생산성, 유지보수 편의성 및 시스템 응답 속도를 극대화할 수 있습니다.
| 평가 기준 | Invocable Apex | Autolaunched Flow | MuleSoft External Services |
|---|---|---|---|
| 주요 개발 담당 | Salesforce 전문 개발자 (Apex) | 시스템 관리자 / 로우코드 개발자 | 엔터프라이즈 통합 아키텍트 / MuleSoft 개발자 |
| 실행 런타임 환경 | Salesforce 코어 플랫폼 내부 | Salesforce 코어 플랫폼 내부 | 사외 기간계 시스템 및 분산 마이크로서비스 |
| 최적의 사용 사례 | 고난도 연산, 다중 객체 정합성 제어, 특수 인증, 배치 처리 | 표준 CRM CRUD, 승인 절차 연동, 기존 비즈니스 플로우 재사용 | ERP(SAP/Oracle) 재고 동기화, 대외 결제 게이트웨이, 물류 추적 |
| 거버너 제한 및 지연 시간 | Apex 동기 CPU 시간 (10초), SOQL/DML 제한 | Flow 요소 실행 수 및 루프 카운트 제한 | 외부 네트워크 지연 시간에 종속, 최대 120초 콜아웃 타임아웃 |
| 형상 및 버전 관리 | Git, SFDX 및 메타데이터 패키징 | Flow Builder 선언적 버전 활성화 관리 | Anypoint Exchange 계약 관리 및 API 거버넌스 |
| 예외 처리 방식 | 강력한 try-catch 캡처 및 구조화 래퍼 반환 | Fault Connector 오류 분기 및 할당 | 표준 HTTP 상태 코드(2xx/4xx/5xx) 및 JSON 바디 |
7. 테스트 검증, 권한 거버넌스 및 배포 전략
1. Agent User 권한 및 실행 컨텍스트
에이전트가 액션을 수행할 때의 접근 권한은 설정된 Agent User에 종속됩니다. 실운영 환경에서 발생하는 대부분의 오류는 권한 누락에서 비롯됩니다.
- Apex 클래스 권한: Agent User의 프로필 또는 권한 집합에 대상 Apex 클래스 접근 권한을 부여하십시오.
- 플로우 실행 권한: Agent User에게 Run Flows 시스템 권한이 부여되어 있는지 확인하십시오.
- 지정된 자격 증명 및 필드 레벨 보안(FLS): MuleSoft 호출을 위한 Named Credential 권한과 대상 객체/필드의 FLS 읽기/쓰기 권한을 확인하십시오.
2. 다계층 테스트 및 품질 보증
- Apex 단위 테스트: 코드 커버리지 85% 이상을 달성하는 테스트 클래스를 작성하여 null 입력, 권한 부족 상황 및 예외 처리를 검증합니다.
- Agentforce Builder 실시간 대화 테스트: 테스트 패널에서 다양한 고객 질문을 입력하고 Reasoning 탭을 통해 Atlas 엔진이 올바른 토픽을 인식하고 매개변수를 추출하는지 추적합니다.
- Agentforce Testing Center 일괄 평가: 대량의 평가 데이터셋을 구성하여 수백 개의 사용자 발화를 테스트하고 도구 선택 정확도, 매개변수 매핑율 및 환각 발생 빈도를 측정합니다.
Invocable Apex의 정밀한 제어력, Autolaunched Flow의 빠른 선언적 생산성, 그리고 MuleSoft API의 강력한 엔터프라이즈 연결성을 결합함으로써, 기업은 확장 가능하고 안전한 차세대 AI 에이전트 인프라를 완성할 수 있습니다.
참고 자료
- Agent Customization with Apex | Salesforce Trailhead
- Learn How to Make Agent-Ready Flows | Salesforce Trailhead
- How to Write Effective Natural Language Instructions for Agentforce | Salesforce Developers Blog
- A Developer’s Guide to Context Engineering with Agentforce | Salesforce Developers Blog
- Salesforce Agentforce Specialist Certification Guide & Tips | Salesforce Ben
- External Services | Salesforce Help