에이전트 스크립트를 사용하여 에이전트 작성

학습 목표

이 뱃지에서는 다음 작업을 수행합니다.

• 에이전트 스크립트와 작성 번들에 대해 알아봅니다.
  
• 에이전트 스크립트 파일을 사용해 에이전트를 미리 봅니다.
  
• 에이전트 스크립트 파일을 업데이트 및 검증하여 에이전트를 코딩합니다.
  
• 에이전트를 조직에 게시합니다.
  
• 게시된 에이전트를 조직의 Agentforce 빌더 UI에서 확인합니다.
  

이 단계에서는 1단계에서 생성한 것과 동일한 Developer Edition 조직을 사용합니다.

참고

한국어로 학습하시겠어요? Trailhead playground에서 한국어로 실습 과제를 시작하고, 괄호 안에 제공된 번역을 사용해 탐색해 보세요. 영어 데이터를 기반으로 실습 과제 검증이 이루어지므로 영문으로 표시된 값만 복사해 붙여 넣습니다. 한국어 조직에서 실습 과제를 통과하지 못한 경우, (1) 로캘을 미국을 바꾸고 (2) 여기에 제시된 지침에 따라 언어를 영어로 바꾼 후 (3) "Check Challenge(과제 확인)" 버튼을 눌러 다시 진행해 보세요.

원하는 언어로 Trailhead 사용하기 뱃지를 확인해 현지화된 Trailhead 경험을 활용하는 방법에 대해 자세히 알아보세요.

에이전트 스크립트, 에이전트 청사진 알아보기

에이전트를 구축할 때는 특정한 수명 주기를 따르게 됩니다.

• 개발: 에이전트의 지침과 논리를 정의하기 위해 에이전트 스크립트 파일을 코딩합니다.
  
• 게시: 에이전트 스크립트 파일을 개발 조직에 배포하여 에이전트 메타데이터를 생성합니다.
  
• 테스트: Sandbox 또는 스크래치 조직에서 에이전트의 동작을 검증합니다.
  
• 배포: 에이전트 메타데이터를 프로덕션 환경으로 마이그레이션합니다.
  
• 활성화: 고객이 사용할 수 있도록 에이전트를 활성화합니다.
  

이 뱃지에서는 개발과 게시 단계에 중점을 둡니다.

에이전트 스크립트는 차세대 Agentforce 에이전트의 기반입니다. 자연어를 사용하여 코드를 직관적으로 구현하는 유연성과 비즈니스 규칙을 처리하기 위한 프로그래밍 식의 신뢰성을 모두 갖춘 언어입니다. 에이전트 스크립트는 대규모 언어 모델(LLM)을 활용할 수 있는 모든 장점을 제공하면서도, 에이전트에 더 결정론적인 동작을 추가할 수 있는 방법도 제공합니다.

Salesforce 내 대부분의 기능과 마찬가지로, 에이전트의 에이전트 스크립트 파일은 AiAuthoringBundle이라는 메타데이터 구성 요소의 일부이며, 이를 간단히 작성 번들이라고 합니다. CLI 명령이나 VS Code를 사용하여 DX 프로젝트에서 작성 번들을 처음부터 생성하거나, 코드를 직관적으로 구현하여 생성할 수 있습니다. 또는 Agentforce 빌더를 사용하여 조직에서 먼저 에이전트를 생성한 다음 작성 번들을 DX 프로젝트로 가져올 수도 있습니다. 작성 번들에는 .agent 확장자를 가진 파일이 포함되며, 이 파일이 에이전트의 청사진 역할을 하는 에이전트 스크립트 파일입니다.

이 Trailhead 뱃지에서는 이전 유닛에서 복제한 리포지토리에 있는 기존 작성 번들 및 에이전트 스크립트 파일로 시작합니다. 시작할 준비가 되셨나요?

VS Code에서 이전 유닛에서 복제한 DX 프로젝트의 force-app/main/default/aiAuthoringBundles/Local_Info_Agent 디렉토리에 있는 Local_Info_Agent.agent라는 에이전트 스크립트 파일을 엽니다.

에이전트 스크립트 파일에는 색상이 지정된 구문 하이라이트, 구문 오류에 대한 시각적 단서(빨간 물결 밑줄 등), 코드 탐색 등의 기능이 표시됩니다. 이러한 색상은 Salesforce VS Code 확장 프로그램이 에이전트 스크립트를 Apex와 LWC처럼 프로그래밍 언어로 지원하기 때문에 표시되는 것입니다.

에이전트 스크립트 언어 자체에 대한 학습은 이 뱃지에서 다루지 않지만, 파일을 잠시 살펴보면 도움이 됩니다. 예를 들어, 파일은 system, config, variables와 같은 블록으로 구성됩니다. config 블록에는 에이전트를 정의하는 구성 매개변수가 포함되어 있습니다. 이 뱃지의 후반부에서 이러한 매개변수 중 하나를 변경하게 됩니다.

자세한 내용은 에이전트 스크립트 시작하기를 참고하세요.

에이전트 스크립트 파일만 사용하여 에이전트 미리보기

에이전트의 에이전트 스크립트 파일을 코딩할 때, 주기적으로 에이전트와 대화해 보면 도움이 됩니다. 변경 사항 및 업데이트를 실시간으로 적용하면서 에이전트의 응답을 확인할 수 있습니다. 이러한 대화 미리보기는 에이전트가 예상대로 동작하는지 확인하는 인터랙티브 테스트 역할을 합니다.

먼저 시뮬레이션 모드를 사용하여 에이전트를 미리 봅니다. 이 모드에서는 에이전트 스크립트 파일만을 사용하여 대화하고 모든 도구를 시뮬레이션합니다. 이 모드는 도구를 구현하는 Apex 클래스, 플로 또는 프롬프트 템플릿이 아직 준비되지 않았을 때 특히 유용합니다. LLM은 에이전트 스크립트 파일에 추가한 서브에이전트 정보를 사용하여 도구의 동작이나 응답을 시뮬레이션합니다. LLM은 조직을 통해 액세스하므로 시뮬레이션 모드에서도 조직 인증이 필요합니다.

1. VS Code의 Local_Info_Agent.agent 에이전트 스크립트 파일에서 컨텍스트 메뉴를 엽니다(오른쪽 버튼 클릭).
   
2. AFDX: Preview This Agent(AFDX: 이 에이전트 미리보기)를 선택합니다.
   왼쪽에 Agentforce DX 패널이 열립니다.
   
3. Select agent…(에이전트 선택...) 드롭다운 목록에서 Local_Info_Agent를 선택합니다(이미 선택되어 있을 수 있음).
   목록에서 Agent Script(에이전트 스크립트) 섹션에 위치해 있는 것을 확인합니다. 새 에이전트를 생성하지 않았다면 목록에는 에이전트가 Local_Info_Agent 하나만 있습니다.
   
4. 드롭다운에서 Simulation(시뮬레이션)을 선택한 다음 Start Simulation(시뮬레이션 시작)을 클릭하여 미리보기를 시작합니다.
   
   
5. 채팅 상자에 What can you help me with?(도움을 요청할 내용)라는 질문을 입력하여 에이전트가 할 수 있는 일을 데모로 확인합니다.
   에이전트는 잠시 생각한 후 응답을 제공합니다.
   
6. 다음 질문을 입력합니다.

   What’s the weather like?

날씨 요약을 받아 볼 수 있는데, 에이전트가 해적처럼 말하는 것을 눈치채셨나요? 예를 들면 응답이 "어이, 친구"로 시작할 수 있습니다. 좀 이상하게 보이죠. 이렇게 응답하는 이유는 에이전트 스크립트 파일에서 지역 날씨를 설명할 때 해적처럼 말하도록 지시하고 있기 때문입니다.

해적 페르소나는 어조를 테스트하는 재미있는 방법이지만, 실제 에이전트에게는 일관된 브랜드 어조가 필요합니다. 에이전트의 대화 응답을 개선하기 위해 에이전트 스크립트 파일을 수정하는 방법을 알아보세요.

에이전트 스크립트 파일 코딩

에이전트의 동작을 변경하려면 에이전트 스크립트 파일을 코딩해야 합니다. 코딩하면서 파일을 검증하여 오류가 없는지 확인하세요. 이제 해적 말투를 그만 쓰도록 할 때가 된 것 같습니다. 방법을 배워 볼까요?

1. VS Code에서 에이전트 스크립트 파일을 살펴보고 지역 날씨를 설명할 때 해적처럼 말하도록 만드는 지침을 찾습니다.
   힌트: local_weather의 추론 지침을 확인하세요. 그래도 찾기 어려우신가요? 약 117번째 줄에서 Finally, ALWAYS give answers로 시작하는 줄을 확인하세요.
   
2. 파일을 수정하려면 Finally, ALWAYS give answers로 시작하는 줄 전체를 삭제합니다. 어떤 작업을 수행하고 있는지 잘 모르겠다면 다른 부분은 수정하지 마세요.
   
3. 파일을 저장합니다.
   
4. 에이전트 스크립트 파일에서 컨텍스트 메뉴(오른쪽 버튼 클릭)를 열고 AFDX: Validate this Agent(AFDX: 이 에이전트 검증)를 선택합니다.
   파일이 검증되는 동안 VS Code 오른쪽 하단에 작은 창이 나타납니다. 검증이 실패하면 Problems(문제) 탭이 열리며 오류 메시지와 문제 해결을 위한 힌트가 표시됩니다. 하지만 정상적으로 진행했다면 에이전트 스크립트 검증은 성공합니다.
   
5. Agentforce DX 미리보기 창 오른쪽 상단에서 Restart Options(재시작 옵션)를 클릭한 후 Compile & Restart(컴파일 및 재시작)를 클릭합니다.
   
   
6. 채팅 상자에 동일한 질문(What’s the weather like? (날씨가 어떤가요?))을 입력합니다. 위쪽 화살표를 눌러 이전 질문을 사용할 수도 있습니다.
   이번에는 더 전문적인 답변이 제공되며, 어조는 비교적 단조로울 수 있지만 괜찮습니다.
   
7. 질문이 끝나면 Stop Simulation(시뮬레이션 중지)을 클릭합니다.
   

라이브 모드로 에이전트 미리보기

라이브 모드에서 에이전트를 미리 보면 개발 조직의 실제 Apex 클래스, 플로, 프롬프트 템플릿을 사용하여 보다 정확한 에이전트 동작을 확인할 수 있습니다.

이미 이 Trailhead 뱃지의 초기 설정 과정에서 필요한 Apex 클래스와 관련 자산을 조직에 배포했습니다. 이후 로컬 DX 프로젝트에서 이를 변경했다면 다시 배포하여 라이브 미리보기에서 사용할 수 있게 해야 합니다.

또한 라이브 미리보기에서는 이전 유닛에서 생성된 실제 조직 사용자를 사용합니다. 이를 위해 에이전트 스크립트 파일을 수정해야 합니다. 시작해보죠!

1. VS Code의 편집기에서 Local_Info_Agent.agent 파일을 엽니다.
   
2. config 섹션(약 11번째 줄)에서 default_agent_user 속성을 찾습니다.
   
3. UPDATE_WITH_YOUR_DEFAULT_AGENT_USER 자리 표시자를 이전 유닛의 스크립트에서 생성된 사용자 이름으로 업데이트하여 에이전트 스크립트 파일을 편집합니다.
   
   • 예를 들어 생성된 사용자 이름이 afdx-agent@testdrive.org98eca4a312-3456xyz라면 업데이트된 속성은
     default_agent_user: "afdx-agent@testdrive.org98eca4a312-3456xyz"
     와 같습니다.
     
4. 에이전트 스크립트 파일을 수정할 때마다 검증하는 것이 좋습니다.
   
5. Agentforce DX 패널이 열려 있지 않다면 스크립트 파일의 아무 위치에서 컨텍스트 메뉴를 선택(오른쪽 버튼 클릭)한 후 AFDX: Preview This Agent(AFDX: 이 에이전트 미리보기)를 선택합니다.
   
6. 드롭다운에서 Live Test(라이브 테스트)를 선택한 다음 Start Live Test(라이브 테스트 시작)를 클릭하여 에이전트를 미리 봅니다.
   
   
7. What’s the weather like?(날씨가 어떤가요?) 질문을 다시 제시합니다.

응답은 시뮬레이션을 진행했을 때와 비슷하지만, 이번에는 온도 범위가 정확히 65.3F에서 81.1F 사이로 표시됩니다. 이는 에이전트가 조직의 실제 Apex 클래스(WeatherService)를 사용하고 있으며, 테스트 목적상 온도 값을 이 범위로 하드코딩해 두었기 때문입니다. 직접 확인해 보고 싶으신가요? force-app/main/default/classes/WeatherService.cls 파일을 확인해 보세요.

Agentforce 빌더에서 에이전트 확인 및 변경

조직의 Agentforce 빌더 UI로 돌아갑니다. 여기서도 VS Code처럼 에이전트를 미리 보고 코딩할 수 있습니다. 사실 너무 전문적인 것보다는 익살스러운 분위기가 더 나을 수 있습니다. 이번에는 에이전트가 광대처럼 응답하도록 변경해 보겠습니다.

하지만 먼저 로컬 에이전트 스크립트 파일에 변경 사항을 적용했던 것을 기억해 보세요. 조직 내 빌더를 사용할 때 동일한 코드로 작업하도록 하려면 Local_Info_Agent 작성 번들을 조직에 배포해야 합니다. 프로코드와 로우코드 도구를 함께 사용할 때는 DX 프로젝트와 조직의 동기화 상태를 유지하는 것이 중요합니다.

1. VS Code에서 통합 터미널에 다음 CLI 명령을 실행하여 업데이트된 작성 번들을 조직에 배포합니다.
   sf project deploy start --metadata aiAuthoringBundle:Local_Info_Agent
   터미널에는 다음과 같은 배포 상태가 표시됩니다.
   
   
2. 브라우저에서 Agentforce Studio를 열려면 VS Code 통합 터미널에서 다음 CLI 명령을 실행합니다.
   sf org open authoring-bundle
   
3. 잘못된 위치에 있다는 메시지가 표시되면 Take Me There(이동하기)를 클릭합니다.
   
4. 표에서 Local Info Agent(지역 정보 에이전트)를 클릭하여 Agentforce 빌더에서 엽니다. 표에 에이전트가 표시되지 않으면 VS Code에서 sf org open authoring-bundle 명령을 다시 실행합니다.
   

Agentforce 빌더가 처음이라면 기능을 살펴보세요. Local Info Agent(지역 정보 에이전트)의 버전은 Version 1 (Draft)(버전 1(초안))입니다.

5. Agentforce Builder(Agentforce 빌더)에서 Script(스크립트) 뷰를 선택하고, ALWAYS Provide forecasts that include a temperature range(항상 온도 범위를 추가하는 예측 제공)(약 116번째 줄) 바로 다음 줄에 새 지침을 추가합니다.
   

   Finally, ALWAYS give answers like you're a clown in a circus, using clown-themed language and expressions to make the interaction more engaging and fun for the user.

   
   
6. Save(저장)를 클릭합니다.
   
7. 선택적으로 Preview(미리보기) 버튼을 사용하여 조직 내에서 바로 에이전트를 미리 볼 수 있습니다.
   
8. VS Code에서 터미널에 다음 CLI 명령을 실행하여 업데이트된 작성 번들을 조직에서 DX 프로젝트로 가져옵니다.
   sf project retrieve start --metadata AiAuthoringBundle:Local_Info_Agent
   
9. 라이브 모드 미리보기를 다시 컴파일 및 재시작한 다음, 다시 날씨에 대해 질문합니다. 이제 에이전트는 광대처럼 응답할 것입니다.
   

작성 번들 게시

작성 번들을 조직에 게시하면, 조직은 에이전트 스크립트 파일을 사용하여 관련 에이전트 메타데이터를 생성합니다. 그러면 메타데이터의 초기 버전 또는 새로운 버전이 생성됩니다. 에이전트 메타데이터에는 Bot, BotVersion, GenAiPlannerBundle, GenAiFunction 등의 구성 요소가 포함됩니다. 이 에이전트 메타데이터는 조직에 새로운 에이전트를 생성하거나 기존 에이전트의 새 버전을 생성합니다. 이후 게시된 에이전트를 테스트하고, 나중에 프로덕션 조직에 배포하여 활성화하고 사용자에게 제공할 수 있습니다. 마지막으로 DX 프로젝트는 조직에서 새로 생성되거나 업데이트된 모든 메타데이터를 가져옵니다.

1. VS Code의 편집기에서 Local_Info_Agent.agent 파일을 엽니다.
   
2. 에이전트 스크립트 파일에서 컨텍스트 메뉴(오른쪽 버튼 클릭)를 열고 AFDX: Publish This Agent(AFDX: 이 에이전트 게시)를 선택합니다.
   게시 진행 중에는 Output(출력) 탭에서 진행 상황을 확인합니다. 드롭다운을 사용하여 Agentforce DX 정보를 필터링해야 합니다.
   
3. Explorer를 사용하여 DX 프로젝트의 force-app/main/default 패키지 디렉토리에 가져온 메타데이터를 확인합니다. 이 예시에서는 GenAiPlannerBundle 메타데이터 구성 요소 XML 파일이 편집기에서 열려 있습니다.
   
   
4. 조직의 Agentforce 빌더로 돌아가 페이지를 새로 고칩니다. 이제 Local Info Agent(지역 정보 에이전트)의 커밋된 버전인 Version 1 (Committed)(버전 1(커밋됨))이 표시됩니다.
   

작성 번들을 게시하면 BotVersion과 GenAiPlannerBundle을 포함한 새로운 에이전트 메타데이터 버전이 생성됩니다. 앞의 이미지에서 이를 v1로 확인할 수 있습니다.

에이전트 활성화

Coral Clouds Resort 고객이 Local Info Agent(지역 정보 에이전트)를 사용할 수 있게 하세요. VS Code에서는 BotVersion 메타데이터 파일을 사용하여 에이전트를 활성화할 수 있습니다.

1. VS Code에서 Explorer를 사용해 force-app/main/default/bots/Local_Info_Agent 디렉토리로 이동합니다.
   
2. Local_Info_Agent.bot-meta.xml 파일에서 컨텍스트 메뉴(오른쪽 버튼 클릭)를 열고 AFDX: Activate Agent(AFDX: 에이전트 활성화)를 선택합니다.
   
   
3. VS Code 상단 드롭다운에서 Version 1(버전 1)을 클릭합니다.
   
4. 조직의 Agentforce 빌더로 돌아가 Local Info Agent(지역 정보 에이전트) 페이지를 새로 고칩니다. 이제 Version 1 (Active)(버전 1(활성))와 같은 활성 에이전트 버전이 표시됩니다.
   

축하합니다! 이제 Agentforce DX를 사용하여 에이전트의 에이전트 스크립트 파일을 코딩하고, 에이전트를 미리 보고, 조직에 게시했습니다. 이러한 프로코드 도구를 활용하여 이제 자신만의 에이전트를 만들 준비가 되었습니다. 프로덕션 에이전트를 게시하기 전에, 특정 사용 사례에 적합하도록 에이전트의 어조를 조정하는 것을 잊지 마세요.

리소스

• Salesforce 개발자: Agentforce DX로 에이전트 구축
• Salesforce 개발자: Salesforce CLI 명령 참조| agent 명령
• Salesforce 개발자: Agentforce Vibes 확장 프로그램
• Salesforce 도움말: 에이전트 설계 및 구현
• Trailhead: 새로운 Agentforce 빌더 알아보기