Azure OpenAI Chat Completions Agent

Overview

The Azure OpenAI Chat Completions Agent Snap accepts input containing an initial request contents, a list of tools, and parameters to invoke an Agent execution loop. The Snap handles the call to the Azure OpenAI Chat Completions, consumes the result and call tools, then collect them accordingly until the model has no more tools to call.


Snap dialog with fieldsets expanded on the right side

Learn more about the Agent Snap in this developer blog.

  • Read-type Snap

Prerequisites

Deploy the specific model in the Azure OpenAI Studio portal. Learn more about how to access Azure OpenAI.

Snap views

View Description Examples of upstream and downstream Snaps
Input This Snap supports a maximum of one binary or document input view. When the Input type is a document, you must provide a field to specify the path to the input prompt. The Snap requires a prompt, which can be generated either by the Azure OpenAI Prompt Generator or any user-desired prompt intended for submission to the chat completions LLM API. Mapper
Output This Snap has at the most one document output view. The Snap provides the result generated by the Azure OpenAI LLMs. Mapper
Error

Error handling is a generic way to handle errors without losing data or failing the Snap execution. You can handle the errors that the Snap might encounter when running the pipeline by choosing one of the following options from the When errors occur list under the Views tab. The available options are:

  • Stop Pipeline Execution Stops the current pipeline execution when an error occurs.
  • Discard Error Data and Continue Ignores the error, discards that record, and continues with the remaining records.
  • Route Error Data to Error View Routes the error data to an error view without stopping the Snap execution.

Learn more about Error handling in Pipelines.

Snap settings

Legend:
  • Expression icon (): Allows using JavaScript syntax to access SnapLogic Expressions to set field values dynamically (if enabled). If disabled, you can provide a static value. Learn more.
  • SnapGPT (): Generates SnapLogic Expressions based on natural language using SnapGPT. Learn more.
  • Suggestion icon (): Populates a list of values dynamically based on your Snap configuration. You can select only one attribute at a time using the icon. Type into the field if it supports a comma-separated list of values.
  • Upload : Uploads files. Learn more.
Learn more about the icons in the Snap settings dialog.
Field / Field set Type Description
Label String

Required. Specify a unique name for the Snap. Modify this to be more appropriate, especially if more than one of the same Snaps is in the pipeline.

Default value: Azure OpenAI Chat Completions Agent

Example: Sales-briefing-agent
Visualize agent flow String

Launch the Agent Visualizer UI.

Default value: N/A
Deployment ID String/Expression/ Suggestion

Required. Specify the deployment ID to run with to receive chat completions.

Default value: N/A

Example: gpt-4o
Message payload String/Expression

Required. Specify the message payload that will be processed by the model. This payload typically includes input messages in JSON format.

Important: Here are the typical scenarios of how the tool calling Snap processes different types of message lists in the input document:
  • If a message does not contain sl_role, the Snap sends the message to the model without any modifications.
  • If a message does not contain sl_role but has sl_type in any item of the content list, the Snap sends without any modifications; however it also displays a lint warning.
  • If the sl_role is SYSTEM, USER or ASSISTANT, the Snap parses the sl_role, name and the content fields. All the other fields are filtered out and are not sent to the model; however, they are displayed in the output document.
  • If the sl_role is SYSTEM, USER or ASSISTANT and if the content is multimodal content generated by Multimodal Content Generator Snap, the Snap reformats the content as the model requires.
  • If the sl_role is TOOL, which is a function result generated by Function Result Generator Snap, the Snap parses the sl_role, name and the content fields. All the other fields are filtered out and are not sent to the model; however they are displayed in the output document.
Learn more about how the tool calling Snap parses the message payload.

Default value: N/A

Example: $inputMessage
Tool payload String/Expression

Required. Specify the tool payload that defines the tools to be called along with the model.

Default value: N/A

Example: $specifiedTools
Output handling Configure how the Snap handles the output data.
Store Checkbox/Expression

Select this checkbox to persist the output. This is an optional setting.

Default status: Deselected
Agent operation configuration

Modify the limitation of the Agent execution.
Iteration limit Integer/Expression

Required. The maximum iterations an agent should run.

Default value: 10

Example: 10
Monitor tool calls Checkbox

Monitor tool call parameters in pipeline statistics.

Default status: Selected
Pool size Integer/Expression

Required. The number of threads for parallel tool execution.

Default value:1

Example: 1
Reuse tool pipeline Checkbox

Reuse the tool pipeline for tool execution.

Default status: Deselected
Advanced tool configuration Use this field set to allow users to configure advanced options for calling the Azure OpenAI tool, enabling fine-tuned control over how the tool operates within the pipeline. Each field within this set provides specific customization options to optimize the performance and results generated by the Azure OpenAI tool.
Tool choice Dropdown list/Expression

Required. Choose the tool or function you want to call within the model. Options available are:

  • SPECIFY A FUNCTION
  • REQUIRED
  • NONE
  • AUTO

Default value: AUTO

Example: REQUIRED
Function name String/Expression

Required.

Appears when SPECIFY A FUNCTION is selected in Tool choice is expression-enabled.

Provide the function name that you want to call from the model. This field is required when specifying a function.
Important: Azure OpenAI has a limit of function names of 1024 characters.

Default value: None

Example: Analyze sentiment
Parallel tool calling Checkbox/Expression Select this checkbox to enable parallel calls to multiple tools.

Default status: Selected
Disable parallel tool calling parameter Checkbox Select this checkbox to remove the parallel tool calling parameter in the request body.

Deselect this checkbox for OpenAI o-series models.

Default status: Deselected
Model parameters Configure the parameters to tune the model runtime.
Reasoning effort Dropdown list Choose the reasoning effort level for the selected model. This Snap supports only OpenAI o-series models. The available options are:
  • Disabled
  • Low
  • Medium
  • High

Default value: disabled

Example: low
Maximum tokens Integer/Expression

Specify the maximum number of tokens to generate in the chat completion. If left blank, the default value of the endpoint is used.

Default value: N/A

Example: 50
Temperature Decimal/Expression

Specify the sampling temperature to use a decimal value between 0 and 1. If left blank, the default value of the endpoint is used.

Default value: N/A

Example: 0.2
Top P Decimal/Expression

Specify the nucleus sampling value, a decimal value between 0 and 1. If left blank, the default value of the endpoint is used.

Default value: N/A

Example: 0.2
Stop sequences String/Expression

Specify a sequence of texts or tokens to stop the model from generating further output. Learn more.

Note:
  • You can configure up to four stop sequences when generating the text. These stop sequences tell the model to halt further text generation if any of the specified sequences are encountered.
  • The returned text does not contain the stop sequence.

Default value: N/A

Example: pay, ["amazing"], ["September", "paycheck"]
Advanced prompt configurations

Set advanced prompt configurations.
JSON mode Checkbox/Expression

To include a JSON response in the output from the chat completion.

Default status: Deselected
Advanced prompt configuration Configure the prompt settings to guide the model responses and optimize output processing.
Structured outputs String/Expression

Enter the schema or expression to ensure that the model always returns outputs that match your defined JSON Schema.

Default value: N/A

Example: $response_format.json_schema

Learn more about how to use the Structured Outputs capability.
JSON mode Checkbox/Expression

Select this checkbox to enable the model to generate strings that can be parsed into valid JSON objects. The output includes the json_output field that contains the parsed JSON object, encapsulating the data.

Default status: Deselected
Snap execution Dropdown list
Choose one of the three modes in which the Snap executes. Available options are:
  • Validate & Execute: Performs limited execution of the Snap and generates a data preview during pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during pipeline runtime.
  • Execute only: Performs full execution of the Snap during pipeline execution without generating preview data.
  • Disabled: Disables the Snap and all Snaps that are downstream from it.

Default value: Validate & Execute

Example: Execute only