Inicio rápido: Implementación de su propio código como agente hospedado

Note

Los agentes hospedados están actualmente disponibles en versión preliminar.

En Implementar el primer agente hospedado, implementó un ejemplo. En esta guía de inicio rápido, desplegará su propio código de agente en Python en Foundry Agent Service.

Prerequisites

Antes de comenzar, necesita lo siguiente:

El directorio del proyecto debe contener como mínimo:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Elección del protocolo

Seleccione la pestaña que coincide con el patrón de interacción del agente. Las respuestas administran el historial de conversaciones y son compatibles con OpenAI. Las invocaciones proporcionan un control total sobre los esquemas de solicitud y respuesta.

Tip

¿No está seguro de qué protocolo usar? Comience con respuestas.

Paso 1: Agregar la biblioteca de hospedaje

Agregue la biblioteca de protocolos a requirements.txt. La biblioteca controla el servidor HTTP, las comprobaciones de estado y el cumplimiento del protocolo.

azure-ai-agentserver-responses>=1.0.0b7

Paso 2: Agregar el contenedor de hospedaje

Cree o actualice main.py con el contenedor de hospedaje. Los ejemplos muestran el patrón mínimo: reemplace el bloque marcado por la lógica del agente existente.

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Note

Estos ejemplos hacen eco de la entrada del usuario para demostrar el contenedor de hospedaje. Reemplace el bloque marcado por las llamadas de modelo, la lógica RAG o cualquier código de marco de agente. Para ver los patrones de producción, consulte los ejemplos de Python y ejemplos de C#.

Paso 3: Inicializar el proyecto

Ejecute azd ai agent init desde el directorio de origen del agente:

azd ai agent init --protocol responses --deploy-mode code

El flujo interactivo solicita lo siguiente:

  • Nombre del agente: personalice el nombre o acepte el valor predeterminado.
  • Foundry Project: seleccione Usar un proyecto de Foundry existente o Crear un nuevo proyecto de Foundry.
  • Suscripción: Seleccione su suscripción a Azure.
  • Ubicación: seleccione una región de Azure.

Cuando se complete, verá: Se ha agregado correctamente la definición del agente de IA a su proyecto de azd.

Paso 4: Aprovisionar recursos de Azure

azd provision

Esto crea los recursos Azure necesarios, como Application Insights.

Paso 5: Probar el agente localmente

azd ai agent run

Este comando crea un entorno virtual, instala dependencias e inicia el agente. También abre el inspector del agente en tu navegador para que puedas chatear con el agente.

También puede invocar desde la CLI en un terminal independiente:

azd ai agent invoke --local "Hello from my hosted agent"

Paso 6: Implementación en el servicio del Agente Foundry

azd deploy

Cuando termine el comando, la salida muestra enlaces al entorno de pruebas del agente y al punto de conexión del agente:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

Paso 7: Invocación del agente implementado

azd ai agent invoke "Hello from my hosted agent"

Debería ver una respuesta en unos segundos.

Limpieza de recursos

Advertencia

azd down elimina permanentemente todos los recursos del grupo de recursos, incluido el proyecto Foundry y el agente hospedado. Si el grupo de recursos contiene otros recursos, también se eliminan.

azd down

Troubleshooting

Issue Solución
ModuleNotFoundError: azure.ai.agentserver Compruebe que la biblioteca de protocolos está en requirements.txt y vuelva a instalar: pip install -r requirements.txt.
FOUNDRY_PROJECT_ENDPOINT not set Use azd ai agent run (lo establece automáticamente) en lugar de python main.py. O agréguelo al .env archivo.
Connection refused durante la ejecución local Asegúrese de que ningún otro proceso use el puerto 8088.
AuthorizationFailed durante la implementación Necesita Foundry Project Manager en el ámbito del proyecto.
Agente bloqueado en provisioning Ejecute azd ai agent show para comprobar el estado. Las primeras implementaciones pueden tardar entre 2 y 3 minutos mientras se instalan las dependencias.
azd ai agent init falla Ejecute azd version para comprobar la versión 1.25.3 o posterior. Actualice la extensión: azd ext upgrade microsoft.foundry.

Para obtener la matriz completa de permisos y asignación de roles, consulte Referencia de permisos del agente hospedado.

Lo que ha aprendido

En esta guía de inicio rápido:

  • Agregue una biblioteca de hospedaje al código existente de su agente.
  • Se ha inicializado un proyecto azd a partir de tu directorio de origen.
  • Probado localmente con azd ai agent run y azd ai agent invoke --local.
  • Implementado en el servicio Foundry Agent Service con azd deploy.

Pasos siguientes

Administración del ciclo de vida del agente hospedado

Contenido relacionado

  • Last updated on