Construir con agentes, conversaciones y respuestas

Microsoft Foundry Agent Service usa tres componentes principales del entorno de ejecución: agents, conversations y responses, para activar interacciones con estado y multiturno. Un agente usa un modelo del catálogo de modelos Foundry, junto con instrucciones y herramientas. Una conversación mantiene el historial entre turnos. Una respuesta es la salida que genera el agente cuando procesa la entrada.

En este artículo se explica cada componente y se muestra cómo usarlos juntos en el código. Aprenderá a crear un agente, iniciar una conversación, generar respuestas (con o sin un agente), agregar mensajes de seguimiento y transmitir resultados, con ejemplos en Python, C#, JavaScript, Java y la API REST.

Funcionamiento conjunto de componentes en tiempo de ejecución

Al trabajar con un agente, sigue un patrón coherente:

  • Crear un agente: defina un agente para empezar a enviar mensajes y recibir respuestas.
  • Crear una conversación (opcional): use una conversación para mantener el historial a través de turnos. Si no utiliza una conversación, transfiera el contexto mediante la salida de una respuesta anterior.
  • Generar una respuesta: El modelo Foundry del agente procesa los elementos de entrada en la conversación y las instrucciones proporcionadas en la solicitud. El agente puede anexar elementos a la conversación.
  • Comprobar el estado de la respuesta: supervise la respuesta hasta que finalice (especialmente en modo de streaming o en segundo plano).
  • Recuperar la respuesta: muestra la respuesta generada al usuario.

En el diagrama siguiente se muestra cómo interactúan estos componentes en un bucle de agente típico.

Diagrama que muestra el bucle en tiempo de ejecución del agente: una definición del agente y un historial de conversación opcional para la generación de respuestas, que puede llamar a herramientas, agregar elementos a la conversación y producir elementos de salida que se muestran al usuario.

Proporciona entradas de usuario (y, opcionalmente, historial de conversaciones), el servicio genera una respuesta (incluidas las llamadas a herramientas cuando se configura) y los elementos resultantes se pueden reutilizar como contexto para el siguiente turno.

Requisitos previos

Para ejecutar los ejemplos de este artículo, necesita:

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

Creación de un agente

Un agente es una definición de orquestación persistente que combina modelos de IA, instrucciones, código, herramientas, parámetros y controles opcionales de seguridad o gobernanza.

Almacene agentes como activos con nombre y con control de versiones en Microsoft Foundry. Durante la generación de respuestas, la definición del agente funciona con el historial de interacción (conversación o respuesta anterior) para procesar y responder a la entrada del usuario.

En el ejemplo siguiente se crea un agente de indicación con un nombre, un modelo y unas instrucciones. Use el cliente del proyecto para la creación y el control de versiones del agente.

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Nota

Los agentes ahora se identifican mediante el nombre del agente y la versión del agente. Ya no tienen un GUID llamado AgentID .

Para obtener tipos de agente adicionales (flujo de trabajo, hospedado), consulte Ciclo de vida de desarrollo del agente.

Creación de un agente con herramientas

Las herramientas amplían lo que un agente puede hacer más allá de generar texto. Al adjuntar herramientas a un agente, el agente puede llamar a servicios externos, ejecutar código, archivos de búsqueda y acceder a orígenes de datos durante la generación de respuestas, mediante herramientas como la búsqueda web o la llamada a funciones.

Puede adjuntar una o varias herramientas al crear un agente. Durante la generación de respuesta, el agente decide si se debe llamar a una herramienta en función de la entrada del usuario y sus instrucciones. En el ejemplo siguiente se crea un agente con una herramienta de búsqueda web adjunta.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Para obtener la lista completa de las herramientas disponibles, consulte la introducción a las herramientas. Para conocer los procedimientos recomendados, consulte Procedimientos recomendados para usar herramientas.

Generar respuestas

La generación de respuestas invoca al agente. El agente usa su configuración y cualquier historial proporcionado (conversación o respuesta anterior) para realizar tareas mediante una llamada a modelos y herramientas. Como parte de la generación de respuestas, el agente anexa elementos a la conversación.

También puede generar una respuesta sin definir un agente. En este caso, proporcionará todas las configuraciones directamente en la solicitud y las usará solo para esa respuesta. Este enfoque es útil para escenarios sencillos con herramientas mínimas.

Además, puede bifurcar la conversación en el primer identificador de respuesta o en el segundo identificador de respuesta.

Genera una respuesta con un agente

En el ejemplo siguiente se genera una respuesta mediante una referencia del agente y, a continuación, se envía una pregunta de seguimiento mediante la respuesta anterior como contexto.

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

Cuando un agente usa herramientas durante la generación de respuestas, la salida de la respuesta contiene elementos de llamada de herramienta junto con el mensaje final. Puede iterar response.output para inspeccionar cada elemento y mostrar llamadas a herramientas (como búsquedas web, llamadas a funciones o búsquedas de archivos) antes de imprimir la respuesta de texto.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

Generar una respuesta sin almacenar

De forma predeterminada, el servicio almacena el historial de respuestas en el lado del servidor, para que pueda referirse a previous_response_id en el contexto de múltiples turnos. Si configura store en false, el servicio no persiste la respuesta. Debe trasladar el contexto de la conversación de manera autónoma pasando los resultados anteriores como entrada a la siguiente solicitud.

Este enfoque es útil cuando necesita un control total sobre el estado de la conversación, quiere minimizar los datos almacenados o trabajar en un entorno de retención de datos cero.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

Conversaciones y elementos de conversación

Las conversaciones son objetos duraderos con identificadores únicos. Después de la creación, puede reutilizarlos entre sesiones.

Las conversaciones almacenan elementos, que pueden incluir mensajes, llamadas a herramientas, salidas de herramientas y otros datos.

Creación de una conversación

En el ejemplo siguiente se crea una conversación con un mensaje de usuario inicial. Use el cliente openAI (obtenido del cliente del proyecto) para las conversaciones y respuestas.

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

Cuándo usar una conversación

Use una conversación cuando desee:

  • Continuidad multiturno: Mantenga un historial estable a través de turnos sin tener que reconstruir el contexto por sí mismo.
  • Continuidad entre sesiones: reutilice la misma conversación para un usuario que devuelva más adelante.
  • Depuración más sencilla: inspeccione lo que ha ocurrido a lo largo del tiempo (por ejemplo, llamadas a herramientas y resultados).

Cuando se usa una conversación para generar una respuesta (con o sin un agente), la conversación completa se proporciona como entrada al modelo. A continuación, la respuesta generada se anexa a la misma conversación.

Nota

Si la conversación supera el tamaño de contexto admitido del modelo, el modelo truncará automáticamente el contexto de entrada. La propia conversación no se trunca, sino que solo se usa un subconjunto de ella para generar la respuesta.

Si no crea una conversación, todavía puede crear flujos de varios turnos mediante la salida de una respuesta anterior como punto de partida para la siguiente solicitud. Este enfoque proporciona más flexibilidad que el patrón basado en subprocesos anterior, donde el estado estaba estrechamente acoplado a los objetos de subproceso. Para obtener instrucciones de migración, consulte Migración al SDK de agentes.

Tipos de elementos de conversación

Las conversaciones almacenan elementos en lugar de solo mensajes de chat. Los elementos capturan lo que sucedió durante la generación de respuesta para que el siguiente turno pueda reutilizar ese contexto.

Entre los tipos de elementos comunes se incluyen:

  • Elementos de mensaje: mensajes de usuario o asistente.
  • Elementos relacionados con llamadas de herramienta: registros de invocaciones de herramienta que el agente intentó.
  • Elementos de salida de la herramienta: salidas devueltas por herramientas (por ejemplo, resultados de recuperación).
  • Elementos de salida: el contenido de respuesta que se muestra de nuevo al usuario.

Agregar elementos a una conversación

Después de crear una conversación, use conversations.items.create() para agregar mensajes de usuario posteriores u otros elementos.

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

Uso de una conversación con un agente

Combine una conversación con una referencia de agente para mantener el historial en varios turnos. Agente procesa todos los elementos de la conversación y adjunta automáticamente el resultado.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

Para obtener ejemplos que muestran cómo funcionan juntas las conversaciones y las respuestas en el código, consulte Creación y uso de memoria en foundry Agent Service.

Streaming y respuestas en segundo plano

En el caso de las operaciones de larga duración, puede devolver resultados incrementalmente mediante streaming o ejecutar completamente en modo asincrónico mediante background. En estos casos, normalmente se supervisa la respuesta hasta que finaliza y, a continuación, se consumen los elementos de salida finales.

Transmisión de una respuesta

El streaming devuelve resultados parciales a medida que se generan. Este enfoque es útil para mostrar la salida a los usuarios en tiempo real.

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

Para obtener más información sobre los modos de respuesta y cómo consumir resultados, consulte API de respuestas.

Ejecución de un agente en modo en segundo plano

El modo de fondo ejecuta el agente de forma asincrónica, lo que resulta útil para tareas de ejecución prolongada, como el razonamiento complejo o la generación de imágenes. Establezca background en true y luego sondee el estado de la respuesta hasta que se complete.

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

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

Adjuntar memoria a un agente (versión preliminar)

La memoria proporciona a los agentes la capacidad de conservar información entre sesiones, por lo que pueden personalizar las respuestas y recuperar las preferencias del usuario a lo largo del tiempo. Sin memoria, cada conversación comienza desde cero.

Foundry Agent Service proporciona una solución de memoria administrada (versión preliminar) que se configura a través de almacenes de memoria. Un almacén de memoria define qué tipos de información debe conservar el agente. Adjunte un almacén de memoria al agente y el agente use memorias almacenadas como contexto adicional durante la generación de respuestas.

En el ejemplo siguiente se crea un almacén de memoria y se asocia a un agente.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

Para obtener detalles conceptuales, consulte Memory in Foundry Agent Service. Para obtener instrucciones de implementación completas, consulte Creación y uso de memoria.

Seguridad y control de datos

Dado que las conversaciones y respuestas pueden conservar las salidas de herramientas y contenido proporcionados por el usuario, trate los datos en tiempo de ejecución como los datos de la aplicación:

  • Evite almacenar secretos en mensajes o historial de conversaciones. Use conexiones y almacenes de secretos administrados en su lugar (por ejemplo, Set up a Key Vault connection).
  • Use privilegios mínimos para el acceso a herramientas. Cuando una herramienta accede a sistemas externos, el agente puede leer o enviar datos a través de esa herramienta.
  • Tener cuidado con los servicios que no son de Microsoft. Si el agente llama a herramientas respaldadas por servicios no proporcionados por Microsoft, algunos datos pueden ser transferidos a esos servicios. Para conocer las consideraciones relacionadas, consulte Descubrir herramientas en Foundry Tools.

Límites y restricciones

Los límites pueden depender del modelo, la región y las herramientas que adjunte (por ejemplo, la disponibilidad de streaming y la compatibilidad con herramientas). Para obtener disponibilidad y restricciones actuales para las respuestas, consulte Api de respuestas.

Contenido relacionado

  • Last updated on