Python 도구 및 콜백에서 Python 코드를 사용할 수 있습니다. 이 참조에서는 코드에서 사용할 수 있는 Python 런타임, 가져오기 옵션 및 클래스, 전역 변수, 함수를 설명합니다.
Python 환경
Python 도구와 콜백은 안전한 샌드박스 환경에서 실행됩니다. 이 환경은 Python 3.12를 실행합니다.
가져오기
모듈을 가져오는 기능은 다음으로 제한됩니다.
클래스
AsyncTools
도구를 비동기식으로 호출하기 위한 별칭 클래스입니다.
자세한 내용은 async_tools 전역 변수를 참고하세요.
Blob
인라인 바이트 데이터입니다.
속성:
| 속성 | 설명 |
|---|---|
display_name: Optional[str] |
Blob의 표시 이름입니다. blob을 구분하기 위해 라벨 또는 파일 이름을 제공하는 데 사용됩니다. |
data: Optional[bytes] |
Base64로 인코딩된 바이트입니다. |
raw_data: Optional[bytes] |
디코딩된 원시 바이트입니다. |
mime_type: Optional[str] |
소스 데이터의 IANA 표준 MIME 유형입니다. |
메서드
| 메서드 | 설명 |
|---|---|
transcript() -> Optional[str] |
Blob 데이터에 대한 캐시된 스크립트가 있는 경우 이를 반환합니다. 이는 오디오 blob에만 적용됩니다. |
from_json(data: str) -> Blob |
mime_type가 'application/json'으로 설정된 JSON 문자열에서 Blob 인스턴스를 만드는 클래스 메서드입니다. |
샘플:
# Create a blob from raw bytes
blob = Blob(mime_type='text/plain')
blob.raw_data = b'hello world'
# Create a blob from a JSON string
Blob.from_json(data='{"key": "value"}')
CallbackContext
콜백 중에 사용할 수 있는 세션 정보입니다.
속성:
| 속성 | 설명 |
|---|---|
user_content: Optional[Content] |
사용자의 최근 입력입니다. |
invocation_id: str |
특정 콜백 호출의 고유 식별자로, 디버깅에 유용합니다. |
agent_name: str |
현재 콜백과 연결된 상담사의 표시 이름입니다. |
session_id: str |
현재 진행 중인 세션의 고유 세션 식별자입니다. |
variables: dict[str, Any] |
설계 시 정의되거나 런타임 중에 삽입된 변수의 키-값 쌍이 포함된 사전입니다. 이는 콜백 실행 시점의 현재 변수 상태입니다. |
state: dict[str, Any] |
variables 속성과 동일합니다. |
events: list[Event] |
세션 이벤트 |
메서드
| 메서드 | 설명 |
|---|---|
get_variable(key: str, default: Any) -> Any |
상태에서 변수를 가져옵니다. 변수가 없으면 기본값을 반환합니다. |
set_variable(key: str, value: Any) -> None |
상태에서 변수를 설정합니다. |
remove_variable(key: str) -> None |
상태에서 변수를 삭제합니다. |
get_last_user_input() -> list[Part] |
사용자 이벤트의 마지막 청크에 있는 모든 부분의 목록을 가져옵니다. |
get_last_agent_output() -> list[Part] |
에이전트 이벤트의 마지막 청크에 있는 모든 부분의 목록을 가져옵니다. |
parts() -> list[Part] |
세션 기록에 기록된 모든 부분의 목록입니다. |
Content
사용자 또는 에이전트의 메시지 콘텐츠입니다.
속성:
| 속성 | 설명 |
|---|---|
parts: Optional[list[Part]] |
단일 메시지를 구성하는 부분의 목록입니다. 부분마다 IANA MIME 유형이 다를 수 있습니다. |
role: Optional[str] |
콘텐츠 작성자의 역할입니다. 'user' 또는 'agent'. |
메서드
| 메서드 | 설명 |
|---|---|
is_user() -> bool |
역할이 'user'이면 True를 반환합니다. |
is_model() -> bool |
역할이 'model'이면 True를 반환합니다. |
Event
세션의 이벤트 표현입니다.
속성:
| 속성 | 설명 |
|---|---|
id: str |
이벤트 식별자입니다. |
invocation_id: str |
이벤트 호출 식별자입니다. |
author: str |
'user' 또는 상담사 이름으로, 세션에 참석한 사람을 나타냅니다. |
timestamp: int |
이벤트 타임스탬프입니다. |
content: Content |
이 이벤트와 연결된 콘텐츠입니다. |
actions: EventActions |
에이전트가 수행한 작업입니다. |
long_running_tool_ids: set[str] |
장기 실행 함수 호출의 식별자 집합입니다. |
partial: bool |
True: LLM 스트리밍 응답의 불완전한 청크 |
turn_complete: bool |
True: 현재 차례가 완료된 경우 |
error_code: str |
오류 코드입니다. |
error_message: str |
오류 메시지. |
interrupted: bool |
True: 차례가 중단된 경우 |
branch: str |
이벤트의 브랜치입니다. 형식은 agent_1.agent_2.agent_3와 같습니다. 여기서 agent_1는 agent_2의 상위 요소이고 agent_2는 agent_3의 상위 요소입니다.브랜치는 여러 하위 에이전트가 동료 에이전트의 대화 기록을 볼 수 없어야 하는 경우에 사용됩니다. |
grounding_metadata: Any |
이벤트의 그라운딩 메타데이터입니다. |
메서드
| 메서드 | 설명 |
|---|---|
is_user() -> bool |
True: 이벤트 작성자가 'user'인 경우 |
is_agent(agent_name: Optional[str] = None) -> bool |
이벤트 작성자가 상담사인 경우 True입니다. agent_name가 제공되면 작성자가 해당 에이전트와 일치하는지 확인합니다. |
has_error() -> bool |
True: 이벤트에 연결된 오류 코드가 있는 경우 |
parts() -> list[Part] |
이벤트의 content에서 Part 객체 목록을 가져오는 편의 메서드입니다. 콘텐츠 또는 부분이 없으면 빈 목록을 반환합니다. |
EventActions
이벤트에 대해 발생하는 작업입니다.
속성:
| 속성 | 설명 |
|---|---|
skip_summarization: bool |
True인 경우 모델이 함수 응답을 요약하기 위해 호출되지 않습니다. function_response 이벤트에만 사용됩니다. |
state_delta: dict[str,Any] |
이 이벤트로 인한 변수 변경사항입니다. |
artifact_delta: dict[str,Any] |
이 이벤트로 인한 아티팩트 변경사항입니다. 키는 파일 이름이고 값은 버전입니다. |
transfer_to_agent: str |
설정하면 이벤트가 지정된 에이전트로 전송됩니다. |
escalate: bool |
상담사가 상위 상담사에게 에스컬레이션합니다. |
requested_auth_configs: dict[str,dict[str,Any]] |
도구 응답에서 요청한 인증 구성입니다. 이 필드는 도구 요청 인증 사용자 인증 정보를 나타내는 도구 응답 이벤트에 의해서만 설정됩니다. 키: 함수 호출 식별자입니다. 하나의 함수 응답 이벤트에 여러 함수 호출에 해당하는 여러 함수 응답이 포함될 수 있기 때문입니다. 각 함수 호출은 서로 다른 인증 구성을 요청할 수 있습니다. 이 식별자는 함수 호출을 식별하는 데 사용됩니다. 값: 요청된 인증 구성입니다. |
end_invocation: bool |
에이전트 루프가 중단됩니다. |
ExternalResponse
도구 호출 또는 HTTP 요청과 같은 Python 환경 외부의 응답을 나타냅니다.
속성:
| 속성 | 설명 |
|---|---|
text: str |
응답 본문(문자열)입니다. |
status_code: int |
HTTP 상태 코드입니다. |
reason: str |
오류가 발생하는 이유입니다. 오류가 없으면 비어 있습니다. |
ok: bool |
status_code가 400 미만인 경우 True, 그렇지 않으면 False입니다. |
메서드
| 메서드 | 설명 |
|---|---|
json() -> Any |
텍스트 속성 JSON을 파싱하고 결과를 반환합니다. 파싱에 실패하면 오류가 발생합니다. |
raise_for_status() |
응답이 정상이 아니면 StatusError를 발생시킵니다 (ok == False). |
FunctionCall
함수 호출을 나타냅니다.
속성:
| 속성 | 설명 |
|---|---|
id: Optional[str] |
함수 호출의 고유 식별자입니다. |
args: Optional[dict[str,Any]] |
JSON 객체 형식의 함수 파라미터와 값입니다. |
name: Optional[str] |
함수 이름입니다. |
FunctionDeclaration
매개변수 및 해당 값과 함께 FunctionDeclaration name 속성을 나타내는 문자열이 포함된 모델에서 반환된 예측된 FunctionCall입니다.
속성:
| 속성 | 설명 |
|---|---|
name: Optional[str] |
함수 이름입니다. |
FunctionResponse
FunctionDeclaration name 속성을 나타내는 문자열과 함수 호출의 출력이 포함된 구조화된 JSON 객체가 포함된 FunctionCall의 결과입니다.
모델에 대한 컨텍스트로 사용됩니다.
속성:
| 속성 | 설명 |
|---|---|
id: Optional[str] |
해당 함수 호출의 식별자입니다. |
name: Optional[str] |
함수 이름입니다. |
response: Optional[dict[str,Any]] |
JSON 객체 형식의 함수 응답입니다. 'output' 키를 사용하여 함수 출력을 지정하고 'error' 키를 사용하여 오류 세부정보 (있는 경우)를 지정합니다. 'output' 및 'error' 키가 지정되지 않으면 전체 'response'가 함수 출력으로 처리됩니다. |
GenerateContentConfig
선택적 모델 구성 파라미터입니다.
속성:
| 속성 | 설명 |
|---|---|
system_instruction: Optional[Content] |
성능 향상을 위해 모델을 조정하는 안내입니다. 예를 들면 '가능한 한 간결하게 답변하세요' 또는 '응답에 기술 용어를 사용하지 마세요' 등이 있습니다. |
tools: Optional[list[ToolDeclaration]] |
모델이 실행할 수 있는 사용 가능한 도구 목록입니다. |
excluded_tools: Optional[list[str]] |
모델에서 무시할 도구 이름 목록입니다. 이렇게 하면 tools이 재정의됩니다. |
메서드
| 메서드 | 설명 |
|---|---|
hide_tool(tool_name: str) |
excluded_tools 목록에 tool_name를 추가합니다. |
HttpMethod
HTTP 메서드를 나타내는 문자열 enum입니다. 사용할 수 있는 값은 다음과 같습니다.
GETPOSTPUTDELETEPATCHHEADOPTIONS
LlmRequest
LLM에 대한 요청을 나타내는 데이터 모델입니다.
속성:
| 속성 | 설명 |
|---|---|
model: Optional[str] |
모델 이름 |
contents: List[Content] |
모델에 전송된 콘텐츠 목록입니다. |
config: Optional[GeneralContentConfig] |
모델 구성 파라미터입니다. |
LlmResponse
LLM의 응답을 나타내는 데이터 모델입니다.
속성:
| 속성 | 설명 |
|---|---|
content: Content |
모델이 응답하는 첫 번째 Content입니다. |
partial: Optional[bool] |
콘텐츠가 불완전한 모델 응답을 나타내는지 여부를 나타냅니다. 에이전트는 부분 응답을 내보낸 후 처리를 계속합니다. |
메서드
| 메서드 | 설명 |
|---|---|
from_parts(parts: list[Part]) -> LlmResponse |
모델에서 LlmResponse를 반환하는 클래스 메서드입니다. |
샘플:
response = LlmResponse.from_parts(
parts=[
Part.from_text(text="hello world")
]
)
Part
미디어 콘텐츠를 포함하는 데이터 유형입니다.
Part 내에서 정확히 하나의 필드를 설정해야 하며, 이는 전달되는 특정 콘텐츠 유형을 나타냅니다.
동일한 Part 인스턴스 내에서 여러 필드를 사용하는 것은 잘못된 것으로 간주됩니다.
속성:
| 속성 | 설명 |
|---|---|
function_call: Optional[FunctionCall] |
함수 이름을 나타내는 문자열과 파라미터 및 해당 값이 포함된 구조화된 JSON 객체를 포함하는 모델에서 반환된 예측된 FunctionCall입니다. |
function_response: Optional[FunctionResponse] |
함수 이름을 나타내는 문자열과 함수 호출의 출력이 포함된 구조화된 JSON 객체가 포함된 FunctionCall의 결과 출력입니다. 모델에 대한 컨텍스트로 사용됩니다. |
text: Optional[str] |
메시지 텍스트입니다. |
inline_data: Optional[Blob] |
인라인 바이트 데이터입니다. |
메서드
| 메서드 | 설명 |
|---|---|
text_or_transcript() -> Optional[str] |
사용 가능한 경우 텍스트를 반환하고, 그렇지 않으면 인라인 데이터의 스크립트를 반환합니다. |
has_function_call(name) -> bool |
부분에 특정 함수 호출이 포함된 경우 True를 반환합니다. |
has_function_response(name) -> bool |
부분에 특정 함수 응답이 포함된 경우 True를 반환합니다. |
from_text(text: str) -> Part |
텍스트 Part를 만드는 클래스 메서드입니다. |
from_function_call(name: str, args: dict[str, Any]) -> Part |
함수 호출 Part을 만드는 클래스 메서드입니다. |
from_function_response(name: str, response: dict[str, Any]) -> Part |
함수 응답 Part을 만드는 클래스 메서드입니다. |
from_inline_data(data: bytes, mime_type: str) -> Part |
인라인 데이터 Part를 만드는 클래스 메서드입니다. |
from_json(data: str) -> Part |
JSON 인라인 데이터 Part를 만드는 클래스 메서드입니다. |
from_agent_transfer(agent: str) -> Part |
다른 에이전트로 트랜스퍼하기 위해 Part를 만드는 클래스 메서드입니다. |
from_end_session(*, reason: str, escalated: bool = False) -> Part |
세션을 종료하기 위한 Part를 만드는 클래스 메서드입니다. |
from_customized_response(*, content: str, disable_barge_in: bool = False, enable_dtmf: bool = False, dtmf_finish_digit = str: '#', dtmf_endpointing_timeout: int = 3) -> Part |
맞춤설정된 동작 (예: 끼어들기 사용 중지, DTMF 입력 사용 설정 등)으로 응답에 대한 Part를 만드는 클래스 메서드입니다. |
샘플:
text_part = ces_public.Part.from_text(text="Hello from the user!")
tool_part = ces_public.Part.from_function_call(
name="get_weather",
args={"location": "Mountain View"}
)
Requests
HTTP 요청을 수행하기 위한 별칭 클래스입니다. 자세한 내용은 ces_requests 전역 변수를 참조하세요.
메서드
get(url, params=None, **kwargs)post(url, data=None, json=None, **kwargs)put(url, data=None, json=None, **kwargs)delete(url, **kwargs)patch(url, data=None, json=None, **kwargs)head(url, **kwargs)options(url, **kwargs)
StatusError
상태 코드와 함께 발생하는 오류에 사용됩니다.
속성:
| 속성 | 설명 |
|---|---|
status_code: int |
이 오류와 연결된 HTTP 상태 코드입니다. |
reason: str |
오류가 발생하는 이유입니다. |
Tool
이름과 설명이 있는 도구를 나타냅니다.
속성:
| 속성 | 설명 |
|---|---|
name: str |
도구의 이름입니다. |
description: str |
도구의 기능에 대한 설명입니다. |
ToolContext
CallbackContext에서 파생됩니다.
도구를 실행할 때 사용할 수 있는 세션 정보입니다.
속성:
| 속성 | 설명 |
|---|---|
function_call_id: str |
실행 중인 현재 도구 호출의 함수 호출 식별자입니다. |
Tools
도구를 동기식으로 호출하기 위한 별칭 클래스입니다. 자세한 내용은 도구 전역 변수를 참고하세요.
ToolDeclaration
모델에 표시할 수 있는 도구 스키마입니다.
속성:
| 속성 | 설명 |
|---|---|
function_declarations: Optional[list[FunctionDeclaration]] |
도구에서 지원하는 함수 선언 목록입니다. |
함수
get_variable
이 함수는 제공된 키를 사용하여 세션 상태에서 값을 가져옵니다.
context.state.get(key) 또는 context.variables.get(key)의 단축키 역할을 합니다.
샘플 코드:
def get_a_value() -> int:
# Retrieve the value of 'my_key' from the state
my_value = get_variable('my_key')
return my_value + 5
remove_variable
이 함수는 세션 상태에서 키-값 쌍을 삭제합니다.
del context.state[key]의 바로가기입니다.
샘플 코드:
def remove_a_value() -> None:
# Delete 'my_key' from the state
remove_variable('my_key')
set_variable
이 함수는 세션 상태에서 지정된 키의 값을 설정합니다.
키가 이미 있으면 값이 업데이트됩니다.
context.state[key] = value의 바로가기입니다.
샘플 코드:
def set_a_value() -> None:
# Set the value of 'my_key' to 10
set_variable('my_key', 10)
전역 변수
_session
모듈식 구성요소에서와 마찬가지로 대화의 현재 채널과 모달리티에 액세스할 수 있습니다.
_session라는 사전 정의된 변수를 사용하여 이러한 값에 액세스합니다.
Python 도구 샘플 (전역 context 변수 사용):
def check_order_status(order_id: str) -> str:
# Resolve modality and channel from the session state
session_vars = context.variables.get('_session', {})
modality = session_vars.get('modality', 'TEXT')
channel = session_vars.get('channel', 'API')
status = get_raw_order_status(order_id) # Internal API lookup
if modality == 'VOICE':
# Keep response concise and remove markdown/links for natural TTS playback
return "Your order has shipped and is estimated to arrive tomorrow."
else:
# Rich text with markdown links for Chat/Web interfaces
return f"Your order shipped [Track it](https://shipper.com/{order_id})."
콜백 샘플 (CallbackContext 사용):
def before_agent_callback(callback_context: CallbackContext) -> None:
session_vars = callback_context.get_variable('_session', {})
modality = session_vars.get('modality', 'TEXT')
channel = session_vars.get('channel', 'API')
callback_context.set_variable('active_modality', modality)
async_tools
AsyncTools의 인스턴스로, 도구에 비동기 호출을 수행할 수 있습니다.
샘플:
response_future = async_tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)
# ... misc work
response = response_future() # poll for response
# Check if the tool call was successful
try:
response.raise_for_status()
except StatusError:
print(f"Request failed with status {response.status_code}")
# Convert the response to json
data = response.json()
ces_requests
Requests의 인스턴스입니다.
Requests를 사용하면 인기 있는 Python 요청 모듈과 유사한 문법으로 HTTP 호출을 수행할 수 있습니다.
샘플:
# Make a GET request
response = ces_requests.get('https://api.example.com/data')
# Check if the request was successful
try:
response.raise_for_status()
except StatusError:
print(f"Request failed with status {response.status_code}")
# Convert the response to json
data = response.json()
tools
Tools의 인스턴스로, 도구를 동기식으로 호출할 수 있습니다.
샘플:
response = tools.<TOOL_DISPLAY_NAME>(<ARGS_AS_DICT>)
# Check if the tool call was successful
try:
response.raise_for_status()
except StatusError:
print(f"Request failed with status {response.status_code}")
# Convert the response to json
data = response.json()
context
코드에서 ADK 컨텍스트에 액세스할 수 있으며, 이를 사용하여 다양한 유형의 ADK 컨텍스트 데이터를 읽고 쓸 수 있습니다.
context라는 전역 변수를 코드에서 사용할 수 있습니다.
context.state 객체와 context.variables 객체는 서로 바꿔서 사용할 수 있습니다.
state 객체는 ADK 코드와의 호환성을 위해 지원되지만 새 코드에서는 variables 객체를 사용해야 합니다.