Repair Tool Arguments
Repair Tool Arguments
이 문서에서는 모델이 잘못된 JSON 도구 인자를 생성했을 때 이를 복구하는 RepairToolArguments capability를 알려드려요. 뒤에 오는 쉼표, 단일 따옴표 키, 불완전한 JSON을 복구하며, 검증·안전 동작과 텔레메트리 방식도 설명해요.
출처: 문서
본문
모델이 뒤에 오는 쉼표(trailing commas), 단일 따옴표 키, 불완전한 JSON을 생성할 때 잘못된 JSON 도구 인자를 복구해요. 이 capability를 단독으로 사용하거나, 이를 포함하는 Coder를 통해 사용할 수 있어요.
Pydantic AI Harness가 0.x 릴리스인 동안에는 minor 릴리스 사이에 API가 바뀔 수 있어요. 그럴 때는 deprecation 경고와 릴리스 노트 마이그레이션 안내가 (당신이나 당신의 에이전트에게) 정확히 업그레이드 방법을 알려줘요. 버전 정책을 참고하세요.
Usage
pydantic-ai-harness를 설치하세요. 복구에는 추가 패키지가 필요 없어요. 이 예시는 로컬 테스트 모델을 사용해요.
Terminal
pip install pydantic-ai-harness
Terminal
uv add pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic_ai_harness.repair_tool_arguments import RepairToolArguments
agent = Agent(TestModel(), capabilities=[RepairToolArguments()])
@agent.tool_plain
async def greet(name: str) -> str:
return f'Hello, {name}!'
result = agent.run_sync('Greet someone')
print(result.output)
Validation and safety
RepairToolArguments는 일반 Pydantic AI 도구 스키마 검증 전에 before_tool_validate에서 json-repair를 사용해요. 이는 에이전트의 모든 도구(다른 capability가 제공하는 도구 포함)에 적용돼요. 유효한 JSON 문자열과 이미 파싱된 인자는 변경 없이 통과해요. 누락된 필드와 잘못된 필드 타입은 여전히 정상적인 검증·재시도 동작을 따르 있어요. 복구 파서가 ValueError나 RecursionError를 발생시키면 원래 인자가 정상 검증을 거쳐요.
복구는 휴리스틱이에요. 잘못된 입력은 모호할 수 있고, 추론된 문자열이 모델의 의도와 다를 수 있어요. 이 capability는 복구 라이브러리에 스키마를 제공하지 않으며 도구 검증, 승인, 실행 검사를 우회하지 않아요. 구성 옵션도 없어요.
Telemetry
각 복구 시도는 ctx.tracer를 통해 repair_tool_arguments 스팬을 발생시켜요. 유효한 JSON과 파싱된 인자는 이 스팬을 발생시키지 않아요. 스팬은 trace_include_content가 활성화된 경우를 포함해 인자나 도구 콘텐츠를 포함하지 않아요. Core는 여전히 일반적인 도구 스팬을 발생시켜요.
소스 코드를 참고하세요.
API reference
RepairToolArguments
Bases: AbstractCapability[AgentDepsT]
json-repair로 잘못된 JSON 도구 인자를 복구해요.
유효한 JSON과 파싱된 인자는 변경 없이 통과해요. 복구는 휴리스틱이며, 복구 시도 후에도 정상 스키마 검증과 재시도가 적용돼요.
Methods
before_tool_validate
@async
def before_tool_validate(
ctx: RunContext[AgentDepsT],
*,
call: ToolCallPart,
tool_def: ToolDefinition,
args: RawToolArgs,
) -> RawToolArgs
정상 도구 스키마 검증 전에 잘못된 JSON 인자를 복구해요.
Returns
RawToolArgs