AgentsClient Class

  • java.lang.Object
    • com.azure.ai.agents.AgentsClient

public final class AgentsClient

Initializes a new instance of the synchronous AgentsClient type.

Method Summary

Modifier and Type Method and Description
SyncPoller<AgentOptimizationJob,AgentOptimizationJobResult> beginCreateOptimizationJob(AgentOptimizationJob job)

Create an agent optimization job Creates an optimization job and returns the queued job.

SyncPoller<AgentOptimizationJob,AgentOptimizationJobResult> beginCreateOptimizationJob(AgentOptimizationJob job, String operationId)

Create an agent optimization job Creates an optimization job and returns the queued job.

SyncPoller<BinaryData,BinaryData> beginCreateOptimizationJob(BinaryData job, RequestOptions requestOptions)

Create an agent optimization job Creates an optimization job and returns the queued job.

AgentOptimizationJob cancelOptimizationJob(String jobId)

Cancel an agent optimization job Requests cancellation of a running or queued job.

Response<BinaryData> cancelOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)

Cancel an agent optimization job Requests cancellation of a running or queued job.

AgentVersionDetails createAgentVersion(String agentName, AgentDefinition definition)

Create an agent version Creates a new version for the specified agent and returns the created version resource.

AgentVersionDetails createAgentVersion(String agentName, AgentDefinition definition, Map<String,String> metadata, String description)

Create a new agent version.

AgentVersionDetails createAgentVersion(String agentName, CreateAgentVersionInput createAgentVersionInput)

Create a new agent version.

AgentVersionDetails createAgentVersionFromCode(String agentName, HostedAgentDefinition definition, CodeFileDetails code, String description, Map<String,String> metadata)

Create a new code-based hosted agent version.

AgentVersionDetails createAgentVersionFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)

Create an agent version from code Creates a new agent version from code.

AgentVersionDetails createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues)

Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.

AgentVersionDetails createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues, Map<String,String> metadata, String description)

Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.

Response<BinaryData> createAgentVersionFromManifestWithResponse(String agentName, BinaryData createAgentVersionFromManifestRequest, RequestOptions requestOptions)

Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.

Response<BinaryData> createAgentVersionWithResponse(String agentName, BinaryData createAgentVersionRequest, RequestOptions requestOptions)

Create an agent version Creates a new version for the specified agent and returns the created version resource.

AgentSessionResource createSession(String agentName, VersionIndicator versionIndicator)

Create a session Creates a new session for an agent endpoint.

AgentSessionResource createSession(String agentName, VersionIndicator versionIndicator, String agentSessionId)

Create a session Creates a new session for an agent endpoint.

Response<BinaryData> createSessionWithResponse(String agentName, BinaryData createSessionRequest, RequestOptions requestOptions)

Create a session Creates a new session for an agent endpoint.

void deleteAgent(String agentName)

Deletes an agent.

void deleteAgentVersion(String agentName, String agentVersion)

Deletes a specific version of an agent.

Response<Void> deleteAgentVersionWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)

Deletes a specific version of an agent.

Response<Void> deleteAgentWithResponse(String agentName, RequestOptions requestOptions)

Deletes an agent.

void deleteOptimizationJob(String jobId)

Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts.

Response<Void> deleteOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)

Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts.

void deleteSession(String agentName, String sessionId)

Delete a session Deletes a session synchronously.

void deleteSessionFile(String agentName, String sessionId, String path)

Delete a session file Deletes the specified file or directory from the session sandbox.

void deleteSessionFile(String agentName, String sessionId, String path, Boolean recursive)

Delete a session file Deletes the specified file or directory from the session sandbox.

Response<Void> deleteSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)

Delete a session file Deletes the specified file or directory from the session sandbox.

Response<Void> deleteSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)

Delete a session Deletes a session synchronously.

void disableAgent(String agentName)

Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests.

Response<Void> disableAgentWithResponse(String agentName, RequestOptions requestOptions)

Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests.

BinaryData downloadAgentCode(String agentName)

Download agent code Downloads the code zip for a code-based hosted agent.

BinaryData downloadAgentCode(String agentName, String agentVersion)

Download agent code Downloads the code zip for a code-based hosted agent.

void downloadAgentCode(String agentName, String agentVersion, String filePath)

Download agent code Downloads the code zip for a code-based hosted agent.

void downloadAgentCode(String agentName, String agentVersion, String filePath, boolean overwrite)

Download agent code Downloads the code zip for a code-based hosted agent and writes it to filePath.

Response<BinaryData> downloadAgentCodeWithResponse(String agentName, RequestOptions requestOptions)

Download agent code Downloads the code zip for a code-based hosted agent.

Response<Void> downloadAgentCodeWithResponse(String agentName, String filePath, boolean overwrite, RequestOptions requestOptions)

Download agent code Downloads the code zip for a code-based hosted agent and writes it to filePath.

Response<Void> downloadAgentCodeWithResponse(String agentName, String filePath, RequestOptions requestOptions)

Download agent code Downloads the code zip for a code-based hosted agent.

BinaryData downloadSessionFile(String agentName, String sessionId, String path)

Download a session file Downloads the file at the specified sandbox path as a binary stream.

Response<Void> downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, boolean overwrite, RequestOptions requestOptions)

Download a session file Downloads the file at the specified sandbox path and writes it to filePath.

Response<Void> downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)

Download a session file Downloads the file at the specified sandbox path as a binary stream.

Response<BinaryData> downloadSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)

Download a session file Downloads the file at the specified sandbox path as a binary stream.

void enableAgent(String agentName)

Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests.

Response<Void> enableAgentWithResponse(String agentName, RequestOptions requestOptions)

Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests.

AgentOptimizationEstimateResult estimateOptimizationJob(AgentOptimizationEstimateInputs inputs)

Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.

Response<BinaryData> estimateOptimizationJobWithResponse(BinaryData inputs, RequestOptions requestOptions)

Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.

AgentDetails getAgent(String agentName)

Get an agent Retrieves an agent definition by its unique name.

AgentVersionDetails getAgentVersionDetails(String agentName, String agentVersion)

Get an agent version Retrieves the specified version of an agent by its agent name and version identifier.

Response<BinaryData> getAgentVersionDetailsWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)

Get an agent version Retrieves the specified version of an agent by its agent name and version identifier.

Response<BinaryData> getAgentWithResponse(String agentName, RequestOptions requestOptions)

Get an agent Retrieves an agent definition by its unique name.

BinaryData getMicrosoft365AppPackage(GetMicrosoft365AppPackageOptions options)

Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it.

Response<BinaryData> getMicrosoft365AppPackageWithResponse(String agentName, BinaryData getMicrosoft365AppPackageRequest, RequestOptions requestOptions)

Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it.

Microsoft365PublishDefaults getMicrosoft365PublishDefaults(String agentName)

Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

Microsoft365PublishDefaults getMicrosoft365PublishDefaults(String agentName, Boolean publishAsDigitalWorker)

Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

Response<BinaryData> getMicrosoft365PublishDefaultsWithResponse(String agentName, RequestOptions requestOptions)

Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

AgentOptimizationCandidate getOptimizationCandidate(String jobId, String candidateId)

Get a candidate for an agent optimization job Retrieves a single candidate.

Response<BinaryData> getOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)

Get a candidate for an agent optimization job Retrieves a single candidate.

AgentOptimizationJob getOptimizationJob(String jobId)

Get an agent optimization job Retrieves an optimization job by its identifier.

Response<BinaryData> getOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)

Get an agent optimization job Retrieves an optimization job by its identifier.

AgentSessionResource getSession(String agentName, String sessionId)

Get a session Retrieves the details of a hosted agent session by agent name and session identifier.

IterableStream<SessionLogEvent> getSessionLogStream(String agentName, String agentVersion, String sessionId)

Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values.

IterableStream<SessionLogEvent> getSessionLogStream(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)

Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values.

Response<BinaryData> getSessionLogStreamWithResponse(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)

Stream console logs for a hosted agent session Streams console logs (stdout / stderr) for a specific hosted agent session as a Server-Sent Events (SSE) stream.

Response<BinaryData> getSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)

Get a session Retrieves the details of a hosted agent session by agent name and session identifier.

PagedIterable<com.openai.models.conversations.Conversation> listAgentConversations()

List conversations Returns the conversations available in the current project.

PagedIterable<com.openai.models.conversations.Conversation> listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId)

Returns the list of all conversations.

PagedIterable<com.openai.models.conversations.Conversation> listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId, String userIdentity)

List conversations Returns the conversations available in the current project.

PagedIterable<BinaryData> listAgentConversations(RequestOptions requestOptions)

List conversations Returns the conversations available in the current project.

PagedIterable<AgentDetails> listAgents()

List agents Returns a paged collection of agent resources.

PagedIterable<AgentDetails> listAgents(AgentKind kind, Integer limit, PageOrder order, String after, String before)

List agents Returns a paged collection of agent resources.

PagedIterable<BinaryData> listAgents(RequestOptions requestOptions)

List agents Returns a paged collection of agent resources.

PagedIterable<AgentVersionDetails> listAgentVersions(String agentName)

List agent versions Returns a paged collection of versions for the specified agent.

PagedIterable<AgentVersionDetails> listAgentVersions(String agentName, Integer limit, PageOrder order, String after, String before, Boolean includeDrafts)

List agent versions Returns a paged collection of versions for the specified agent.

PagedIterable<BinaryData> listAgentVersions(String agentName, RequestOptions requestOptions)

List agent versions Returns a paged collection of versions for the specified agent.

PagedIterable<AgentOptimizationCandidate> listOptimizationCandidates(String jobId)

List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates.

PagedIterable<AgentOptimizationCandidate> listOptimizationCandidates(String jobId, List<AgentOptimizationCandidateExpand> expand, Integer limit, PageOrder order, String after, String before)

List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates.

PagedIterable<BinaryData> listOptimizationCandidates(String jobId, RequestOptions requestOptions)

List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates.

PagedIterable<AgentOptimizationJob> listOptimizationJobs()

List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.

PagedIterable<AgentOptimizationJob> listOptimizationJobs(Integer limit, PageOrder order, String after, String before, JobStatus status, String agentName)

List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.

PagedIterable<BinaryData> listOptimizationJobs(RequestOptions requestOptions)

List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.

PagedIterable<SessionDirectoryEntry> listSessionFiles(String agentName, String sessionId)

List session files Returns files and directories at the specified path in the session sandbox.

PagedIterable<BinaryData> listSessionFiles(String agentName, String sessionId, RequestOptions requestOptions)

List session files Returns files and directories at the specified path in the session sandbox.

PagedIterable<SessionDirectoryEntry> listSessionFiles(String agentName, String sessionId, String path, Integer limit, PageOrder order, String after, String before)

List session files Returns files and directories at the specified path in the session sandbox.

PagedIterable<AgentSessionResource> listSessions(String agentName)

List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.

PagedIterable<AgentSessionResource> listSessions(String agentName, Integer limit, PageOrder order, String after, String before)

List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.

PagedIterable<BinaryData> listSessions(String agentName, RequestOptions requestOptions)

List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.

AgentOptimizationCandidate promoteOptimizationCandidate(String jobId, String candidateId)

Promote a candidate for an agent optimization job Promotes a candidate to the Foundry agent stored in the parent job's target configuration.

Response<BinaryData> promoteOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)

Promote a candidate for an agent optimization job Promotes a candidate to the Foundry agent stored in the parent job's target configuration.

Microsoft365PublishResult publishAgentToMicrosoft365(PublishAgentToMicrosoft365Options options)

Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids.

Response<BinaryData> publishAgentToMicrosoft365WithResponse(String agentName, BinaryData publishAgentToMicrosoft365Request, RequestOptions requestOptions)

Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids.

void stopSession(String agentName, String sessionId)

Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.

Response<Void> stopSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)

Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.

AgentDetails updateAgentDetails(String agentName, UpdateAgentDetailsOptions patchAgentObjectRequest)

Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration.

Response<BinaryData> updateAgentDetailsWithResponse(String agentName, BinaryData patchAgentObjectRequest, RequestOptions requestOptions)

Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration.

AgentDetails updateAgentFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)

Update a code-based agent Updates a code-based agent by uploading new code and creating a new version.

SessionFileWriteResult uploadSessionFile(String agentName, String sessionId, String path, BinaryData content)

Upload a session file Uploads binary file content to the specified path in the session sandbox.

Response<BinaryData> uploadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)

Upload a session file Uploads binary file content to the specified path in the session sandbox.

Response<BinaryData> uploadSessionFileWithResponse(String agentName, String sessionId, String path, BinaryData content, RequestOptions requestOptions)

Upload a session file Uploads binary file content to the specified path in the session sandbox.

Methods inherited from java.lang.Object

Method Details

beginCreateOptimizationJob

public SyncPoller<AgentOptimizationJob,AgentOptimizationJobResult> beginCreateOptimizationJob(AgentOptimizationJob job)

Create an agent optimization job Creates an optimization job and returns the queued job. Honors `Operation-Id` for idempotent retry. Clients poll the URL in `Operation-Location` by using the get operation.

Parameters:

job - The job to create.

Returns:

the SyncPoller<T,U> for polling of agent optimization job resource \u2014 a long-running job that produces candidate changes to a Foundry agent configuration.

beginCreateOptimizationJob

public SyncPoller<AgentOptimizationJob,AgentOptimizationJobResult> beginCreateOptimizationJob(AgentOptimizationJob job, String operationId)

Create an agent optimization job Creates an optimization job and returns the queued job. Honors `Operation-Id` for idempotent retry. Clients poll the URL in `Operation-Location` by using the get operation.

Parameters:

job - The job to create.
operationId - Client-generated unique ID for idempotent retries. When absent, the server creates the job unconditionally.

Returns:

the SyncPoller<T,U> for polling of agent optimization job resource \u2014 a long-running job that produces candidate changes to a Foundry agent configuration.

beginCreateOptimizationJob

public SyncPoller<BinaryData,BinaryData> beginCreateOptimizationJob(BinaryData job, RequestOptions requestOptions)

Create an agent optimization job Creates an optimization job and returns the queued job. Honors `Operation-Id` for idempotent retry. Clients poll the URL in `Operation-Location` by using the get operation.

Header Parameters

| ------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| Name         | Type   | Required | Description                                                                                                 |
| Operation-Id | String | No       | Client-generated unique ID for idempotent retries. When absent, the server creates the job unconditionally. |

You can add these to a request with RequestOptions#addHeader

Request Body Schema

{
     id: String (Required)
     result (Optional): {
         candidate_summary (Optional): {
             completed_candidate_count: int (Required)
             baseline_id: String (Optional)
             best_id: String (Optional)
             baseline_score: Double (Optional)
             best_score: Double (Optional)
             latest_promoted_candidate (Optional): {
                 promoted_at: long (Required)
                 promoted_agent (Required): {
                     type: String (Required)
                     name: String (Required)
                     version: String (Optional)
                 }
             }
         }
         token_usage (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 input_tokens: Long (Optional)
                 output_tokens: Long (Optional)
                 total_tokens: Long (Optional)
                 cached_tokens: Long (Optional)
                 reasoning_tokens: Long (Optional)
             }
         ]
         latency_metrics (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 avg_latency_ms: long (Required)
                 call_count: long (Required)
             }
         ]
         termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
     }
     status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
     error (Optional): {
         code: String (Required)
         message: String (Required)
         param: String (Optional)
         type: String (Optional)
         misalignment (Optional): {
             error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
             detailed_explanation: String (Optional)
             steer (Optional): {
                 message: String (Required)
             }
         }
         details (Optional): [
             (recursive schema, see above)
         ]
         additionalInfo (Optional): {
             String: BinaryData (Required)
         }
         debugInfo (Optional): {
             String: BinaryData (Required)
         }
     }
     display_name: String (Optional)
     target_configuration (Optional): {
         type: String(foundry_agent) (Required)
     }
     optimization_model_configuration (Required): {
         model: String (Required)
     }
     optimization_configuration (Required): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     run_duration_ms: long (Required)
     created_at: long (Required)
     updated_at: long (Required)
     warnings (Optional): [
         String (Optional)
     ]
 }

Response Body Schema

{
     id: String (Required)
     result (Optional): {
         candidate_summary (Optional): {
             completed_candidate_count: int (Required)
             baseline_id: String (Optional)
             best_id: String (Optional)
             baseline_score: Double (Optional)
             best_score: Double (Optional)
             latest_promoted_candidate (Optional): {
                 promoted_at: long (Required)
                 promoted_agent (Required): {
                     type: String (Required)
                     name: String (Required)
                     version: String (Optional)
                 }
             }
         }
         token_usage (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 input_tokens: Long (Optional)
                 output_tokens: Long (Optional)
                 total_tokens: Long (Optional)
                 cached_tokens: Long (Optional)
                 reasoning_tokens: Long (Optional)
             }
         ]
         latency_metrics (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 avg_latency_ms: long (Required)
                 call_count: long (Required)
             }
         ]
         termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
     }
     status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
     error (Optional): {
         code: String (Required)
         message: String (Required)
         param: String (Optional)
         type: String (Optional)
         misalignment (Optional): {
             error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
             detailed_explanation: String (Optional)
             steer (Optional): {
                 message: String (Required)
             }
         }
         details (Optional): [
             (recursive schema, see above)
         ]
         additionalInfo (Optional): {
             String: BinaryData (Required)
         }
         debugInfo (Optional): {
             String: BinaryData (Required)
         }
     }
     display_name: String (Optional)
     target_configuration (Optional): {
         type: String(foundry_agent) (Required)
     }
     optimization_model_configuration (Required): {
         model: String (Required)
     }
     optimization_configuration (Required): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     run_duration_ms: long (Required)
     created_at: long (Required)
     updated_at: long (Required)
     warnings (Optional): [
         String (Optional)
     ]
 }

Parameters:

job - The job to create.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the SyncPoller<T,U> for polling of agent optimization job resource \u2014 a long-running job that produces candidate changes to a Foundry agent configuration.

cancelOptimizationJob

public AgentOptimizationJob cancelOptimizationJob(String jobId)

Cancel an agent optimization job Requests cancellation of a running or queued job. Returns 409 Conflict if the job is already in a terminal state.

Parameters:

jobId - The ID of the job to cancel.

Returns:

agent optimization job resource \u2014 a long-running job that produces candidate changes to a Foundry agent configuration.

cancelOptimizationJobWithResponse

public Response<BinaryData> cancelOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)

Cancel an agent optimization job Requests cancellation of a running or queued job. Returns 409 Conflict if the job is already in a terminal state.

Response Body Schema

{
     id: String (Required)
     result (Optional): {
         candidate_summary (Optional): {
             completed_candidate_count: int (Required)
             baseline_id: String (Optional)
             best_id: String (Optional)
             baseline_score: Double (Optional)
             best_score: Double (Optional)
             latest_promoted_candidate (Optional): {
                 promoted_at: long (Required)
                 promoted_agent (Required): {
                     type: String (Required)
                     name: String (Required)
                     version: String (Optional)
                 }
             }
         }
         token_usage (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 input_tokens: Long (Optional)
                 output_tokens: Long (Optional)
                 total_tokens: Long (Optional)
                 cached_tokens: Long (Optional)
                 reasoning_tokens: Long (Optional)
             }
         ]
         latency_metrics (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 avg_latency_ms: long (Required)
                 call_count: long (Required)
             }
         ]
         termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
     }
     status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
     error (Optional): {
         code: String (Required)
         message: String (Required)
         param: String (Optional)
         type: String (Optional)
         misalignment (Optional): {
             error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
             detailed_explanation: String (Optional)
             steer (Optional): {
                 message: String (Required)
             }
         }
         details (Optional): [
             (recursive schema, see above)
         ]
         additionalInfo (Optional): {
             String: BinaryData (Required)
         }
         debugInfo (Optional): {
             String: BinaryData (Required)
         }
     }
     display_name: String (Optional)
     target_configuration (Optional): {
         type: String(foundry_agent) (Required)
     }
     optimization_model_configuration (Required): {
         model: String (Required)
     }
     optimization_configuration (Required): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     run_duration_ms: long (Required)
     created_at: long (Required)
     updated_at: long (Required)
     warnings (Optional): [
         String (Optional)
     ]
 }

Parameters:

jobId - The ID of the job to cancel.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

agent optimization job resource \u2014 a long-running job that produces candidate changes to a Foundry agent configuration along with Response<T>.

createAgentVersion

public AgentVersionDetails createAgentVersion(String agentName, AgentDefinition definition)

Create an agent version Creates a new version for the specified agent and returns the created version resource.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
definition - The agent definition. This can be a prompt, workflow, hosted, external, or voice agent definition.

Returns:

the response.

createAgentVersion

public AgentVersionDetails createAgentVersion(String agentName, AgentDefinition definition, Map<String,String> metadata, String description)

Create a new agent version.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
definition - The agent definition. This can be a workflow, hosted agent, or a simple agent definition.
metadata - 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.
description - A human-readable description of the agent.

Returns:

the response.

createAgentVersion

public AgentVersionDetails createAgentVersion(String agentName, CreateAgentVersionInput createAgentVersionInput)

Create a new agent version.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
createAgentVersionInput - The request body for creating an agent version, which includes the agent definition and optional metadata.

Returns:

the response.

createAgentVersionFromCode

public AgentVersionDetails createAgentVersionFromCode(String agentName, HostedAgentDefinition definition, CodeFileDetails code, String description, Map<String,String> metadata)

Create a new code-based hosted agent version.

This convenience overload flattens the request: instead of assembling a CreateAgentVersionFromCodeContent that wraps a CreateAgentVersionFromCodeMetadata, the caller passes the HostedAgentDefinition and code zip directly. The required x-ms-code-zip-sha256 value is computed from code automatically.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
definition - The hosted agent definition, including code_configuration, cpu, memory, and protocol_versions.
code - The code zip file to upload (max 250 MB).
description - An optional human-readable description of the agent. May be null.
metadata - An optional set of key-value pairs to attach to the agent version. May be null. Keys are strings with a maximum length of 64 characters and values are strings with a maximum length of 512 characters.

Returns:

the created agent version.

createAgentVersionFromCode

public AgentVersionDetails createAgentVersionFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)

Create an agent version from code Creates a new agent version from code. Uploads the code zip and creates a new version for an existing agent. The SHA-256 hex digest of the zip is provided in the `x-ms-code-zip-sha256` header for integrity and dedup. The request body is multipart/form-data with a JSON metadata part and a binary code part (part order is irrelevant). Maximum upload size is 250 MB.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
codeZipSha256 - SHA-256 hex digest of the uploaded code zip. Used for change detection (dedup) and integrity verification.
content - The content multipart request content.

Returns:

the response.

createAgentVersionFromManifest

public AgentVersionDetails createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues)

Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
manifestId - The manifest ID to import the agent version from.
parameterValues - The inputs to the manifest that will result in a fully materialized Agent.

Returns:

the response.

createAgentVersionFromManifest

public AgentVersionDetails createAgentVersionFromManifest(String agentName, String manifestId, Map<String,BinaryData> parameterValues, Map<String,String> metadata, String description)

Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
manifestId - The manifest ID to import the agent version from.
parameterValues - The inputs to the manifest that will result in a fully materialized Agent.
metadata - 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.
description - A human-readable description of the agent.

Returns:

the response.

createAgentVersionFromManifestWithResponse

public Response<BinaryData> createAgentVersionFromManifestWithResponse(String agentName, BinaryData createAgentVersionFromManifestRequest, RequestOptions requestOptions)

Create an agent version from manifest Imports the provided manifest to create a new version for the specified agent.

Request Body Schema

{
     metadata (Optional): {
         String: String (Required)
     }
     description: String (Optional)
     manifest_id: String (Required)
     parameter_values (Required): {
         String: BinaryData (Required)
     }
 }

Response Body Schema

{
     metadata (Required): {
         String: String (Required)
     }
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     version: String (Required)
     description: String (Optional)
     created_at: long (Required)
     definition (Required): {
         kind: String(prompt/hosted/workflow/external/voice) (Required)
         rai_config (Optional): {
             rai_policy_name: String (Required)
             invocations_moderation (Optional): {
                 input_content_type: String(json/text) (Optional)
                 output_content_type: String(json/text) (Optional)
                 response_mode: String(non_streaming/streaming/both) (Required)
                 input_paths (Optional): [
                     String (Optional)
                 ]
                 output_paths (Optional): [
                     String (Optional)
                 ]
                 stream_selectors (Optional): [
                      (Optional){
                         event_type: String (Required)
                         text_field: String (Optional)
                     }
                 ]
             }
         }
     }
     draft: Boolean (Optional)
     status: String(creating/active/failed/deleting/deleted) (Optional)
     instance_identity (Optional): {
         principal_id: String (Required)
         client_id: String (Required)
         status: String(active/disabled) (Optional)
     }
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): {
         type: String(ManagedAgentIdentityBlueprint) (Required)
     }
     agent_guid: String (Optional)
 }

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
createAgentVersionFromManifestRequest - The createAgentVersionFromManifestRequest parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

createAgentVersionWithResponse

public Response<BinaryData> createAgentVersionWithResponse(String agentName, BinaryData createAgentVersionRequest, RequestOptions requestOptions)

Create an agent version Creates a new version for the specified agent and returns the created version resource.

Request Body Schema

{
     metadata (Optional): {
         String: String (Required)
     }
     description: String (Optional)
     definition (Required): {
         kind: String(prompt/hosted/workflow/external/voice) (Required)
         rai_config (Optional): {
             rai_policy_name: String (Required)
             invocations_moderation (Optional): {
                 input_content_type: String(json/text) (Optional)
                 output_content_type: String(json/text) (Optional)
                 response_mode: String(non_streaming/streaming/both) (Required)
                 input_paths (Optional): [
                     String (Optional)
                 ]
                 output_paths (Optional): [
                     String (Optional)
                 ]
                 stream_selectors (Optional): [
                      (Optional){
                         event_type: String (Required)
                         text_field: String (Optional)
                     }
                 ]
             }
         }
     }
     blueprint_reference (Optional): {
         type: String(ManagedAgentIdentityBlueprint) (Required)
     }
     digital_worker_type: String(m365) (Optional)
     draft: Boolean (Optional)
 }

Response Body Schema

{
     metadata (Required): {
         String: String (Required)
     }
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     version: String (Required)
     description: String (Optional)
     created_at: long (Required)
     definition (Required): {
         kind: String(prompt/hosted/workflow/external/voice) (Required)
         rai_config (Optional): {
             rai_policy_name: String (Required)
             invocations_moderation (Optional): {
                 input_content_type: String(json/text) (Optional)
                 output_content_type: String(json/text) (Optional)
                 response_mode: String(non_streaming/streaming/both) (Required)
                 input_paths (Optional): [
                     String (Optional)
                 ]
                 output_paths (Optional): [
                     String (Optional)
                 ]
                 stream_selectors (Optional): [
                      (Optional){
                         event_type: String (Required)
                         text_field: String (Optional)
                     }
                 ]
             }
         }
     }
     draft: Boolean (Optional)
     status: String(creating/active/failed/deleting/deleted) (Optional)
     instance_identity (Optional): {
         principal_id: String (Required)
         client_id: String (Required)
         status: String(active/disabled) (Optional)
     }
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): {
         type: String(ManagedAgentIdentityBlueprint) (Required)
     }
     agent_guid: String (Optional)
 }

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
createAgentVersionRequest - The createAgentVersionRequest parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

createSession

public AgentSessionResource createSession(String agentName, VersionIndicator versionIndicator)

Create a session Creates a new session for an agent endpoint. The endpoint resolves the backing agent version from `version_indicator` and enforces session ownership using the provided user identity for session-mutating operations.

Parameters:

agentName - The name of the agent to create a session for.
versionIndicator - Determines which agent version backs the session.

Returns:

an agent session providing a long-lived compute sandbox for hosted agent invocations.

createSession

public AgentSessionResource createSession(String agentName, VersionIndicator versionIndicator, String agentSessionId)

Create a session Creates a new session for an agent endpoint. The endpoint resolves the backing agent version from `version_indicator` and enforces session ownership using the provided user identity for session-mutating operations.

Parameters:

agentName - The name of the agent to create a session for.
versionIndicator - Determines which agent version backs the session.
agentSessionId - Optional caller-provided session ID. If specified, it must be unique within the agent endpoint. Auto-generated if omitted.

Returns:

an agent session providing a long-lived compute sandbox for hosted agent invocations.

createSessionWithResponse

public Response<BinaryData> createSessionWithResponse(String agentName, BinaryData createSessionRequest, RequestOptions requestOptions)

Create a session Creates a new session for an agent endpoint. The endpoint resolves the backing agent version from `version_indicator` and enforces session ownership using the provided user identity for session-mutating operations.

Request Body Schema

{
     agent_session_id: String (Optional)
     version_indicator (Required): {
         type: String(version_ref) (Required)
     }
 }

Response Body Schema

{
     agent_session_id: String (Required)
     version_indicator (Required): {
         type: String(version_ref) (Required)
     }
     status: String(creating/active/idle/updating/failed/deleting/deleted/expired) (Required)
     created_at: long (Required)
     last_accessed_at: long (Required)
     expires_at: long (Required)
     stopped_at: Long (Optional)
 }

Parameters:

agentName - The name of the agent to create a session for.
createSessionRequest - The createSessionRequest parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

an agent session providing a long-lived compute sandbox for hosted agent invocations along with Response<T>.

deleteAgent

public void deleteAgent(String agentName)

Deletes an agent.

Parameters:

agentName - The name of the agent to delete.

deleteAgentVersion

public void deleteAgentVersion(String agentName, String agentVersion)

Deletes a specific version of an agent.

Parameters:

agentName - The name of the agent to delete.
agentVersion - The version of the agent to delete.

deleteAgentVersionWithResponse

public Response<Void> deleteAgentVersionWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)

Deletes a specific version of an agent.

Response Body Schema

{
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     name: String (Required)
     version: String (Required)
     deleted: boolean (Required)
 }

Parameters:

agentName - The name of the agent to delete.
agentVersion - The version of the agent to delete.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

deleteAgentWithResponse

public Response<Void> deleteAgentWithResponse(String agentName, RequestOptions requestOptions)

Deletes an agent.

Response Body Schema

{
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     name: String (Required)
     deleted: boolean (Required)
 }

Parameters:

agentName - The name of the agent to delete.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

deleteOptimizationJob

public void deleteOptimizationJob(String jobId)

Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts.

Parameters:

jobId - The ID of the job to delete.

deleteOptimizationJobWithResponse

public Response<Void> deleteOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)

Delete an agent optimization job Cancels active work, then deletes the job and its candidate artifacts.

Parameters:

jobId - The ID of the job to delete.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

deleteSession

public void deleteSession(String agentName, String sessionId)

Delete a session Deletes a session synchronously. Returns 204 No Content when the session is deleted or does not exist.

Parameters:

agentName - The name of the agent.
sessionId - The session identifier.

deleteSessionFile

public void deleteSessionFile(String agentName, String sessionId, String path)

Delete a session file Deletes the specified file or directory from the session sandbox. When `recursive` is false, deleting a non-empty directory returns 409 Conflict.

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The file or directory path to delete, relative to the session home directory.

deleteSessionFile

public void deleteSessionFile(String agentName, String sessionId, String path, Boolean recursive)

Delete a session file Deletes the specified file or directory from the session sandbox. When `recursive` is false, deleting a non-empty directory returns 409 Conflict.

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The file or directory path to delete, relative to the session home directory.
recursive - Whether to recursively delete directory contents. The service defaults to false if a value is not specified by the caller.

deleteSessionFileWithResponse

public Response<Void> deleteSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)

Delete a session file Deletes the specified file or directory from the session sandbox. When `recursive` is false, deleting a non-empty directory returns 409 Conflict.

Query Parameters

| --------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Name      | Type    | Required | Description                                                                                                                    |
| recursive | Boolean | No       | Whether to recursively delete directory contents. The service defaults to \`false\` if a value is not specified by the caller. |

You can add these to a request with RequestOptions#addQueryParam

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The file or directory path to delete, relative to the session home directory.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

deleteSessionWithResponse

public Response<Void> deleteSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)

Delete a session Deletes a session synchronously. Returns 204 No Content when the session is deleted or does not exist.

Parameters:

agentName - The name of the agent.
sessionId - The session identifier.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

disableAgent

public void disableAgent(String agentName)

Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests. Existing active sessions are allowed to drain gracefully but no new sessions can be created. This operation is idempotent — disabling an already-disabled agent returns success with no side effects.

Parameters:

agentName - The name of the agent to disable.

disableAgentWithResponse

public Response<Void> disableAgentWithResponse(String agentName, RequestOptions requestOptions)

Disable an agent Disables the specified agent, preventing it from accepting new sessions or processing requests. Existing active sessions are allowed to drain gracefully but no new sessions can be created. This operation is idempotent — disabling an already-disabled agent returns success with no side effects.

Parameters:

agentName - The name of the agent to disable.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

downloadAgentCode

public BinaryData downloadAgentCode(String agentName)

Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.

Parameters:

agentName - The name of the agent.

Returns:

the response.

downloadAgentCode

public BinaryData downloadAgentCode(String agentName, String agentVersion)

Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.

Parameters:

agentName - The name of the agent.
agentVersion - The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned.

Returns:

the response.

downloadAgentCode

public void downloadAgentCode(String agentName, String agentVersion, String filePath)

Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.

Parameters:

agentName - The name of the agent.
agentVersion - The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned.
filePath - destination file.

Throws:

IOException

- thrown if parameters fail the validation.

downloadAgentCode

public void downloadAgentCode(String agentName, String agentVersion, String filePath, boolean overwrite)

Download agent code Downloads the code zip for a code-based hosted agent and writes it to filePath.

Parameters:

agentName - The name of the agent.
agentVersion - The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned.
filePath - destination file.
overwrite - Whether to overwrite an existing file at filePath. When false, the operation fails if a file already exists at the destination.

Throws:

IOException

- thrown if parameters fail the validation.

downloadAgentCodeWithResponse

public Response<BinaryData> downloadAgentCodeWithResponse(String agentName, RequestOptions requestOptions)

Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.

Query Parameters

| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Name           | Type   | Required | Description                                                                                                          |
| agent\_version | String | No       | The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned. |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

BinaryData

Response Headers

| ------------------ | ------ | ------------------------------------------------------------------------- |
| Name               | Type   | Description                                                               |
| x-ms-agent-version | String | The version of the agent whose code zip is returned in the response body. |

Parameters:

agentName - The name of the agent.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

downloadAgentCodeWithResponse

public Response<Void> downloadAgentCodeWithResponse(String agentName, String filePath, boolean overwrite, RequestOptions requestOptions)

Download agent code Downloads the code zip for a code-based hosted agent and writes it to filePath.

Parameters:

agentName - The name of the agent.
filePath - The path to the file where the downloaded code zip will be saved.
overwrite - Whether to overwrite an existing file at filePath. When false, the operation fails if a file already exists at the destination.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

Throws:

IOException

- thrown if the request is rejected by server.

downloadAgentCodeWithResponse

public Response<Void> downloadAgentCodeWithResponse(String agentName, String filePath, RequestOptions requestOptions)

Download agent code Downloads the code zip for a code-based hosted agent. Returns the previously-uploaded zip (`application/zip`). If `agent_version` is supplied, returns that version's code zip; otherwise returns the latest version's code zip. The SHA-256 digest of the returned bytes matches the `content_hash` on the resolved version's `code_configuration`.

Query Parameters

| -------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Name           | Type   | Required | Description                                                                                                          |
| agent\_version | String | No       | The version of the agent whose code zip should be downloaded. If omitted, the latest version's code zip is returned. |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

BinaryData

Parameters:

agentName - The name of the agent.
filePath - The path to the file where the downloaded code zip will be saved.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

Throws:

IOException

- thrown if the request is rejected by server.

downloadSessionFile

public BinaryData downloadSessionFile(String agentName, String sessionId, String path)

Download a session file Downloads the file at the specified sandbox path as a binary stream. The path is resolved relative to the session home directory.

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The file path to download from the sandbox, relative to the session home directory.

Returns:

the response.

downloadSessionFileWithResponse

public Response<Void> downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, boolean overwrite, RequestOptions requestOptions)

Download a session file Downloads the file at the specified sandbox path and writes it to filePath. The path is resolved relative to the session home directory.

Parameters:

agentName - The name of the agent.
agentSessionId - The session ID.
path - The file path to download from the sandbox, relative to the session home directory.
filePath - path to disc in file where to save the downloaded file.
overwrite - Whether to overwrite an existing file at filePath. When false, the operation fails if a file already exists at the destination.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

Throws:

IOException

- thrown if the request is rejected by server.

downloadSessionFileWithResponse

public Response<Void> downloadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)

Download a session file Downloads the file at the specified sandbox path as a binary stream. The path is resolved relative to the session home directory.

Header Parameters

| ----------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Name                    | Type   | Required | Description                                                                                                                   |
| x-ms-user-isolation-key | String | No       | Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user. |

You can add these to a request with RequestOptions#addHeader

Response Body Schema

BinaryData

Parameters:

agentName - The name of the agent.
agentSessionId - The session ID.
path - The file path to download from the sandbox, relative to the session home directory.
filePath - path to disc in file where to save the downloaded file.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

Throws:

IOException

- thrown if the request is rejected by server.

downloadSessionFileWithResponse

public Response<BinaryData> downloadSessionFileWithResponse(String agentName, String sessionId, String path, RequestOptions requestOptions)

Download a session file Downloads the file at the specified sandbox path as a binary stream. The path is resolved relative to the session home directory.

Response Body Schema

BinaryData

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The file path to download from the sandbox, relative to the session home directory.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

enableAgent

public void enableAgent(String agentName)

Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests. This operation is idempotent — enabling an already-enabled agent returns success with no side effects.

Parameters:

agentName - The name of the agent to enable.

enableAgentWithResponse

public Response<Void> enableAgentWithResponse(String agentName, RequestOptions requestOptions)

Enable an agent Enables the specified agent, allowing it to accept new sessions and process requests. This operation is idempotent — enabling an already-enabled agent returns success with no side effects.

Parameters:

agentName - The name of the agent to enable.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

estimateOptimizationJob

public AgentOptimizationEstimateResult estimateOptimizationJob(AgentOptimizationEstimateInputs inputs)

Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.

Parameters:

inputs - The inputs to estimate against.

Returns:

result returned when estimating an agent-optimization job.

estimateOptimizationJobWithResponse

public Response<BinaryData> estimateOptimizationJobWithResponse(BinaryData inputs, RequestOptions requestOptions)

Estimate an agent optimization job Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.

Request Body Schema

{
     target_configuration (Optional): {
         type: String(foundry_agent) (Required)
     }
     optimization_model_configuration (Required): {
         model: String (Required)
     }
     optimization_configuration (Required): {
         type: String(agent_optimization/prompt_optimization) (Required)
         goal: String(improve_quality) (Optional)
         evaluation_configuration (Required): {
             training_set (Required): {
                 type: String(target_completion/user_conversation_simulation) (Required)
             }
             validation_set (Optional): (recursive schema, see validation_set above)
             evaluators (Required): [
                  (Required){
                     name: String (Required)
                     version: String (Optional)
                     initialization_parameters (Optional): {
                         String: BinaryData (Required)
                     }
                 }
             ]
             evaluation_model (Required): {
                 model: String (Required)
                 sampling_params (Optional): {
                     temperature: Double (Optional)
                     top_p: Double (Optional)
                     seed: Integer (Optional)
                     max_completion_tokens: Long (Optional)
                 }
                 voice_model (Optional): {
                     type: String (Required)
                 }
             }
             max_concurrent_agent_runs: Integer (Optional)
         }
         candidate_search_configuration (Required): {
             max_candidates: Integer (Optional)
         }
         baseline_agent_configuration (Optional): {
             system_prompt: String (Optional)
             current_model: String (Optional)
             skills (Optional): [
                  (Optional){
                     name: String (Required)
                     description: String (Required)
                     body: String (Optional)
                 }
             ]
             tools (Optional): [
                  (Optional){
                     type: String (Required)
                     function (Required): {
                         description: String (Optional)
                         name: String (Required)
                         parameters (Optional): {
                              (Optional): {
                                 String: BinaryData (Required)
                             }
                         }
                         strict: Boolean (Optional)
                     }
                 }
             ]
         }
         agent_optimization_space (Required): {
             target_attributes (Optional): [
                 String(instructions/model/skills/tools) (Optional)
             ]
             model_search_space (Optional): [
                 String (Optional)
             ]
         }
     }
 }

Response Body Schema

{
     call_counts (Optional): {
         agent (Optional): {
             low: double (Required)
             typical: double (Required)
             ceiling: double (Required)
         }
         evaluation (Optional): (recursive schema, see evaluation above)
         optimization (Optional): (recursive schema, see optimization above)
     }
     cost (Optional): {
         currency: String (Required)
         total (Optional): (recursive schema, see total above)
         by_stage (Optional): (recursive schema, see by_stage above)
         unpriced_stages (Optional): [
             String(agent/evaluation/optimization) (Optional)
         ]
     }
     prices_as_of: Long (Optional)
 }

Parameters:

inputs - The inputs to estimate against.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

result returned when estimating an agent-optimization job along with Response<T>.

getAgent

public AgentDetails getAgent(String agentName)

Get an agent Retrieves an agent definition by its unique name.

Parameters:

agentName - The name of the agent to retrieve.

Returns:

an agent Retrieves an agent definition by its unique name.

getAgentVersionDetails

public AgentVersionDetails getAgentVersionDetails(String agentName, String agentVersion)

Get an agent version Retrieves the specified version of an agent by its agent name and version identifier.

Parameters:

agentName - The name of the agent to retrieve.
agentVersion - The version of the agent to retrieve.

Returns:

an agent version Retrieves the specified version of an agent by its agent name and version identifier.

getAgentVersionDetailsWithResponse

public Response<BinaryData> getAgentVersionDetailsWithResponse(String agentName, String agentVersion, RequestOptions requestOptions)

Get an agent version Retrieves the specified version of an agent by its agent name and version identifier.

Response Body Schema

{
     metadata (Required): {
         String: String (Required)
     }
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     version: String (Required)
     description: String (Optional)
     created_at: long (Required)
     definition (Required): {
         kind: String(prompt/hosted/workflow/external/voice) (Required)
         rai_config (Optional): {
             rai_policy_name: String (Required)
             invocations_moderation (Optional): {
                 input_content_type: String(json/text) (Optional)
                 output_content_type: String(json/text) (Optional)
                 response_mode: String(non_streaming/streaming/both) (Required)
                 input_paths (Optional): [
                     String (Optional)
                 ]
                 output_paths (Optional): [
                     String (Optional)
                 ]
                 stream_selectors (Optional): [
                      (Optional){
                         event_type: String (Required)
                         text_field: String (Optional)
                     }
                 ]
             }
         }
     }
     draft: Boolean (Optional)
     status: String(creating/active/failed/deleting/deleted) (Optional)
     instance_identity (Optional): {
         principal_id: String (Required)
         client_id: String (Required)
         status: String(active/disabled) (Optional)
     }
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): {
         type: String(ManagedAgentIdentityBlueprint) (Required)
     }
     agent_guid: String (Optional)
 }

Parameters:

agentName - The name of the agent to retrieve.
agentVersion - The version of the agent to retrieve.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

an agent version Retrieves the specified version of an agent by its agent name and version identifier along with Response<T>.

getAgentWithResponse

public Response<BinaryData> getAgentWithResponse(String agentName, RequestOptions requestOptions)

Get an agent Retrieves an agent definition by its unique name.

Response Body Schema

{
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     state: String(enabled/disabled) (Required)
     configuration_state: String(enabled/disabled) (Required)
     state_source: String(agent_instance_identity/agent_blueprint) (Optional)
     versions (Required): {
         latest (Required): {
             metadata (Required): {
                 String: String (Required)
             }
             object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
             id: String (Required)
             name: String (Required)
             version: String (Required)
             description: String (Optional)
             created_at: long (Required)
             definition (Required): {
                 kind: String(prompt/hosted/workflow/external/voice) (Required)
                 rai_config (Optional): {
                     rai_policy_name: String (Required)
                     invocations_moderation (Optional): {
                         input_content_type: String(json/text) (Optional)
                         output_content_type: String(json/text) (Optional)
                         response_mode: String(non_streaming/streaming/both) (Required)
                         input_paths (Optional): [
                             String (Optional)
                         ]
                         output_paths (Optional): [
                             String (Optional)
                         ]
                         stream_selectors (Optional): [
                              (Optional){
                                 event_type: String (Required)
                                 text_field: String (Optional)
                             }
                         ]
                     }
                 }
             }
             draft: Boolean (Optional)
             status: String(creating/active/failed/deleting/deleted) (Optional)
             instance_identity (Optional): {
                 principal_id: String (Required)
                 client_id: String (Required)
                 status: String(active/disabled) (Optional)
             }
             blueprint (Optional): (recursive schema, see blueprint above)
             blueprint_reference (Optional): {
                 type: String(ManagedAgentIdentityBlueprint) (Required)
             }
             agent_guid: String (Optional)
         }
     }
     agent_endpoint (Optional): {
         version_selector (Optional): {
             version_selection_rules (Optional, Required on create): [
                  (Optional, Required on create){
                     type: String(FixedRatio) (Required)
                     agent_version: String (Optional, Required on create)
                 }
             ]
         }
         protocol_configuration (Optional): {
             activity (Optional): {
                 enable_m365_public_endpoint: Boolean (Optional)
                 access_boundaries (Optional): [
                     String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
                 ]
             }
             responses (Optional): {
             }
             a2a (Optional): {
             }
             mcp (Optional): {
             }
             invocations (Optional): {
             }
             invocations_ws (Optional): {
             }
         }
         authorization_schemes (Optional): [
              (Optional){
                 type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
             }
         ]
         publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
     }
     digital_worker_type: String(m365) (Optional)
     instance_identity (Optional): (recursive schema, see instance_identity above)
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): (recursive schema, see blueprint_reference above)
     agent_card (Optional): {
         version: String (Optional, Required on create)
         description: String (Optional)
         skills (Optional, Required on create): [
              (Optional, Required on create){
                 id: String (Optional, Required on create)
                 name: String (Optional, Required on create)
                 description: String (Optional)
                 tags (Optional): [
                     String (Optional)
                 ]
                 examples (Optional): [
                     String (Optional)
                 ]
             }
         ]
     }
 }

Parameters:

agentName - The name of the agent to retrieve.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

an agent Retrieves an agent definition by its unique name along with Response<T>.

getMicrosoft365AppPackage

public BinaryData getMicrosoft365AppPackage(GetMicrosoft365AppPackageOptions options)

Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it. Returns the app package as `application/zip`.

Parameters:

options - Options for getMicrosoft365AppPackage API.

Returns:

the response.

getMicrosoft365AppPackageWithResponse

public Response<BinaryData> getMicrosoft365AppPackageWithResponse(String agentName, BinaryData getMicrosoft365AppPackageRequest, RequestOptions requestOptions)

Generate a Microsoft 365 app package Generates the Microsoft Teams app package (zip) for a Foundry agent from the supplied publish request, without publishing it. Returns the app package as `application/zip`.

Request Body Schema

{
     agentDisplayName: String (Optional)
     botServiceArmId: String (Optional)
     publishAsAutopilot: Boolean (Optional)
     accessBoundaries (Optional): [
         String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
     ]
     optionalPermissionScopes (Optional): [
          (Optional){
             resourceAppId: String (Required)
             scopes (Required): [
                 String (Required)
             ]
         }
     ]
     publishScope: String(Personal/Shared/Tenant) (Required)
     canRespondWithoutMention: Boolean (Optional)
     appVersion: String (Optional)
     shortDescription: String (Optional)
     fullDescription: String (Optional)
     developerName: String (Optional)
     developerWebsiteUrl: String (Optional)
     privacyUrl: String (Optional)
     termsOfUseUrl: String (Optional)
     colorIconBase64: String (Optional)
     outlineIconBase64: String (Optional)
 }

Response Body Schema

BinaryData

Parameters:

agentName - The name of the agent to generate the app package for.
getMicrosoft365AppPackageRequest - The getMicrosoft365AppPackageRequest parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

getMicrosoft365PublishDefaults

public Microsoft365PublishDefaults getMicrosoft365PublishDefaults(String agentName)

Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

Parameters:

agentName - The name of the agent to get publish defaults for.

Returns:

microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

getMicrosoft365PublishDefaults

public Microsoft365PublishDefaults getMicrosoft365PublishDefaults(String agentName, Boolean publishAsDigitalWorker)

Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

Parameters:

agentName - The name of the agent to get publish defaults for.
publishAsDigitalWorker - When true, returns defaults for publishing the agent as an autopilot (digital worker) agent.

Returns:

microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

getMicrosoft365PublishDefaultsWithResponse

public Response<BinaryData> getMicrosoft365PublishDefaultsWithResponse(String agentName, RequestOptions requestOptions)

Get Microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent.

Query Parameters

| ---------------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| Name                   | Type    | Required | Description                                                                                  |
| publishAsDigitalWorker | Boolean | No       | When true, returns defaults for publishing the agent as an autopilot (digital worker) agent. |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     appPublishScope: String(Personal/Shared/Tenant) (Optional)
     agentName: String (Optional)
     agentDisplayName: String (Optional)
     appRegistrationClientId: String (Optional)
     botServiceArmId: String (Optional)
     appVersion: String (Optional)
     recommendedNextAppVersion: String (Optional)
     titleId: String (Optional)
     teamsAppId: String (Optional)
     shortDescription: String (Optional)
     fullDescription: String (Optional)
     developerName: String (Optional)
     developerWebsiteUrl: String (Optional)
     privacyUrl: String (Optional)
     termsOfUseUrl: String (Optional)
 }

Parameters:

agentName - The name of the agent to get publish defaults for.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

microsoft 365 publish defaults Returns default and previously-published values used to pre-populate a Microsoft 365 publish request for a Foundry agent along with Response<T>.

getOptimizationCandidate

public AgentOptimizationCandidate getOptimizationCandidate(String jobId, String candidateId)

Get a candidate for an agent optimization job Retrieves a single candidate. Mutation values are always included.

Parameters:

jobId - The ID of the parent optimization job.
candidateId - The candidate identifier.

Returns:

a candidate for an agent optimization job Retrieves a single candidate.

getOptimizationCandidateWithResponse

public Response<BinaryData> getOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)

Get a candidate for an agent optimization job Retrieves a single candidate. Mutation values are always included.

Response Body Schema

{
     candidate_id: String (Required)
     job_id: String (Required)
     name: String (Required)
     status: String(generating/evaluating/completed/failed) (Required)
     started_at: long (Required)
     output (Optional): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     rationale: String (Optional)
     agent_version: String (Optional)
     evaluation (Optional): {
         score: Double (Optional)
         avg_tokens: Double (Optional)
         avg_latency_ms: Long (Optional)
         eval_id: String (Optional)
         eval_run_id: String (Optional)
         completed_at: Long (Optional)
     }
     promotion (Optional): {
         promoted_at: long (Required)
         promoted_agent (Required): {
             type: String (Required)
             name: String (Required)
             version: String (Optional)
         }
     }
 }

Parameters:

jobId - The ID of the parent optimization job.
candidateId - The candidate identifier.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

a candidate for an agent optimization job Retrieves a single candidate along with Response<T>.

getOptimizationJob

public AgentOptimizationJob getOptimizationJob(String jobId)

Get an agent optimization job Retrieves an optimization job by its identifier.

Parameters:

jobId - The ID of the job.

Returns:

an agent optimization job Retrieves an optimization job by its identifier.

getOptimizationJobWithResponse

public Response<BinaryData> getOptimizationJobWithResponse(String jobId, RequestOptions requestOptions)

Get an agent optimization job Retrieves an optimization job by its identifier.

Response Body Schema

{
     id: String (Required)
     result (Optional): {
         candidate_summary (Optional): {
             completed_candidate_count: int (Required)
             baseline_id: String (Optional)
             best_id: String (Optional)
             baseline_score: Double (Optional)
             best_score: Double (Optional)
             latest_promoted_candidate (Optional): {
                 promoted_at: long (Required)
                 promoted_agent (Required): {
                     type: String (Required)
                     name: String (Required)
                     version: String (Optional)
                 }
             }
         }
         token_usage (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 input_tokens: Long (Optional)
                 output_tokens: Long (Optional)
                 total_tokens: Long (Optional)
                 cached_tokens: Long (Optional)
                 reasoning_tokens: Long (Optional)
             }
         ]
         latency_metrics (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 avg_latency_ms: long (Required)
                 call_count: long (Required)
             }
         ]
         termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
     }
     status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
     error (Optional): {
         code: String (Required)
         message: String (Required)
         param: String (Optional)
         type: String (Optional)
         misalignment (Optional): {
             error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
             detailed_explanation: String (Optional)
             steer (Optional): {
                 message: String (Required)
             }
         }
         details (Optional): [
             (recursive schema, see above)
         ]
         additionalInfo (Optional): {
             String: BinaryData (Required)
         }
         debugInfo (Optional): {
             String: BinaryData (Required)
         }
     }
     display_name: String (Optional)
     target_configuration (Optional): {
         type: String(foundry_agent) (Required)
     }
     optimization_model_configuration (Required): {
         model: String (Required)
     }
     optimization_configuration (Required): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     run_duration_ms: long (Required)
     created_at: long (Required)
     updated_at: long (Required)
     warnings (Optional): [
         String (Optional)
     ]
 }

Response Headers

| ----------- | ---- | ----------------------------------------------------------- |
| Name        | Type | Description                                                 |
| Retry-After | int  | Recommended number of seconds to wait before polling again. |

Parameters:

jobId - The ID of the job.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

an agent optimization job Retrieves an optimization job by its identifier along with Response<T>.

getSession

public AgentSessionResource getSession(String agentName, String sessionId)

Get a session Retrieves the details of a hosted agent session by agent name and session identifier.

Parameters:

agentName - The name of the agent.
sessionId - The session identifier.

Returns:

a session Retrieves the details of a hosted agent session by agent name and session identifier.

getSessionLogStream

public IterableStream<SessionLogEvent> getSessionLogStream(String agentName, String agentVersion, String sessionId)

Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values.

Parameters:

agentName - The name of the hosted agent.
agentVersion - The version of the agent.
sessionId - The session ID (maps to an ADC sandbox).

Returns:

A stream of SessionLogEvent values emitted by the hosted agent session log stream.

getSessionLogStream

public IterableStream<SessionLogEvent> getSessionLogStream(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)

Streams console logs (stdout / stderr) for a specific hosted agent session as typed SessionLogEvent values.

Parameters:

agentName - The name of the hosted agent.
agentVersion - The version of the agent.
sessionId - The session ID (maps to an ADC sandbox).
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

A stream of SessionLogEvent values emitted by the hosted agent session log stream.

getSessionLogStreamWithResponse

public Response<BinaryData> getSessionLogStreamWithResponse(String agentName, String agentVersion, String sessionId, RequestOptions requestOptions)

Stream console logs for a hosted agent session Streams console logs (stdout / stderr) for a specific hosted agent session as a Server-Sent Events (SSE) stream. Each SSE frame contains: - `event`: always `"log"` - `data`: a plain-text log line (currently JSON-formatted, but the schema is not contractual and may include additional keys or change format over time — clients should treat it as an opaque string) Example SSE frames: ``` event: log data: {"timestamp":"2026-03-10T09:33:17.121Z","stream":"stdout","message":"Starting FoundryCBAgent server on port 8088"} event: log data: {"timestamp":"2026-03-10T09:33:17.130Z","stream":"stderr","message":"INFO: Application startup complete."} event: log data: {"timestamp":"2026-03-10T09:34:52.714Z","stream":"status","message":"Successfully connected to container"} event: log data: {"timestamp":"2026-03-10T09:35:52.714Z","stream":"status","message":"No logs since last 60 seconds"} ``` The stream remains open until the client disconnects or the server terminates the connection. Clients should handle reconnection as needed.

Response Body Schema

{
     event: String(log) (Required)
     data: String (Required)
 }

Parameters:

agentName - The name of the hosted agent.
agentVersion - The version of the agent.
sessionId - The session ID (maps to an ADC sandbox).
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

a single Server-Sent Event frame emitted by the hosted agent session log stream. Each frame contains an event field identifying the event type and a data field carrying the payload as plain text along with Response<T>.

getSessionWithResponse

public Response<BinaryData> getSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)

Get a session Retrieves the details of a hosted agent session by agent name and session identifier.

Response Body Schema

{
     agent_session_id: String (Required)
     version_indicator (Required): {
         type: String(version_ref) (Required)
     }
     status: String(creating/active/idle/updating/failed/deleting/deleted/expired) (Required)
     created_at: long (Required)
     last_accessed_at: long (Required)
     expires_at: long (Required)
     stopped_at: Long (Optional)
 }

Parameters:

agentName - The name of the agent.
sessionId - The session identifier.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

a session Retrieves the details of a hosted agent session by agent name and session identifier along with Response<T>.

listAgentConversations

public PagedIterable<Conversation> listAgentConversations()

List conversations Returns the conversations available in the current project.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgentConversations

public PagedIterable<Conversation> listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId)

Returns the list of all conversations.

Parameters:

limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
agentName - Filter by agent name. If provided, only items associated with the specified agent will be returned.
agentId - Filter by agent ID in the format name:version. If provided, only items associated with the specified agent ID will be returned.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgentConversations

public PagedIterable<Conversation> listAgentConversations(Integer limit, PageOrder order, String after, String before, String agentName, String agentId, String userIdentity)

List conversations Returns the conversations available in the current project.

Parameters:

limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
agentName - Filter by agent name. If provided, only items associated with the specified agent will be returned.
agentId - Filter by agent ID in the format name:version. If provided, only items associated with the specified agent ID will be returned.
userIdentity - Opaque per-user identity string used to scope endpoint-scoped data to a specific end user. The caller must have the agents/endpoints/UserIdentityImpersonation/action RBAC permission.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgentConversations

public PagedIterable<BinaryData> listAgentConversations(RequestOptions requestOptions)

List conversations Returns the conversations available in the current project.

Query Parameters

| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name        | Type    | Required | Description                                                                                                                                                                                                                                                                               |
| limit       | Integer | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                                                                |
| order       | String  | No       | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc".                                                                                                                                  |
| after       | String  | No       | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list.       |
| before      | String  | No       | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
| agent\_name | String  | No       | Filter by agent name. If provided, only items associated with the specified agent will be returned.                                                                                                                                                                                       |
| agent\_id   | String  | No       | Filter by agent ID in the format \`name:version\`. If provided, only items associated with the specified agent ID will be returned.                                                                                                                                                       |

You can add these to a request with RequestOptions#addQueryParam

Header Parameters

| ------------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Name               | Type   | Required | Description                                                                                                                                                                                |
| x-ms-user-identity | String | No       | Opaque per-user identity string used to scope endpoint-scoped data to a specific end user. The caller must have the \`agents/endpoints/UserIdentityImpersonation/action\` RBAC permission. |

You can add these to a request with RequestOptions#addHeader

Response Body Schema

{
     id: String (Required)
     object: String (Required)
     metadata (Required): {
         String: String (Required)
     }
     created_at: long (Required)
 }

Parameters:

requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgents

public PagedIterable<AgentDetails> listAgents()

List agents Returns a paged collection of agent resources.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgents

public PagedIterable<AgentDetails> listAgents(AgentKind kind, Integer limit, PageOrder order, String after, String before)

List agents Returns a paged collection of agent resources.

Parameters:

kind - Filter agents by kind. If not provided, all agents are returned.
limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgents

public PagedIterable<BinaryData> listAgents(RequestOptions requestOptions)

List agents Returns a paged collection of agent resources.

Query Parameters

| ------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name   | Type    | Required | Description                                                                                                                                                                                                                                                                               |
| kind   | String  | No       | Filter agents by kind. If not provided, all agents are returned. Allowed values: "prompt", "hosted", "workflow", "external", "voice".                                                                                                                                                     |
| limit  | Integer | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                                                                |
| order  | String  | No       | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc".                                                                                                                                  |
| after  | String  | No       | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list.       |
| before | String  | No       | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     state: String(enabled/disabled) (Required)
     configuration_state: String(enabled/disabled) (Required)
     state_source: String(agent_instance_identity/agent_blueprint) (Optional)
     versions (Required): {
         latest (Required): {
             metadata (Required): {
                 String: String (Required)
             }
             object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
             id: String (Required)
             name: String (Required)
             version: String (Required)
             description: String (Optional)
             created_at: long (Required)
             definition (Required): {
                 kind: String(prompt/hosted/workflow/external/voice) (Required)
                 rai_config (Optional): {
                     rai_policy_name: String (Required)
                     invocations_moderation (Optional): {
                         input_content_type: String(json/text) (Optional)
                         output_content_type: String(json/text) (Optional)
                         response_mode: String(non_streaming/streaming/both) (Required)
                         input_paths (Optional): [
                             String (Optional)
                         ]
                         output_paths (Optional): [
                             String (Optional)
                         ]
                         stream_selectors (Optional): [
                              (Optional){
                                 event_type: String (Required)
                                 text_field: String (Optional)
                             }
                         ]
                     }
                 }
             }
             draft: Boolean (Optional)
             status: String(creating/active/failed/deleting/deleted) (Optional)
             instance_identity (Optional): {
                 principal_id: String (Required)
                 client_id: String (Required)
                 status: String(active/disabled) (Optional)
             }
             blueprint (Optional): (recursive schema, see blueprint above)
             blueprint_reference (Optional): {
                 type: String(ManagedAgentIdentityBlueprint) (Required)
             }
             agent_guid: String (Optional)
         }
     }
     agent_endpoint (Optional): {
         version_selector (Optional): {
             version_selection_rules (Optional, Required on create): [
                  (Optional, Required on create){
                     type: String(FixedRatio) (Required)
                     agent_version: String (Optional, Required on create)
                 }
             ]
         }
         protocol_configuration (Optional): {
             activity (Optional): {
                 enable_m365_public_endpoint: Boolean (Optional)
                 access_boundaries (Optional): [
                     String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
                 ]
             }
             responses (Optional): {
             }
             a2a (Optional): {
             }
             mcp (Optional): {
             }
             invocations (Optional): {
             }
             invocations_ws (Optional): {
             }
         }
         authorization_schemes (Optional): [
              (Optional){
                 type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
             }
         ]
         publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
     }
     digital_worker_type: String(m365) (Optional)
     instance_identity (Optional): (recursive schema, see instance_identity above)
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): (recursive schema, see blueprint_reference above)
     agent_card (Optional): {
         version: String (Optional, Required on create)
         description: String (Optional)
         skills (Optional, Required on create): [
              (Optional, Required on create){
                 id: String (Optional, Required on create)
                 name: String (Optional, Required on create)
                 description: String (Optional)
                 tags (Optional): [
                     String (Optional)
                 ]
                 examples (Optional): [
                     String (Optional)
                 ]
             }
         ]
     }
 }

Parameters:

requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgentVersions

public PagedIterable<AgentVersionDetails> listAgentVersions(String agentName)

List agent versions Returns a paged collection of versions for the specified agent.

Parameters:

agentName - The name of the agent to retrieve versions for.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgentVersions

public PagedIterable<AgentVersionDetails> listAgentVersions(String agentName, Integer limit, PageOrder order, String after, String before, Boolean includeDrafts)

List agent versions Returns a paged collection of versions for the specified agent.

Parameters:

agentName - The name of the agent to retrieve versions for.
limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
includeDrafts - (Preview) Whether to include draft versions in the listing. The service defaults to false if a value is not specified by the caller (only non-draft versions are returned).

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listAgentVersions

public PagedIterable<BinaryData> listAgentVersions(String agentName, RequestOptions requestOptions)

List agent versions Returns a paged collection of versions for the specified agent.

Query Parameters

| --------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name            | Type    | Required | Description                                                                                                                                                                                                                                                                               |
| limit           | Integer | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                                                                |
| order           | String  | No       | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc".                                                                                                                                  |
| after           | String  | No       | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list.       |
| before          | String  | No       | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
| include\_drafts | Boolean | No       | (Preview) Whether to include draft versions in the listing. The service defaults to \`false\` if a value is not specified by the caller (only non-draft versions are returned).                                                                                                           |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     metadata (Required): {
         String: String (Required)
     }
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     version: String (Required)
     description: String (Optional)
     created_at: long (Required)
     definition (Required): {
         kind: String(prompt/hosted/workflow/external/voice) (Required)
         rai_config (Optional): {
             rai_policy_name: String (Required)
             invocations_moderation (Optional): {
                 input_content_type: String(json/text) (Optional)
                 output_content_type: String(json/text) (Optional)
                 response_mode: String(non_streaming/streaming/both) (Required)
                 input_paths (Optional): [
                     String (Optional)
                 ]
                 output_paths (Optional): [
                     String (Optional)
                 ]
                 stream_selectors (Optional): [
                      (Optional){
                         event_type: String (Required)
                         text_field: String (Optional)
                     }
                 ]
             }
         }
     }
     draft: Boolean (Optional)
     status: String(creating/active/failed/deleting/deleted) (Optional)
     instance_identity (Optional): {
         principal_id: String (Required)
         client_id: String (Required)
         status: String(active/disabled) (Optional)
     }
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): {
         type: String(ManagedAgentIdentityBlueprint) (Required)
     }
     agent_guid: String (Optional)
 }

Parameters:

agentName - The name of the agent to retrieve versions for.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listOptimizationCandidates

public PagedIterable<AgentOptimizationCandidate> listOptimizationCandidates(String jobId)

List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. Each `output.mutations` item identifies a changed attribute by `type`; mutation `value` fields are omitted unless the client passes `expand=mutations`.

Parameters:

jobId - The ID of the parent optimization job.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listOptimizationCandidates

public PagedIterable<AgentOptimizationCandidate> listOptimizationCandidates(String jobId, List<AgentOptimizationCandidateExpand> expand, Integer limit, PageOrder order, String after, String before)

List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. Each `output.mutations` item identifies a changed attribute by `type`; mutation `value` fields are omitted unless the client passes `expand=mutations`.

Parameters:

jobId - The ID of the parent optimization job.
expand - Comma-separated list of expand keys. Pass mutations to populate mutation value fields; omit to receive mutation items containing only type. Additional expand keys may be added in future previews.
limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the candidate started_at timestamp.
after - Candidate-ID cursor identifying the last item from the previous page.
before - Candidate-ID cursor identifying the first item from the following page.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listOptimizationCandidates

public PagedIterable<BinaryData> listOptimizationCandidates(String jobId, RequestOptions requestOptions)

List candidates for an agent optimization job Lists candidates for the given optimization job with cursor pagination, including the original baseline and generated candidates. Each `output.mutations` item identifies a changed attribute by `type`; mutation `value` fields are omitted unless the client passes `expand=mutations`.

Query Parameters

| ------ | ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name   | Type         | Required | Description                                                                                                                                                                                                                                          |
| expand | List<String> | No       | Comma-separated list of expand keys. Pass \`mutations\` to populate mutation \`value\` fields; omit to receive mutation items containing only \`type\`. Additional expand keys may be added in future previews. In the form of "," separated string. |
| limit  | Integer      | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                           |
| order  | String       | No       | Sort order by the candidate \`started\_at\` timestamp. Allowed values: "asc", "desc".                                                                                                                                                                |
| after  | String       | No       | Candidate-ID cursor identifying the last item from the previous page.                                                                                                                                                                                |
| before | String       | No       | Candidate-ID cursor identifying the first item from the following page.                                                                                                                                                                              |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     candidate_id: String (Required)
     job_id: String (Required)
     name: String (Required)
     status: String(generating/evaluating/completed/failed) (Required)
     started_at: long (Required)
     output (Optional): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     rationale: String (Optional)
     agent_version: String (Optional)
     evaluation (Optional): {
         score: Double (Optional)
         avg_tokens: Double (Optional)
         avg_latency_ms: Long (Optional)
         eval_id: String (Optional)
         eval_run_id: String (Optional)
         completed_at: Long (Optional)
     }
     promotion (Optional): {
         promoted_at: long (Required)
         promoted_agent (Required): {
             type: String (Required)
             name: String (Required)
             version: String (Optional)
         }
     }
 }

Parameters:

jobId - The ID of the parent optimization job.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listOptimizationJobs

public PagedIterable<AgentOptimizationJob> listOptimizationJobs()

List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listOptimizationJobs

public PagedIterable<AgentOptimizationJob> listOptimizationJobs(Integer limit, PageOrder order, String after, String before, JobStatus status, String agentName)

List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.

Parameters:

limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
status - Filter to jobs in this lifecycle state.
agentName - Filter to jobs targeting this agent name.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listOptimizationJobs

public PagedIterable<BinaryData> listOptimizationJobs(RequestOptions requestOptions)

List agent optimization jobs Lists optimization jobs with cursor pagination and optional status or agent name filters.

Query Parameters

| ----------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name        | Type    | Required | Description                                                                                                                                                                                                                                                                               |
| limit       | Integer | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                                                                |
| order       | String  | No       | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc".                                                                                                                                  |
| after       | String  | No       | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list.       |
| before      | String  | No       | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |
| status      | String  | No       | Filter to jobs in this lifecycle state. Allowed values: "queued", "in\_progress", "succeeded", "failed", "cancelled".                                                                                                                                                                     |
| agent\_name | String  | No       | Filter to jobs targeting this agent name.                                                                                                                                                                                                                                                 |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     id: String (Required)
     result (Optional): {
         candidate_summary (Optional): {
             completed_candidate_count: int (Required)
             baseline_id: String (Optional)
             best_id: String (Optional)
             baseline_score: Double (Optional)
             best_score: Double (Optional)
             latest_promoted_candidate (Optional): {
                 promoted_at: long (Required)
                 promoted_agent (Required): {
                     type: String (Required)
                     name: String (Required)
                     version: String (Optional)
                 }
             }
         }
         token_usage (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 input_tokens: Long (Optional)
                 output_tokens: Long (Optional)
                 total_tokens: Long (Optional)
                 cached_tokens: Long (Optional)
                 reasoning_tokens: Long (Optional)
             }
         ]
         latency_metrics (Required): [
              (Required){
                 stage: String(agent/evaluation/optimization) (Required)
                 model: String (Optional)
                 avg_latency_ms: long (Required)
                 call_count: long (Required)
             }
         ]
         termination_reason: String(completed/budget_exhausted/candidate_screening_stalled) (Optional)
     }
     status: String(queued/in_progress/succeeded/failed/cancelled) (Required)
     error (Optional): {
         code: String (Required)
         message: String (Required)
         param: String (Optional)
         type: String (Optional)
         misalignment (Optional): {
             error_type: String(potentially_unintended_data_transfer/potentially_unintended_data_access/potentially_unintended_destructive_activity/other) (Optional)
             detailed_explanation: String (Optional)
             steer (Optional): {
                 message: String (Required)
             }
         }
         details (Optional): [
             (recursive schema, see above)
         ]
         additionalInfo (Optional): {
             String: BinaryData (Required)
         }
         debugInfo (Optional): {
             String: BinaryData (Required)
         }
     }
     display_name: String (Optional)
     target_configuration (Optional): {
         type: String(foundry_agent) (Required)
     }
     optimization_model_configuration (Required): {
         model: String (Required)
     }
     optimization_configuration (Required): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     run_duration_ms: long (Required)
     created_at: long (Required)
     updated_at: long (Required)
     warnings (Optional): [
         String (Optional)
     ]
 }

Parameters:

requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listSessionFiles

public PagedIterable<SessionDirectoryEntry> listSessionFiles(String agentName, String sessionId)

List session files Returns files and directories at the specified path in the session sandbox. The response includes only the immediate children of the target directory and defaults to the session home directory when no path is supplied.

Parameters:

agentName - The name of the agent.
sessionId - The session ID.

Returns:

the paginated response with PagedIterable<T>.

listSessionFiles

public PagedIterable<BinaryData> listSessionFiles(String agentName, String sessionId, RequestOptions requestOptions)

List session files Returns files and directories at the specified path in the session sandbox. The response includes only the immediate children of the target directory and defaults to the session home directory when no path is supplied.

Query Parameters

| ------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name   | Type    | Required | Description                                                                                                                                                                                                                                                                               |
| path   | String  | No       | The directory path to list, relative to the session home directory. Defaults to the home directory if not provided.                                                                                                                                                                       |
| limit  | Integer | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                                                                |
| order  | String  | No       | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc".                                                                                                                                  |
| after  | String  | No       | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list.       |
| before | String  | No       | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     name: String (Required)
     size: long (Required)
     is_directory: boolean (Required)
     modified_time: long (Required)
 }

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the paginated response with PagedIterable<T>.

listSessionFiles

public PagedIterable<SessionDirectoryEntry> listSessionFiles(String agentName, String sessionId, String path, Integer limit, PageOrder order, String after, String before)

List session files Returns files and directories at the specified path in the session sandbox. The response includes only the immediate children of the target directory and defaults to the session home directory when no path is supplied.

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The directory path to list, relative to the session home directory. Defaults to the home directory if not provided.
limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

Returns:

the paginated response with PagedIterable<T>.

listSessions

public PagedIterable<AgentSessionResource> listSessions(String agentName)

List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.

Parameters:

agentName - The name of the agent.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listSessions

public PagedIterable<AgentSessionResource> listSessions(String agentName, Integer limit, PageOrder order, String after, String before)

List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.

Parameters:

agentName - The name of the agent.
limit - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.
order - Sort order by the created_at timestamp of the objects. asc for ascending order anddesc for descending order.
after - A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before - A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

listSessions

public PagedIterable<BinaryData> listSessions(String agentName, RequestOptions requestOptions)

List sessions for an agent Returns a paged collection of sessions associated with the specified agent endpoint.

Query Parameters

| ------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name   | Type    | Required | Description                                                                                                                                                                                                                                                                               |
| limit  | Integer | No       | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20.                                                                                                                                                                                |
| order  | String  | No       | Sort order by the \`created\_at\` timestamp of the objects. \`asc\` for ascending order and\`desc\` for descending order. Allowed values: "asc", "desc".                                                                                                                                  |
| after  | String  | No       | A cursor for use in pagination. \`after\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include after=obj\_foo in order to fetch the next page of the list.       |
| before | String  | No       | A cursor for use in pagination. \`before\` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include before=obj\_foo in order to fetch the previous page of the list. |

You can add these to a request with RequestOptions#addQueryParam

Response Body Schema

{
     agent_session_id: String (Required)
     version_indicator (Required): {
         type: String(version_ref) (Required)
     }
     status: String(creating/active/idle/updating/failed/deleting/deleted/expired) (Required)
     created_at: long (Required)
     last_accessed_at: long (Required)
     expires_at: long (Required)
     stopped_at: Long (Optional)
 }

Parameters:

agentName - The name of the agent.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response data for a requested list of items as paginated response with PagedIterable<T>.

promoteOptimizationCandidate

public AgentOptimizationCandidate promoteOptimizationCandidate(String jobId, String candidateId)

Promote a candidate for an agent optimization job Promotes a candidate to the Foundry agent stored in the parent job's target configuration. Promotion is unavailable when the job omitted target_configuration. Prompt-agent promotion creates a new agent version. Hosted-agent promotion currently records promotion metadata without deploying a new hosted-agent version.

Parameters:

jobId - The ID of the parent optimization job.
candidateId - The candidate identifier.

Returns:

a candidate generated by an optimization job.

promoteOptimizationCandidateWithResponse

public Response<BinaryData> promoteOptimizationCandidateWithResponse(String jobId, String candidateId, RequestOptions requestOptions)

Promote a candidate for an agent optimization job Promotes a candidate to the Foundry agent stored in the parent job's target configuration. Promotion is unavailable when the job omitted target_configuration. Prompt-agent promotion creates a new agent version. Hosted-agent promotion currently records promotion metadata without deploying a new hosted-agent version.

Response Body Schema

{
     candidate_id: String (Required)
     job_id: String (Required)
     name: String (Required)
     status: String(generating/evaluating/completed/failed) (Required)
     started_at: long (Required)
     output (Optional): {
         type: String(agent_optimization/prompt_optimization) (Required)
     }
     rationale: String (Optional)
     agent_version: String (Optional)
     evaluation (Optional): {
         score: Double (Optional)
         avg_tokens: Double (Optional)
         avg_latency_ms: Long (Optional)
         eval_id: String (Optional)
         eval_run_id: String (Optional)
         completed_at: Long (Optional)
     }
     promotion (Optional): {
         promoted_at: long (Required)
         promoted_agent (Required): {
             type: String (Required)
             name: String (Required)
             version: String (Optional)
         }
     }
 }

Parameters:

jobId - The ID of the parent optimization job.
candidateId - The candidate identifier.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

a candidate generated by an optimization job along with Response<T>.

publishAgentToMicrosoft365

public Microsoft365PublishResult publishAgentToMicrosoft365(PublishAgentToMicrosoft365Options options)

Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids.

Parameters:

options - Options for publishAgentToMicrosoft365 API.

Returns:

response from publishing an agent to Microsoft 365 / Microsoft Teams.

publishAgentToMicrosoft365WithResponse

public Response<BinaryData> publishAgentToMicrosoft365WithResponse(String agentName, BinaryData publishAgentToMicrosoft365Request, RequestOptions requestOptions)

Publish an agent to Microsoft 365 Publishes a Foundry agent to Microsoft 365 / Microsoft Teams and returns the published title and Teams app ids.

Request Body Schema

{
     agentDisplayName: String (Optional)
     botServiceArmId: String (Optional)
     publishAsAutopilot: Boolean (Optional)
     accessBoundaries (Optional): [
         String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
     ]
     optionalPermissionScopes (Optional): [
          (Optional){
             resourceAppId: String (Required)
             scopes (Required): [
                 String (Required)
             ]
         }
     ]
     publishScope: String(Personal/Shared/Tenant) (Required)
     canRespondWithoutMention: Boolean (Optional)
     appVersion: String (Optional)
     shortDescription: String (Optional)
     fullDescription: String (Optional)
     developerName: String (Optional)
     developerWebsiteUrl: String (Optional)
     privacyUrl: String (Optional)
     termsOfUseUrl: String (Optional)
     colorIconBase64: String (Optional)
     outlineIconBase64: String (Optional)
 }

Response Body Schema

{
     titleId: String (Optional)
     teamsAppId: String (Optional)
 }

Parameters:

agentName - The name of the agent to publish.
publishAgentToMicrosoft365Request - The publishAgentToMicrosoft365Request parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

response from publishing an agent to Microsoft 365 / Microsoft Teams along with Response<T>.

stopSession

public void stopSession(String agentName, String sessionId)

Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.

Parameters:

agentName - The name of the agent.
sessionId - The session identifier.

stopSessionWithResponse

public Response<Void> stopSessionWithResponse(String agentName, String sessionId, RequestOptions requestOptions)

Stop a session Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.

Parameters:

agentName - The name of the agent.
sessionId - The session identifier.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

updateAgentDetails

public AgentDetails updateAgentDetails(String agentName, UpdateAgentDetailsOptions patchAgentObjectRequest)

Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration.

Parameters:

agentName - The name of the agent to retrieve The name of the agent to retrieve.
patchAgentObjectRequest - The patchAgentObjectRequest parameter.

Returns:

the response.

updateAgentDetailsWithResponse

public Response<BinaryData> updateAgentDetailsWithResponse(String agentName, BinaryData patchAgentObjectRequest, RequestOptions requestOptions)

Update an agent endpoint Applies a merge-patch update to the specified agent endpoint configuration.

Request Body Schema

{
     agent_endpoint (Optional): {
         version_selector (Optional): {
             version_selection_rules (Optional, Required on create): [
                  (Optional, Required on create){
                     type: String(FixedRatio) (Required)
                     agent_version: String (Optional, Required on create)
                 }
             ]
         }
         protocol_configuration (Optional): {
             activity (Optional): {
                 enable_m365_public_endpoint: Boolean (Optional)
                 access_boundaries (Optional): [
                     String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
                 ]
             }
             responses (Optional): {
             }
             a2a (Optional): {
             }
             mcp (Optional): {
             }
             invocations (Optional): {
             }
             invocations_ws (Optional): {
             }
         }
         authorization_schemes (Optional): [
              (Optional){
                 type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
             }
         ]
         publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
     }
     agent_card (Optional): {
         version: String (Optional, Required on create)
         description: String (Optional)
         skills (Optional, Required on create): [
              (Optional, Required on create){
                 id: String (Optional, Required on create)
                 name: String (Optional, Required on create)
                 description: String (Optional)
                 tags (Optional): [
                     String (Optional)
                 ]
                 examples (Optional): [
                     String (Optional)
                 ]
             }
         ]
     }
 }

Response Body Schema

{
     object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
     id: String (Required)
     name: String (Required)
     state: String(enabled/disabled) (Required)
     configuration_state: String(enabled/disabled) (Required)
     state_source: String(agent_instance_identity/agent_blueprint) (Optional)
     versions (Required): {
         latest (Required): {
             metadata (Required): {
                 String: String (Required)
             }
             object: String(agent/agent.version/agent.deleted/agent.version.deleted/agent.container) (Required)
             id: String (Required)
             name: String (Required)
             version: String (Required)
             description: String (Optional)
             created_at: long (Required)
             definition (Required): {
                 kind: String(prompt/hosted/workflow/external/voice) (Required)
                 rai_config (Optional): {
                     rai_policy_name: String (Required)
                     invocations_moderation (Optional): {
                         input_content_type: String(json/text) (Optional)
                         output_content_type: String(json/text) (Optional)
                         response_mode: String(non_streaming/streaming/both) (Required)
                         input_paths (Optional): [
                             String (Optional)
                         ]
                         output_paths (Optional): [
                             String (Optional)
                         ]
                         stream_selectors (Optional): [
                              (Optional){
                                 event_type: String (Required)
                                 text_field: String (Optional)
                             }
                         ]
                     }
                 }
             }
             draft: Boolean (Optional)
             status: String(creating/active/failed/deleting/deleted) (Optional)
             instance_identity (Optional): {
                 principal_id: String (Required)
                 client_id: String (Required)
                 status: String(active/disabled) (Optional)
             }
             blueprint (Optional): (recursive schema, see blueprint above)
             blueprint_reference (Optional): {
                 type: String(ManagedAgentIdentityBlueprint) (Required)
             }
             agent_guid: String (Optional)
         }
     }
     agent_endpoint (Optional): {
         version_selector (Optional): {
             version_selection_rules (Optional, Required on create): [
                  (Optional, Required on create){
                     type: String(FixedRatio) (Required)
                     agent_version: String (Optional, Required on create)
                 }
             ]
         }
         protocol_configuration (Optional): {
             activity (Optional): {
                 enable_m365_public_endpoint: Boolean (Optional)
                 access_boundaries (Optional): [
                     String(read.1on1.developers/read.1on1.manager/read.1on1.allowlisted/read.1on1.tenant/write.1on1.developers/write.1on1.manager/write.1on1.allowlisted/write.1on1.tenant/read.group.developers/read.group.allowlisted/read.group.manager-invited/read.group.manager-present/read.group.tenant/write.group.developers/write.group.allowlisted/write.group.manager-invited/write.group.manager-present/write.group.tenant) (Optional)
                 ]
             }
             responses (Optional): {
             }
             a2a (Optional): {
             }
             mcp (Optional): {
             }
             invocations (Optional): {
             }
             invocations_ws (Optional): {
             }
         }
         authorization_schemes (Optional): [
              (Optional){
                 type: String(Entra/BotService/BotServiceRbac/BotServiceTenant) (Required)
             }
         ]
         publish_approval_status: String(not_published/pending/approved/rejected/no_approval_needed) (Optional)
     }
     digital_worker_type: String(m365) (Optional)
     instance_identity (Optional): (recursive schema, see instance_identity above)
     blueprint (Optional): (recursive schema, see blueprint above)
     blueprint_reference (Optional): (recursive schema, see blueprint_reference above)
     agent_card (Optional): {
         version: String (Optional, Required on create)
         description: String (Optional)
         skills (Optional, Required on create): [
              (Optional, Required on create){
                 id: String (Optional, Required on create)
                 name: String (Optional, Required on create)
                 description: String (Optional)
                 tags (Optional): [
                     String (Optional)
                 ]
                 examples (Optional): [
                     String (Optional)
                 ]
             }
         ]
     }
 }

Parameters:

agentName - The name of the agent to retrieve The name of the agent to retrieve.
patchAgentObjectRequest - The patchAgentObjectRequest parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

the response body along with Response<T>.

updateAgentFromCode

public AgentDetails updateAgentFromCode(String agentName, String codeZipSha256, CreateAgentVersionFromCodeContent content)

Update a code-based agent Updates a code-based agent by uploading new code and creating a new version. If the code and definition are unchanged (matched by x-ms-code-zip-sha256 header), returns the existing version. The request body is multipart/form-data with a JSON metadata part and a binary code part (part order is irrelevant). Maximum upload size is 250 MB.

Parameters:

agentName - The unique name that identifies the agent. Name can be used to retrieve/update/delete the agent.
  • Must start and end with alphanumeric characters,
  • Can contain hyphens in the middle
  • Must not exceed 63 characters.
codeZipSha256 - SHA-256 hex digest of the uploaded code zip. Used for change detection (dedup) and integrity verification.
content - The content multipart request content.

Returns:

the response.

uploadSessionFile

public SessionFileWriteResult uploadSessionFile(String agentName, String sessionId, String path, BinaryData content)

Upload a session file Uploads binary file content to the specified path in the session sandbox. The service stores the file relative to the session home directory and rejects payloads larger than 50 MB.

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The destination file path within the sandbox, relative to the session home directory.
content - The content parameter.

Returns:

response from uploading a file to a session sandbox.

uploadSessionFileWithResponse

public Response<BinaryData> uploadSessionFileWithResponse(String agentName, String agentSessionId, String path, String filePath, RequestOptions requestOptions)

Upload a session file Uploads binary file content to the specified path in the session sandbox. The service stores the file relative to the session home directory and rejects payloads larger than 50 MB.

Header Parameters

| ----------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Name                    | Type   | Required | Description                                                                                                                   |
| x-ms-user-isolation-key | String | No       | Opaque per-user isolation key used to scope endpoint-scoped data (responses, conversations, sessions) to a specific end user. |

You can add these to a request with RequestOptions#addHeader

Request Body Schema

BinaryData

Response Body Schema

{
     path: String (Required)
     bytes_written: long (Required)
 }

Parameters:

agentName - The name of the agent.
agentSessionId - The session ID.
path - The destination file path within the sandbox, relative to the session home directory.
filePath - The path to the local file whose contents will be uploaded.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

response from uploading a file to a session sandbox along with Response<T>.

uploadSessionFileWithResponse

public Response<BinaryData> uploadSessionFileWithResponse(String agentName, String sessionId, String path, BinaryData content, RequestOptions requestOptions)

Upload a session file Uploads binary file content to the specified path in the session sandbox. The service stores the file relative to the session home directory and rejects payloads larger than 50 MB.

Request Body Schema

BinaryData

Response Body Schema

{
     path: String (Required)
     bytes_written: long (Required)
 }

Parameters:

agentName - The name of the agent.
sessionId - The session ID.
path - The destination file path within the sandbox, relative to the session home directory.
content - The content parameter.
requestOptions - The options to configure the HTTP request before HTTP client sends it.

Returns:

response from uploading a file to a session sandbox along with Response<T>.

Applies to