도구 반환 스키마 포함
도구 반환 스키마 포함 (Include Tool Return Schemas)
IncludeToolReturnSchemas는 모델에 보내는 도구 정의에 반환 타입 스키마를 포함시켜 주는 캐퍼빌리티예요. 모델의 능력에 따라 스키마를 전달하는 방식이 달라지는 점을 이 문서에서 정리해 드릴게요.
출처: 문서
본문
반환 스키마를 네이티브로 지원하는 모델(예: Google Gemini)에서는 스키마가 API 요청의 구조화된 필드로 전달되고, 그 외 모델에서는 도구 설명(description)에 JSON 텍스트로 주입됩니다.
from pydantic_ai import Agent
from pydantic_ai.capabilities import IncludeToolReturnSchemas
from pydantic_ai.models.test import TestModel
test_model = TestModel()
agent = Agent(test_model, capabilities=[IncludeToolReturnSchemas()])
@agent.tool_plain
def get_temperature(city: str) -> float:
"""Get the temperature for a city."""
return 21.0
result = agent.run_sync('What is the temperature in Paris?')
params = test_model.last_model_request_parameters
assert params is not None
td = params.function_tools[0]
assert td.include_return_schema is True
(이 예제는 완전하며, "그대로" 실행할 수 있어요)
tools 매개변수를 사용하면 어떤 도구에 반환 스키마를 포함할지 선택할 수 있어요. 도구 이름 목록, 일치에 쓸 메타데이터 dict, 또는 callable 조건자(predicate)를 받습니다:
from pydantic_ai import Agent
from pydantic_ai.capabilities import IncludeToolReturnSchemas
from pydantic_ai.models.test import TestModel
test_model = TestModel()
agent = Agent(
test_model,
capabilities=[IncludeToolReturnSchemas(tools=['get_temperature'])],
)
@agent.tool_plain
def get_temperature(city: str) -> float:
"""Get the temperature for a city."""
return 21.0
@agent.tool_plain
def get_greeting(name: str) -> str:
"""Get a greeting."""
return f'Hello, {name}!'
result = agent.run_sync('Hello')
params = test_model.last_model_request_parameters
assert params is not None
temp_tool = next(t for t in params.function_tools if t.name == 'get_temperature')
greet_tool = next(t for t in params.function_tools if t.name == 'get_greeting')
assert temp_tool.include_return_schema is True
assert greet_tool.include_return_schema is None
(이 예제는 완전하며, "그대로" 실행할 수 있어요)
같은 효과를 툴셋(toolset) 수준에서 .include_return_schemas()로 얻을 수도 있어요 — 툴셋 구성을 참고하세요.