코드 블록

플레이북을 정의할 때 원하는 경우 상담사 동작을 더 효과적으로 제어하는 데 사용할 수 있는 인라인 Python 코드인 코드 블록을 제공할 수 있습니다. 이 코드는 특수 데코레이터가 있는 함수와 필요한 모든 유틸리티 함수로 구성됩니다.

코드를 작성할 때 코드 블록 시스템 라이브러리를 사용하여 에이전트 동작을 제어할 수 있습니다.

제한사항

다음과 같은 제한사항이 적용됩니다.

  • 코드 블록에는 데이터를 유지하는 객체가 포함될 수 없습니다. 하지만 도구를 사용하여 데이터를 유지하고 상태를 유지할 수 있습니다.
  • 코드 블록은 원격 호출을 직접 실행할 수 없습니다. 예를 들어 Python requests 라이브러리를 사용할 수 없습니다. 하지만 도구를 활용하여 간접적으로 원격 호출을 실행할 수 있습니다.
  • Python 이름으로 변환되는 리소스 이름은 유효한 Python 이름이어야 합니다.
  • 흐름 전환이 발생하지 않는 한 코드 블록은 세션 매개변수를 읽거나 쓸 수 없습니다.
  • 코드 블록이 OpenAPI 도구를 사용하고 200이 아닌 HTTP 상태 코드를 수신하면 코드 블록이 실패하고 오류를 포착할 방법이 없습니다.

인라인 작업

인라인 작업은 도구 작업과 유사하게 작동합니다. 정의된 입력 및 출력 스키마가 있으며, 이는 유형 주석 및 문서 문자열을 포함하여 Python 함수 서명에 의해 결정됩니다. 도구 호출과 마찬가지로 LLM은 작업을 구현하는 코드를 인식하지 못합니다.

샘플:

@Action
def is_prime(n: int): bool
  """Returns true if n is prime."""
  import math
  return (all([False for i in range(2, math.sqrt(n)
               if n % i == 0 ]) and not n < 2)

이 함수의 경우 LLM에 작업, 입력, 출력에 관한 정보가 제공됩니다.

플레이북 안내에서 인라인 작업을 참조하려면 백틱으로 작업 이름을 참조하고 사용 방법을 설명하기만 하면 됩니다.

place_order 인라인 작업 샘플:

Take the customer's order, then call the `place_order` action when the order is ready.

인라인 작업을 사용하는 예시를 만들려면 입력 및 출력 섹션에서 inline-action 도구 유형을 사용하세요.

자세한 내용은 @Action 참조 문서를 참고하세요.

트리거 함수

트리거 함수는 코드에서 조건부 작업을 정의하는 데 사용됩니다.

트리거 함수는 데코레이터를 사용하여 선언됩니다. 다음과 같은 트리거 함수 데코레이터를 사용할 수 있습니다.

데코레이터 데코레이터 매개변수 설명
@EventTrigger event: str, condition: str(조건은 선택사항) 이벤트에 의해 트리거됨
@BeforeModelTrigger condition: str(조건은 선택사항) LLM이 다음 작업을 예측하기 전에 매번 트리거됩니다.
@BeforeActionTrigger condition: str(조건은 선택사항) LLM이 작업을 실행하기 전에 매번 트리거됩니다.
@BeforePlaybookTrigger condition: str(조건은 선택사항) 플레이북이 처음 시작될 때 트리거됩니다.

예를 들어 이러한 함수는 이러한 데코레이터와 데코레이터 매개변수를 사용하는 방법과 응답 코드 블록 시스템 라이브러리 함수를 사용하는 방법을 보여줍니다.

# No decorator parameter
@PlaybookStartTrigger
def my_playbook_conditional_action():
  respond("How can I help?")

# With a condition decorator parameter
@BeforeActionTrigger('$next-action.name = "search"')
def my_before_action_conditional_action():
  respond("One moment please")

# Event
@EventTrigger(event="welcome")
def my_welcome_event():
  respond("hi")

# Event with a condition:
@EventTrigger(event="welcome",
              condition="$sys.func.NOW().hours < 10")
def my_good_morning_event():
  respond("Good morning ☕")

흐름, 플레이북, 도구 참조

코드 블록에서 흐름, 플레이북, 도구 전역 변수를 사용하여 특정 흐름, 플레이북, 도구를 참조할 수 있습니다.

이러한 각 객체에는 해당 리소스의 이름과 일치하는 구성원이 있습니다. 이러한 이름은 유효한 Python 이름이어야 합니다.

샘플:

  add_override(playbooks.troubleshooting, {})
  add_override(flows.billing)
  add_override(tools.weather_api.get_weather, {"location": "San Francisco"})

코드 블록에서 흐름과 플레이북을 참조할 때는 다음 문법을 사용하여 플레이북 안내에서도 이를 참조해야 합니다.

${RESOURCE_TYPE: my_resource_name}

예를 들어 코드 블록에 flows.myflowplaybooks.myplaybook가 포함되어 있는 경우 플레이북 안내에는 다음이 포함되어야 합니다.

${FLOW: myflow}
${PLAYBOOK: myplaybook}

작업 재정의

코드 블록을 사용하여 LLM에서 결정한 추가 작업 전에 실행할 작업의 대기열을 만들고 이를 재정의할 수 있습니다. add_override 전역 함수를 사용하여 작업 재정의를 만듭니다.

대기열에 추가된 모든 재정의 작업은 순차적으로 실행되며 작업 출력은 LLM에서 사용할 수 있습니다. 대기열이 비워지면 재정의가 respond 또는 턴을 완료하는 다른 함수로 턴을 완료하지 않는 한 작업이 LLM로 돌아가서 작업 및 입력 선택을 처리합니다.

함수 인수:

  • action: 실행할 작업입니다. 인라인 작업의 경우 my_function_name를 사용합니다. 도구 작업에는 tools.my_tool_name.my_tool_action를 사용합니다. 흐름 작업의 경우 flows.my_flow_name를 사용합니다.
  • inputs: 작업의 선택적 입력입니다. 예를 들면 {"location": "Omaha"}입니다.

샘플:

# Assuming remote tool named "dmv" with operationId "search_offices"
# remote tool with only requestBody
add_override(tools.dmv.search_offices,{"address": "95030"})

# remote tool with only parameters
add_override(tools.pets.get_pet, {"id": "123"})

# remote tool with requestBody + parameters:
add_override(tools.pets.create_pet, {"requestBody": {"arg1":"foo"}, "param1": "bar"})

# datastore. Assumes existing datastore tool named "Menu".
add_override(tools.menu.Menu, {"query": "what is the menu"})

# code block action. Assumes another code block @Action my_action.
add_override(my_action)

응답 재정의

작업 재정의와 유사하지만 특히 상담사 응답의 경우 respond 전역 함수를 사용하여 상담사가 사용자에게 특정 콘텐츠로 응답하도록 강제할 수 있습니다.

샘플:

respond("Hello")

도구 호출

코드 블록 함수에서 상담사에게 정의된 도구를 호출할 수 있습니다. 도구 작업을 재정의할 때와 달리 도구를 직접 호출하면 도구 실행 결과를 LLM에서 사용할 수 없습니다.

샘플:

# Assumes existing tool named "DMV" with operationId "search_offices"
# remote tool with only request body.
offices = tools.dmv.search_offices({"address": "95030"})

# remote tool with parameters and request body
offices = tools.dmv.search_offices({"requestBody": {"address":"95030"}, "param1":"foo"})

# datastore actions. Assumes existing datastore tool named "Menu".
data = tools.menu.Menu({"query": "get the menu"})["snippets"]

의도 일치

코드 블록은 Flow.match_intent 함수를 사용하여 지정된 흐름의 인텐트를 프로그래매틱 방식으로 일치시킬 수 있습니다.

샘플:

matches = flows.flow1.match_intent(history.last_user_utterance).matches
if matches and matches[0].intent == "some_intent":
  to_country = matches[0].parameters.get("to_country")
  if to_country:
    respond(f"To confirm, you're going to {to_country}, right?")

디버깅

시뮬레이터를 사용하여 코드 블록 함수를 디버그할 수 있습니다. 이러한 함수는 시뮬레이터에 작업으로 표시되며 필요에 따라 세부정보를 제공합니다.

추가 관리 기능

이 가이드에서는 코드 블록 시스템 라이브러리의 몇 가지 일반적인 사용 사례를 설명합니다. 추가 제어 유형은 라이브러리 문서를 참고하세요.