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-Maverick, 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

Security considerations for managed identity authentication

When the GenAI Prompt skill uses managed identity authentication, Azure AI Search obtains a Microsoft Entra access token for the Foundry Tools audience (https://cognitiveservices.azure.com) and includes it in requests sent to the endpoint specified by uri. Managed identity authentication applies when authIdentity is set, or when both apiKey and authIdentity are empty and the service uses the system-assigned identity.

The endpoint referenced by uri is expected to be your own Azure OpenAI or Foundry resource. Supported domains are:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

Azure API Management (APIM) endpoints (*.azure-api.net) and custom domains that front these resources are also supported. Because a custom domain or APIM hostname can't be verified from its name alone, Azure AI Search validates these endpoints with a live connectivity check at configuration time rather than by domain matching. You're responsible for configuring and maintaining the relationship between the endpoint and the Azure OpenAI or Foundry resource behind it.

Recommended security practices

To help maintain a secure deployment, follow these practices:

• Set uri only to endpoints you own and trust. Prefer the Foundry Tools domains listed earlier. If you use an APIM or custom-domain endpoint, confirm it fronts your own resource before enabling managed identity. A trusted-looking hostname isn't proof of ownership.
• Apply the principle of least privilege to the managed identity used by the search service:
  • On Azure OpenAI, assign only Cognitive Services OpenAI User.
  • On Foundry, assign only Foundry User. Avoid granting broader roles.
• Use Network Security Perimeter (NSP) and private endpoints or VNet integration to restrict which endpoints the search service can reach and which sources the target resource accepts requests from.
• If you use an APIM or custom-domain endpoint, ensure the gateway validates inbound requests and forwards them only to the intended backend. You should also review its access policies periodically.
• Prefer managed identity over apiKey. If you use apiKey, store and rotate it securely and don't embed it in source control. The service rejects configurations that set both apiKey and authIdentity.
• Periodically review skillset definitions, managed identity role assignments, and APIM and custom-domain configurations to confirm that uri values, access controls, and identity permissions remain current and appropriate. Review configuration changes through your established change-management and security-review processes.
• Monitor Azure OpenAI, Foundry Tools, and Foundry sign-in logs, authentication events, and access logs for unexpected or unauthorized activity.
• Remove unused skills, endpoints, role assignments, and API keys that are no longer required.

Restrict access to skillset configuration

Users who can create, modify, or run skillsets control both the destination endpoint (uri) and the authentication configuration used by the skill. Because the skill sends a managed identity token for the Foundry Tools audience to that endpoint, restrict these permissions to trusted administrators and follow your standard change-management and security-review processes when configuring managed identity–enabled skills.

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