Python 도구와 콜백에서 Python 코드를 사용할 수 있습니다. 이 참조에서는 코드에서 사용할 수 있는 Python 런타임, 가져오기 옵션 및 클래스, 전역 변수, 함수를 설명합니다.
Python 환경
Python 도구와 콜백은 안전한 샌드박스 환경에서 실행됩니다. 이 환경은 Python 3.12를 실행합니다.
가져오기
모듈을 가져올 수 있는 기능은 다음과 같이 제한됩니다.
클래스
AsyncTools
도구를 비동기적으로 호출하기 위한 별칭 클래스입니다.
자세한 내용은 async_tools 전역 변수를 참고하세요.
Blob
인라인 바이트 데이터입니다.
속성:
| 속성 | 설명 |
|---|---|
display_name: Optional[str] |
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() |
응답이 ok (ok == False)가 아니면 StatusError를 발생시킵니다. |
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) |
tool_name를 excluded_tools 목록에 추가합니다. |
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 |
맞춤 동작 (예: barege-in 사용 중지, 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)
전역 변수
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 객체를 사용해야 합니다.