Implementation:Openai Openai agents python ImageGenerationTool Pattern

Knowledge Sources	Openai_Openai_agents_python
Domains	Tool_Integration, Image_Generation
Last Updated	2026-02-11 00:00 GMT

Overview

Demonstrates the ImageGenerationTool hosted tool, showing how to configure image generation quality and extract generated images from run results by inspecting image_generation_call items and decoding base64 image data.

Description

This implementation shows how to use the ImageGenerationTool as a hosted tool within an agent. The tool is configured via a tool_config dictionary that specifies the type as "image_generation" and sets quality parameters (e.g., "low"). When the agent decides to generate an image, the model invokes the hosted tool on the server side, and the result comes back as part of the run items.

Extracting generated images requires iterating over result.new_items and filtering for items where item.type == "tool_call_item" and the raw item has type == "image_generation_call". The result field of the raw item contains the image data as a base64-encoded string, which can be decoded and written to a file. The example uses a helper function _get_field that handles both Mapping (dict-like) and attribute-based access patterns, ensuring compatibility with different response formats.

The example also includes a cross-platform open_file utility that opens the generated image using the system default viewer on macOS, Windows, or Linux.

Usage

Use this pattern when building agents that need to generate images as part of their responses. This is particularly useful for creative assistants, content generation tools, or any workflow that requires on-the-fly image creation with configurable quality settings.

Code Reference

Source Location

• Repository: Openai_Openai_agents_python
• File: examples/tools/image_generator.py
• Lines: 1-68

Signature

ImageGenerationTool(
    tool_config={"type": "image_generation", "quality": "low"},
)

Import

from agents import Agent, ImageGenerationTool, Runner, trace

I/O Contract

Inputs

Name	Type	Required	Description
tool_config	dict	Yes	Configuration dictionary specifying the tool type ("image_generation") and quality level (e.g., "low", "medium", "high").
prompt	str	Yes (at Runner.run)	The user prompt describing what image to generate, passed to Runner.run().

Outputs

Name	Type	Description
result.final_output	str	The agent's text response about the generated image.
result.new_items	list[RunItem]	List of run items; items with type == "tool_call_item" and raw item type "image_generation_call" contain the generated image data.
raw_item.result	str	Base64-encoded PNG image data from the image generation call.

Usage Examples

Generate an Image and Save to File

import asyncio
import base64
import tempfile
from collections.abc import Mapping
from typing import Any

from agents import Agent, ImageGenerationTool, Runner, trace


def _get_field(obj: Any, key: str) -> Any:
    if isinstance(obj, Mapping):
        return obj.get(key)
    return getattr(obj, key, None)


async def main():
    agent = Agent(
        name="Image generator",
        instructions="You are a helpful agent.",
        tools=[
            ImageGenerationTool(
                tool_config={"type": "image_generation", "quality": "low"},
            )
        ],
    )

    with trace("Image generation example"):
        result = await Runner.run(
            agent, "Create an image of a frog eating a pizza, comic book style."
        )
        print(result.final_output)

        for item in result.new_items:
            if item.type != "tool_call_item":
                continue

            raw_call = item.raw_item
            call_type = _get_field(raw_call, "type")
            if call_type != "image_generation_call":
                continue

            img_result = _get_field(raw_call, "result")
            if not isinstance(img_result, str):
                continue

            with tempfile.NamedTemporaryFile(suffix=".png", delete=False) as tmp:
                tmp.write(base64.b64decode(img_result))
                print(f"Image saved to: {tmp.name}")

asyncio.run(main())

Related Pages

• Environment:Openai_Openai_agents_python_OpenAI_API_Credentials