이미지 생성 캐퍼빌리티

이미지 생성 캐퍼빌리티 (ImageGeneration Capability)

ImageGeneration 캐퍼빌리티는 에이전트가 이미지를 언제 생성할지 스스로 결정하게 해 줘요. 대화형 모델 공급자의 네이티브 이미지 생성 도구를 선호하고, 직접 이미지 생성 API를 통해 전용 이미지 모델로 폴백할 수 있습니다 (전체 워크스루는 Image Generation 참고).

출처: 문서

본문

from pydantic_ai import Agent, ImageGenerator
from pydantic_ai.capabilities import ImageGeneration
from pydantic_ai.images.openai import OpenAIImageGenerationSettings

image_generator = ImageGenerator(
    'openai:gpt-image-2',
    settings=OpenAIImageGenerationSettings(
        openai_output_format='png',
        openai_quality='low',
    ),
)

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    capabilities=[
        ImageGeneration(
            native=False,
            local=image_generator,
            dimensions=(1024, 1024),
        )
    ],
)

ImageGeneration()은 기본적으로 네이티브 전용이에요. 이미지 API를 통해 — 다른 에이전트를 만들지 않고 — 생성하는 폴백을 두 필드 중 하나로 추가하는데, 무엇을 가졌느냐에 따라 선택합니다: ImageGenerator는 자체 설정을 지니므로 여러분이 공급하는 다른 구현들과 함께 local에 들어가고, 베어 ImageGenerationModel 또는 'provider:model' 이름은 fallback_image_model에 들어가요. 어느 쪽이든 직접 모델은 이미지 API로 생성하며, fallback_subagent_model은 서브에이전트에서 대화형 모델을 실행합니다. 이것은 에이전트의 모델에 네이티브 이미지 생성이 없을 때 — 또는 native=False면 매 호출마다 — 도달합니다. ImageGeneration은 번들 로컬 전략이 없으므로 그 외에는 local이 여러분 자신의 도구를 받습니다.

두 필드가 이미지 모델을 가리키지만 상호 교환할 수는 없어요: image_model은 공급자의 네이티브 도구를 설정하며 접두사가 없고 (image_model='gpt-image-2'), fallback_image_model은 직접 모델을 선택하며 그 공급자를 지닙니다.

from pydantic_ai import ImageGenerator
from pydantic_ai.capabilities import ImageGeneration
from pydantic_ai.images.openai import OpenAIImageGenerationSettings

# Native preferred; use the direct model when native generation is unavailable
ImageGeneration(fallback_image_model='openai:gpt-image-1.5')

# Always use the direct image API
ImageGeneration(native=False, fallback_image_model='google:gemini-3.1-flash-lite-image')

# Supply reusable direct settings through an explicit generator, which goes on `local`
generator = ImageGenerator(
    'openai:gpt-image-2',
    settings=OpenAIImageGenerationSettings(
        openai_output_format='jpeg',
        openai_quality='low',
    ),
)
ImageGeneration(native=False, local=generator, dimensions=(1280, 720))


# A custom callable or Tool of your own also goes on `local`
def my_image_tool(prompt: str) -> bytes: ...


ImageGeneration(local=my_image_tool)

이식 가능한 dimensions와 aspect_ratio 캐퍼빌리티 설정은 명시적 생성자의 기본값을 덮어써요. dimensions를 적용할 수 있는 것은 직접 생성자뿐이고, 네이티브 도구가 공유하지 않는 종횡비(aspect ratio)를 적용할 수 있는 것도 직접 생성자뿐입니다. 그래서 어느 하나가 보장되어야 한다면 native=False를 전달하세요. 기본 native=True에서는 네이티브로 이미지 생성하는 모델이 네이티브 경로를 타고, 그 경로에는 이에 해당하는 것이 없어 두 설정이 적용되지 않았다는 경고가 나옵니다. quality나 output_format 같은 네이티브 도구 전용 설정은 직접 폴백에 적용되지 않으므로, 생성자에 공급자 접두사가 붙은 동등 설정을 구성하세요. action='edit'와 image_model도 적용되지 않아요: 직접 폴백은 action='edit'에 UserError를 발생시키는데 generate_image 도구가 참조 이미지를 받지 못하기 때문이고, image_model은 생성자가 이미 생성에 쓸 이미지 모델을 가리키므로 경고와 함께 무시합니다. native=False는 직접 생성자를 유일한 경로로 만들므로 둘 다 생성 시점에 처리됩니다 — 버려진 설정은 경고로, action='edit'는 오류로요. 네이티브가 활성화되면 네이티브 도구가 여전히 그것들을 지니므로, 대신 직접 생성자로 라우팅되는 요청이 적용되지 않았다고 경고하고, action='edit'에 대해서는 오류를 냅니다. 직접 생성자는 정확히 하나의 생성된 BinaryImage를 반환해야 해요. 여러 이미지나 참조 이미지 편집이 필요하다면 ImageGenerator를 직접 사용하세요.

ImageGenerationTool이 네이티브 구현입니다 (공급자 지원과 설정은 Image Generation Tool 참고). 전체 공급자 네이티브 설정이 필요하면 native=ImageGenerationTool(...)로 명시적 인스턴스를, 동적 구성에는 ImageGenerationTool 또는 None을 반환하는 RunContext를 받는 callable을 전달하세요. callable은 매 모델 요청마다, 그리고 fallback_subagent_model 서브에이전트가 실행될 때 다시 해석됩니다. 두 해석 모두 같은 deps를 받지만, 서브에이전트는 자체 RunContext를 가져요. 양쪽에서 일치해야 하는 설정은 ctx.deps를 사용하세요. 캐퍼빌리티 수준 필드는 서브에이전트에서 팩토리 결과를 덮어씁니다.

정적 네이티브 인스턴스의 aspect_ratio는 구성한 어떤 폴백(fallback_subagent_model 서브에이전트나 직접 생성자)에도 전달되고, 캐퍼빌리티 수준 aspect_ratio는 그것보다 우선하며, 캐퍼빌리티 수준 dimensions도 마찬가지인데 그것은 같은 기하를 다르게 쓴 것이므로 결합할 수 없어요. 상속만 그렇게 동작합니다. 캐퍼빌리티 자체에 dimensions와 aspect_ratio를 모두 설정하면 직접 생성자가 적용하도록 구성된 경우 생성 시점에 UserError가 발생합니다.

계측은 에이전트가 아니라 생성자별이에요. 에이전트 수준 Instrumentation 캐퍼빌리티는 직접 생성자에 닿지 않으므로, 생성자가 자체 계측을 지니지 않는 한 런이 image_generation 스팬을 기록하지 않습니다. 생성할 때 instrument=를 전달하거나, ImageGenerator.instrument_all()로 전역 켜세요:

from pydantic_ai import ImageGenerator
from pydantic_ai.capabilities import ImageGeneration

ImageGeneration(native=False, local=ImageGenerator('openai:gpt-image-2', instrument=True))

그 스팬이 무엇을 담는지 Instrumentation을 보세요.

Temporal과의 지속 실행

생성된 이미지는 Temporal의 activity 경계를 넘어야 하는데, 페이로드 크기 제한이 원시 이미지 바이트에 대해 대략 1.5MB를 남겨요. 더 큰 이미지는 UserError로 실패합니다 — 로컬 구현(local= ImageGenerator, fallback_image_model, 서브에이전트 폴백, 또는 여러분의 local= callable·툴셋)에서 왔을 때는 도구 이름을, 네이티브 도구가 응답에 올렸을 때는 모델 이름을 말합니다. 옵션은 Large Payloads를 보세요.

폴백 옵션 (Fallback Options)

네이티브로 이미지를 생성하지 않는 모델을 두 가지 내장 메커니즘이 커버합니다:

  • 직접 모델 (Direct model): ImageGenerator를 가진 local=, 또는 이미지 모델 이름이나 ImageGenerationModel을 가진 fallback_image_model=. 도구 호출은 추가 에이전트 런 없이 단일 이미지 API 호출이고, 이식 가능한 dimensions와 aspect_ratio 설정을 적용합니다. 기하나 이미지 모델 선택이 여러분의 몫일 때 사용하세요.
  • 서브에이전트 (Subagent): 네이티브로 이미지를 생성하는 대화형 모델을 가진 fallback_subagent_model=. 도구 호출은 그 네이티브 ImageGenerationTool이 이미지를 만드는 추가 에이전트를 실행합니다. 그 모델의 네이티브 도구 시맨틱과 그것이 지니는 설정을 원할 때 사용하세요.

여러분이 작성한 local= callable, Tool, 툴셋은 둘 다를 대체합니다. 세 필드는 대안 관계라 하나보다 많이 지정하면 UserError가 나요.

fallback_model은 더 이상 사용되지 않아요.

fallback_model은 fallback_subagent_model의 이전 이름입니다. 파이썬과 에이전트 스펙 모두에서 계속 동작하며 경고를 냅니다. 두 이름을 함께 전달하면 거부됩니다: 캐퍼빌리티를 만들 때는 UserError, 스펙 로더는 그것을 ValueError로 감쌉니다.

None을 반환하는 팩토리

fallback_subagent_model이 없으면 None은 그 요청에 대해 네이티브 도구를 생략합니다. fallback_subagent_model이 있으면 서브에이전트 도구는 계속 사용 가능하고, 그것을 호출하면 기본 이미지 설정을 조용히 쓰는 대신 UserError가 발생해요.

Temporal 아래의 동적 구성

서브에이전트 도구 호출은 Temporal activity 안에서 실행되므로, 그 native= 팩토리는 제한된 TemporalRunContext를 받아요. ctx.deps는 경계를 넘지만 ctx.messages 같은 필드는 그렇지 않습니다. Agent Run Context and Dependencies를 보세요.

서브에이전트는 네이티브 도구의 기하 어휘를 사용합니다. dimensions 같은 직접 전용 값, 임의의 GPT Image 2 크기, 추가 종횡비는 경고와 함께 무시됩니다. 직접 기하 설정을 적용하려면 직접 생성자와 함께 native=False를 사용하세요 (local=ImageGenerator(...) 또는 fallback_image_model='provider:image-model').

어느 로컬 경로에서든 공급자 콘텐츠 블록은 재시도 프롬프트가 되어, 프롬프트를 쓴 모델이 런을 실패시키는 대신 다시 표현할 기회를 얻어요. 다른 실패는 둘 사이에서 다릅니다: 서브에이전트는 런의 UnexpectedModelBehavior도 재시도 프롬프트로 바꾸지만, 직접 모델은 그것을 발생시킵니다. ImageGenerator를 그 자체로 쓰는 것은 영향을 받지 않으며 — ContentFilterError를 발생시켜요. 직접 API의 예외는 error handling을 보세요.

에이전트 스펙 (Agent Specs)

fallback_image_model='openai:gpt-image-1.5' 같은 직접 모델 이름은 JSON 또는 YAML 에이전트 스펙으로 표현할 수 있어요. 파이썬 생성자가 받는 런타임 객체 — fallback_image_model의 ImageGenerationModel, local이 받는 ImageGenerator, Tool, 툴셋, callable — 는 직렬화할 수 없으므로 파이썬에서 구성해야 합니다. from_spec()은 그 직렬화 가능한 부분집합을 명시적으로 유지하면서 같은 설정 이름을 노출합니다. dimensions는 JSON·YAML이 쓰는 두 항목 배열로 쓰세요. Pydantic AI가 파이썬 API가 쓰는 (width, height) 튜플로 변환합니다:

model: anthropic:claude-sonnet-4-6
capabilities:
  - ImageGeneration:
      native: false
      fallback_image_model: openai:gpt-image-2
      dimensions: [1280, 720]

더 알아보기 (Learn more)