변수는 대화 차례 전반에 걸쳐 데이터를 저장하고 검색하는 데 사용됩니다. 에이전트가 정보를 기억하고 컨텍스트를 유지할 수 있습니다. 에이전트의 프롬프트 안내를 작성할 때 이러한 변수에 대한 참조를 포함할 수 있습니다.
변수 유형
에이전트 빌더는 요청 사항에서 두 가지 고유한 변수 유형인 정적 변수와 동적 변수를 지원합니다.
적절한 유형을 선택하는 것은 사용자의 세션 중에 변수 값을 변경해야 하는지 여부와 지연 시간을 얼마나 최적화해야 하는지에 따라 달라집니다.
정적 변수
정적 변수는 모델 호출이 발생하기 전에 에이전트 프롬프트에 직접 컴파일됩니다. 직접적인 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 헤더 또는 요청 매개변수 내에서 전달할 수 있습니다. 이러한 변수는 명령어에서 참조할 수 없으며 수동으로 덮어쓸 수 없습니다. 사용할 수 있는 기본 변수는 다음과 같습니다.