Use the image generation tool (preview) in Foundry Agent Service

Generate images from text prompts with the image generation tool in Microsoft Foundry Agent Service. Configure agents, deploy models, and save output.

• The image generation tool requires the gpt-image-1 model. See the Azure OpenAI transparency note for limitations and responsible AI considerations.
• You also need a compatible orchestrator model deployed in the same Foundry project. See Tool support by region and model.

The image generation tool in Microsoft Foundry Agent Service generates images from text prompts in conversations and multistep workflows. The agent’s Foundry model orchestrates the image generation request and returns base64-encoded output that you can save to a file.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help verify model and project requirements and add image-generation tool calls to your agent workflow.

Prerequisites

• An Azure account with an active subscription.
• A Foundry project.
• A basic or standard agent environment. See agent environment setup.
• Foundry User role on the Foundry project to create and manage agent versions.

The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

• Approval to use gpt-image-1. Apply for access to GPT Image models before you deploy the model.
• Two model deployments in the same Foundry project:
  • A compatible Azure OpenAI model deployment for the agent (for example, gpt-5).
  • An image generation model deployment (gpt-image-1) in a supported region.

Usage support

The following table shows SDK and setup support.

Microsoft Foundry support	Python SDK	C# SDK	JavaScript SDK	Java SDK	REST API	Basic agent setup	Standard agent setup
✔️	✔️	✔️	✔️	✔️	✔️	✔️	✔️

Configure the image generation tool

1. Deploy your orchestrator model (for example, gpt-5) to your Foundry project.
2. Deploy gpt-image-1 to the same Foundry project.
3. Confirm your region and model support for image generation. See Best practices for using tools in Microsoft Foundry Agent Service.

Code examples

Use the runtime and install command in your selected language section. The .NET SDK is currently in preview. For general SDK setup, see the quickstart.

When to use the image generation tool

Use the image generation tool when an agent needs to generate an image from a text prompt as part of a conversation or multistep workflow. Use the Azure OpenAI Image API directly for image editing, masks, or partial-image streaming.

Optional parameters

Customize image generation by specifying these optional parameters when you create the tool:

Parameter	Description
size	Image size. One of 1024x1024, 1024x1536, 1536x1024, or auto.
quality	Image quality. One of low, medium, high, or auto.
background	Background type. One of transparent, opaque, or auto.
output_format	Output format. One of png, webp, or jpeg.
output_compression	Compression level for webp and jpeg output (0-100).
moderation	Moderation level for the generated image. One of auto or low.

Image generation time varies based on the quality setting and prompt complexity. For time-sensitive applications, consider using quality: "low".

Use the Responses API if you want to:

• Build conversational image experiences with GPT Image.
• Include image generation in a multistep agent workflow.

Write effective text-to-image prompts

Effective prompts produce better images. Describe the subject, visual style, and composition you want. Use action words like “draw,” “create,” or “edit” to guide the model’s output.

Content filtering can block image generation if the service detects unsafe content in your prompt. For more information, see Guardrails and controls overview.

For a thorough look at how you can tweak your text prompts to generate different kinds of images, see Image prompt engineering techniques.

Verify tool execution

Use either of these approaches to confirm that image generation ran successfully:

• In the response payload, look for an output item with type set to image_generation_call.
• In the Foundry portal, open tracing/debug for your run to confirm the tool call and inspect inputs and outputs.

When image generation succeeds, the response includes an image_generation_call output item with a result field containing base64-encoded image data.

If you see only text output and no image_generation_call item, the request might not be routed to image generation. Review the troubleshooting section.

Troubleshooting

Issue	Cause	Resolution
Image generation fails	Missing deployment	Verify both the orchestrator model (for example, gpt-5) and gpt-image-1 deployments exist in the same Foundry project.
Image generation fails	Missing or incorrect header	Verify the header x-ms-oai-image-generation-deployment is present on the Responses request and matches your image generation deployment name.
Agent uses wrong deployment	Model name misconfiguration	Confirm the orchestrator model name in your agent definition differs from the image generation deployment name.
Prompt doesn’t produce an image	Content filtering blocked the request	Check content filtering logs. See Guardrails and controls overview for guidelines on acceptable prompts.
Tool not available	Regional or model limitation	Confirm the image generation tool is available in your region and with your orchestrator model. See Best practices for using tools.
Generated image has low quality	Prompt lacks detail	Provide more specific and detailed prompts describing the desired image style, composition, and elements.
Image generation times out	Large or complex image request	Simplify the prompt or increase timeout settings. Consider breaking complex requests into multiple simpler ones.
Unexpected image content	Ambiguous prompt	Refine your prompt to be more specific. Include negative prompts to exclude unwanted elements.

Related content

• Best practices for using tools in Microsoft Foundry Agent Service
• Image generation in Azure OpenAI
• Responses API in Azure OpenAI
• Guardrails and controls overview