BetaAgentsOperations Class

Cancels an agent optimization job.

Request cancellation. Idempotent on terminal states.

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

Parameters

Returns

Exceptions

Creates an agent optimization job.

Create an optimization job. Returns 201 with the queued job. Honours Operation-Id for idempotent retry.

create_optimization_job(inputs: OptimizationJobInputs | MutableMapping[str, Any] | IO[bytes], *, operation_id: str | None = None, **kwargs: Any) -> OptimizationJob

Parameters

Keyword-Only Parameters

Returns

Exceptions

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 isolation key for session-mutating operations.

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

Parameters

Keyword-Only Parameters

Returns

Exceptions

create_version_from_code.

create_version_from_code(agent_name: str, content: CreateAgentVersionFromCodeContent | MutableMapping[str, Any], *, code_zip_sha256: str, **kwargs: Any) -> AgentVersionDetails

Parameters

Keyword-Only Parameters

Returns

Exceptions

Deletes an agent optimization job.

Delete the job and its candidate artifacts. Cancels first if non-terminal.

delete_optimization_job(job_id: str, *, force: bool | None = None, **kwargs: Any) -> None

Parameters

Keyword-Only Parameters

Returns

Exceptions

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, *, user_isolation_key: str | None = None, **kwargs: Any) -> None

Parameters

Keyword-Only Parameters

Returns

Exceptions

Delete a file or directory from the session sandbox. If recursive is false (default) and the target is a non-empty directory, the API returns 409 Conflict.

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

Parameters

Keyword-Only Parameters

Returns

Exceptions

Download 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

Keyword-Only Parameters

Returns

Exceptions

Download a file from the session sandbox as a binary stream.

download_session_file(agent_name: str, agent_session_id: str, *, path: str, user_isolation_key: str | None = None, **kwargs: Any) -> Iterator[bytes]

Parameters

Keyword-Only Parameters

Returns

Exceptions

Get a candidate file.

Stream a specific file from the candidate's blob directory.

get_candidate_file(job_id: str, candidate_id: str, *, path: str, **kwargs: Any) -> Iterator[bytes]

Parameters

Keyword-Only Parameters

Returns

Exceptions

Get a candidate by id.

Get a single candidate's metadata, manifest, and promotion info.

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

Parameters

Returns

Exceptions

Get candidate deploy config.

Get the candidate's deploy config JSON. Used to compose agents.create_version(...) from a candidate.

get_optimization_candidate_config(job_id: str, candidate_id: str, **kwargs: Any) -> CandidateDeployConfig

Parameters

Returns

Exceptions

Get candidate evaluation results.

Get full per-task evaluation results for a candidate.

get_optimization_candidate_results(job_id: str, candidate_id: str, **kwargs: Any) -> CandidateResults

Parameters

Returns

Exceptions

Get info about an agent optimization job.

Get an optimization job by id. Returns 202 while in progress, 200 when terminal.

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

Parameters

Returns

Exceptions

Retrieves a session by ID.

get_session(agent_name: str, session_id: str, *, user_isolation_key: str | None = None, **kwargs: Any) -> AgentSessionResource

Parameters

Keyword-Only Parameters

Returns

Exceptions

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

Returns

Exceptions

Returns a list of candidates for an optimization job.

List candidates produced by a job.

list_optimization_candidates(job_id: str, *, limit: int | None = None, order: str | PageOrder | None = None, after: str | None = None, before: str | None = None, **kwargs: Any) -> AgentsPagedResultOptimizationCandidate

Parameters

Keyword-Only Parameters

Returns

Exceptions

Returns a list of agent optimization jobs.

List optimization jobs. Supports cursor pagination and optional status / 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[OptimizationJob]

Keyword-Only Parameters

Returns

Exceptions

List files and directories at a given path in the session sandbox. Returns only the immediate children of the specified directory (non-recursive). If path is not provided, lists the session home directory.

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

Parameters

Keyword-Only Parameters

Returns

Exceptions

Returns a list of sessions for the specified agent.

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

Parameters

Keyword-Only Parameters

Returns

Exceptions

Updates an agent endpoint.

patch_agent_details(agent_name: str, body: ~collections.abc.MutableMapping[str, ~typing.Any] | ~typing.IO[bytes] = <object object>, *, 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

Keyword-Only Parameters

Returns

Exceptions

Promote a candidate.

Promotes a candidate, recording the deployment timestamp and target agent version.

promote_candidate(job_id: str, candidate_id: str, candidate_request: PromoteCandidateRequest | MutableMapping[str, Any] | IO[bytes], **kwargs: Any) -> PromoteCandidateResponse

Parameters

Returns

Exceptions

Stops a session. Returns 204 No Content when the stop succeeds.

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

Parameters

Returns

Exceptions

Upload a file to the session sandbox.

Accepts either a bytes buffer or a local file path (str). When a file path is provided the file is read from disk and its contents are forwarded to the service. Maximum file size is 50 MB. Uploads exceeding this limit return 413 Payload Too Large.

upload_session_file(agent_name: str, session_id: str, content_or_file_path: bytes | str, *, path: str, **kwargs: Any) -> SessionFileWriteResult

Parameters

Keyword-Only Parameters

Returns

Exceptions