AgentsOperations Class

Warning

DO NOT instantiate this class directly.

Instead, you should access the following operations through

AIProjectClient's

attribute.

Constructor

AgentsOperations(*args, **kwargs)

Methods

begin_create_optimization_job

Create an agent optimization job.
cancel_optimization_job

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.
create_session

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.
create_version

Create an agent version.

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

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.
create_version_from_manifest

Create an agent version from manifest.

Imports the provided manifest to create a new version for the specified agent.
delete

Delete an agent.

Deletes an agent. For hosted agents, if any version has active sessions, the request is rejected with HTTP 409 unless force is set to true. When force is true, all associated sessions are cascade-deleted along with the agent and its versions.
delete_optimization_job

Delete an agent optimization job.

Cancels active work, then deletes the job and its candidate artifacts.
delete_session

Delete a session.

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

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.
delete_version

Delete an agent version.

Deletes a specific version of an agent. For hosted agents, if the version has active sessions, the request is rejected with HTTP 409 unless force is set to true. When force is true, all sessions associated with this version are cascade-deleted.
disable

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.
download_code

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.
download_session_file

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.
enable

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.
estimate_optimization_job

Estimate an agent optimization job.

Estimates validation-set rows, per-stage model call volumes, and cost bands without submitting the job.
get

Get an agent.

Retrieves an agent definition by its unique name.
get_microsoft365_package

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.
get_microsoft365_publish_defaults

Get Microsoft 365 publish defaults.

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

Get a candidate for an agent optimization job.

Retrieves a single candidate. Mutation values are always included.
get_optimization_job

Get an agent optimization job.

Retrieves an optimization job by its identifier.
get_session

Get a session.

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

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.
get_version

Get an agent version.

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

List agents.

Returns a paged collection of agent resources.
list_optimization_candidates

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.
list_optimization_jobs

List agent optimization jobs.

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

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.
list_sessions

List sessions for an agent.

Returns a paged collection of sessions associated with the specified agent endpoint.
list_versions

List agent versions.

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

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.
publish_to_microsoft365

Publish an agent to Microsoft 365.

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

Stop a session.

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

Update an agent endpoint.

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

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.

begin_create_optimization_job

Create an agent optimization job.

begin_create_optimization_job(job: _models.AgentOptimizationJob, *, operation_id: str | None = None, content_type: str = 'application/json', **kwargs: Any) -> AgentOptimizationLROPoller

Parameters

Name Description
job
Required
AgentOptimizationJob or or IO[bytes]

The job to create. Required.

Keyword-Only Parameters

Name Description
operation_id
str

Client-generated unique ID for idempotent retries. When absent, the server creates the job unconditionally. Default value is None.

Default value: None

Returns

Type Description
AgentOptimizationLROPoller

A poller that returns AgentOptimizationJobResult and exposes the job ID in details.

Exceptions

Type Description
HttpResponseError

cancel_optimization_job

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.

cancel_optimization_job(job_id: str, **kwargs: Any) -> AgentOptimizationJob

Parameters

Name Description
job_id
Required
str

The ID of the job to cancel. Required.

Returns

Type Description
AgentOptimizationJob

AgentOptimizationJob. The AgentOptimizationJob is compatible with MutableMapping

Exceptions

Type Description
HttpResponseError

create_session

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.

create_session(agent_name: str, body: ~collections.abc.MutableMapping[str, ~typing.Any] | ~typing.IO[bytes] = , *, version_indicator: ~azure.ai.projects.models._models.VersionIndicator = , agent_session_id: str | None = None, **kwargs: ~typing.Any) -> AgentSessionResource


		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to create a session for. Required.


		

			




	
		
body

			
	
		

				 or 
				IO[bytes]
		

		

			
Is either a JSON type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
version_indicator

			
	
		

				VersionIndicator
		

		

			
Determines which agent version backs the session. Required.


		

			

					
Default value: 
			
	





	
		
agent_session_id

			
	
		

				str
		

		

			
Optional caller-provided session ID. If specified, it must be unique
within the agent endpoint. Auto-generated if omitted. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentSessionResource
						

					
			
					
AgentSessionResource. The AgentSessionResource is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	











	create_version





	
Create an agent version.


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



		
create_version(agent_name: str, *, definition: _models.AgentDefinition, content_type: str = 'application/json', metadata: dict[str, str] | None = None, description: str | None = None, blueprint_reference: _models.AgentBlueprintReference | None = None, draft: bool | None = None, **kwargs: Any) -> _models.AgentVersionDetails



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
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. Required.
    

    • 



		

			




	
		
body

			
	
		

				 or 
				IO[bytes]
		

		

			
Is either a JSON type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
definition

			
	
		

				AgentDefinition
		

		

			
The agent definition. This can be a workflow, hosted agent, or a simple
agent definition. Required.


		

			

					
Default value: 
			
	





	
		
metadata

			
	
		

				dict[str, str]
		

		

			
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. Default value is None.


		

			

					
Default value: None

			

			




	
		
description

			
	
		

				str
		

		

			
A human-readable description of the agent. Default value is None.


		

			

					
Default value: None

			

			




	
		
blueprint_reference

			
	
		

				AgentBlueprintReference
		

		

			
The blueprint reference for the agent. Default value is None.


		

			

					
Default value: None

			

			




	
		
draft

			
	
		

				bool
		

		

			
(Preview) Whether this agent version is a draft (candidate) rather than a
release. The service defaults to false if a value is not specified by the caller. Draft
versions are recorded but excluded from default 'latest' resolution and are not auto-promoted.
Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentVersionDetails
						

					
			
					
AgentVersionDetails. The AgentVersionDetails is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	create_version_from_code





	
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.



		
create_version_from_code(agent_name: str, *, definition: HostedAgentDefinition, code: IO[bytes], code_zip_sha256: str | None = None, description: str | None = None, metadata: dict[str, str] | None = None, **kwargs: Any) -> AgentVersionDetails



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
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. Required.
    

    • 



		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
definition

			
	
		

				HostedAgentDefinition
		

		

			
The hosted agent definition including code_configuration (runtime,
entry_point), cpu, memory, and protocol_versions. Required.


		

			




	
		
code

			
	
		

				IO[bytes]
		

		

			
The code zip file stream (max 250 MB). Required. The stream must
expose a name attribute (for example, a stream returned by
open) and that name must end with .zip.


		

			




	
		
code_zip_sha256

			
	
		

				str
		

		

			
SHA-256 hex digest of the uploaded code zip. Used for change
detection (dedup) and integrity verification. If not provided, it will be calculated
automatically from the code content. Default value is None.


		

			

					
Default value: None

			

			




	
		
description

			
	
		

				str
		

		

			
A human-readable description of the agent. Default value is None.


		

			

					
Default value: None

			

			




	
		
metadata

			
	
		

				dict[str, str]
		

		

			
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. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentVersionDetails
						

					
			
					
AgentVersionDetails. The AgentVersionDetails is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	create_version_from_manifest





	
Create an agent version from manifest.


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



		
create_version_from_manifest(agent_name: str, body: ~collections.abc.MutableMapping[str, ~typing.Any] | ~typing.IO[bytes] = , *, manifest_id: str = , parameter_values: dict[str, typing.Any] = , metadata: dict[str, str] | None = None, description: str | None = None, **kwargs: ~typing.Any) -> AgentVersionDetails


		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
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. Required.
    

    • 



		

			




	
		
body

			
	
		

				 or 
				IO[bytes]
		

		

			
Is either a JSON type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
manifest_id

			
	
		

				str
		

		

			
The manifest ID to import the agent version from. Required.


		

			

					
Default value: 
			
	





	
		
parameter_values

			
	
		

				dict[str, any]
		

		

			
The inputs to the manifest that will result in a fully materialized
Agent. Required.


		

			

					
Default value: 
			
	





	
		
metadata

			
	
		

				dict[str, str]
		

		

			
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. Default value is None.


		

			

					
Default value: None

			

			




	
		
description

			
	
		

				str
		

		

			
A human-readable description of the agent. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentVersionDetails
						

					
			
					
AgentVersionDetails. The AgentVersionDetails is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	











	delete





	
Delete an agent.


Deletes an agent. For hosted agents, if any version has active sessions, the request is
rejected with HTTP 409 unless force is set to true. When force is true, all associated
sessions are cascade-deleted along with the agent and its versions.



		
delete(agent_name: str, *, force: bool | None = None, **kwargs: Any) -> DeleteAgentResponse



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to delete. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
force

			
	
		

				bool
		

		

			
For Hosted Agents, if true, force-deletes the agent even if its versions
have active sessions, cascading deletion to all associated sessions. The service defaults to
false if a value is not specified by the caller. This value is not relevant for other Agent
types. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							DeleteAgentResponse
						

					
			
					
DeleteAgentResponse. The DeleteAgentResponse is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	delete_optimization_job





	
Delete an agent optimization job.


Cancels active work, then deletes the job and its candidate artifacts.



		
delete_optimization_job(job_id: str, **kwargs: Any) -> None



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
job_id

			

				Required
			

			
	
		

				str
		

		

			
The ID of the job to delete. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							None
						

					
			
					
None


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	delete_session





	
Delete a session.


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



		
delete_session(agent_name: str, session_id: str, **kwargs: Any) -> None



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session identifier. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							None
						

					
			
					
None


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	delete_session_file





	
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.



		
delete_session_file(agent_name: str, session_id: str, *, path: str, recursive: bool | None = None, **kwargs: Any) -> None



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session ID. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
path

			
	
		

				str
		

		

			
The file or directory path to delete, relative to the session home directory.
Required.


		

			




	
		
recursive

			
	
		

				bool
		

		

			
Whether to recursively delete directory contents. The service defaults to
false if a value is not specified by the caller. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							None
						

					
			
					
None


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	delete_version





	
Delete an agent version.


Deletes a specific version of an agent. For hosted agents, if the version has active sessions,
the request is rejected with HTTP 409 unless force is set to true. When force is true, all
sessions associated with this version are cascade-deleted.



		
delete_version(agent_name: str, agent_version: str, *, force: bool | None = None, **kwargs: Any) -> DeleteAgentVersionResponse



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to delete. Required.


		

			




	
		
agent_version

			

				Required
			

			
	
		

				str
		

		

			
The version of the agent to delete. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
force

			
	
		

				bool
		

		

			
For Hosted Agents, if true, force-deletes the version even if it has active
sessions, cascading deletion to all associated sessions. The service defaults to false if a
value is not specified by the caller. This value is not relevant for other Agent types. Default
value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							DeleteAgentVersionResponse
						

					
			
					
DeleteAgentVersionResponse. The DeleteAgentVersionResponse is compatible with
MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	disable





	
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.



		
disable(agent_name: str, **kwargs: Any) -> None



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to disable. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							None
						

					
			
					
None


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	download_code





	
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.



		
download_code(agent_name: str, *, agent_version: str | None = None, **kwargs: Any) -> Iterator[bytes]



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_version

			
	
		

				str
		

		

			
The version of the agent whose code zip should be downloaded.
If omitted, the latest version's code zip is returned. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							Iterator[bytes]
						

					
			
					
Iterator[bytes]


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	download_session_file





	
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.



		
download_session_file(agent_name: str, session_id: str, *, path: str, **kwargs: Any) -> Iterator[bytes]



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session ID. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
path

			
	
		

				str
		

		

			
The file path to download from the sandbox, relative to the session home
directory. Required.


		

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							Iterator[bytes]
						

					
			
					
Iterator[bytes]


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	enable





	
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.



		
enable(agent_name: str, **kwargs: Any) -> None



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to enable. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							None
						

					
			
					
None


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	estimate_optimization_job





	
Estimate an agent optimization job.


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



		
estimate_optimization_job(inputs: AgentOptimizationEstimateInputs | MutableMapping[str, Any] | IO[bytes], **kwargs: Any) -> AgentOptimizationEstimateResult



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
inputs

			

				Required
			

			
	
		

				AgentOptimizationEstimateInputs or 
				 or 
				IO[bytes]
		

		

			
The inputs to estimate against. Is one of the following types:
AgentOptimizationEstimateInputs, JSON, IO[bytes] Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentOptimizationEstimateResult
						

					
			
					
AgentOptimizationEstimateResult. The AgentOptimizationEstimateResult is compatible
with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get





	
Get an agent.


Retrieves an agent definition by its unique name.



		
get(agent_name: str, **kwargs: Any) -> AgentDetails



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to retrieve. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentDetails
						

					
			
					
AgentDetails. The AgentDetails is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get_microsoft365_package





	
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.



		
get_microsoft365_package(agent_name: str, body: ~collections.abc.MutableMapping[str, ~typing.Any] | ~typing.IO[bytes] = , *, publish_scope: str | ~azure.ai.projects.models._enums.Microsoft365PublishScope = , agent_display_name: str | None = None, bot_service_arm_id: str | None = None, publish_as_autopilot: bool | None = None, access_boundaries: list[typing.Union[str, azure.ai.projects.models._enums.ActivityProtocolAccessBoundary]] | None = None, optional_permission_scopes: list[azure.ai.projects.models._models.Microsoft365PermissionScopes] | None = None, can_respond_without_mention: bool | None = None, app_version: str | None = None, short_description: str | None = None, full_description: str | None = None, developer_name: str | None = None, developer_website_url: str | None = None, privacy_url: str | None = None, terms_of_use_url: str | None = None, color_icon_base64: str | None = None, outline_icon_base64: str | None = None, **kwargs: ~typing.Any) -> Iterator[bytes]


		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to generate the app package for. Required.


		

			




	
		
body

			
	
		

				 or 
				IO[bytes]
		

		

			
Is either a JSON type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
publish_scope

			
	
		

				str or 
				Microsoft365PublishScope
		

		

			
Publish scope for the Teams app. Known values are: "Personal",
"Shared", and "Tenant". Required.


		

			

					
Default value: 
			
	





	
		
agent_display_name

			
	
		

				str
		

		

			
Display name used as the published Teams app name. When omitted,
the agent name from the route is
used. Default value is None.


		

			

					
Default value: None

			

			




	
		
bot_service_arm_id

			
	
		

				str
		

		

			
ARM resource id of the Azure Bot Service that fronts this agent in
Microsoft Teams. Required for
workspaces on the default bot-based Teams backend; optional for workspaces on the API-based
backend.
Must not be supplied when publishAsAutopilot is true. Default value is None.


		

			

					
Default value: None

			

			




	
		
publish_as_autopilot

			
	
		

				bool
		

		

			
When true, the agent is published as an autopilot (digital
worker) agent: the bot id is taken from
the agent's blueprint identity and the generated Teams manifest is marked as a digital worker.
Default value is None.


		

			

					
Default value: None

			

			




	
		
access_boundaries

			
	
		

				list[str or 
				ActivityProtocolAccessBoundary]
		

		

			
Activity-protocol access boundaries to apply to the agent when
publishing as an autopilot agent.
An empty list clears the existing boundaries. When omitted, the existing boundaries are left
unchanged. Default value is None.


		

			

					
Default value: None

			

			




	
		
optional_permission_scopes

			
	
		

				list[Microsoft365PermissionScopes]
		

		

			
Exact selection of delegated permission scopes to grant to
the autopilot blueprint. May only be
supplied when publishAsAutopilot is true. When omitted or empty, the platform's default
permission set is used. Mandatory platform permissions are always granted and are not affected
by
this value. Default value is None.


		

			

					
Default value: None

			

			




	
		
can_respond_without_mention

			
	
		

				bool
		

		

			
Controls how the published agent responds to Teams
messages: when true it responds to all messages
on its surfaces, when false only when it is at-mentioned. When omitted, the agent's existing
Teams
message-notification setting is left unchanged. Default value is None.


		

			

					
Default value: None

			

			




	
		
app_version

			
	
		

				str
		

		

			
App version (for example 1.2.3) written into the Teams manifest. May
contain only digits and
periods, must not start with 0, and must end with a digit. When omitted, a platform
default is
used. Default value is None.


		

			

					
Default value: None

			

			




	
		
short_description

			
	
		

				str
		

		

			
Short, one-line description shown in the Teams app listing. Default
value is None.


		

			

					
Default value: None

			

			




	
		
full_description

			
	
		

				str
		

		

			
Full description shown on the Teams app details page. Default value
is None.


		

			

					
Default value: None

			

			




	
		
developer_name

			
	
		

				str
		

		

			
Display name of the developer / publisher shown in the Teams app
listing. Default value is None.


		

			

					
Default value: None

			

			




	
		
developer_website_url

			
	
		

				str
		

		

			
Developer / publisher website URL shown in the Teams app
listing. Must be an https URL. Default value is None.


		

			

					
Default value: None

			

			




	
		
privacy_url

			
	
		

				str
		

		

			
Privacy policy URL shown in the Teams app listing. Must be an http or
https URL. Default value is None.


		

			

					
Default value: None

			

			




	
		
terms_of_use_url

			
	
		

				str
		

		

			
Terms-of-use URL shown in the Teams app listing. Default value is
None.


		

			

					
Default value: None

			

			




	
		
color_icon_base64

			
	
		

				str
		

		

			
Optional base64-encoded PNG used as the color (full-bleed) icon in
the Teams app package. Must be a
192x192 PNG (perfect square, no border or rounded corners). Max 1 MB after decode. When
omitted, the
platform default color icon is used. Default value is None.


		

			

					
Default value: None

			

			




	
		
outline_icon_base64

			
	
		

				str
		

		

			
Optional base64-encoded PNG used as the outline icon in the Teams
app package. Must be a 32x32 PNG.
Max 1 MB after decode. When omitted, the platform default outline icon is used. Default value
is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							Iterator[bytes]
						

					
			
					
Iterator[bytes]


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	











	get_microsoft365_publish_defaults





	
Get Microsoft 365 publish defaults.


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



		
get_microsoft365_publish_defaults(agent_name: str, *, publish_as_digital_worker: bool | None = None, **kwargs: Any) -> Microsoft365PublishDefaults



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to get publish defaults for. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
publish_as_digital_worker

			
	
		

				bool
		

		

			
When true, returns defaults for publishing the agent as an
autopilot (digital worker) agent. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							Microsoft365PublishDefaults
						

					
			
					
Microsoft365PublishDefaults. The Microsoft365PublishDefaults is compatible with
MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get_optimization_candidate





	
Get a candidate for an agent optimization job.


Retrieves a single candidate. Mutation values are always included.



		
get_optimization_candidate(job_id: str, candidate_id: str, **kwargs: Any) -> AgentOptimizationCandidate



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
job_id

			

				Required
			

			
	
		

				str
		

		

			
The ID of the parent optimization job. Required.


		

			




	
		
candidate_id

			

				Required
			

			
	
		

				str
		

		

			
The candidate identifier. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentOptimizationCandidate
						

					
			
					
AgentOptimizationCandidate. The AgentOptimizationCandidate is compatible with
MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get_optimization_job





	
Get an agent optimization job.


Retrieves an optimization job by its identifier.



		
get_optimization_job(job_id: str, **kwargs: Any) -> AgentOptimizationJob



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
job_id

			

				Required
			

			
	
		

				str
		

		

			
The ID of the job. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentOptimizationJob
						

					
			
					
AgentOptimizationJob. The AgentOptimizationJob is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get_session





	
Get a session.


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



		
get_session(agent_name: str, session_id: str, **kwargs: Any) -> AgentSessionResource



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session identifier. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentSessionResource
						

					
			
					
AgentSessionResource. The AgentSessionResource is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get_session_log_stream





	
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.



		
get_session_log_stream(agent_name: str, agent_version: str, session_id: str, **kwargs: Any) -> SessionLogEvent



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the hosted agent. Required.


		

			




	
		
agent_version

			

				Required
			

			
	
		

				str
		

		

			
The version of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session ID (maps to an ADC sandbox). Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							SessionLogEvent
						

					
			
					
SessionLogEvent. The SessionLogEvent is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	get_version





	
Get an agent version.


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



		
get_version(agent_name: str, agent_version: str, **kwargs: Any) -> AgentVersionDetails



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to retrieve. Required.


		

			




	
		
agent_version

			

				Required
			

			
	
		

				str
		

		

			
The version of the agent to retrieve. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentVersionDetails
						

					
			
					
AgentVersionDetails. The AgentVersionDetails is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	list





	
List agents.


Returns a paged collection of agent resources.



		
list(*, kind: str | AgentKind | None = None, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[AgentDetails]




		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
kind

			
	
		

				str or 
				AgentKind
		

		

			
Filter agents by kind. If not provided, all agents are returned. Known values
are: "prompt", "hosted", "workflow", "external", and "voice". Default value is None.


		

			

					
Default value: None

			

			




	
		
limit

			
	
		

				int
		

		

			
A limit on the number of objects to be returned. Limit can range between 1 and
100, and the
default is 20. Default value is None.


		

			

					
Default value: None

			

			




	
		
order

			
	
		

				str or 
				PageOrder
		

		

			
Sort order by the created_at timestamp of the objects. asc for
ascending order anddesc
for descending order. Known values are: "asc" and "desc". Default value is None.


		

			

					
Default value: None

			

			




	
		
before

			
	
		

				str
		

		

			
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.
Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							ItemPaged[AgentDetails]
						

					
			
					
An iterator like instance of AgentDetails


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	list_optimization_candidates





	
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.



		
list_optimization_candidates(job_id: str, *, expand: list[Union[str, azure.ai.projects.models._enums.AgentOptimizationCandidateExpand]] | None = None, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[AgentOptimizationCandidate]



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
job_id

			

				Required
			

			
	
		

				str
		

		

			
The ID of the parent optimization job. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
expand

			
	
		

				list[str or 
				AgentOptimizationCandidateExpand]
		

		

			
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. Default value is None.


		

			

					
Default value: None

			

			




	
		
limit

			
	
		

				int
		

		

			
A limit on the number of objects to be returned. Limit can range between 1 and
100, and the
default is 20. Default value is None.


		

			

					
Default value: None

			

			




	
		
order

			
	
		

				str or 
				PageOrder
		

		

			
Sort order by the candidate started_at timestamp. Known values are: "asc"
and "desc". Default value is None.


		

			

					
Default value: None

			

			




	
		
before

			
	
		

				str
		

		

			
Candidate-ID cursor identifying the first item from the following page.
Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							ItemPaged[AgentOptimizationCandidate]
						

					
			
					
An iterator like instance of AgentOptimizationCandidate


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	list_optimization_jobs





	
List agent optimization jobs.


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



		
list_optimization_jobs(*, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, status: str | JobStatus | None = None, agent_name: str | None = None, **kwargs: Any) -> ItemPaged[AgentOptimizationJob]




		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
limit

			
	
		

				int
		

		

			
A limit on the number of objects to be returned. Limit can range between 1 and
100, and the
default is 20. Default value is None.


		

			

					
Default value: None

			

			




	
		
order

			
	
		

				str or 
				PageOrder
		

		

			
Sort order by the created_at timestamp of the objects. asc for
ascending order anddesc
for descending order. Known values are: "asc" and "desc". Default value is None.


		

			

					
Default value: None

			

			




	
		
before

			
	
		

				str
		

		

			
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.
Default value is None.


		

			

					
Default value: None

			

			




	
		
status

			
	
		

				str or 
				JobStatus
		

		

			
Filter to jobs in this lifecycle state. Known values are: "queued",
"in_progress", "succeeded", "failed", and "cancelled". Default value is None.


		

			

					
Default value: None

			

			




	
		
agent_name

			
	
		

				str
		

		

			
Filter to jobs targeting this agent name. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							ItemPaged[AgentOptimizationJob]
						

					
			
					
An iterator like instance of AgentOptimizationJob


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	list_session_files





	
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.



		
list_session_files(agent_name: str, session_id: str, *, path: str | None = None, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[SessionDirectoryEntry]



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session ID. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
path

			
	
		

				str
		

		

			
The directory path to list, relative to the session home directory. Defaults to
the home directory if not provided. Default value is None.


		

			

					
Default value: None

			

			




	
		
limit

			
	
		

				int
		

		

			
A limit on the number of objects to be returned. Limit can range between 1 and
100, and the
default is 20. Default value is None.


		

			

					
Default value: None

			

			




	
		
order

			
	
		

				str or 
				PageOrder
		

		

			
Sort order by the created_at timestamp of the objects. asc for
ascending order anddesc
for descending order. Known values are: "asc" and "desc". Default value is None.


		

			

					
Default value: None

			

			




	
		
before

			
	
		

				str
		

		

			
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.
Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							ItemPaged[SessionDirectoryEntry]
						

					
			
					
An iterator like instance of SessionDirectoryEntry


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	list_sessions





	
List sessions for an agent.


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



		
list_sessions(agent_name: str, *, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, **kwargs: Any) -> ItemPaged[AgentSessionResource]



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
limit

			
	
		

				int
		

		

			
A limit on the number of objects to be returned. Limit can range between 1 and
100, and the
default is 20. Default value is None.


		

			

					
Default value: None

			

			




	
		
order

			
	
		

				str or 
				PageOrder
		

		

			
Sort order by the created_at timestamp of the objects. asc for
ascending order anddesc
for descending order. Known values are: "asc" and "desc". Default value is None.


		

			

					
Default value: None

			

			




	
		
before

			
	
		

				str
		

		

			
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.
Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							ItemPaged[AgentSessionResource]
						

					
			
					
An iterator like instance of AgentSessionResource


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	list_versions





	
List agent versions.


Returns a paged collection of versions for the specified agent.



		
list_versions(agent_name: str, *, limit: int | None = None, order: str | PageOrder | None = None, before: str | None = None, include_drafts: bool | None = None, **kwargs: Any) -> ItemPaged[AgentVersionDetails]



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to retrieve versions for. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
limit

			
	
		

				int
		

		

			
A limit on the number of objects to be returned. Limit can range between 1 and
100, and the
default is 20. Default value is None.


		

			

					
Default value: None

			

			




	
		
order

			
	
		

				str or 
				PageOrder
		

		

			
Sort order by the created_at timestamp of the objects. asc for
ascending order anddesc
for descending order. Known values are: "asc" and "desc". Default value is None.


		

			

					
Default value: None

			

			




	
		
before

			
	
		

				str
		

		

			
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.
Default value is None.


		

			

					
Default value: None

			

			




	
		
include_drafts

			
	
		

				bool
		

		

			
(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). Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							ItemPaged[AgentVersionDetails]
						

					
			
					
An iterator like instance of AgentVersionDetails


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	promote_optimization_candidate





	
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.



		
promote_optimization_candidate(job_id: str, candidate_id: str, **kwargs: Any) -> AgentOptimizationCandidate



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
job_id

			

				Required
			

			
	
		

				str
		

		

			
The ID of the parent optimization job. Required.


		

			




	
		
candidate_id

			

				Required
			

			
	
		

				str
		

		

			
The candidate identifier. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentOptimizationCandidate
						

					
			
					
AgentOptimizationCandidate. The AgentOptimizationCandidate is compatible with
MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	publish_to_microsoft365





	
Publish an agent to Microsoft 365.


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



		
publish_to_microsoft365(agent_name: str, body: ~collections.abc.MutableMapping[str, ~typing.Any] | ~typing.IO[bytes] = , *, publish_scope: str | ~azure.ai.projects.models._enums.Microsoft365PublishScope = , agent_display_name: str | None = None, bot_service_arm_id: str | None = None, publish_as_autopilot: bool | None = None, access_boundaries: list[typing.Union[str, azure.ai.projects.models._enums.ActivityProtocolAccessBoundary]] | None = None, optional_permission_scopes: list[azure.ai.projects.models._models.Microsoft365PermissionScopes] | None = None, can_respond_without_mention: bool | None = None, app_version: str | None = None, short_description: str | None = None, full_description: str | None = None, developer_name: str | None = None, developer_website_url: str | None = None, privacy_url: str | None = None, terms_of_use_url: str | None = None, color_icon_base64: str | None = None, outline_icon_base64: str | None = None, **kwargs: ~typing.Any) -> Microsoft365PublishResult


		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to publish. Required.


		

			




	
		
body

			
	
		

				 or 
				IO[bytes]
		

		

			
Is either a JSON type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
publish_scope

			
	
		

				str or 
				Microsoft365PublishScope
		

		

			
Publish scope for the Teams app. Known values are: "Personal",
"Shared", and "Tenant". Required.


		

			

					
Default value: 
			
	





	
		
agent_display_name

			
	
		

				str
		

		

			
Display name used as the published Teams app name. When omitted,
the agent name from the route is
used. Default value is None.


		

			

					
Default value: None

			

			




	
		
bot_service_arm_id

			
	
		

				str
		

		

			
ARM resource id of the Azure Bot Service that fronts this agent in
Microsoft Teams. Required for
workspaces on the default bot-based Teams backend; optional for workspaces on the API-based
backend.
Must not be supplied when publishAsAutopilot is true. Default value is None.


		

			

					
Default value: None

			

			




	
		
publish_as_autopilot

			
	
		

				bool
		

		

			
When true, the agent is published as an autopilot (digital
worker) agent: the bot id is taken from
the agent's blueprint identity and the generated Teams manifest is marked as a digital worker.
Default value is None.


		

			

					
Default value: None

			

			




	
		
access_boundaries

			
	
		

				list[str or 
				ActivityProtocolAccessBoundary]
		

		

			
Activity-protocol access boundaries to apply to the agent when
publishing as an autopilot agent.
An empty list clears the existing boundaries. When omitted, the existing boundaries are left
unchanged. Default value is None.


		

			

					
Default value: None

			

			




	
		
optional_permission_scopes

			
	
		

				list[Microsoft365PermissionScopes]
		

		

			
Exact selection of delegated permission scopes to grant to
the autopilot blueprint. May only be
supplied when publishAsAutopilot is true. When omitted or empty, the platform's default
permission set is used. Mandatory platform permissions are always granted and are not affected
by
this value. Default value is None.


		

			

					
Default value: None

			

			




	
		
can_respond_without_mention

			
	
		

				bool
		

		

			
Controls how the published agent responds to Teams
messages: when true it responds to all messages
on its surfaces, when false only when it is at-mentioned. When omitted, the agent's existing
Teams
message-notification setting is left unchanged. Default value is None.


		

			

					
Default value: None

			

			




	
		
app_version

			
	
		

				str
		

		

			
App version (for example 1.2.3) written into the Teams manifest. May
contain only digits and
periods, must not start with 0, and must end with a digit. When omitted, a platform
default is
used. Default value is None.


		

			

					
Default value: None

			

			




	
		
short_description

			
	
		

				str
		

		

			
Short, one-line description shown in the Teams app listing. Default
value is None.


		

			

					
Default value: None

			

			




	
		
full_description

			
	
		

				str
		

		

			
Full description shown on the Teams app details page. Default value
is None.


		

			

					
Default value: None

			

			




	
		
developer_name

			
	
		

				str
		

		

			
Display name of the developer / publisher shown in the Teams app
listing. Default value is None.


		

			

					
Default value: None

			

			




	
		
developer_website_url

			
	
		

				str
		

		

			
Developer / publisher website URL shown in the Teams app
listing. Must be an https URL. Default value is None.


		

			

					
Default value: None

			

			




	
		
privacy_url

			
	
		

				str
		

		

			
Privacy policy URL shown in the Teams app listing. Must be an http or
https URL. Default value is None.


		

			

					
Default value: None

			

			




	
		
terms_of_use_url

			
	
		

				str
		

		

			
Terms-of-use URL shown in the Teams app listing. Default value is
None.


		

			

					
Default value: None

			

			




	
		
color_icon_base64

			
	
		

				str
		

		

			
Optional base64-encoded PNG used as the color (full-bleed) icon in
the Teams app package. Must be a
192x192 PNG (perfect square, no border or rounded corners). Max 1 MB after decode. When
omitted, the
platform default color icon is used. Default value is None.


		

			

					
Default value: None

			

			




	
		
outline_icon_base64

			
	
		

				str
		

		

			
Optional base64-encoded PNG used as the outline icon in the Teams
app package. Must be a 32x32 PNG.
Max 1 MB after decode. When omitted, the platform default outline icon is used. Default value
is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							Microsoft365PublishResult
						

					
			
					
Microsoft365PublishResult. The Microsoft365PublishResult is compatible with
MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	











	stop_session





	
Stop a session.


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



		
stop_session(agent_name: str, session_id: str, **kwargs: Any) -> None



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session identifier. Required.


		

			


			
		




Returns



	
		

			Type
			Description
		

	
	
		

			
						

							None
						

					
			
					
None


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	













	update_details





	
Update an agent endpoint.


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



		
update_details(agent_name: str, body: ~collections.abc.MutableMapping[str, ~typing.Any] | ~typing.IO[bytes] = , *, agent_endpoint: ~azure.ai.projects.models._models.AgentEndpointConfig | None = None, agent_card: ~azure.ai.projects.models._models.AgentCard | None = None, **kwargs: ~typing.Any) -> AgentDetails


		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent to retrieve. Required.


		

			




	
		
body

			
	
		

				 or 
				IO[bytes]
		

		

			
Is either a JSON type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_endpoint

			
	
		

				AgentEndpointConfig
		

		

			
The endpoint configuration for the agent. Default value is None.


		

			

					
Default value: None

			

			




	
		
agent_card

			
	
		

				AgentCard
		

		

			
Optional agent card for the agent. Default value is None.


		

			

					
Default value: None

			

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							AgentDetails
						

					
			
					
AgentDetails. The AgentDetails is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError
						

						
				
					
				
			

	











	upload_session_file





	
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.



		
upload_session_file(agent_name: str, session_id: str, content: bytes | IO[bytes], *, path: str, **kwargs: Any) -> SessionFileWriteResult



		
Parameters

		

			
				

					Name
					Description
				

			
			


	
		
agent_name

			

				Required
			

			
	
		

				str
		

		

			
The name of the agent. Required.


		

			




	
		
session_id

			

				Required
			

			
	
		

				str
		

		

			
The session ID. Required.


		

			




	
		
content

			

				Required
			

			
	
		

				bytes or 
				IO[bytes]
		

		

			
Is either a bytes type or a IO[bytes] type. Required.


		

			


			
		


		
Keyword-Only Parameters

		

			
				

					Name
					Description
				

			
			


	
		
path

			
	
		

				str
		

		

			
The destination file path within the sandbox, relative to the session home
directory. Required.


		

			


			
		



Returns



	
		

			Type
			Description
		

	
	
		

			
						

							SessionFileWriteResult
						

					
			
					
SessionFileWriteResult. The SessionFileWriteResult is compatible with MutableMapping


					
		

	




Exceptions



	
		

			Type
			Description
		

	
	
			

				
						

							HttpResponseError