변수

변수는 대화 턴 전반에서 데이터를 저장하고 검색하는 데 사용됩니다. 이를 통해 에이전트는 정보를 기억하고 컨텍스트를 유지할 수 있습니다. 에이전트의 프롬프트 안내를 작성할 때 이러한 변수를 참조할 수 있습니다.

변수 유형

에이전트 빌더는 명령어에서 정적 변수와 동적 변수라는 두 가지 변수 유형을 지원합니다.

올바른 유형을 선택하는 것은 사용자의 세션 중에 변수의 값을 변경해야 하는지 여부와 지연 시간을 얼마나 최적화해야 하는지에 따라 달라집니다.

정적 변수

정적 변수는 모델 호출이 발생하기 전에 에이전트 프롬프트로 직접 컴파일됩니다. 직접적인 1:1 텍스트 대체 역할을 하며 자주 업데이트되지 않습니다.

정적 변수는 안내 준수 품질을 극대화하며 다양한 시나리오의 조건부 안내에 적합합니다. 단일 대화 수명 동안 변경되지 않는 구성 데이터, 엄격한 비즈니스 규칙 또는 대규모 컨텍스트 페이로드에는 정적 변수를 사용합니다.

안내에서 이름으로 정적 변수를 참조하려면 이중 중괄호 {{variable_name}}를 사용하세요.

예를 들어 대규모의 정적 제품 카탈로그가 있는 소매 에이전트를 만드는 경우 다음과 같은 요청 사항을 사용할 수 있습니다.

You are a helpful shopping assistant.
Please follow these business rules: {{business_rules}}.

동적 변수

동적 변수는 대화 중에 언제든지 도구, 콜백 또는 API 요청에 의해 업데이트될 수 있습니다. 프롬프트의 텍스트에 직접 대체되지 않습니다. 대신 업데이트되면 새 값이 대화 기록에 state update 이벤트로 추가됩니다. 예를 들면 <state_update>var_name: value</state_update>입니다.

세션 중에 사용자로부터 추출된 정보, 외부 API (도구)에서 가져온 출력 또는 대화가 진행됨에 따라 변경되는 상태에 동적 변수를 사용합니다.

동적 변수에는 다음과 같은 단점이 있습니다.

  • 동적 변수는 대화 기록에 추가되므로 긴 세션이 컨텍스트 윈도우 한도를 초과하면 기록을 자를 때 손실되는 변수 값을 상담사가 잊을 수 있습니다.
  • 동적 변수는 정적 변수에 비해 안내 준수율이 약간 낮을 수 있습니다. 변수 값이 명령어에서 더 멀리 정의되어 있기 때문입니다. 또한 모델이 명령에서 더 멀리 떨어진 값을 찾아야 하므로 지연 시간이 추가될 수 있습니다.

안내에서 이름으로 동적 변수를 참조하려면 단일 중괄호({variable_name})를 사용하세요.

예를 들어 사용자를 인증한 다음 도구를 사용하여 특정 계정 세부정보를 조회해야 하는 에이전트를 만드는 경우 다음과 같은 명령어를 사용할 수 있습니다.

If the user asks for their balance, call the {@TOOL: LookupBalance}.
The tool will update the {current_account_balance} variable.
Always share the {current_account_balance} with the user.

변수 데이터

변수에는 다음 데이터가 있습니다.

  • 이름: 스네이크 표기법을 사용하는 변수 이름
  • 유형: 기본 데이터 유형:
    • 텍스트: 문자열 값
    • 숫자: 숫자 값
    • 예/아니요: 불리언 값
    • 맞춤 객체: 객체의 스키마를 제공합니다.
    • 목록: 변수 목록입니다. 쉼표로 구분된 목록으로 값을 입력합니다.
  • 기본값: 변수의 기본값
  • 설명: 변수에 대한 설명입니다(선택사항).

변수 값 업데이트

에이전트 자체는 변수 값을 업데이트할 수 없지만 도구와 콜백은 변수 값을 업데이트할 수 있습니다.

에이전트 변수는 변수를 업데이트하는 데 사용할 수 있는 ADK 컨텍스트 상태를 사용합니다. context라는 전역 변수를 Python 도구 코드에서 사용할 수 있습니다. 예를 들어 Python 도구에서 다음 문을 사용하여 ADK 기능을 통해 변수를 업데이트할 수 있습니다.

context.state["variable_name"] = value

기본 제공 세션 컨텍스트 변수

맞춤 변수 외에도 OpenAPI 및 MCP 도구는 기본 제공 세션 컨텍스트 변수를 참조할 수 있습니다. 이러한 값은 기본적으로 제공되며 HTTP 헤더 또는 요청 매개변수 내에서 전달할 수 있습니다. 이러한 변수는 명령어에서 참조할 수 없으며 수동으로 덮어쓸 수 없습니다. 다음과 같은 내장 변수를 사용할 수 있습니다.