프로시저

관련 상황에서 에이전트가 불러오는 작업별 지침

개요

프로시저에는 하나의 특정 작업을 위한 지침이 포함됩니다. 각 프로시저에는 적용 시점을 설명하는 트리거와 수행할 작업을 설명하는 콘텐츠가 있습니다. 대화가 트리거와 일치하면 에이전트가 프로시저를 불러옵니다.

에이전트가 여러 개의 서로 다른 작업을 처리해야 할 때 프로시저를 사용하세요. 예를 들어 고객 지원 에이전트에서는 각 프로시저가 환불, 신원 확인, 계정 복구 또는 연결 문제 해결과 같이 하나의 요청 유형을 처리할 수 있습니다.

프로시저 유형

프로시저에는 두 가지 유형이 있습니다.

자유 형식 프로시저 는 에이전트가 해석하고 상황에 맞게 조정하는 자연어 지침으로 작성됩니다.
구조화된 프로시저 는 에이전트가 매번 동일한 방식으로 실행하는 유형이 지정된 단계의 순서 목록입니다.

동일한 에이전트에서 두 유형을 모두 사용할 수 있습니다. 에이전트는 유형과 관계없이 트리거를 기준으로 관련 프로시저를 선택합니다.

프로시저는 서로를 호출할 수 있습니다. 자유 형식 프로시저는 인라인 참조를 통해 다른 프로시저를 호출하고, 구조화된 프로시저는 하위 프로시저 단계를 통해 다른 구조화된 프로시저를 호출합니다. 일반적으로 자유 형식 프로시저에서 열린 형태의 처리를 유지하고, 매번 동일하게 실행해야 하는 부분은 구조화된 프로시저로 넘깁니다.

에이전트는 프로시저, 워크플로 또는 둘 다를 가질 수 있습니다. 둘 다 있는 경우 모든 프로시저는 워크플로의 모든 지점에서 사용할 수 있으며, 특정 워크플로 노드로 프로시저를 제한할 수 없습니다. 대부분의 에이전트는 두 방식 중 하나를 중심으로 구축되지만, 함께 사용할 수도 있습니다.

프로시저를 사용해야 하는 경우

모든 에이전트에는 시스템 프롬프트가 있습니다. 프로시저와 워크플로는 그 위에 구조를 추가하는 두 가지 방법이며, 에이전트는 둘 다 사용할 수 있습니다. 대화가 얼마나 다양하게 진행될 수 있는지에 따라 시작점을 선택하세요.

요구 사항	사용	이유
간단한 개념 증명 에이전트	시스템 프롬프트만 사용	가장 빠르게 설정하고 반복 개선할 수 있지만, 에이전트의 범위가 커질수록 단일 프롬프트는 다루기 어려워집니다.
에이전트가 표현과 순서를 조정할 수 있는 작업	자유 형식 프로시저	전체 대화를 하나의 LLM 컨텍스트에 유지하므로 에이전트가 표현과 순서를 조정하고 예상치 못한 흐름도 처리할 수 있습니다. 컨텍스트 윈도우를 더 많이 사용합니다.
단계가 매번 동일한 방식으로 실행되어야 하는 작업	구조화된 프로시저	각 단계가 설정한 순서대로 매번 동일하게 실행되며, 짧은 단계 목록으로 작성할 수 있습니다.
복잡한 분기와 예외 상황을 완전히 제어해야 하는 경우	워크플로	직접 설계하고 연결한 하위 에이전트 그래프로 실행되며, 분기와 각 단계에서 사용할 모델을 완전히 제어할 수 있습니다.

자유 형식 프로시저가 기본 선택입니다. 가장 빠르게 작성할 수 있고 문서처럼 읽히므로 비기술 팀도 관리할 수 있으며, 대화가 예상된 흐름에서 벗어나도 에이전트가 복구할 수 있습니다. 인증, 에스컬레이션 또는 금융 거래처럼 단계를 건너뛰거나 순서가 바뀌는 비용이 큰 경우에는 구조화된 프로시저를 사용하세요. 두 프로시저 유형 모두 제공하지 않는 라우팅 로직이나 단계별 모델 제어가 필요할 때는 워크플로를 사용하세요.

프로시저 관리

대시보드는 프로시저를 작성하는 데 권장되는 방법입니다. 프로시저를 프로그래밍 방식으로 관리하거나 배포 도구에 통합하려면 CLI 또는 API를 사용하세요.

대시보드에서 구축

CLI로 관리

API로 관리

대시보드에서 에이전트를 연 다음 프로시저를 선택하세요. + 를 사용해 자유 형식 또는 구조화된 프로시저를 만드세요. 같은 메뉴에서 프로시저를 폴더로 그룹화할 수 있습니다. 작성 방법은 자유 형식 프로시저 및 구조화된 프로시저를 참조하세요.

대화별 프로시저 선택

기본적으로 모든 대화에서 에이전트의 모든 프로시저를 사용할 수 있으며, 대화가 트리거와 일치한 후에만 에이전트가 프로시저를 불러옵니다. 애플리케이션은 대화가 시작되기 전에 사용자, 사용자 지역 또는 문의 사유 등 더 많은 정보를 알고 있는 경우가 많습니다. 이 정보를 활용하려면 대화 시작 클라이언트 데이터에 프로시저 ID를 전달하세요. 에이전트가 사용할 수 있는 프로시저와 첫 턴부터 따를 프로시저를 직접 결정할 수 있습니다.

필드	기능	사용 이유
`procedure_ids`	대화를 이 프로시저로 제한합니다. 빈 배열이면 에이전트의 모든 프로시저가 비활성화됩니다.	각 사용자에게 적용되는 프로시저만 제공하세요. 예를 들어 로그인하지 않은 사용자에게는 계정 프로시저를 숨길 수 있습니다. 지역별 환불 프로시저처럼 피할 수 없는 유사한 트리거가 있을 때도 사용하세요. 사용자의 지역만 전달하면 에이전트가 다른 지역의 프로시저를 따를 수 없습니다.
`start_procedure_ids`	대화와 함께 이 자유 형식 프로시저를 시작하므로 에이전트가 첫 턴부터 따릅니다. 최대 5개의 ID를 허용합니다.	IVR 메뉴 선택, 위젯이 있는 페이지 또는 CRM 데이터 등을 통해 사용자의 작업을 이미 알고 있다면 더 빠르게 응답할 수 있습니다.

start_procedure_ids의 프로시저는 사용자가 처음 말할 때 이미 로드되어 있으므로, 에이전트는 이를 로드하기 위한 LLM 호출을 건너뜁니다. 에이전트나 애플리케이션이 시작했는지와 관계없이 활성 프로시저는 매 턴 프롬프트에 유지됩니다. 대화에서 전혀 필요하지 않은 시작 프로시저도 매 턴 콘텐츠를 추가하므로, 대화에서 사용할 가능성이 높은 프로시저만 시작하세요.

프로시저 선택 허용

프로시저 오버라이드는 기본적으로 꺼져 있습니다. 클라이언트의 프로시저 ID를 수락해야 하는 각 에이전트에서 이를 활성화하세요.

대시보드

CLI

SDK

대시보드에서 에이전트를 열고 보안 탭을 선택한 다음 프로시저 오버라이드를 활성화하세요.

대화 시작 시 ID 전달

에이전트에서 프로시저 오버라이드가 활성화되어 있지 않거나 ID가 유효하지 않으면 대화를 시작할 수 없습니다.

프로시저 목록에서 프로시저 ID를 가져오세요. 대화 시작 클라이언트 데이터에 procedure_ids, start_procedure_ids 또는 둘 다를 추가합니다.

대화 시작 페이로드

{
  "type": "conversation_initiation_client_data",
  "procedure_ids": [
    "agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b",
    "agtprc_2301k8f3xq9zfa7tkrqs6m4bdn5e",
    "agtprc_7801k8f3yt4mfzh2xbq9d0vcpw1r"
  ],
  "start_procedure_ids": ["agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b"]
}

에이전트는 첫 번째 프로시저가 이미 실행 중인 상태로 대화를 시작합니다. 대화가 해당 트리거와 일치하면 다른 두 프로시저도 계속 시작할 수 있습니다.

Python 및 JavaScript 대화 SDK는 procedure_ids 또는 start_procedure_ids를 전송하지 않습니다. 이 필드를 사용하려면 WebSocket을 통해 직접 시작 메시지를 전송하세요.

두 필드에는 다음 규칙이 적용됩니다.

procedure_ids의 각 ID는 에이전트에 속해야 합니다. 선택한 프로시저가 하위 프로시저를 호출하는 경우 하위 프로시저도 포함하세요.
start_procedure_ids의 각 ID는 자유 형식 프로시저여야 합니다. procedure_ids도 전달하는 경우 각 ID는 해당 목록에도 있어야 합니다.
procedure_ids는 대화가 시작되는 에이전트에만 적용됩니다. 에이전트 전송 후에는 적용되지 않습니다.
시작된 프로시저는 제한 사항의 활성 프로시저 5개 제한에 포함됩니다. 대화 기록에는 각각 start_procedure 도구 호출로 기록됩니다.

제한 사항

프로시저 콘텐츠는 최대 50,000자로 제한됩니다.
에이전트는 가장 최근에 시작된 프로시저 5개를 컨텍스트에 유지합니다. 하나의 대화에서 더 많은 프로시저가 시작되면 가장 오래된 자유 형식 프로시저의 콘텐츠, 인라인 도구 및 지식 베이스 문서가 프롬프트에서 제외됩니다. 프로시저는 집중된 범위로 유지하고 하위 프로시저를 사용하여 동시에 활성화되는 수를 줄이세요.
프로시저를 만든 후에는 유형을 변경할 수 없습니다. 자유 형식과 구조화된 형식 간에 변환하려면 새 프로시저를 만들고 해당 프로시저에 대한 모든 참조를 업데이트하세요.
프로시저는 하나의 에이전트에 속합니다. 에이전트 간에 공유하거나 워크스페이스 수준 리소스로 저장할 수 없습니다.
에이전트를 복제하면 프로시저를 공유하는 대신 복사합니다. 복사본에는 새 프로시저 ID가 부여되므로, 복제된 에이전트의 참조는 새 ID를 사용해야 합니다.
프로시저를 특정 워크플로 노드로 제한할 수 없습니다. 에이전트에 둘 다 있으면 모든 프로시저를 모든 노드에서 사용할 수 있습니다.
구조화된 프로시저는 지식 베이스 문서를 참조할 수 없습니다.