Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
La abstracción del agente base expone varias opciones para ejecutar el agente. Los autores de llamadas pueden elegir proporcionar cero, uno o varios mensajes de entrada. Los autores de llamadas también pueden elegir entre streaming y no streaming. Vamos a profundizar en los distintos escenarios de uso.
Streaming y no streaming
Microsoft Agent Framework admite métodos de streaming y que no son de streaming para ejecutar un agente.
Para no streaming, use el RunAsync método .
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));
Para streaming, use el RunStreamingAsync método .
await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
Console.Write(update);
}
Para no streaming, use el run método .
result = await agent.run("What is the weather like in Amsterdam?")
print(result.text)
Para streaming, use el run_stream método .
async for update in agent.run_stream("What is the weather like in Amsterdam?"):
if update.text:
print(update.text, end="", flush=True)
Opciones de ejecución del agente
La abstracción del agente base permite pasar un objeto de opciones para cada ejecución del agente, pero la capacidad de personalizar una ejecución en el nivel de abstracción es bastante limitada. Los agentes pueden variar significativamente y, por lo tanto, no hay opciones de personalización realmente comunes.
En los casos en los que el autor de la llamada conoce el tipo del agente con el que trabaja, es posible pasar opciones específicas de tipo para permitir la personalización de la ejecución.
Por ejemplo, aquí el agente es y ChatClientAgent es posible pasar un ChatClientAgentRunOptions objeto que hereda de AgentRunOptions.
Esto permite al autor de la llamada proporcionar personalizados ChatOptions que se combinan con cualquier opción de nivel de agente antes de pasarse a la instancia de en la IChatClientChatClientAgent que se basa.
var chatOptions = new ChatOptions() { Tools = [AIFunctionFactory.Create(GetWeather)] };
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", options: new ChatClientAgentRunOptions(chatOptions)));
Los agentes de Python admiten pasar argumentos de palabra clave para personalizar cada ejecución. Las opciones específicas disponibles dependen del tipo de agente, pero ChatAgent admite muchos parámetros de cliente de chat que se pueden pasar a ambos run métodos y run_stream .
Entre las opciones comunes se ChatAgent incluyen:
-
max_tokens: número máximo de tokens que se van a generar -
temperature: controla la aleatoriedad en la generación de respuestas. -
model: invalide el modelo de esta ejecución específica. -
tools: se han agregado herramientas adicionales solo para esta ejecución. -
response_format: especifique el formato de respuesta (por ejemplo, salida estructurada)
# Run with custom options
result = await agent.run(
"What is the weather like in Amsterdam?",
temperature=0.3,
max_tokens=150,
model="gpt-4o"
)
# Streaming with custom options
async for update in agent.run_stream(
"Tell me a detailed weather forecast",
temperature=0.7,
tools=[additional_weather_tool]
):
if update.text:
print(update.text, end="", flush=True)
Cuando se proporcionan los valores predeterminados de nivel de agente y las opciones de nivel de ejecución, las opciones de nivel de ejecución tienen prioridad.
Tipos de respuesta
Tanto las respuestas de streaming como las que no son de streaming de los agentes contienen todo el contenido generado por el agente. El contenido puede incluir datos que no son el resultado (es decir, la respuesta a la pregunta del usuario) del agente. Algunos ejemplos de otros datos devueltos incluyen llamadas a la herramienta de función, resultados de llamadas a herramientas de función, texto de razonamiento, actualizaciones de estado y muchos más.
Dado que no todo el contenido devuelto es el resultado, es importante buscar tipos de contenido específicos al intentar aislar el resultado del otro contenido.
Para extraer el resultado del texto de una respuesta, es necesario agregar todos los TextContent elementos de todos los ChatMessages elementos.
Para simplificar esto, proporcionamos una Text propiedad en todos los tipos de respuesta que agregan todos .TextContent
Para el caso que no es de streaming, todo se devuelve en un AgentRunResponse objeto .
AgentRunResponse permite el acceso a los mensajes generados a través de la Messages propiedad .
var response = await agent.RunAsync("What is the weather like in Amsterdam?");
Console.WriteLine(response.Text);
Console.WriteLine(response.Messages.Count);
Para el caso de streaming, AgentRunResponseUpdate los objetos se transmiten a medida que se generan.
Cada actualización puede contener una parte del resultado del agente y también otros elementos de contenido.
De forma similar al caso que no es de streaming, es posible usar la Text propiedad para obtener la parte del resultado contenido en la actualización y profundizar en los detalles a través de la Contents propiedad .
await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
Console.WriteLine(update.Text);
Console.WriteLine(update.Contents.Count);
}
Para el caso que no es de streaming, todo se devuelve en un AgentRunResponse objeto .
AgentRunResponse permite el acceso a los mensajes generados a través de la messages propiedad .
Para extraer el resultado del texto de una respuesta, es necesario agregar todos los TextContent elementos de todos los ChatMessage elementos.
Para simplificar esto, proporcionamos una text propiedad en todos los tipos de respuesta que agregan todos .TextContent
response = await agent.run("What is the weather like in Amsterdam?")
print(response.text)
print(len(response.messages))
# Access individual messages
for message in response.messages:
print(f"Role: {message.role}, Text: {message.text}")
Para el caso de streaming, AgentRunResponseUpdate los objetos se transmiten a medida que se generan.
Cada actualización puede contener una parte del resultado del agente y también otros elementos de contenido.
De forma similar al caso que no es de streaming, es posible usar la text propiedad para obtener la parte del resultado contenido en la actualización y profundizar en los detalles a través de la contents propiedad .
async for update in agent.run_stream("What is the weather like in Amsterdam?"):
print(f"Update text: {update.text}")
print(f"Content count: {len(update.contents)}")
# Access individual content items
for content in update.contents:
if hasattr(content, 'text'):
print(f"Content: {content.text}")
Tipos de mensaje
La entrada y la salida de los agentes se representan como mensajes. Los mensajes se subdividirán en elementos de contenido.
Microsoft Agent Framework usa los tipos de mensaje y contenido proporcionados por las Microsoft.Extensions.AI abstracciones.
Los mensajes se representan mediante la ChatMessage clase y todas las clases de contenido heredan de la clase base AIContent .
Existen varias AIContent subclases que se usan para representar diferentes tipos de contenido. Algunos se proporcionan como parte de las abstracciones base Microsoft.Extensions.AI , pero los proveedores también pueden agregar sus propios tipos, cuando sea necesario.
Estos son algunos tipos populares de Microsoft.Extensions.AI:
| Tipo | Description |
|---|---|
| TextContent | Contenido textual que puede ser de entrada, por ejemplo, de un usuario o desarrollador, y la salida del agente. Normalmente contiene el resultado de texto de un agente. |
| DataContent | Contenido binario que puede ser tanto de entrada como de salida. Se puede usar para pasar datos de imagen, audio o vídeo al agente (donde se admite). |
| UriContent | Dirección URL que suele apuntar al contenido hospedado, como una imagen, audio o vídeo. |
| FunctionCallContent | Solicitud de un servicio de inferencia para invocar una herramienta de función. |
| FunctionResultContent | Resultado de una invocación de la herramienta de función. |
El marco del agente de Python usa tipos de contenido y mensajes del agent_framework paquete.
Los mensajes se representan mediante la ChatMessage clase y todas las clases de contenido heredan de la clase base BaseContent .
Existen varias BaseContent subclases que se usan para representar diferentes tipos de contenido:
| Tipo | Description |
|---|---|
TextContent |
Contenido textual que puede ser tanto de entrada como de salida del agente. Normalmente contiene el resultado de texto de un agente. |
DataContent |
Contenido binario representado como un URI de datos (por ejemplo, imágenes codificadas en base64). Se puede usar para pasar datos binarios hacia y desde el agente. |
UriContent |
URI que apunta al contenido hospedado, como una imagen, un archivo de audio o un documento. |
FunctionCallContent |
Solicitud de un servicio de IA para invocar una herramienta de función. |
FunctionResultContent |
Resultado de una invocación de la herramienta de función. |
ErrorContent |
Información de error cuando se produce un error en el procesamiento. |
UsageContent |
Información de facturación y uso de tokens del servicio de IA. |
Aquí se muestra cómo trabajar con diferentes tipos de contenido:
from agent_framework import ChatMessage, TextContent, DataContent, UriContent
# Create a text message
text_message = ChatMessage(role="user", text="Hello!")
# Create a message with multiple content types
image_data = b"..." # your image bytes
mixed_message = ChatMessage(
role="user",
contents=[
TextContent("Analyze this image:"),
DataContent(data=image_data, media_type="image/png"),
]
)
# Access content from responses
response = await agent.run("Describe the image")
for message in response.messages:
for content in message.contents:
if isinstance(content, TextContent):
print(f"Text: {content.text}")
elif isinstance(content, DataContent):
print(f"Data URI: {content.uri}")
elif isinstance(content, UriContent):
print(f"External URI: {content.uri}")