Administración de sesiones del agente hospedado

• CLI de Azure versión 2.80 o posterior, autenticado con az login.

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

• Azure CLI para desarrolladores versión 1.23.0 o posterior.

• La extensión de Foundry para agentes:

  azd ext install azure.ai.agents
  

Configurar variables

En los ejemplos de la API REST de este artículo se usa az rest para llamar directamente a los puntos de conexión del Servicio de Agente Foundry. Establezca las siguientes variables antes de ejecutar los 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"

Configuración del cliente

Todos los ejemplos de Python de este artículo usan la siguiente configuración 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
    }'

La carga de respuesta incluye la agent_session_id plataforma creada. Para seguir usando esa sesión en una llamada posterior cuando se manejen subprocesos con previous_response_id, incluya agent_session_id en el cuerpo de la solicitud.

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

Si convierte el hilo en un identificador conversation en su lugar, la plataforma enruta automáticamente cada llamada de esa conversación a la misma agent_session_id. No necesitas pasar agent_session_id tú mismo.

Cuando llamas a get_openai_client con un agent_name, el cliente de OpenAI devuelto se enruta al punto de conexión del agente. La primera llamada crea la sesión; la respuesta incluye el nuevo agent_session_id en 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)

Si el subproceso gira con un conversation identificador en lugar de previous_response_id, la plataforma enruta automáticamente cada llamada de esa conversación a la misma agent_session_id, puede 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"}'

En el caso de un contenedor emisor de SSE como los ejemplos de Agent Service, el evento final done lleva session_id y invocation_id. Para reutilizar ese espacio aislado en una llamada posterior, pase el identificador de sesión como el parámetro de consulta agent_session_id:

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

El SDK de Python no proporciona un cliente de invocaciones tipado. Llame al punto de conexión con requests (o cualquier biblioteca HTTP) y autentíquese con un token de portador desde 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 el cuerpo (o envíe {}) para permitir que la plataforma seleccione la versión utilizando las reglas de enrutamiento de tráfico del punto de conexión del 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})")

El SDK requiere la isolation_key palabra clave en create_session y delete_session. El servidor solo lo aplica cuando el punto de conexión del agente está configurado para leer las claves de los encabezados; consulte Claves de aislamiento.

Para anclar la sesión a una versión específica del agente, incluya version_indicator en el cuerpo:

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

Las sesiones se crean automáticamente al invocar un agente a través de azd. La creación manual de sesiones no está disponible actualmente como comando independiente.

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

La lista de sesiones no está disponible actualmente como comando independiente. Use la API REST o el 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}")

La administración de sesiones no está disponible actualmente como comando independiente. Use la API REST o el 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",
)

La administración de sesiones no está disponible actualmente como comando independiente. Use la API REST o el 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",
)

El content_or_file_path parámetro acepta una cadena de ruta de acceso de archivo. El SDK lee y carga automáticamente el contenido del archivo.

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