agents

Creates, updates, deletes, gets or lists an agents resource.

Overview

Name	agents
Type	Resource
Id	azure.ai_projects.agents

Fields

The following fields are returned by SELECT queries:

get_session_log_stream

Name	Datatype	Description
data	string	The event payload as plain text. Currently JSON-formatted but the schema is not contractual and may change. Required.
event	string	The SSE event type. Currently log, but additional event types may be added in the future. Clients should ignore unrecognized event types. Required. "log" (log)

list_session_files

Name	Datatype	Description
name	string	The name of the file or directory. Required.
is_directory	boolean	Whether this entry is a directory. Required.
modified_time	string (date-time)	The Unix timestamp (in seconds) when the file was last modified. Required.
size	integer	The size in bytes (0 for directories). Required.

get_version

Name	Datatype	Description
id	string	The unique identifier of the agent version. Required.
name	string	The name of the agent. Name can be used to retrieve/update/delete the agent. Required.
agent_guid	string	The unique GUID identifier of the agent.
blueprint	object	The blueprint for the agent.
blueprint_reference	object	The blueprint for the agent.
created_at	string (date-time)	The Unix timestamp (seconds) when the agent was created. Required.
definition	object	Required.
description	string	A human-readable description of the agent.
draft	boolean	Whether this agent version is a draft (candidate) rather than a release. Draft versions are recorded but excluded from default 'latest' resolution and are not auto-promoted. Defaults to false.
instance_identity	object	The instance identity of the agent.
metadata	object	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. Required.
object	string	The object type, which is always 'agent.version'. Required. AGENT_VERSION.
status	string	The provisioning status of the agent version. Defaults to 'active' for non-hosted agents. For hosted agents, reflects infrastructure readiness. Known values are: "creating", "active", "failed", "deleting", and "deleted". (creating, active, failed, deleting, deleted)
version	string	The version identifier of the agent. Agents are immutable and every update creates a new version while keeping the name same. Required.

get_session

Name	Datatype	Description
agent_session_id	string	The session identifier. Required.
created_at	string (date-time)	The Unix timestamp (in seconds) when the session was created. Required.
expires_at	string (date-time)	The Unix timestamp (in seconds) when the session expires (rolling, 30 days from last activity). Required.
last_accessed_at	string (date-time)	The Unix timestamp (in seconds) when the session was last accessed. Required.
status	string	The current status of the session. Required. Known values are: "creating", "active", "idle", "updating", "failed", "deleting", "deleted", and "expired". (creating, active, idle, updating, failed, deleting, deleted, expired)
version_indicator	object	The version indicator determining which agent version backs this session. Required.

get

Name	Datatype	Description
id	string	The unique identifier of the agent. Required.
name	string	The name of the agent. Required.
agent_card	object	:vartype agent_card: ~azure.ai.projects.models.AgentCard
agent_endpoint	object	The endpoint configuration for the agent.
blueprint	object	The blueprint for the agent.
blueprint_reference	object	The blueprint for the agent.
instance_identity	object	The instance identity of the agent.
object	string	The object type, which is always 'agent'. Required. AGENT.
state	string	The operational state of the agent. Controls whether the agent endpoint accepts or rejects requests. Required. Known values are: "enabled" and "disabled". (enabled, disabled)
versions	object	The latest version of the agent. Required.

list

Name	Datatype	Description
id	string	The unique identifier of the agent. Required.
name	string	The name of the agent. Required.
agent_card	object	:vartype agent_card: ~azure.ai.projects.models.AgentCard
agent_endpoint	object	The endpoint configuration for the agent.
blueprint	object	The blueprint for the agent.
blueprint_reference	object	The blueprint for the agent.
instance_identity	object	The instance identity of the agent.
object	string	The object type, which is always 'agent'. Required. AGENT.
state	string	The operational state of the agent. Controls whether the agent endpoint accepts or rejects requests. Required. Known values are: "enabled" and "disabled". (enabled, disabled)
versions	object	The latest version of the agent. Required.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_session_log_stream	select	agent_name, agent_version, session_id, endpoint		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: .. code-block:: 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.
list_session_files	select	agent_name, agent_session_id, endpoint	path, limit, order, after, 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.
get_version	select	agent_name, agent_version, endpoint		Get an agent version. Retrieves the specified version of an agent by its agent name and version identifier.
get_session	select	agent_name, session_id, endpoint		Get a session. Retrieves the details of a hosted agent session by agent name and session identifier.
get	select	agent_name, endpoint		Get an agent. Retrieves an agent definition by its unique name.
list	select	endpoint	kind, limit, order, after, before	List agents. Returns a paged collection of agent resources.
delete	delete	agent_name, endpoint	force	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.
update_details	exec	agent_name, endpoint		Update an agent endpoint. Applies a merge-patch update to the specified agent endpoint configuration.
list_versions	exec	agent_name, endpoint	limit, order, after, before, include_drafts	List agent versions. Returns a paged collection of versions for the specified agent.
create_version	exec	agent_name, endpoint		Create an agent version. Creates a new version for the specified agent and returns the created version resource.
list_sessions	exec	agent_name, endpoint	limit, order, after, before	List sessions for an agent. Returns a paged collection of sessions associated with the specified agent endpoint.
create_session	exec	agent_name, endpoint		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.
delete_session_file	exec	agent_name, agent_session_id, path, endpoint	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.
delete_version	exec	agent_name, agent_version, endpoint	force	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_session	exec	agent_name, session_id, endpoint		Delete a session. Deletes a session synchronously. Returns 204 No Content when the session is deleted or does not exist.
create_version_from_manifest	exec	agent_name, endpoint		Create an agent version from manifest. Imports the provided manifest to create a new version for the specified agent.
download_code	exec	agent_name, endpoint	agent_version	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.
enable	exec	agent_name, endpoint		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.
disable	exec	agent_name, endpoint		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.
stop_session	exec	agent_name, session_id, endpoint		Stop a session. Terminates the specified hosted agent session and returns 204 No Content when the request succeeds.
upload_session_file	exec	agent_name, agent_session_id, path, endpoint		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.
download_session_file	exec	agent_name, agent_session_id, path, endpoint		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

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
agent_name	string	The name of the agent. Required.
agent_session_id	string	The session ID. Required.
agent_version	string	The version of the agent to delete. Required.
endpoint	string	The service endpoint host (no scheme), e.g. myaccount.table.cosmos.azure.com:443 - value of the client endpoint parameter. (default: )
path	string	The file path to download from the sandbox, relative to the session home directory. Required.
session_id	string	The session identifier. Required.
after	string
agent_version	string	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.
before	string	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.
force	boolean	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.
include_drafts	boolean	(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.
kind	string	Filter agents by kind. If not provided, all agents are returned. Known values are: "prompt", "hosted", "workflow", and "external". Default value is None.
limit	integer	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.
order	string	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.
path	string	The directory path to list, relative to the session home directory. Defaults to the home directory if not provided. Default value is None.
recursive	boolean	Whether to recursively delete directory contents. The service defaults to false if a value is not specified by the caller. Default value is None.

SELECT examples

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: .. code-block:: 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.

SELECT
data,
event
FROM azure.ai_projects.agents
WHERE agent_name = '{{ agent_name }}' -- required
AND agent_version = '{{ agent_version }}' -- required
AND session_id = '{{ session_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

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.

SELECT
name,
is_directory,
modified_time,
size
FROM azure.ai_projects.agents
WHERE agent_name = '{{ agent_name }}' -- required
AND agent_session_id = '{{ agent_session_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
AND path = '{{ path }}'
AND limit = '{{ limit }}'
AND order = '{{ order }}'
AND after = '{{ after }}'
AND before = '{{ before }}'
;

get_version

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

SELECT
id,
name,
agent_guid,
blueprint,
blueprint_reference,
created_at,
definition,
description,
draft,
instance_identity,
metadata,
object,
status,
version
FROM azure.ai_projects.agents
WHERE agent_name = '{{ agent_name }}' -- required
AND agent_version = '{{ agent_version }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

get_session

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

SELECT
agent_session_id,
created_at,
expires_at,
last_accessed_at,
status,
version_indicator
FROM azure.ai_projects.agents
WHERE agent_name = '{{ agent_name }}' -- required
AND session_id = '{{ session_id }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

get

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

SELECT
id,
name,
agent_card,
agent_endpoint,
blueprint,
blueprint_reference,
instance_identity,
object,
state,
versions
FROM azure.ai_projects.agents
WHERE agent_name = '{{ agent_name }}' -- required
AND endpoint = '{{ endpoint }}' -- required
;

list

List agents. Returns a paged collection of agent resources.

SELECT
id,
name,
agent_card,
agent_endpoint,
blueprint,
blueprint_reference,
instance_identity,
object,
state,
versions
FROM azure.ai_projects.agents
WHERE endpoint = '{{ endpoint }}' -- required
AND kind = '{{ kind }}'
AND limit = '{{ limit }}'
AND order = '{{ order }}'
AND after = '{{ after }}'
AND before = '{{ before }}'
;

DELETE examples

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 FROM azure.ai_projects.agents
WHERE agent_name = '{{ agent_name }}' --required
AND endpoint = '{{ endpoint }}' --required
AND force = '{{ force }}'
;

Lifecycle Methods

update_details

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

EXEC azure.ai_projects.agents.update_details 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

list_versions

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

EXEC azure.ai_projects.agents.list_versions 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@limit='{{ limit }}', 
@order='{{ order }}', 
@after='{{ after }}', 
@before='{{ before }}', 
@include_drafts={{ include_drafts }}
;

create_version

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

EXEC azure.ai_projects.agents.create_version 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

list_sessions

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

EXEC azure.ai_projects.agents.list_sessions 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@limit='{{ limit }}', 
@order='{{ order }}', 
@after='{{ after }}', 
@before='{{ before }}'
;

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.

EXEC azure.ai_projects.agents.create_session 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

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.

EXEC azure.ai_projects.agents.delete_session_file 
@agent_name='{{ agent_name }}' --required, 
@agent_session_id='{{ agent_session_id }}' --required, 
@path='{{ path }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@recursive={{ recursive }}
;

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.

EXEC azure.ai_projects.agents.delete_version 
@agent_name='{{ agent_name }}' --required, 
@agent_version='{{ agent_version }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@force={{ force }}
;

delete_session

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

EXEC azure.ai_projects.agents.delete_session 
@agent_name='{{ agent_name }}' --required, 
@session_id='{{ session_id }}' --required, 
@endpoint='{{ endpoint }}' --required
;

create_version_from_manifest

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

EXEC azure.ai_projects.agents.create_version_from_manifest 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

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.

EXEC azure.ai_projects.agents.download_code 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required, 
@agent_version='{{ agent_version }}'
;

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.

EXEC azure.ai_projects.agents.enable 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

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.

EXEC azure.ai_projects.agents.disable 
@agent_name='{{ agent_name }}' --required, 
@endpoint='{{ endpoint }}' --required
;

stop_session

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

EXEC azure.ai_projects.agents.stop_session 
@agent_name='{{ agent_name }}' --required, 
@session_id='{{ session_id }}' --required, 
@endpoint='{{ endpoint }}' --required
;

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.

EXEC azure.ai_projects.agents.upload_session_file 
@agent_name='{{ agent_name }}' --required, 
@agent_session_id='{{ agent_session_id }}' --required, 
@path='{{ path }}' --required, 
@endpoint='{{ endpoint }}' --required
;

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.

EXEC azure.ai_projects.agents.download_session_file 
@agent_name='{{ agent_name }}' --required, 
@agent_session_id='{{ agent_session_id }}' --required, 
@path='{{ path }}' --required, 
@endpoint='{{ endpoint }}' --required
;