> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # 프로시저 ## 개요 프로시저에는 하나의 특정 작업을 위한 지침이 포함됩니다. 각 프로시저에는 적용 시점을 설명하는 트리거와 수행할 작업을 설명하는 콘텐츠가 있습니다. 대화가 트리거와 일치하면 에이전트가 프로시저를 불러옵니다. 에이전트가 여러 개의 서로 다른 작업을 처리해야 할 때 프로시저를 사용하세요. 예를 들어 고객 지원 에이전트에서는 각 프로시저가 환불, 신원 확인, 계정 복구 또는 연결 문제 해결과 같이 하나의 요청 유형을 처리할 수 있습니다. ![에이전트 대시보드의 프로시저 탭](/docs/_fern-files/_img/38b190b7a08cb9e628da309a86c5e4b315eabccf238a41d5d3a6c2646aba11af.webp) ## 프로시저 유형 프로시저에는 두 가지 유형이 있습니다. * **[자유 형식 프로시저](/docs/ko/eleven-agents/customization/procedures/free-form-procedures)** 는 에이전트가 해석하고 상황에 맞게 조정하는 자연어 지침으로 작성됩니다. * **[구조화된 프로시저](/docs/ko/eleven-agents/customization/procedures/structured-procedures)** 는 에이전트가 매번 동일한 방식으로 실행하는 유형이 지정된 단계의 순서 목록입니다. 동일한 에이전트에서 두 유형을 모두 사용할 수 있습니다. 에이전트는 유형과 관계없이 트리거를 기준으로 관련 프로시저를 선택합니다. > **Tip** > > 프로시저는 서로를 호출할 수 있습니다. 자유 형식 프로시저는 [인라인 참조](/docs/ko/eleven-agents/customization/procedures/free-form-procedures#inline-references)를 통해 다른 프로시저를 호출하고, > 구조화된 프로시저는 > [하위 프로시저](/docs/ko/eleven-agents/customization/procedures/structured-procedures#sub-procedure) > 단계를 통해 다른 구조화된 프로시저를 호출합니다. 일반적으로 자유 형식 프로시저에서 열린 형태의 처리를 유지하고, 매번 동일하게 실행해야 하는 부분은 구조화된 프로시저로 넘깁니다. 에이전트는 프로시저, [워크플로](/docs/ko/eleven-agents/customization/agent-workflows) 또는 둘 다를 가질 수 있습니다. 둘 다 있는 경우 모든 프로시저는 워크플로의 모든 지점에서 사용할 수 있으며, 특정 워크플로 노드로 프로시저를 제한할 수 없습니다. 대부분의 에이전트는 두 방식 중 하나를 중심으로 구축되지만, 함께 사용할 수도 있습니다. ## 프로시저를 사용해야 하는 경우 모든 에이전트에는 [시스템 프롬프트](/docs/ko/eleven-agents/best-practices/prompting-guide)가 있습니다. 프로시저와 [워크플로](/docs/ko/eleven-agents/customization/agent-workflows)는 그 위에 구조를 추가하는 두 가지 방법이며, 에이전트는 둘 다 사용할 수 있습니다. 대화가 얼마나 다양하게 진행될 수 있는지에 따라 시작점을 선택하세요. | 요구 사항 | 사용 | 이유 | | ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | 간단한 개념 증명 에이전트 | 시스템 프롬프트만 사용 | 가장 빠르게 설정하고 반복 개선할 수 있지만, 에이전트의 범위가 커질수록 단일 프롬프트는 다루기 어려워집니다. | | 에이전트가 표현과 순서를 조정할 수 있는 작업 | [자유 형식 프로시저](/docs/ko/eleven-agents/customization/procedures/free-form-procedures) | 전체 대화를 하나의 LLM 컨텍스트에 유지하므로 에이전트가 표현과 순서를 조정하고 예상치 못한 흐름도 처리할 수 있습니다. 컨텍스트 윈도우를 더 많이 사용합니다. | | 단계가 매번 동일한 방식으로 실행되어야 하는 작업 | [구조화된 프로시저](/docs/ko/eleven-agents/customization/procedures/structured-procedures) | 각 단계가 설정한 순서대로 매번 동일하게 실행되며, 짧은 단계 목록으로 작성할 수 있습니다. | | 복잡한 분기와 예외 상황을 완전히 제어해야 하는 경우 | [워크플로](/docs/ko/eleven-agents/customization/agent-workflows) | 직접 설계하고 연결한 하위 에이전트 그래프로 실행되며, 분기와 각 단계에서 사용할 모델을 완전히 제어할 수 있습니다. | 자유 형식 프로시저가 기본 선택입니다. 가장 빠르게 작성할 수 있고 문서처럼 읽히므로 비기술 팀도 관리할 수 있으며, 대화가 예상된 흐름에서 벗어나도 에이전트가 복구할 수 있습니다. 인증, 에스컬레이션 또는 금융 거래처럼 단계를 건너뛰거나 순서가 바뀌는 비용이 큰 경우에는 구조화된 프로시저를 사용하세요. 두 프로시저 유형 모두 제공하지 않는 라우팅 로직이나 단계별 모델 제어가 필요할 때는 워크플로를 사용하세요. ## 프로시저 관리 대시보드는 프로시저를 작성하는 데 권장되는 방법입니다. 프로시저를 프로그래밍 방식으로 관리하거나 배포 도구에 통합하려면 CLI 또는 API를 사용하세요. #### 대시보드에서 구축 [대시보드](https://elevenlabs.io/app/agents)에서 에이전트를 연 다음 **프로시저**를 선택하세요. **+** 를 사용해 자유 형식 또는 구조화된 프로시저를 만드세요. 같은 메뉴에서 프로시저를 폴더로 그룹화할 수 있습니다. 작성 방법은 [자유 형식 프로시저](/docs/ko/eleven-agents/customization/procedures/free-form-procedures) 및 [구조화된 프로시저](/docs/ko/eleven-agents/customization/procedures/structured-procedures)를 참조하세요. #### CLI로 관리 [ElevenLabs CLI](/docs/ko/eleven-agents/operate/cli)는 `elevenlabs agents procedures` 명령어 그룹으로 프로시저를 관리합니다. 먼저 환경에 `ELEVENLABS_API_KEY`를 설정하세요. ```bash # List the procedures on a branch elevenlabs agents procedures list \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t # Create a procedure elevenlabs agents procedures create \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json '{"name": "Refund request", "type": "free_form", "trigger": "When the user asks to refund an order", "content": "Ask for the order ID."}' # Publish every changed procedure draft on the branch elevenlabs agents update \ --agent-id agent_7101k5zvyjhmfg983brhmhkd98n6 \ --branch-id agtbranch_0901k4aafjxxfxt93gd841r7tv5t \ --json '{"version_description": "Publish refund procedure"}' ``` 초안을 읽거나 업데이트하거나 삭제하려면 `elevenlabs agents procedures drafts`를 사용하고, 삭제를 준비하려면 `elevenlabs agents procedures remove`를 사용하세요. 모든 명령어에 `--schema`를 추가하면 입력 및 출력 계약을 확인할 수 있습니다. #### API로 관리 프로시저 초안은 [에이전트 버전 관리 수명 주기](/docs/ko/eleven-agents/operate/versioning#drafts)를 따릅니다. 초안은 사용자별, 브랜치별로 관리되므로 각 팀 구성원은 각 브랜치에서 별도의 초안을 가집니다. 게시하면 해당 브랜치에 새 불변 에이전트 버전으로 프로시저 변경 사항이 저장됩니다. 다른 사용자의 초안에는 영향이 없습니다. 에이전트 구성 응답에는 ID, 이름, 유형, 트리거 등의 프로시저 메타데이터가 포함되지만 프로시저 본문이나 초안은 포함되지 않습니다. 전체 콘텐츠를 읽고 편집하려면 프로시저 엔드포인트를 사용하세요. 모든 프로시저 엔드포인트는 `/v1/convai/agents/{agent_id}/branches/{branch_id}` 아래에 중첩되어 있습니다. ### 초안 생성 또는 업데이트 `POST /procedures`로 프로시저를 생성합니다. `PATCH /procedures/{procedure_id}/draft`로 업데이트하며, 모든 요청에 `name`, `content`, `type`, `trigger`를 포함해야 합니다. `type`은 프로시저의 기존 유형과 일치해야 합니다. 게시되지 않은 변경 사항을 읽으려면 `GET /procedures/{procedure_id}/draft`를 사용하세요. 초안이 없으면 엔드포인트는 게시된 버전을 반환합니다. ### 변경 사항 게시 [에이전트 업데이트](/docs/ko/api-reference/agents/update)를 사용해 새 에이전트 버전을 생성하여 초안을 게시합니다. 하나의 요청으로 두 프로시저 유형 모두에 대해 브랜치의 변경된 모든 프로시저 초안이 게시됩니다. 구조화된 프로시저의 단계를 에이전트가 실행하는 형식으로 변환하는 작업을 컴파일이라고 합니다. 플랫폼은 에이전트 초안이 저장되거나 에이전트가 게시될 때 모든 구조화된 프로시저를 컴파일합니다. 작성자가 직접 컴파일할 필요는 없습니다. 두 작업 모두 모든 구조화된 프로시저를 검증하고 오류가 있으면 반환합니다. 검증을 통과하면 에이전트 구성이 저장되거나 게시됩니다. 유형별 지침은 [자유 형식 프로시저](/docs/ko/eleven-agents/customization/procedures/free-form-procedures#manage-a-free-form-procedure) 또는 [구조화된 프로시저](/docs/ko/eleven-agents/customization/procedures/structured-procedures#manage-a-structured-procedure)를 따르세요. ### 프로시저 삭제 취소 또는 제거 `DELETE /procedures/{procedure_id}/draft`는 게시되지 않은 편집을 취소하고 게시된 버전을 복원합니다. 프로시저가 한 번도 게시된 적이 없다면 삭제됩니다. `DELETE /procedures/{procedure_id}`는 게시된 프로시저의 제거를 준비합니다. 같은 흐름을 사용해 변경 사항을 게시하세요. 전체 엔드포인트 스키마는 [프로시저 API 레퍼런스](/docs/ko/api-reference/agents/procedures/)를 참조하세요. ## 대화별 프로시저 선택 기본적으로 모든 대화에서 에이전트의 모든 프로시저를 사용할 수 있으며, 대화가 트리거와 일치한 후에만 에이전트가 프로시저를 불러옵니다. 애플리케이션은 대화가 시작되기 전에 사용자, 사용자 지역 또는 문의 사유 등 더 많은 정보를 알고 있는 경우가 많습니다. 이 정보를 활용하려면 대화 시작 클라이언트 데이터에 프로시저 ID를 전달하세요. 에이전트가 사용할 수 있는 프로시저와 첫 턴부터 따를 프로시저를 직접 결정할 수 있습니다. | 필드 | 기능 | 사용 이유 | | --------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `procedure_ids` | 대화를 이 프로시저로 제한합니다. 빈 배열이면 에이전트의 모든 프로시저가 비활성화됩니다. | 각 사용자에게 적용되는 프로시저만 제공하세요. 예를 들어 로그인하지 않은 사용자에게는 계정 프로시저를 숨길 수 있습니다. 지역별 환불 프로시저처럼 피할 수 없는 유사한 트리거가 있을 때도 사용하세요. 사용자의 지역만 전달하면 에이전트가 다른 지역의 프로시저를 따를 수 없습니다. | | `start_procedure_ids` | 대화와 함께 이 자유 형식 프로시저를 시작하므로 에이전트가 첫 턴부터 따릅니다. 최대 5개의 ID를 허용합니다. | IVR 메뉴 선택, 위젯이 있는 페이지 또는 CRM 데이터 등을 통해 사용자의 작업을 이미 알고 있다면 더 빠르게 응답할 수 있습니다. | `start_procedure_ids`의 프로시저는 사용자가 처음 말할 때 이미 로드되어 있으므로, 에이전트는 이를 로드하기 위한 LLM 호출을 건너뜁니다. 에이전트나 애플리케이션이 시작했는지와 관계없이 활성 프로시저는 매 턴 프롬프트에 유지됩니다. 대화에서 전혀 필요하지 않은 시작 프로시저도 매 턴 콘텐츠를 추가하므로, 대화에서 사용할 가능성이 높은 프로시저만 시작하세요. ### 프로시저 선택 허용 **프로시저** 오버라이드는 기본적으로 꺼져 있습니다. 클라이언트의 프로시저 ID를 수락해야 하는 각 에이전트에서 이를 활성화하세요. #### 대시보드 [대시보드](https://elevenlabs.io/app/agents)에서 에이전트를 열고 **보안** 탭을 선택한 다음 **프로시저** 오버라이드를 활성화하세요. #### CLI 에이전트 구성을 가져옵니다. ```bash elevenlabs agents pull --agent "" ``` `agent_configs/.json`에서 `platform_settings.overrides.enable_procedure_ids_from_client`를 `true`로 설정하세요. ```json { "platform_settings": { "overrides": { "enable_procedure_ids_from_client": true } } } ``` 변경 사항을 푸시합니다. ```bash elevenlabs agents push --agent "" ``` #### SDK ```python import os from dotenv import load_dotenv from elevenlabs import ElevenLabs load_dotenv() elevenlabs = ElevenLabs(api_key=os.getenv("ELEVENLABS_API_KEY")) elevenlabs.conversational_ai.agents.update( agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6", platform_settings={ "overrides": { "enable_procedure_ids_from_client": True, }, }, ) ``` ```typescript import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js"; const elevenlabs = new ElevenLabsClient({ apiKey: process.env.ELEVENLABS_API_KEY }); await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", { platformSettings: { overrides: { enableProcedureIdsFromClient: true, }, }, }); ``` ### 대화 시작 시 ID 전달 > **Warning** > > 에이전트에서 **프로시저** 오버라이드가 활성화되어 있지 않거나 ID가 유효하지 않으면 > 대화를 시작할 수 없습니다. [프로시저 목록](/docs/ko/api-reference/agents/procedures/list)에서 프로시저 ID를 가져오세요. 대화 시작 클라이언트 데이터에 `procedure_ids`, `start_procedure_ids` 또는 둘 다를 추가합니다. **`대화 시작 페이로드`** ```json title="대화 시작 페이로드" { "type": "conversation_initiation_client_data", "procedure_ids": [ "agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b", "agtprc_2301k8f3xq9zfa7tkrqs6m4bdn5e", "agtprc_7801k8f3yt4mfzh2xbq9d0vcpw1r" ], "start_procedure_ids": ["agtprc_4101k8f3w2pqv6xs9mhdr0tz7n3b"] } ``` 에이전트는 첫 번째 프로시저가 이미 실행 중인 상태로 대화를 시작합니다. 대화가 해당 트리거와 일치하면 다른 두 프로시저도 계속 시작할 수 있습니다. > **Note** > > Python 및 JavaScript 대화 SDK는 `procedure_ids` 또는 `start_procedure_ids`를 전송하지 않습니다. > 이 필드를 사용하려면 > [WebSocket](/docs/ko/eleven-agents/libraries/web-sockets)을 통해 직접 시작 메시지를 전송하세요. 두 필드에는 다음 규칙이 적용됩니다. * `procedure_ids`의 각 ID는 에이전트에 속해야 합니다. 선택한 프로시저가 하위 프로시저를 호출하는 경우 하위 프로시저도 포함하세요. * `start_procedure_ids`의 각 ID는 자유 형식 프로시저여야 합니다. `procedure_ids`도 전달하는 경우 각 ID는 해당 목록에도 있어야 합니다. * `procedure_ids`는 대화가 시작되는 에이전트에만 적용됩니다. [에이전트 전송](/docs/ko/eleven-agents/customization/tools/system-tools/agent-transfer) 후에는 적용되지 않습니다. * 시작된 프로시저는 [제한 사항](#limitations)의 활성 프로시저 5개 제한에 포함됩니다. 대화 기록에는 각각 `start_procedure` 도구 호출로 기록됩니다. ## 제한 사항 * 프로시저 콘텐츠는 최대 50,000자로 제한됩니다. * 에이전트는 가장 최근에 시작된 프로시저 5개를 컨텍스트에 유지합니다. 하나의 대화에서 더 많은 프로시저가 시작되면 가장 오래된 자유 형식 프로시저의 콘텐츠, 인라인 도구 및 지식 베이스 문서가 프롬프트에서 제외됩니다. 프로시저는 집중된 범위로 유지하고 하위 프로시저를 사용하여 동시에 활성화되는 수를 줄이세요. * 프로시저를 만든 후에는 유형을 변경할 수 없습니다. 자유 형식과 구조화된 형식 간에 변환하려면 새 프로시저를 만들고 해당 프로시저에 대한 모든 참조를 업데이트하세요. * 프로시저는 하나의 에이전트에 속합니다. 에이전트 간에 공유하거나 워크스페이스 수준 리소스로 저장할 수 없습니다. * 에이전트를 복제하면 프로시저를 공유하는 대신 복사합니다. 복사본에는 새 프로시저 ID가 부여되므로, 복제된 에이전트의 참조는 새 ID를 사용해야 합니다. * 프로시저를 특정 워크플로 노드로 제한할 수 없습니다. 에이전트에 둘 다 있으면 모든 프로시저를 모든 노드에서 사용할 수 있습니다. * 구조화된 프로시저는 지식 베이스 문서를 참조할 수 없습니다.