GenAI Prompt skill

The GenAI (Generative AI) Prompt skill executes a chat completion request against a large language model (LLM) deployed in Azure OpenAI in Foundry Models or Microsoft Foundry. Use this skill to create new information that can be indexed and stored as searchable content.

Here are some examples of how the GenAI prompt skill can help you create content:

• Verbalize images
• Summarize large passages of text
• Simplify complex content
• Perform any other task that you can articulate in a prompt

The GenAI Prompt skill is generally available in the 2026-04-01 Search Service REST API and in Azure SDKs that target this version. This skill supports text, image, and multimodal content, such as images with visuals and text extracted from PDF files.

Supported models

• You can use any chat completion inference model deployed in Foundry, such as GPT models, Deepseek R#, Llama-4-Mavericj, and Cohere-command-r. For GPT models specifically, only the chat completions API endpoints are supported. Endpoints using the Azure OpenAI Responses API (containing /openai/responses in the URI) aren't currently compatible.

• For image verbalization, the model you use to analyze the image determines what image formats are supported.

• For GPT-5 models, the temperature parameter is not supported in the same way as previous models. If defined, it must be set to 1.0, as other values will result in errors.

• Billing is based on the pricing of the model you use.

Prerequisites

• An Azure OpenAI in Foundry Models resource or Foundry project.

• A supported model deployed to your resource or project.

  • For Azure OpenAI, copy the endpoint with the openai.azure.com domain from the Keys and Endpoint page in the Azure portal. Use this endpoint for the Uri parameter in this skill.

  • For Foundry, copy the target URI for the deployment from the Models page in the Foundry portal. Use this endpoint for the Uri parameter in this skill.

• Authentication can be key-based with an API key from your Foundry or Azure OpenAI resource. However, we recommend role-based access using a search service managed identity assigned to a role.

  • On Azure OpenAI, assign Cognitive Services OpenAI User to the managed identity.

  • On Foundry, assign Foundry User to the managed identity.

    Important

    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.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Data limits

Skill parameters

* Exactly one of apiKey, authIdentity, or the service’s system-assigned identity must be used.

commonModelParameters defaults

Skill inputs

Skill outputs

Sample definitions

Text-only summarization

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    { "name": "systemMessage", "source": "='You are a concise AI assistant.'" },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

Text + image description

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": "11111111-2222-3333-4444-555555555555",
  "responseFormat": { "type": "text" }
}

Structured numerical fact-finder

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

Sample output (truncated)

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

Best practices

• Chunk long documents with the Text Split skill to stay within the model’s context window.
• For high-volume indexing, dedicate a separate model deployment to this skill so that token quotas for query-time RAG workloads remain unaffected.
• To minimize latency, co-locate the model and your Azure AI Search service in the same Azure region.
• Use responseFormat.json_schema with GPT-4o for reliable structured extraction and easier mapping to index fields.
• Monitor token usage and submit quota-increase requests if the indexer saturates your Tokens per Minute (TPM) limits.

Errors and warnings

See also

• Azure AI Search built-in indexers
• Integrated vectorization
• How to define a skillset
• How to generate chat completions with Azure AI model inference (Foundry)
• Structured outputs in Azure OpenAI