Llevo un tiempo siguiendo la evolución de Azure AI Foundry y, hasta hace poco, montar un agente conversacional requería bastantes piezas: orquestadores, gestión manual de hilos, autenticación con tokens… La cosa se ha simplificado mucho. Con el nuevo Foundry Agent Service y el SDK azure-ai-projects 2.x puedes tener un agente funcionando en menos de 50 líneas de Python.
En esta guía vamos a hacer exactamente eso. Partimos desde cero: creamos el proyecto en Azure, desplegamos un modelo, preparamos el entorno y programamos un agente que mantiene historial de conversación entre turnos. Sin magia negra.
Qué es un Prompt Agent en Foundry
Un Prompt Agent es, en esencia, un agente definido de forma declarativa. Le dices qué modelo usa, qué instrucciones sigue y qué herramientas tiene disponibles — y Foundry se encarga de lo demás. No hay que gestionar hilos manualmente ni construir el contexto a mano.
Lo interesante es que soporta todos los modelos directos de Foundry: gpt-4.1-mini, gpt-5-mini, y cualquier otro que tengas desplegado en tu proyecto. Y la conversación multi-turno viene de serie — el historial se mantiene automáticamente usando un objeto Conversation.
Nota: El SDK 2.x usa la nueva API «Foundry projects (new)». Si vienes de azure-ai-projects 1.x, el código NO es compatible. Hay una sección de migración en la documentación oficial.
Prerrequisitos: montar la infraestructura
Antes de escribir una sola línea de Python necesitamos tres cosas en Azure: un recurso Foundry, un proyecto dentro de ese recurso, y un modelo desplegado. Vamos con Azure CLI, que es más reproducible que el portal.
1. Crear el recurso y el proyecto
Primero, un grupo de recursos (o usa uno existente):
az group create –name my-foundry-rg –location eastus
Luego el recurso Foundry — ojo con el flag –allow-project-management, es obligatorio:
az cognitiveservices account create \
–name my-foundry-resource \
–resource-group my-foundry-rg \
–kind AIServices \
–sku s0 \
–location eastus \
–allow-project-management
El nombre del recurso también se usa como subdominio, así que tiene que ser único globalmente. Si el nombre está ocupado, añade un sufijo numérico o tus iniciales.
az cognitiveservices account update \
–name my-foundry-resource \
–resource-group my-foundry-rg \
–custom-domain my-foundry-resource
az cognitiveservices account project create \
–name my-foundry-resource \
–resource-group my-foundry-rg \
–project-name my-foundry-project \
–location eastus
2. Desplegar un modelo
Desplegamos gpt-4.1-mini. Es el modelo que usaremos en el agente — pequeño, rápido y más que suficiente para este escenario:
az cognitiveservices account deployment create \
–name my-foundry-resource \
–resource-group my-foundry-rg \
–deployment-name gpt-4.1-mini \
–model-name gpt-4.1-mini \
–model-version «2025-04-14» \
–model-format OpenAI \
–sku-capacity 10 \
–sku-name Standard
Cuando el estado sea provisioningState: Succeeded ya estamos listos. Anota el endpoint del proyecto — lo necesitarás en el código. Puedes verlo en el portal de Foundry (https://ai.azure.com) en la pantalla de bienvenida del proyecto, o con az cognitiveservices account project show.
Preparar el entorno de desarrollo
Python 3.10 o superior, entorno virtual, Azure CLI instalado. Nada especial. Pero sí hay un detalle importante: la autenticación se hace con az login, no con API keys. El SDK usa DefaultAzureCredential, que en local lee tus credenciales del CLI.
# Windows
py -3 -m venv .venv
.venv\scripts\activate
# Instalar Azure CLI (si no lo tienes)
winget install -e –id Microsoft.AzureCLI
# Autenticarse
az login
# Instalar el SDK (versión 2.x, obligatorio)
pip install «azure-ai-projects>=2.0.0»
Un apunte sobre la versión: el pip install sin restricción puede darte la 1.x si hay problemas de resolución. Mejor fijar el rango como aparece arriba.
Crear el agente con Python
Con el entorno listo, crear el agente son cuatro líneas efectivas. El resto es setup de cliente:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
PROJECT_ENDPOINT = «https://my-foundry-resource.ai.azure.com/api/projects/my-foundry-project»
AGENT_NAME = «MiAsistenteGeneral»
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
agent = project.agents.create_version(
agent_name=AGENT_NAME,
definition=PromptAgentDefinition(
model=»gpt-4.1-mini»,
instructions=»Eres un asistente técnico que responde en español.»,
),
)
print(f»Agente creado: {agent.name} (id: {agent.id}, versión: {agent.version})»)
Fíjate en el objeto PromptAgentDefinition: ahí van las instrucciones del sistema y el modelo. Puedes actualizar o eliminar el agente en cualquier momento — no es inmutable.
Conversación multi-turno: el agente recuerda
Y aquí viene lo bueno. Con un objeto Conversation el agente mantiene el contexto entre mensajes. No hace falta pasar el historial manualmente:
openai = project.get_openai_client()
# Crear una conversación (hilo persistente)
conversation = openai.conversations.create()
# Primer mensaje
response = openai.responses.create(
conversation=conversation.id,
extra_body={«agent_reference»: {«name»: AGENT_NAME, «type»: «agent_reference»}},
input=»¿Cuál es la superficie de Francia en kilómetros cuadrados?»,
)
print(response.output_text)
# Pregunta de seguimiento — el agente recuerda el contexto
response = openai.responses.create(
conversation=conversation.id,
extra_body={«agent_reference»: {«name»: AGENT_NAME, «type»: «agent_reference»}},
input=»¿Y cuál es su capital?»,
)
print(response.output_text)
La segunda pregunta —»¿Y cuál es su capital?»— no necesita contexto adicional. El agente ya sabe que estamos hablando de Francia porque la conversación lo recuerda. Esto es justo lo que diferencia un agente real de un simple completion de una sola vuelta.
Nota: El endpoint del proyecto tiene el formato: https://nombre-recurso.ai.azure.com/api/projects/nombre-proyecto. Puedes copiarlo directamente desde la pantalla de bienvenida del proyecto en ai.azure.com.
Conclusión
Si trabajas con Azure AI Foundry y necesitas montar agentes conversacionales rápido, el Foundry Agent Service con azure-ai-projects 2.x es la opción más directa ahora mismo. La infraestructura con CLI te lleva unos 10 minutos, y el código del agente es sorprendentemente limpio.
Hay cosas que no hemos cubierto aquí — herramientas personalizadas, function calling, memoria persistente entre sesiones — pero este quickstart es el punto de partida correcto. Desde aquí ya puedes explorar el catálogo de herramientas del SDK y añadir capacidades según lo que necesite tu caso de uso.
Documentación oficial utilizada (actualizada a abril de 2026):
- Quickstart: Create a prompt agent: Quickstart: Create a prompt agent – Microsoft Foundry | Microsoft Learn
- Quickstart: Set up Microsoft Foundry resources: Quickstart: Set up Microsoft Foundry resources – Microsoft Foundry | Microsoft Learn
- Prepare your development environment: Prepare your development environment – Microsoft Foundry | Microsoft Learn