Compartir por

Creación con agentes, conversaciones y respuestas

El servicio Microsoft Foundry Agent usa tres componentes principales del entorno de ejecución (agentes, conversaciones y respuestas) para impulsar interacciones con estado y multiturno. Un agente define qué modelo, instrucciones y herramientas se van a usar. Una conversación conserva 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 usa una conversación, mantenga el contexto utilizando el resultado de una respuesta anterior.
  • Generar una respuesta: el 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 siguiente diagrama se ilustra cómo interactúan estos componentes en un bucle típico de agente.

Diagrama que muestra el bucle de tiempo de ejecución del agente: una definición del agente y la generación opcional de respuestas alimentadas por el historial de conversaciones, que puede llamar a herramientas, incorporar elementos de vuelta a la conversación y generar elementos de salida que usted muestra 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.

Prerrequisitos

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

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

Crear 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 versiones y con nombre 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 respuesta con un nombre, modelo e 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.

Generar 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, por lo que puede hacer referencia al previous_response_id para el contexto de varios turnos. Si establece store en false, el servicio no conserva la respuesta. Debe arrastrar el contexto de la conversación por su cuenta, pasando los elementos de salida 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 recompilar el contexto usted 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 y salidas de herramientas).

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 desarrollar flujos de varios turnos utilizando 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 de invocación de herramientas: registros de invocaciones de herramienta que intentó el agente.
  • 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 entre varios turnos. El agente procesa todos los elementos de la conversación y agrega 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 de manera incremental utilizando streaming o realizar una ejecución completamente asincrónica mediante el modo 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)

Asociar 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. Anexe un almacén de memoria al agente, y el agente utilizará las memorias almacenadas como contexto adicional durante la generación de respuestas.

En el ejemplo siguiente se crea un almacén de memoria y se adjunta 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).
  • Utilice el privilegio mínimo 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.
  • Tenga cuidado con los servicios que no son de Microsoft. Si el agente llama a herramientas respaldadas por servicios que no son de Microsoft, algunos datos pueden fluir 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