Azure AI Foundry Agent Service (Preview)

Easily integrate Azure AI Foundry Agent Service capabilities into your workflows.

This connector is available in the following products and regions:

Service Class Regions
Copilot Studio Standard All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Logic Apps Standard All Logic Apps regions except the following:
     -   Azure Government regions
     -   Azure China regions
     -   US Department of Defense (DoD)
Power Apps Standard All Power Apps regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Power Automate Standard All Power Automate regions except the following:
     -   US Government (GCC)
     -   US Government (GCC High)
     -   China Cloud operated by 21Vianet
     -   US Department of Defense (DoD)
Contact
Name Microsoft
URL https://support.microsoft.com
Connector Metadata
Publisher Microsoft
Website https://learn.microsoft.com/en-us/azure/ai-services/agents/
Privacy policy https://learn.microsoft.com/en-us/legal/cognitive-services/agents/data-privacy-security
Categories AI;Business Intelligence

Azure AI Agent Service is a fully managed service designed to empower developers to securely build, deploy, and scale high-quality, and extensible AI agents without needing to manage the underlying compute and storage resources. Azure AI Agent Service integrates models, tools and technology and enables you to extend agents with knowledge from connected sources (such as Bing Search, SharePoint, Fabric, Azure Blob storage, and licensed data) and actions using tools such as Azure Logic Apps, Azure Functions, OpenAPI 3.0 specified tools and Code Interpreter

Prerequisites

Get your credentials

To authenticate your API requests, you will need the endpoint for your Azure AI Agent Service resources.

For your Azure AI Agent Service resource:

  1. Navigate to your resource in the Azure portal.
  2. On the page for your resource, select Keys and endpoint on the left navigation menu. Make note of your credentials. You will use one of your keys and your endpoint.

Known issues and limitations

  • Only Azure AI Agent Service is supported as a agent service with this Power Platform connector for Logic Apps only. Not for power automate and power apps

Creating a connection

The connector supports the following authentication types:

Managed Identity Create a connection using a Managed Identity LOGICAPPS only Shareable
Microsoft Entra ID User Login Login with Microsoft Entra ID Credentials All regions Not shareable
Default [DEPRECATED] This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility. All regions Not shareable

Managed Identity

Auth ID: managedIdentityAuth

Applicable: LOGICAPPS only

Create a connection using a Managed Identity

This is shareable connection. If the power app is shared with another user, connection is shared as well. For more information, please see the Connectors overview for canvas apps - Power Apps | Microsoft Docs

Name Type Description Required
Managed Identity managedIdentity Sign in with a Managed Identity True
Azure AI Project Endpoint string The name of the Azure AI Project Endpoint like https://{account-name}.services.ai.azure.com/api/projects/{project-name} True

Microsoft Entra ID User Login

Auth ID: entraIDUserLogin

Applicable: All regions

Login with Microsoft Entra ID Credentials

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Name Type Description Required
Azure AI Project Endpoint string The name of the Azure AI Project Endpoint like https://{account-name}.services.ai.azure.com/api/projects/{project-name} True

Default [DEPRECATED]

Applicable: All regions

This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Throttling Limits

Name Calls Renewal Period
API calls per connection 1000 60 seconds

Actions

Create Hosted Agent

Creates a hosted agent and its initial version from a container image.

Create Hosted Agent Version

Creates a new hosted agent version from a container image.

Create Hosted Session

Creates a hosted agent session. Optionally select a specific agent version; otherwise, the hosted agent's routing configuration selects the version.

Create Prompt Agent Version

Creates a new prompt agent version using a model deployment, instructions, and optional tools.

Create Run

Create Run

Create Thread

Create Thread

Delete Agent

Permanently deletes an agent and all of its versions. For hosted agents, active sessions cause a conflict unless Force delete is enabled.

Delete Agent Version

Permanently deletes a specific agent version. For hosted agents, active sessions cause a conflict unless Force delete is enabled.

Delete Hosted Session

Deletes a hosted agent session, terminates its sandbox, and releases its resources.

Delete Hosted Session File

Deletes a file or directory from a hosted session.

Disable Hosted Agent

Disables a hosted agent endpoint without deleting the agent or its versions.

Download Hosted Session File

Downloads the binary content of a file from a hosted session.

Enable Hosted Agent

Enables a hosted agent endpoint so that it can serve requests.

External agent activity protocol based on agent identifier

External agent activity protocol based on agent identifier

External agent activity protocol based on agent identifier with V2 endpoint

External agent activity protocol based on agent identifier with V2 endpoint

External agent activity protocol based on application

External agent activity protocol based on application

Get Agent

Gets an agent and its latest version.

Get Agent Version

Gets a specific version of an agent.

Get Hosted Session

Gets a hosted agent session by its session identifier.

Get Run

Get Run

Invoke Hosted Agent (Invocations)

Invokes a hosted agent that exposes the Invocations protocol. The request and response JSON are defined by the hosted agent implementation.

Invoke Hosted Agent (Responses)

Invokes a hosted agent that exposes the Responses protocol. The action uses non-streaming JSON responses.

Invoke Prompt Agent

Invokes a prompt agent.

List Agent Versions

Lists versions of an agent.

List Agents

List Agents

List Agents (Agent Service)

List Agents from Agent Service

List Hosted Session Files

Lists files and directories at a path in a hosted session.

List Hosted Sessions

Lists hosted sessions for an agent that are accessible to the caller.

List Messages

List Messages

Update Hosted Agent Routing

Updates the hosted agent endpoint to route 100 percent of traffic to a specific active agent version. Draft versions cannot be routing targets.

Upload Hosted Session File

Uploads raw file content to a hosted session. The maximum file size is 50 MB.

Create Hosted Agent

Creates a hosted agent and its initial version from a container image.

Parameters

Name Key Required Type Description
Agent name
name True string

The name of the hosted agent.

Description
description string

A human-readable description of the hosted agent.

Metadata
metadata object

Metadata to associate with the hosted agent.

Container image
image True string

The full container image reference, for example myregistry.azurecr.io/my-agent:v1.

Registry connection ID
registry_connection_id string

The Foundry project connection identifier for the container registry, when required.

CPU
cpu True string

The number of CPU cores requested for the hosted agent container, for example 1.

Memory
memory True string

The amount of memory requested for the hosted agent container, for example 2Gi.

Protocol
protocol True string

The protocol exposed by the hosted agent. Select Responses or Invocations.

Environment variables
environment_variables object

Environment variables passed to the hosted agent container.

Responsible AI configuration
rai_config object

Optional responsible AI content-filter configuration.

Telemetry configuration
telemetry_config object

Optional telemetry configuration.

Session configuration
session_configuration object

Optional hosted-agent session configuration.

Returns

Create Hosted Agent Version

Creates a new hosted agent version from a container image.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Description
description string

A human-readable description of the hosted agent version.

Metadata
metadata object

Metadata to associate with the hosted agent version.

Create as draft
draft boolean

Whether to create a draft version. Draft versions are excluded from normal routing and listings.

Container image
image True string

The full container image reference, for example myregistry.azurecr.io/my-agent:v1.

Registry connection ID
registry_connection_id string

The Foundry project connection identifier for the container registry, when required.

CPU
cpu True string

The number of CPU cores requested for the hosted agent container, for example 1.

Memory
memory True string

The amount of memory requested for the hosted agent container, for example 2Gi.

Protocol
protocol True string

The protocol exposed by the hosted agent. Select Responses or Invocations.

Environment variables
environment_variables object

Environment variables passed to the hosted agent container.

Responsible AI configuration
rai_config object

Optional responsible AI content-filter configuration.

Telemetry configuration
telemetry_config object

Optional telemetry configuration.

Session configuration
session_configuration object

Optional hosted-agent session configuration.

Returns

Create Hosted Session

Creates a hosted agent session. Optionally select a specific agent version; otherwise, the hosted agent's routing configuration selects the version.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Agent version
agent_version string

A specific hosted agent version for the session. Leave blank to use the hosted agent's routing configuration.

Returns

Create Prompt Agent Version

Creates a new prompt agent version using a model deployment, instructions, and optional tools.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Description
description string

A human-readable description of the prompt agent version.

Metadata
metadata object

Metadata to associate with the prompt agent version.

Create as draft
draft boolean

Whether to create a draft version.

Model deployment
model True string

The name of a model deployment available in the current Foundry project. Supported Foundry direct model names can also be entered manually.

Instructions
instructions string

System instructions that define the prompt agent's behavior.

Tools
Tools object
Tool choice
tool_choice

Controls how the prompt agent selects tools.

Temperature
temperature float

Sampling temperature between 0 and 2.

Top P
top_p float

Nucleus sampling probability between 0 and 1.

Text configuration
text object

Optional text and structured-output configuration.

Reasoning configuration
reasoning object

Optional reasoning configuration for supported models.

Skills
Skills object
Structured inputs
structured_inputs object

Optional structured input definitions.

Harness
harness object

Optional agent harness configuration.

Returns

Create Run

Create Run

Parameters

Name Key Required Type Description
API version
api-version True string

API version

The ID of the thread to create a message for.
ThreadId True string

The ID of the thread to create a message for.

assistant_id
assistant_id True string

The ID of the assistant to use to execute this run.

model
model string

The model deployment name to be used to execute this run. If provided, it overrides the assistant's model deployment name.

instructions
instructions string

Overrides the instructions of the assistant. Useful for modifying behavior on a per-run basis.

additional_instructions
additional_instructions string

Appends additional instructions at the end of the instructions for the run.

role
role string

The role of the entity that is creating the message. Can be user or assistant. 'user' indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. 'assistant' indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.

content
content string

The content of the message.

name
name string

List of file ids or messages that can be used in the run.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

name
name string

List of tools that can be used in the run.

metadata
metadata object

Set of 16 key-value pairs attached to an object. Keys max length: 64 chars, Values max length: 512 chars.

temperature
temperature number

Sampling temperature (0-2). Higher values (e.g., 0.8) increase randomness, lower values (e.g., 0.2) make output more deterministic.

top_p
top_p number

Nucleus sampling alternative to temperature. 0.1 means top 10% probability mass is considered.

stream
stream boolean

If true, returns a stream of events during the run as server-sent events, terminating with a 'data: [DONE]' message.

max_prompt_tokens
max_prompt_tokens integer

The maximum number of completion tokens that might be used over the run. If exceeded, the run ends as incomplete.

max_completion_tokens
max_completion_tokens integer

The maximum number of completion tokens that might be used over the run. If exceeded, the run ends as incomplete.

truncation_strategy
truncation_strategy object

Controls how a thread is truncated before the run to manage the initial context window.

tool_choice
tool_choice

Controls which tool the model calls. Defaults to 'auto', allowing the model to decide. Can be set to 'none' to disable tool usage.

response_format
response_format object

Specifies the output format. Setting { 'type': 'json_object' } enables JSON mode for valid JSON responses.

Returns

Create Thread

Create Thread

Parameters

Name Key Required Type Description
API version
api-version True string

API version

role
role string

The role of the entity that is creating the message. Can be user or assistant. 'user' indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. 'assistant' indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.

content
content string

The content of the message.

name
name string

List of file ids or messages that can be used in the run.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

tool_resources
tool_resources object

A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

Returns

Delete Agent

Permanently deletes an agent and all of its versions. For hosted agents, active sessions cause a conflict unless Force delete is enabled.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Force delete
force boolean

For hosted agents, delete active sessions associated with the agent or version.

Delete Agent Version

Permanently deletes a specific agent version. For hosted agents, active sessions cause a conflict unless Force delete is enabled.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Agent version
AgentVersion True string

The version identifier of the agent.

Force delete
force boolean

For hosted agents, delete active sessions associated with the agent or version.

Delete Hosted Session

Deletes a hosted agent session, terminates its sandbox, and releases its resources.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Session ID
SessionId True string

The hosted session identifier.

Delete Hosted Session File

Deletes a file or directory from a hosted session.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Session ID
SessionId True string

The hosted session identifier.

File path
path True string

The path of the file or directory in the hosted session.

Disable Hosted Agent

Disables a hosted agent endpoint without deleting the agent or its versions.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Download Hosted Session File

Downloads the binary content of a file from a hosted session.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Session ID
SessionId True string

The hosted session identifier.

File path
path True string

The path of the file or directory in the hosted session.

Returns

The content of the hosted session file.

File content
binary

Enable Hosted Agent

Enables a hosted agent endpoint so that it can serve requests.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

External agent activity protocol based on agent identifier

External agent activity protocol based on agent identifier

Parameters

Name Key Required Type Description
The ID of the agent to send a message to.
AgentId True string

The ID of the agent to send a message to.

object

Returns

response
object

External agent activity protocol based on agent identifier with V2 endpoint

External agent activity protocol based on agent identifier with V2 endpoint

Parameters

Name Key Required Type Description
The ID of the agent to send a message to.
AgentId True string

The ID of the agent to send a message to.

object

Returns

response
object

External agent activity protocol based on application

External agent activity protocol based on application

Parameters

Name Key Required Type Description
Agent application.
MyApplication True string

Agent application.

object

Returns

response
object

Get Agent

Gets an agent and its latest version.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Returns

Get Agent Version

Gets a specific version of an agent.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Agent version
AgentVersion True string

The version identifier of the agent.

Returns

Get Hosted Session

Gets a hosted agent session by its session identifier.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Session ID
SessionId True string

The hosted session identifier.

Returns

Get Run

Get Run

Parameters

Name Key Required Type Description
API version
api-version True string

API version

The ID of the thread to create a message for.
ThreadId True string

The ID of the thread to create a message for.

The ID of the run.
RunId True string

The ID of the run.

Returns

Invoke Hosted Agent (Invocations)

Invokes a hosted agent that exposes the Invocations protocol. The request and response JSON are defined by the hosted agent implementation.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

object

The JSON payload expected by the hosted agent's Invocations handler.

Returns

response
object

Invoke Hosted Agent (Responses)

Invokes a hosted agent that exposes the Responses protocol. The action uses non-streaming JSON responses.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Input
input True

Text, image, file, or structured input for the hosted agent.

Previous response ID
previous_response_id string

The previous response identifier to continue a multi-turn interaction.

Instructions
instructions string

Additional instructions for this response.

Store response
store boolean

Whether to store the response for later retrieval.

Run in background
background boolean

Whether to run the response in the background.

Maximum output tokens
max_output_tokens integer

The maximum number of output tokens.

Metadata
metadata object

Metadata to associate with the response.

User
user string

A unique identifier for the end user.

Returns

Invoke Prompt Agent

Invokes a prompt agent.

Parameters

Name Key Required Type Description
API version
api-version True string

API version

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

user
user string

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

top_logprobs
top_logprobs integer

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.

previous_response_id
previous_response_id string

The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about conversation state.

background
background boolean

Whether to run the model response in the background. Learn more.

max_output_tokens
max_output_tokens integer

An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

max_tool_calls
max_tool_calls integer

The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.

type
type True string

An object specifying the format that the model must output.

Configuring { "type": "json_schema" } enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

The default format is { "type": "text" } with no additional options.

Not recommended for gpt-4o and newer models:

Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.

type
type True string

A tool that can be used to generate a response.

tool_choice
tool_choice

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

id
id True string

The unique identifier of the prompt template to use.

version
version string

Optional version of the prompt template.

variables
variables object

Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files.

truncation
truncation string

The truncation strategy to use for the model response.

  • auto: If the context of this response and previous ones exceeds the model's context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation.
  • disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error.
input
input

Text, image, or file inputs to the model, used to generate a response.

Learn more:

include
include string

Specify additional output data to include in the model response. Currently supported values are:

  • code_interpreter_call.outputs: Includes the outputs of python code execution in code interpreter tool call items.
  • computer_call_output.output.image_url: Include image urls from the computer call output.
  • file_search_call.results: Include the search results of the file search tool call.
  • message.input_image.image_url: Include image urls from the input message.
  • message.output_text.logprobs: Include logprobs with assistant messages.
  • reasoning.encrypted_content: Includes an encrypted version of reasoning tokens in reasoning item outputs. This enables reasoning items to be used in multi-turn conversations when using the Responses API statelessly (like when the store parameter is set to false, or when an organization is enrolled in the zero data retention program).
parallel_tool_calls
parallel_tool_calls boolean

Whether to allow the model to run tool calls in parallel.

store
store boolean

Whether to store the generated model response for later retrieval via API.

instructions
instructions string

A system (or developer) message inserted into the model's context.

When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

Conversation Id
id True string

Conversation Id. Select 'Create new Conversation' to create a new conversation.

type
type True string
name
name True string

The name of the agent.

version
version True string

The version identifier of the agent.

Returns

List Agent Versions

Lists versions of an agent.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Include draft versions
include_drafts boolean

Whether to include draft versions. The service excludes drafts by default.

Limit
limit integer

The maximum number of versions to return.

Order
order string

Sort order by the created_at timestamp.

After cursor
after string

Return versions after this cursor.

Before cursor
before string

Return versions before this cursor.

Returns

List Agents

List Agents

Parameters

Name Key Required Type Description
API version
api-version True string

API version

Returns

List Agents (Agent Service)

List Agents from Agent Service

Returns

List Hosted Session Files

Lists files and directories at a path in a hosted session.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Session ID
SessionId True string

The hosted session identifier.

Directory path
path string

The directory path to list. The default is the session's current directory.

Returns

List Hosted Sessions

Lists hosted sessions for an agent that are accessible to the caller.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Returns

List Messages

List Messages

Parameters

Name Key Required Type Description
API version
api-version True string

API version

The ID of the thread to create a message for.
ThreadId True string

The ID of the thread to create a message for.

Returns

Update Hosted Agent Routing

Updates the hosted agent endpoint to route 100 percent of traffic to a specific active agent version. Draft versions cannot be routing targets.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

Agent version
agent_version True string

The active, non-draft agent version that receives endpoint traffic.

Returns

Upload Hosted Session File

Uploads raw file content to a hosted session. The maximum file size is 50 MB.

Parameters

Name Key Required Type Description
Agent name
AgentName True string

The name of the agent.

User isolation key
x-ms-user-isolation-key string

An optional partitioning key for hosted agents configured with header-based session isolation. Use the same value for every operation on the session. This key does not provide authentication.

Session ID
SessionId True string

The hosted session identifier.

File path
path True string

The path of the file or directory in the hosted session.

File content
body True binary

The binary content of the file to upload.

Returns

Definitions

listAgentsResponse

Name Path Type Description
object
object string

Details of the response object type.

data
data array of Data

The list of messages returned by the service.

first_id
first_id string

Details of the first id.

last_id
last_id string

Details of the last id.

has_more
has_more boolean

Tells whether more agents are there.

listAgentsServiceResponse

Name Path Type Description
data
data array of AgentServiceData

The list of agents returned by the service.

AgentServiceData

Name Path Type Description
id
id string

The unique identifier of the agent.

name
name string

The name of the agent.

description
description string

The description of the agent.

version
version string

The version of the agent.

createdAt
createdAt date-time

When the agent was created.

AgentRecord

Name Path Type Description
object
object string

The object type.

id
id string

The unique identifier of the agent.

name
name string

The name of the agent.

state
state string

The operational state of the agent.

configuration_state
configuration_state string

The configuration state of the agent.

state_source
state_source string

The source of the current state.

versions
versions AgentRecordVersions
agent_endpoint
agent_endpoint object

The endpoint configuration for the agent.

digital_worker_type
digital_worker_type string

The digital worker type, when applicable.

instance_identity
instance_identity object

The instance identity of the agent.

blueprint
blueprint object

The blueprint identity of the agent.

blueprint_reference
blueprint_reference object

The blueprint reference for the agent.

agent_card
agent_card object

The agent card, when available.

AgentRecordVersions

Name Path Type Description
latest
latest AgentVersionRecord

AgentVersionRecord

Name Path Type Description
metadata
metadata object

Metadata associated with the agent version.

object
object string

The object type.

id
id string

The unique identifier of the agent version.

name
name string

The name of the agent.

version
version string

The version identifier.

description
description string

A human-readable description of the agent version.

created_at
created_at integer

The Unix timestamp, in seconds, when the agent version was created.

definition
definition object

The agent definition.

draft
draft boolean

Whether this is a draft version.

status
status string

The provisioning status of the agent version.

instance_identity
instance_identity object

The instance identity of the agent version.

blueprint
blueprint object

The blueprint identity of the agent version.

blueprint_reference
blueprint_reference object

The blueprint reference for the agent version.

agent_guid
agent_guid string

The unique GUID identifier of the agent.

AgentVersionListResponse

Name Path Type Description
object
object string

The object type.

data
data array of AgentVersionRecord

The list of agent versions returned by the service.

first_id
first_id string

The first object identifier in the page.

last_id
last_id string

The last object identifier in the page.

has_more
has_more boolean

Whether more results are available.

HostedSession

Name Path Type Description
agent_session_id
agent_session_id string

The hosted session identifier.

version_indicator
version_indicator HostedSessionVersionIndicator
status
status string

The current session status.

created_at
created_at integer

The Unix timestamp, in seconds, when the session was created.

last_accessed_at
last_accessed_at integer

The Unix timestamp, in seconds, when the session was last accessed.

expires_at
expires_at integer

The Unix timestamp, in seconds, when the session expires.

stopped_at
stopped_at integer

The Unix timestamp, in seconds, when the session stopped, when applicable.

HostedSessionVersionIndicator

Name Path Type Description
type
type string

The version-selection indicator type.

agent_version
agent_version string

The hosted agent version assigned to the session.

HostedSessionListResponse

Name Path Type Description
data
data array of HostedSession

The hosted sessions returned by the service.

first_id
first_id string

The first hosted session identifier in the page.

last_id
last_id string

The last hosted session identifier in the page.

has_more
has_more boolean

Whether more hosted sessions are available.

HostedSessionFileUploadResponse

Name Path Type Description
path
path string

The path of the uploaded file.

bytes_written
bytes_written integer

The number of bytes written.

success
success boolean

Whether the upload succeeded.

source_type
source_type string

The source type used for the upload.

HostedSessionFileListResponse

Name Path Type Description
path
path string

The directory path that was listed.

entries
entries array of HostedSessionFileEntry

The files and directories at the requested path.

has_more
has_more boolean

Whether more entries are available.

HostedSessionFileEntry

Name Path Type Description
name
name string

The file or directory name.

size
size integer

The file size in bytes.

is_directory
is_directory boolean

Whether the entry is a directory.

modified_time
modified_time integer

The entry's modification time as reported by the hosted session.

createThreadResponse

Name Path Type Description
id
id string

The identifier, which can be referenced in API endpoints.

object
object string

The object type, which is always thread.

created_at
created_at integer

The Unix timestamp (in seconds) for when the thread was created.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format. Keys can be a maximum of 64 characters long and values can be a maximum of 512 characters long.

createRunResponse

Name Path Type Description
id
id string

The identifier, which can be referenced in API endpoints.

object
object string

The object type, which is always thread.run.

created_at
created_at integer

The Unix timestamp (in seconds) for when the run was created.

thread_id
thread_id string

The ID of the thread that was executed on as a part of this run.

assistant_id
assistant_id string

The ID of the assistant used for execution of this run.

status
status string

The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, or expired.

required_action
required_action object

Details on the action required to continue the run. Will be null if no action is required.

last_error
last_error object

The last error associated with this run. Will be null if there are no errors.

expires_at
expires_at integer

The Unix timestamp (in seconds) for when the run will expire.

started_at
started_at integer

The Unix timestamp (in seconds) for when the run was started.

cancelled_at
cancelled_at integer

The Unix timestamp (in seconds) for when the run was canceled.

failed_at
failed_at integer

The Unix timestamp (in seconds) for when the run failed.

completed_at
completed_at integer

The Unix timestamp (in seconds) for when the run was completed.

model
model string

The model deployment name that the assistant used for this run.

instructions
instructions string

The instructions that the assistant used for this run.

tools
tools array of tools

The list of tools that the assistant used for this run.

file_ids
file_ids array of fileIds

The list of File IDs the assistant used for this run.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. Keys can be a maximum of 64 characters long, and values can be a maximum of 512 characters long.

tool_choice
tool_choice

Controls which (if any) tool is called by the model. 'none' means the model won't call any tools and instead generates a message. 'auto' means the model can pick between generating a message or calling a tool. Specifying a tool like {'type': 'file_search'} or {'type': 'function', 'function': {'name': 'my_function'}} forces the model to call that tool.

max_prompt_tokens
max_prompt_tokens number

The maximum number of prompt tokens specified to have been used over the course of the run.

max_completion_tokens
max_completion_tokens number

The maximum number of completion tokens specified to have been used over the course of the run.

usage
usage object

Usage statistics related to the run. This value will be null if the run is not in a terminal state (e.g., in_progress, queued).

truncation_strategy
truncation_strategy object

Controls how a thread is truncated prior to the run.

response_format
response_format string

The format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.

getRunResponse

Name Path Type Description
id
id string

The identifier, which can be referenced in API endpoints.

object
object string

The object type, which is always thread.run.

created_at
created_at integer

The Unix timestamp (in seconds) for when the run was created.

thread_id
thread_id string

The ID of the thread that was executed on as a part of this run.

assistant_id
assistant_id string

The ID of the assistant used for execution of this run.

status
status string

The status of the run, which can be either queued, in_progress, requires_action, cancelling, cancelled, failed, completed, or expired.

required_action
required_action object

Details on the action required to continue the run. Will be null if no action is required.

last_error
last_error object

The last error associated with this run. Will be null if there are no errors.

expires_at
expires_at integer

The Unix timestamp (in seconds) for when the run will expire.

started_at
started_at integer

The Unix timestamp (in seconds) for when the run was started.

cancelled_at
cancelled_at integer

The Unix timestamp (in seconds) for when the run was canceled.

failed_at
failed_at integer

The Unix timestamp (in seconds) for when the run failed.

completed_at
completed_at integer

The Unix timestamp (in seconds) for when the run was completed.

model
model string

The model deployment name that the assistant used for this run.

instructions
instructions string

The instructions that the assistant used for this run.

tools
tools array of tools

The list of tools that the assistant used for this run.

file_ids
file_ids array of fileIds

The list of File IDs the assistant used for this run.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. Keys can be a maximum of 64 characters long, and values can be a maximum of 512 characters long.

tool_choice
tool_choice

Controls which (if any) tool is called by the model. 'none' means the model won't call any tools and instead generates a message. 'auto' means the model can pick between generating a message or calling a tool. Specifying a tool like {'type': 'file_search'} or {'type': 'function', 'function': {'name': 'my_function'}} forces the model to call that tool.

max_prompt_tokens
max_prompt_tokens number

The maximum number of prompt tokens specified to have been used over the course of the run.

max_completion_tokens
max_completion_tokens number

The maximum number of completion tokens specified to have been used over the course of the run.

usage
usage object

Usage statistics related to the run. This value will be null if the run is not in a terminal state (e.g., in_progress, queued).

truncation_strategy
truncation_strategy object

Controls how a thread is truncated prior to the run.

response_format
response_format string

The format that the model must output. Compatible with GPT-4 Turbo and all GPT-3.5 Turbo models since gpt-3.5-turbo-1106.

listMessageResponse

Name Path Type Description
object
object string

Details of the response object type

data
data array of Data

The list of messages returned by the service.

first_id
first_id string

Details of the first id

last_id
last_id string

Details of the last id

has_more
has_more boolean

Tells whether more agents are there

Data

Name Path Type Description
id
id string

The identifier, which can be referenced in API endpoints.

object
object string

The object type, which is always assistant.

created_at
created_at integer

The Unix timestamp (in seconds) for when the assistant was created.

name
name string

The name of the assistant. The maximum length is 256 characters.

description
description string

The description of the assistant. The maximum length is 512 characters.

model
model string

Name of the model deployment name to use.

instructions
instructions string

The system instructions that the assistant uses. The maximum length is 32768 characters.

tools
tools array of tools

A list of tools enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types code_interpreter or function. A function description can be a maximum of 1,024 characters.

metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. Useful for storing additional information in a structured format. Keys can be a maximum of 64 characters long, and values can be a maximum of 512 characters long.

temperature
temperature number

Defaults to 1. Determines what sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

top_p
top_p number

Defaults to 1. An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

response_format
response_format object

Specifies the format that the model must output. Setting this parameter to { 'type': 'json_object' } enables JSON mode, ensuring the message is valid JSON.

tool_resources
tool_resources object

A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the code_interpreter tool requires a list of file IDs, while the file_search tool requires a list of vector store IDs.

OpenAI.ServiceTier

Specifies the processing type used for serving the request.

  • If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.
  • If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
  • If set to 'flex' or 'priority', then the request will be processed with the corresponding service tier. Contact sales to learn more about Priority processing.
  • When not set, the default behavior is 'auto'.

When the service_tier parameter is set, the response body will include the service_tier value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

Specifies the processing type used for serving the request.

  • If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.
  • If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
  • If set to 'flex' or 'priority', then the request will be processed with the corresponding service tier. Contact sales to learn more about Priority processing.
  • When not set, the default behavior is 'auto'.

When the service_tier parameter is set, the response body will include the service_tier value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

OpenAI.Reasoning

o-series models only

Configuration options for reasoning models.

Name Path Type Description
effort
effort string
summary
summary string

A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed.

generate_summary
generate_summary string

Deprecated: use summary instead.

A summary of the reasoning performed by the model. This can be useful for debugging and understanding the model's reasoning process. One of auto, concise, or detailed.

OpenAI.ResponseTextFormatConfiguration

Name Path Type Description
type
type OpenAI.ResponseTextFormatConfigurationType

An object specifying the format that the model must output.

Configuring { "type": "json_schema" } enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

The default format is { "type": "text" } with no additional options.

Not recommended for gpt-4o and newer models:

Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.

OpenAI.ResponseTextFormatConfigurationType

An object specifying the format that the model must output.

Configuring { "type": "json_schema" } enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

The default format is { "type": "text" } with no additional options.

Not recommended for gpt-4o and newer models:

Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.

An object specifying the format that the model must output.

Configuring { "type": "json_schema" } enables Structured Outputs, which ensures the model will match your supplied JSON schema. Learn more in the Structured Outputs guide.

The default format is { "type": "text" } with no additional options.

Not recommended for gpt-4o and newer models:

Setting to { "type": "json_object" } enables the older JSON mode, which ensures the message the model generates is valid JSON. Using json_schema is preferred for models that support it.

OpenAI.Tool

Name Path Type Description
type
type OpenAI.ToolType

A tool that can be used to generate a response.

OpenAI.ToolType

A tool that can be used to generate a response.

A tool that can be used to generate a response.

OpenAI.Prompt

Reference to a prompt template and its variables. Learn more.

Name Path Type Description
id
id string

The unique identifier of the prompt template to use.

version
version string

Optional version of the prompt template.

variables
variables OpenAI.ResponsePromptVariables

Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files.

OpenAI.Response

Name Path Type Description
metadata
metadata object

Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard.

Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters.

temperature
temperature float

What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or top_p but not both.

top_p
top_p float

An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered.

We generally recommend altering this or temperature but not both.

user
user string

A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

service_tier
service_tier OpenAI.ServiceTier

Specifies the processing type used for serving the request.

  • If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.
  • If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
  • If set to 'flex' or 'priority', then the request will be processed with the corresponding service tier. Contact sales to learn more about Priority processing.
  • When not set, the default behavior is 'auto'.

When the service_tier parameter is set, the response body will include the service_tier value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

top_logprobs
top_logprobs integer

An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.

previous_response_id
previous_response_id string

The unique ID of the previous response to the model. Use this to create multi-turn conversations. Learn more about conversation state.

model
model string

The model deployment to use for the creation of this response.

reasoning
reasoning OpenAI.Reasoning

o-series models only

Configuration options for reasoning models.

background
background boolean

Whether to run the model response in the background. Learn more.

max_output_tokens
max_output_tokens integer

An upper bound for the number of tokens that can be generated for a response, including visible output tokens and reasoning tokens.

max_tool_calls
max_tool_calls integer

The maximum number of total calls to built-in tools that can be processed in a response. This maximum number applies across all built-in tool calls, not per individual tool. Any further attempts to call a tool by the model will be ignored.

format
text.format OpenAI.ResponseTextFormatConfiguration
tools
tools array of OpenAI.Tool

An array of tools the model may call while generating a response. You can specify which tool to use by setting the tool_choice parameter.

The two categories of tools you can provide the model are:

  • Built-in tools: Tools that are provided by OpenAI that extend the model's capabilities, like web search or file search. Learn more about built-in tools.
  • Function calls (custom tools): Functions that are defined by you, enabling the model to call your own code. Learn more about function calling.
tool_choice
tool_choice

How the model should select which tool (or tools) to use when generating a response. See the tools parameter to see how to specify which tools the model can call.

prompt
prompt OpenAI.Prompt

Reference to a prompt template and its variables. Learn more.

truncation
truncation string

The truncation strategy to use for the model response.

  • auto: If the context of this response and previous ones exceeds the model's context window size, the model will truncate the response to fit the context window by dropping input items in the middle of the conversation.
  • disabled (default): If a model response will exceed the context window size for a model, the request will fail with a 400 error.
id
id string

Unique identifier for this Response.

object
object string

The object type of this resource - always set to response.

status
status string

The status of the response generation. One of completed, failed, in_progress, cancelled, queued, or incomplete.

created_at
created_at unixtime

Unix timestamp (in seconds) of when this Response was created.

error
error OpenAI.ResponseError

An error object returned when the model fails to generate a Response.

reason
incomplete_details.reason string

The reason why the response is incomplete.

output
output array of OpenAI.ItemResource

An array of content items generated by the model.

  • The length and order of items in the output array is dependent on the model's response.
  • Rather than accessing the first item in the output array and assuming it's an assistant message with the content generated by the model, you might consider using the output_text property where supported in SDKs.
instructions
instructions

A system (or developer) message inserted into the model's context.

When using along with previous_response_id, the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

output_text
output_text string

SDK-only convenience property that contains the aggregated text output from all output_text items in the output array, if any are present. Supported in the Python and JavaScript SDKs.

usage
usage OpenAI.ResponseUsage

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

parallel_tool_calls
parallel_tool_calls boolean

Whether to allow the model to run tool calls in parallel.

id
conversation.id string

Conversation Id to set the conversation for this response. If 'create new conversation' is provided, a new conversation will be started with this response as the first message.

agent
agent AgentId

OpenAI.ResponseError

An error object returned when the model fails to generate a Response.

Name Path Type Description
code
code OpenAI.ResponseErrorCode

The error code for the response.

message
message string

A human-readable description of the error.

OpenAI.ResponseErrorCode

The error code for the response.

The error code for the response.

OpenAI.ItemResource

Content item used to generate a response.

Name Path Type Description
type
type OpenAI.ItemType
id
id string

OpenAI.ItemType

OpenAI.ResponseUsage

Represents token usage details including input tokens, output tokens, a breakdown of output tokens, and the total tokens used.

Name Path Type Description
input_tokens
input_tokens integer

The number of input tokens.

cached_tokens
input_tokens_details.cached_tokens integer

The number of tokens that were retrieved from the cache. More on prompt caching.

output_tokens
output_tokens integer

The number of output tokens.

reasoning_tokens
output_tokens_details.reasoning_tokens integer

The number of reasoning tokens.

total_tokens
total_tokens integer

The total number of tokens used.

AgentId

Name Path Type Description
type
type string
name
name string

The name of the agent.

version
version string

The version identifier of the agent.

OpenAI.ResponsePromptVariables

Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files.

Name Path Type Description
object

Optional map of values to substitute in for variables in your prompt. The substitution values can either be strings, or other Response input types like images or files.

tools

Name Path Type Description
name
name string

List of tools that can be used in the run.

fileIds

Name Path Type Description
name
name string

List of file ids that can be used in the run.

object

This is the type 'object'.

binary

This is the basic data type 'binary'.