Gerenciar sessões de agente hospedado

• CLI do Azure versão 2.80 ou posterior, autenticada com az login.

• Python SDK: azure-ai-projects>=2.1.0 e azure-identity.

• Azure CLI do Desenvolvedor versão 1.23.0 ou posterior.

• A extensão de agentes Foundry

  azd ext install azure.ai.agents
  

Configurar variáveis

Os exemplos da API REST neste artigo usam az rest para chamar diretamente os endpoints Foundry Agent Service. Defina as seguintes variáveis antes de executar os comandos:

ACCOUNT_NAME="<your-foundry-account-name>"
PROJECT_NAME="<your-project-name>"
BASE_URL="https://${ACCOUNT_NAME}.services.ai.azure.com/api/projects/${PROJECT_NAME}"
API_VERSION="v1"
RESOURCE="https://ai.azure.com"

Configurar o cliente

Todos os exemplos de Python neste artigo usam a seguinte configuração de cliente:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project = AIProjectClient(
    endpoint="<your-project-endpoint>",
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

AGENT_NAME="my-agent"

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/openai/responses?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --body '{
        "input": "Find me hotels in Seattle under $200 per night",
        "stream": false
    }'

O conteúdo da resposta inclui a agent_session_id plataforma criada. Para continuar usando essa sessão em uma chamada posterior ao realizar threading com previous_response_id, inclua agent_session_id no corpo da solicitação.

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/openai/responses?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --body '{
        "input": "Recommend one of those hotels",
        "stream": false,
        "agent_session_id": "<session-id-from-first-response>",
        "previous_response_id": "<id-from-first-response>"
    }'

Se você altera o thread para usar uma conversation ID, a plataforma roteia automaticamente cada chamada para a mesma agent_session_id conversa. Você não precisa passar agent_session_id por conta própria.

Quando você chama get_openai_client com um agent_name, o cliente OpenAI retornado é roteado para o ponto de extremidade do agente. A primeira chamada cria a sessão; a resposta carrega o novo agent_session_id em model_extra.

openai_client = project.get_openai_client(agent_name="my-agent")

response = openai_client.responses.create(
    input="Find me hotels in Seattle under $200 per night",
)
session_id = response.model_extra.get("agent_session_id")
print(f"Session: {session_id}")
print(f"Response: {response.output_text}")

# Reuse the session and thread the conversation on a later turn.
follow_up = openai_client.responses.create(
    input="Recommend one of those hotels",
    previous_response_id=response.id,
    extra_body={"agent_session_id": session_id},
)
print(follow_up.output_text)

Se o thread for girado com uma conversation ID em vez de previous_response_id, a plataforma roteia automaticamente cada chamada dessa conversa para a mesma agent_session_id— você pode omitir extra_body={"agent_session_id": ...}:

conversation = openai_client.conversations.create()

first = openai_client.responses.create(
    input="Find me hotels in Seattle under $200 per night",
    extra_body={"conversation": conversation.id},
)
follow_up = openai_client.responses.create(
    input="Recommend one of those hotels",
    extra_body={"conversation": conversation.id},
)

azd ai agent invoke --input "Find me hotels in Seattle under $200 per night"

AGENT_NAME="my-agent"

# First call — platform creates a new session.
az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/invocations?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --body '{"input": "Hello"}'

Para um contêiner emissor de SSE, como os exemplos do Serviço do Agente, o evento final done carrega session_id e um invocation_id. Para reutilizar esse sandbox em uma chamada posterior, passe a ID da sessão como o parâmetro de agent_session_id consulta:

SESSION_ID="<session_id-from-first-response>"

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/protocols/invocations?api-version=${API_VERSION}&agent_session_id=${SESSION_ID}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --body '{"input": "Continue our previous discussion"}'

O SDK do Python não fornece um cliente de invocações tipado. Chame o endpoint com requests (ou qualquer biblioteca HTTP) e autentique com um token bearer de azure-identity:

import json
import requests
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
    "Foundry-Features": "HostedAgents=V1Preview",
    "Content-Type": "application/json",
}

base = "<your-project-endpoint>/agents/my-agent/endpoint/protocols/invocations?api-version=v1"

# First call — platform creates a new session.
response = requests.post(base, headers=headers, data=json.dumps({"input": "Hello"}))
for line in response.iter_lines(decode_unicode=True):
    if line.startswith("data:"):
        event = json.loads(line[len("data:"):].strip())
        if event.get("type") == "done":
            session_id = event["session_id"]

# Reuse the session on a later call.
requests.post(
    f"{base}&agent_session_id={session_id}",
    headers=headers,
    data=json.dumps({"input": "Continue our previous discussion"}),
)

azd ai agent invoke --input '{"input": "Hello"}'

AGENT_NAME="my-agent"

az rest --method POST \
    --url "${BASE_URL}/agents/${AGENT_NAME}/endpoint/sessions?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "x-ms-user-isolation-key=user-123" "Foundry-Features=HostedAgents=V1Preview" \
    --body '{
        "version_indicator": {
            "type": "version_ref",
            "agent_version": "2"
        }
    }'

Omita o corpo (ou envie {}) para permitir que a plataforma escolha a versão usando as regras de roteamento de tráfego do ponto de extremidade do agente.

session = project.beta.agents.create_session(
    agent_name="my-agent",
    body={},
    isolation_key="user-123",
)
print(f"Session created (ID: {session.agent_session_id}, status: {session.status})")

O SDK requer a isolation_key palavra-chave e create_sessiondelete_session. O servidor aplica a configuração apenas quando o endpoint do agente está configurado para ler chaves dos cabeçalhos, conforme detalhado em chaves de isolamento.

Para fixar a sessão em uma versão específica do agente, inclua version_indicator no corpo:

session = project.beta.agents.create_session(
    agent_name="my-agent",
    body={
        "version_indicator": {"type": "version_ref", "agent_version": "2"},
    },
    isolation_key="user-123",
)

As sessões são criadas automaticamente quando você invoca um agente por meio de azd. A criação manual de sessão não está disponível no momento como um comando autônomo.

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

sessions = project.beta.agents.list_sessions(agent_name="my-agent")
for item in sessions:
    print(f"Session: {item.agent_session_id} (status: {item.status})")

No momento, a listagem de sessão não está disponível como um comando autônomo. Use a API REST ou o SDK.

SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

session = project.beta.agents.get_session(
    agent_name="my-agent",
    session_id="<session-id>",
)
print(f"Session ID: {session.agent_session_id}, Status: {session.status}")

Atualmente, o gerenciamento de sessão não está disponível como um comando autônomo. Use a API REST ou o SDK.

SESSION_ID="<session-id>"
ISOLATION_KEY="user-123"

az rest --method DELETE \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}?api-version=${API_VERSION}" \
    --resource "${RESOURCE}" \
    --headers "x-ms-user-isolation-key=${ISOLATION_KEY}" "Foundry-Features=HostedAgents=V1Preview"

project.beta.agents.delete_session(
    agent_name="my-agent",
    session_id="<session-id>",
    isolation_key="user-123",
)

Atualmente, o gerenciamento de sessão não está disponível como um comando autônomo. Use a API REST ou o SDK.

SESSION_ID="<session-id>"

az rest --method PUT \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files/content?api-version=${API_VERSION}&path=data.csv" \
    --resource "${RESOURCE}" \
    --body @data.csv \
    --headers "Content-Type=application/octet-stream" "Foundry-Features=HostedAgents=V1Preview"

project.beta.agents.upload_session_file(
    agent_name="my-agent",
    session_id="<session-id>",
    content_or_file_path="./data.csv",
    path="data.csv",
)

O content_or_file_path parâmetro aceita uma cadeia de caracteres de caminho de arquivo. O SDK lê e carrega o conteúdo do arquivo automaticamente.

azd ai agent files upload --file ./data.csv --target-path data.csv

SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files?api-version=${API_VERSION}&path=." \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

files = project.beta.agents.get_session_files(
    agent_name="my-agent",
    agent_session_id="<session-id>",
    path=".",
)
for entry in files.entries:
    print(f"  {entry['name']} (size: {entry['size']}, directory: {entry['is_directory']})")

azd ai agent files list .

SESSION_ID="<session-id>"

az rest --method GET \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files/content?api-version=${API_VERSION}&path=data.csv" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview" \
    --output-file output.csv

content_bytes = b"".join(
    project.beta.agents.download_session_file(
        agent_name="my-agent",
        agent_session_id="<session-id>",
        path="data.csv",
    )
)
with open("./output.csv", "wb") as f:
    f.write(content_bytes)

azd ai agent files download --file data.csv --target-path ./output.csv

SESSION_ID="<session-id>"

az rest --method DELETE \
    --url "${BASE_URL}/agents/my-agent/endpoint/sessions/${SESSION_ID}/files?api-version=${API_VERSION}&path=data.csv" \
    --resource "${RESOURCE}" \
    --headers "Foundry-Features=HostedAgents=V1Preview"

project.beta.agents.delete_session_file(
    agent_name="my-agent",
    agent_session_id="<session-id>",
    path="data.csv",
)

azd ai agent files remove --file data.csv