에이전트 스펙

에이전트 스펙 (Agent Specs)

에이전트 스펙을 사용하면 에이전트를 YAML 또는 JSON으로 선언적으로 정의할 수 있어요. 모델, 지시(instructions), 능력(capabilities) 등 전부를요. 한 줄만으로 로드되며 Python 에이전트 구성 코드가 필요 없어요.

이는 다음과 같은 경우에 유용해요.

• 에이전트 구성을 애플리케이션 코드와 분리할 때
• 개발자가 아닌 사람(프롬프트 엔지니어, 도메인 전문가)이 에이전트를 구성하게 할 때
• 에이전트 정의를 다른 설정 파일과 함께 저장할 때
• 에이전트 구성을 팀이나 프로젝트 간에 공유할 때

출처: 문서

본문

스펙 정의 (Defining a spec)

스펙 파일은 에이전트 구성을 YAML 또는 JSON으로 정의해요.

agent.yaml

model: anthropic:claude-opus-4-6
instructions: You are a helpful research assistant.
model_settings:
  max_tokens: 8192
capabilities:
  - WebSearch:
      local: duckduckgo
  - Thinking:
      effort: high

스펙 로드 (Loading specs)

Agent.from_file은 YAML 또는 JSON 파일에서 스펙을 로드해 에이전트를 구성해요.

from_file_example.py

from pydantic_ai import Agent

agent = Agent.from_file('agent.yaml')

Agent.from_spec은 dict나 AgentSpec 인스턴스를 받으며, 스펙을 보완하거나 덮어쓰는 추가 키워드 인자를 지원해요.

from_spec_example.py

from dataclasses import dataclass

from pydantic_ai import Agent


@dataclass
class UserContext:
    user_name: str


agent = Agent.from_spec(
    {
        'model': 'anthropic:claude-opus-4-6',
        'instructions': 'You are helping {{user_name}}.',
        'capabilities': [{'WebSearch': {'local': 'duckduckgo'}}],
    },
    deps_type=UserContext,
)

키워드 인자는 스펙 필드와 다음과 같이 상호작용해요.

• 스칼라 필드 (model, name, end_strategy 등) — 키워드 인자가 제공되면 스펙 값을 덮어써요. 재시도 예산의 경우 retries 키워드 인자가 스펙의 retries 값을 덮어써요.
• instructions — 병합돼요. 스펙 지시가 먼저 오고, 그다음 키워드 인자 지시가 와요.
• capabilities — 병합돼요. 스펙 능력이 먼저 오고, 그다음 키워드 인자 능력이 와요.
• model_settings — 가산적으로 병합돼요. 키워드 인자 설정이 일치하는 스펙 설정을 덮어써요.
• output_type — 스펙의 output_schema보다 우선해요.

스펙은 model을 생략할 수 있으며, 대신 Agent.from_spec에 제공하거나 에이전트 실행 시 제공할 수 있어요.

deps_type이 전달되면 스펙의 instructions, description 및 능력 인자의 템플릿 문자열이 구성 시점에 deps 타입에 대해 컴파일·검증돼요.

스펙 로드를 더 세밀하게 제어하려면 AgentSpec.from_file로 스펙을 먼저 로드한 뒤 Agent.from_spec에 전달하면 돼요.

템플릿 문자열 (Template strings)

TemplateStr은 Handlebars 스타일 템플릿({{variable}})을 제공하며, 런타임에 에이전트의 의존성(dependencies)에 대해 렌더링돼요. 스펙 파일에서 {{를 포함하는 문자열은 자동으로 템플릿 문자열로 변환돼요.

instructions: "You are assisting {{name}}, who is a {{role}}."

템플릿 변수는 deps 객체의 필드에서 해석돼요. deps_type(또는 deps_schema)가 제공되면 템플릿 변수 이름은 구성 시점에 검증돼요.

Python 코드에서는 TemplateStr을 명시적으로 쓸 수 있지만, IDE 자동완성과 타입 검사를 위해 일반적으로 RunContext를 받는 콜러블이 선호돼요.

template_instructions.py

from dataclasses import dataclass

from pydantic_ai import Agent, TemplateStr


@dataclass
class UserProfile:
    name: str
    role: str


agent = Agent(
    'openai:gpt-5.2',
    deps_type=UserProfile,
    instructions=TemplateStr('You are assisting {{name}}, who is a {{role}}.'),
)
result = agent.run_sync('hello', deps=UserProfile(name='Alice', role='engineer'))
print(result.output)
#> Hello! How can I help you today?

능력 스펙 문법 (Capability spec syntax)

스펙의 능력은 세 가지 형태를 지원해요.

• 'MyCapability' — 인자 없음, MyCapability.from_spec() 호출
• {'MyCapability': value} — 단일 위치 인자, MyCapability.from_spec(value) 호출
• {'MyCapability': {key: value, ...}} — 키워드 인자, MyCapability.from_spec(**kwargs) 호출

이러한 내장 능력은 스펙에서 선언할 수 있어요. Thinking, Instrumentation, WebSearch, WebFetch, ImageGeneration, XSearch, MCP, ToolSearch, PrefixTools, NativeTool, IncludeToolReturnSchemas, SetToolMetadata, RaiseContentFilterError, ReinjectSystemPrompt 등이요. 나머지 내장 능력은 직렬화할 수 없는 인자(콜러블, 툴셋 객체)를 받으므로 Python 코드에서만 쓸 수 있어요.

스펙의 사용자 정의 능력 (Custom capabilities in specs)

사용자 정의 능력을 에이전트 스펙과 연동하는 방법은 능력 게시하기를 참고하세요.

AgentSpec 참조

AgentSpec 모델은 전체 스펙 구조를 나타내요.

deps_schema

Python deps_type 없이 스펙 파일을 로드할 때, deps_schema는 템플릿 문자열 변수 이름을 구성 시점에 검증하는 JSON Schema를 제공해요. 실제 deps 객체를 런타임에 검증하지는 않아요. {{user_name}} 같은 템플릿 변수가 스키마에 정의된 속성과 대응하는지만 보장할 뿐이에요.

output_schema

제공되면(from_spec에 output_type 키워드 인자를 전달하지 않을 때), output_schema는 모델이 최종 출력으로 생성해야 할 구조를 정의해요. 내부적으로 StructuredDict 출력 타입을 만들어요. JSON Schema가 모델 API로 전송되어 모델이 어떤 구조를 만들어야 하는지 알게 되고, 응답은 dict[str, Any]로 반환돼요.

Note

모델의 응답은 스키마의 properties나 required 필드에 대해 검증되지 않아요. 일반 dict로 그대로 받아들여지죠. 스키마는 런타임 검증 제약이 아니라 모델에 대한 지시 역할을 해요.

agent_with_schema.yaml

model: anthropic:claude-opus-4-6
deps_schema:
  type: object
  properties:
    user_name:
      type: string
  required: [user_name]
output_schema:
  type: object
  properties:
    answer:
      type: string
    confidence:
      type: number
  required: [answer, confidence]
instructions: "You are helping {{user_name}}. Always include a confidence score."
capabilities:
  - WebSearch:
      local: duckduckgo

스펙 저장 (Saving specs)

AgentSpec.to_file은 스펙을 YAML 또는 JSON으로 저장하고, 선택적으로 편집기 자동완성을 위한 동반 JSON Schema 파일을 생성해요.

save_spec_example.py

from pydantic_ai import AgentSpec

spec = AgentSpec(
    model='anthropic:claude-opus-4-6',
    instructions='You are a helpful assistant.',
    capabilities=[{'WebSearch': {'local': 'duckduckgo'}}],
)
spec.to_file('agent.yaml')
# Also generates ./agent_schema.json for editor autocompletion

생성된 JSON Schema 파일은 YAML Language Server 프로토콜을 지원하는 편집기에서 자동완성과 검증을 가능하게 해요. 스키마 생성을 건너뛰려면 schema_path=None을 전달하세요.

더 알아보기 (Learn more)

• 에이전트 기본 개념
• Pydantic AI 공식 문서
• 문서 인덱스 확인하기