AgentsOperations interface

Pacote:

@azure/ai-projects

Interface que representa uma operação de Agentes.

Propriedades

createSession	Cria uma nova sessão para um endpoint agente. O endpoint resolve a versão do agente de suporte a partir version_indicator e aplica a propriedade da sessão usando a chave de isolamento fornecida para operações de mutação de sessão.
createVersionFromCode	Cria uma nova versão do agente a partir do código. Faz upload do código postal e cria uma nova versão para um agente existente. O resumo hexadecimal SHA-256 do zip é fornecido no x-ms-code-zip-sha256 cabeçalho para integridade e deduplicação. O corpo da requisição é multipart/formulário-data com uma parte de metadados JSON e uma parte de código binário (a ordem das peças é irrelevante). O tamanho máximo de upload é 250 MB.
delete	Exclui um agente. Para agentes hospedados, se alguma versão tiver sessões ativas, a solicitação é rejeitada com HTTP 409, a menos que force seja definida como true. Quando força é verdadeira, todas as sessões associadas são deletadas em cascata junto com o agente e suas versões.
deleteSession	Exclui uma sessão de forma síncrona. Retorna 204 Sem Conteúdo quando a sessão é excluída ou não existe.
deleteSessionFile	Exclui o arquivo ou diretório especificado do sandbox da sessão. Quando recursive é falso, excluir um diretório não vazio retorna 409 Conflito.
deleteVersion	Exclui uma versão específica de um agente. Para agentes hospedados, se a versão tiver sessões ativas, a solicitação é rejeitada com HTTP 409, a menos que force seja definida como true. Quando força é verdadeira, todas as sessões associadas a esta versão são deletadas em cascata.
disable	Desabilita o agente especificado, impedindo que ele aceite novas sessões ou processe solicitações. Sessões ativas existentes podem drenar de forma elegante, mas nenhuma nova sessão pode ser criada. Essa operação é idempotente — desativar um agente já incapacitado retorna sucesso sem efeitos colaterais.
downloadAgentCode	Baixa o código postal de um agente hospedado baseado em código. Retorna o código postal previamente enviado (application/zip). Se agent_version for fornecido, retorna o código zip daquela versão; caso contrário, retorna o código zip da versão mais recente. O resumo SHA-256 dos bytes retornados corresponde ao content_hash da versão code_configurationresolvida .
downloadSessionFile	Baixa o arquivo no caminho sandbox especificado como um fluxo binário. O caminho é resolvido em relação ao diretório inicial da sessão.
enable	Habilita o agente especificado, permitindo que ele aceite novas sessões e processe solicitações. Essa operação é idempotente — permitindo que um agente já habilitado retorne o sucesso sem efeitos colaterais.
get	Recupera o agente.
getSession	Recupera os detalhes de uma sessão de agente hospedada pelo nome do agente e identificador de sessão.
getSessionLogStream	Transmite logs de console (stdout / stderr) para uma sessão de agente hospedada específica como um fluxo de Server-Sent Eventos (SSE). Cada quadro SSE contém: event: sempre "log" data: uma log line em texto simples (atualmente formatada em JSON, mas o esquema não é contratual e pode incluir chaves adicionais ou mudar de formato ao longo do tempo — os clientes devem tratá-la como uma string opaca) Exemplos de quadros SSE: 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"} O fluxo permanece aberto até que o cliente se desconecte ou o servidor encerre a conexão. Os clientes devem lidar com a reconexão conforme necessário.
getVersion	Recupera uma versão específica de um agente.
list	Retorna a lista de todos os agentes.
listSessionFiles	Retorna arquivos e diretórios no caminho especificado no sandbox da sessão. A resposta inclui apenas os filhos imediatos do diretório de destino e por padrão é direcionado ao diretório inicial da sessão quando nenhum caminho é fornecido.
listSessions	Retorna uma coleção paginada de sessões associadas ao endpoint do agente especificado.
listVersions	Retorna a lista de versões de um agente.
patchAgentObject	Modifica um agente existente.
stopSession	Encerra a sessão do agente hospedado especificada e retorna 204 Sem Conteúdo quando a solicitação é bem-sucedida.
updateAgent	Aplica uma atualização de mesclarão na configuração de endpoint do agente especificada.
uploadSessionFile	Faz upload do conteúdo binário do arquivo para o caminho especificado no sandbox da sessão. O serviço armazena o arquivo em relação ao diretório inicial da sessão e rejeita cargas úteis maiores que 50 MB.

Métodos

create(string, AgentDefinitionUnion, AgentsCreateOptionalParams)	Cria o agente.
create(string, string, Record<string, unknown>, AgentsCreateAgentFromManifestOptionalParams)	Cria um agente a partir de um manifesto.
createVersion(string, AgentDefinitionUnion, AgentsCreateVersionOptionalParams)	Crie uma nova versão do agente.
createVersion(string, string, Record<string, unknown>, AgentsCreateAgentVersionFromManifestOptionalParams)	Crie uma nova versão do agente a partir de um manifesto.
update(string, AgentDefinitionUnion, AgentsUpdateOptionalParams)	Atualiza o agente adicionando uma nova versão se houver alguma alteração na definição do agente. Se nenhuma alteração, retorna a versão existente do agente.
update(string, string, Record<string, unknown>, AgentsUpdateAgentFromManifestOptionalParams)	Atualiza o agente de um manifesto adicionando uma nova versão se houver alterações na definição do agente. Se nenhuma alteração, retorna a versão existente do agente.

Detalhes da propriedade

createSession

Cria uma nova sessão para um endpoint agente. O endpoint resolve a versão do agente de suporte a partir version_indicator e aplica a propriedade da sessão usando a chave de isolamento fornecida para operações de mutação de sessão.

createSession: (agentName: string, versionIndicator: VersionIndicatorUnion, options?: AgentsCreateSessionOptionalParams) => Promise<AgentSessionResource>

Valor da propriedade

(agentName: string, versionIndicator: VersionIndicatorUnion, options?: AgentsCreateSessionOptionalParams) => Promise<AgentSessionResource>

createVersionFromCode

Cria uma nova versão do agente a partir do código. Faz upload do código postal e cria uma nova versão para um agente existente. O resumo hexadecimal SHA-256 do zip é fornecido no x-ms-code-zip-sha256 cabeçalho para integridade e deduplicação. O corpo da requisição é multipart/formulário-data com uma parte de metadados JSON e uma parte de código binário (a ordem das peças é irrelevante). O tamanho máximo de upload é 250 MB.

createVersionFromCode: (agentName: string, codeZipSha256: string, content: CreateAgentVersionFromCodeContent, options?: AgentsCreateVersionFromCodeOptionalParams) => Promise<AgentVersion>

Valor da propriedade

(agentName: string, codeZipSha256: string, content: CreateAgentVersionFromCodeContent, options?: AgentsCreateVersionFromCodeOptionalParams) => Promise<AgentVersion>

delete

Exclui um agente. Para agentes hospedados, se alguma versão tiver sessões ativas, a solicitação é rejeitada com HTTP 409, a menos que force seja definida como true. Quando força é verdadeira, todas as sessões associadas são deletadas em cascata junto com o agente e suas versões.

delete: (agentName: string, options?: AgentsDeleteOptionalParams) => Promise<DeleteAgentResponse>

Valor da propriedade

(agentName: string, options?: AgentsDeleteOptionalParams) => Promise<DeleteAgentResponse>

deleteSession

Exclui uma sessão de forma síncrona. Retorna 204 Sem Conteúdo quando a sessão é excluída ou não existe.

deleteSession: (agentName: string, sessionId: string, options?: AgentsDeleteSessionOptionalParams) => Promise<void>

Valor da propriedade

(agentName: string, sessionId: string, options?: AgentsDeleteSessionOptionalParams) => Promise<void>

deleteSessionFile

Exclui o arquivo ou diretório especificado do sandbox da sessão. Quando recursive é falso, excluir um diretório não vazio retorna 409 Conflito.

deleteSessionFile: (agentName: string, sessionId: string, path: string, options?: AgentsDeleteSessionFileOptionalParams) => Promise<void>

Valor da propriedade

(agentName: string, sessionId: string, path: string, options?: AgentsDeleteSessionFileOptionalParams) => Promise<void>

deleteVersion

Exclui uma versão específica de um agente. Para agentes hospedados, se a versão tiver sessões ativas, a solicitação é rejeitada com HTTP 409, a menos que force seja definida como true. Quando força é verdadeira, todas as sessões associadas a esta versão são deletadas em cascata.

deleteVersion: (agentName: string, agentVersion: string, options?: AgentsDeleteVersionOptionalParams) => Promise<DeleteAgentVersionResponse>

Valor da propriedade

(agentName: string, agentVersion: string, options?: AgentsDeleteVersionOptionalParams) => Promise<DeleteAgentVersionResponse>

disable

Desabilita o agente especificado, impedindo que ele aceite novas sessões ou processe solicitações. Sessões ativas existentes podem drenar de forma elegante, mas nenhuma nova sessão pode ser criada. Essa operação é idempotente — desativar um agente já incapacitado retorna sucesso sem efeitos colaterais.

disable: (agentName: string, options?: AgentsDisableOptionalParams) => Promise<void>

Valor da propriedade

(agentName: string, options?: AgentsDisableOptionalParams) => Promise<void>

downloadAgentCode

Baixa o código postal de um agente hospedado baseado em código. Retorna o código postal previamente enviado (application/zip).

Se agent_version for fornecido, retorna o código zip daquela versão; caso contrário, retorna o código zip da versão mais recente.

O resumo SHA-256 dos bytes retornados corresponde ao content_hash da versão code_configurationresolvida .

downloadAgentCode: (agentName: string, options?: AgentsDownloadAgentCodeOptionalParams) => Promise<AgentsDownloadAgentCodeResponse>

Valor da propriedade

(agentName: string, options?: AgentsDownloadAgentCodeOptionalParams) => Promise<AgentsDownloadAgentCodeResponse>

downloadSessionFile

Baixa o arquivo no caminho sandbox especificado como um fluxo binário. O caminho é resolvido em relação ao diretório inicial da sessão.

downloadSessionFile: (agentName: string, sessionId: string, path: string, options?: AgentsDownloadSessionFileOptionalParams) => Promise<AgentsDownloadSessionFileResponse>

Valor da propriedade

(agentName: string, sessionId: string, path: string, options?: AgentsDownloadSessionFileOptionalParams) => Promise<AgentsDownloadSessionFileResponse>

enable

Habilita o agente especificado, permitindo que ele aceite novas sessões e processe solicitações. Essa operação é idempotente — permitindo que um agente já habilitado retorne o sucesso sem efeitos colaterais.

enable: (agentName: string, options?: AgentsEnableOptionalParams) => Promise<void>

Valor da propriedade

(agentName: string, options?: AgentsEnableOptionalParams) => Promise<void>

get

Recupera o agente.

get: (agentName: string, options?: AgentsGetOptionalParams) => Promise<Agent>

Valor da propriedade

(agentName: string, options?: AgentsGetOptionalParams) => Promise<Agent>

getSession

Recupera os detalhes de uma sessão de agente hospedada pelo nome do agente e identificador de sessão.

getSession: (agentName: string, sessionId: string, options?: AgentsGetSessionOptionalParams) => Promise<AgentSessionResource>

Valor da propriedade

(agentName: string, sessionId: string, options?: AgentsGetSessionOptionalParams) => Promise<AgentSessionResource>

getSessionLogStream

Transmite logs de console (stdout / stderr) para uma sessão de agente hospedada específica como um fluxo de Server-Sent Eventos (SSE).

Cada quadro SSE contém:

• event: sempre "log"
• data: uma log line em texto simples (atualmente formatada em JSON, mas o esquema não é contratual e pode incluir chaves adicionais ou mudar de formato ao longo do tempo — os clientes devem tratá-la como uma string opaca)

Exemplos de quadros SSE:

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"}

O fluxo permanece aberto até que o cliente se desconecte ou o servidor encerre a conexão. Os clientes devem lidar com a reconexão conforme necessário.

getSessionLogStream: (agentName: string, agentVersion: string, sessionId: string, options?: AgentsGetSessionLogStreamOptionalParams) => Promise<AgentsDownloadSessionFileResponse>

Valor da propriedade

(agentName: string, agentVersion: string, sessionId: string, options?: AgentsGetSessionLogStreamOptionalParams) => Promise<AgentsDownloadSessionFileResponse>

getVersion

Recupera uma versão específica de um agente.

getVersion: (agentName: string, agentVersion: string, options?: AgentsGetVersionOptionalParams) => Promise<AgentVersion>

Valor da propriedade

(agentName: string, agentVersion: string, options?: AgentsGetVersionOptionalParams) => Promise<AgentVersion>

list

Retorna a lista de todos os agentes.

list: (options?: AgentsListOptionalParams) => PagedAsyncIterableIterator<Agent, Agent[], PageSettings>

Valor da propriedade

(options?: AgentsListOptionalParams) => PagedAsyncIterableIterator<Agent, Agent[], PageSettings>

listSessionFiles

Retorna arquivos e diretórios no caminho especificado no sandbox da sessão. A resposta inclui apenas os filhos imediatos do diretório de destino e por padrão é direcionado ao diretório inicial da sessão quando nenhum caminho é fornecido.

listSessionFiles: (agentName: string, sessionId: string, options?: AgentsListSessionFilesOptionalParams) => PagedAsyncIterableIterator<SessionDirectoryEntry, SessionDirectoryEntry[], PageSettings>

Valor da propriedade

(agentName: string, sessionId: string, options?: AgentsListSessionFilesOptionalParams) => PagedAsyncIterableIterator<SessionDirectoryEntry, SessionDirectoryEntry[], PageSettings>

listSessions

Retorna uma coleção paginada de sessões associadas ao endpoint do agente especificado.

listSessions: (agentName: string, options?: AgentsListSessionsOptionalParams) => PagedAsyncIterableIterator<AgentSessionResource, AgentSessionResource[], PageSettings>

Valor da propriedade

(agentName: string, options?: AgentsListSessionsOptionalParams) => PagedAsyncIterableIterator<AgentSessionResource, AgentSessionResource[], PageSettings>

listVersions

Retorna a lista de versões de um agente.

listVersions: (agentName: string, options?: AgentsListVersionsOptionalParams) => PagedAsyncIterableIterator<AgentVersion, AgentVersion[], PageSettings>

Valor da propriedade

(agentName: string, options?: AgentsListVersionsOptionalParams) => PagedAsyncIterableIterator<AgentVersion, AgentVersion[], PageSettings>

patchAgentObject

Modifica um agente existente.

patchAgentObject: (agentName: string, options?: AgentsUpdateAgentObjectOptionalParams) => Promise<Agent>

Valor da propriedade

(agentName: string, options?: AgentsUpdateAgentObjectOptionalParams) => Promise<Agent>

stopSession

Encerra a sessão do agente hospedado especificada e retorna 204 Sem Conteúdo quando a solicitação é bem-sucedida.

stopSession: (agentName: string, sessionId: string, options?: AgentsStopSessionOptionalParams) => Promise<void>

Valor da propriedade

(agentName: string, sessionId: string, options?: AgentsStopSessionOptionalParams) => Promise<void>

updateAgent

Aplica uma atualização de mesclarão na configuração de endpoint do agente especificada.

updateAgent: (agentName: string, options?: AgentsUpdateAgentObjectOptionalParams) => Promise<Agent>

Valor da propriedade

(agentName: string, options?: AgentsUpdateAgentObjectOptionalParams) => Promise<Agent>

uploadSessionFile

Faz upload do conteúdo binário do arquivo para o caminho especificado no sandbox da sessão. O serviço armazena o arquivo em relação ao diretório inicial da sessão e rejeita cargas úteis maiores que 50 MB.

uploadSessionFile: (agentName: string, sessionId: string, path: string, content: Uint8Array, options?: AgentsUploadSessionFileOptionalParams) => Promise<SessionFileWriteResponse>

Valor da propriedade

(agentName: string, sessionId: string, path: string, content: Uint8Array, options?: AgentsUploadSessionFileOptionalParams) => Promise<SessionFileWriteResponse>

Detalhes do método

create(string, AgentDefinitionUnion, AgentsCreateOptionalParams)

Cria o agente.

function create(name: string, definition: AgentDefinitionUnion, options?: AgentsCreateOptionalParams): Promise<Agent>

Parâmetros

name

string

definition

AgentDefinitionUnion

options

AgentsCreateOptionalParams

Retornos

Promise<Agent>

create(string, string, Record<string, unknown>, AgentsCreateAgentFromManifestOptionalParams)

Cria um agente a partir de um manifesto.

function create(name: string, manifestId: string, parameterValues: Record<string, unknown>, options?: AgentsCreateAgentFromManifestOptionalParams): Promise<Agent>

Parâmetros

name

string

manifestId

string

parameterValues

Record<string, unknown>

options

AgentsCreateAgentFromManifestOptionalParams

Retornos

Promise<Agent>

createVersion(string, AgentDefinitionUnion, AgentsCreateVersionOptionalParams)

Crie uma nova versão do agente.

function createVersion(agentName: string, definition: AgentDefinitionUnion, options?: AgentsCreateVersionOptionalParams): Promise<AgentVersion>

Parâmetros

agentName

string

definition

AgentDefinitionUnion

options

AgentsCreateVersionOptionalParams

Retornos

Promise<AgentVersion>

createVersion(string, string, Record<string, unknown>, AgentsCreateAgentVersionFromManifestOptionalParams)

Crie uma nova versão do agente a partir de um manifesto.

function createVersion(agentName: string, manifestId: string, parameterValues: Record<string, unknown>, options?: AgentsCreateAgentVersionFromManifestOptionalParams): Promise<AgentVersion>

Parâmetros

agentName

string

manifestId

string

parameterValues

Record<string, unknown>

options

AgentsCreateAgentVersionFromManifestOptionalParams

Retornos

Promise<AgentVersion>

update(string, AgentDefinitionUnion, AgentsUpdateOptionalParams)

Atualiza o agente adicionando uma nova versão se houver alguma alteração na definição do agente. Se nenhuma alteração, retorna a versão existente do agente.

function update(agentName: string, definition: AgentDefinitionUnion, options?: AgentsUpdateOptionalParams): Promise<Agent>

Parâmetros

agentName

string

definition

AgentDefinitionUnion

options

AgentsUpdateOptionalParams

Retornos

Promise<Agent>

update(string, string, Record<string, unknown>, AgentsUpdateAgentFromManifestOptionalParams)

Atualiza o agente de um manifesto adicionando uma nova versão se houver alterações na definição do agente. Se nenhuma alteração, retorna a versão existente do agente.

function update(agentName: string, manifestId: string, parameterValues: Record<string, unknown>, options?: AgentsUpdateAgentFromManifestOptionalParams): Promise<Agent>

Parâmetros

agentName

string

manifestId

string

parameterValues

Record<string, unknown>

options

AgentsUpdateAgentFromManifestOptionalParams

Retornos

Promise<Agent>