Agentes em execução

A abstração base do Agent expõe várias opções para executar o agente. Os chamadores podem optar por fornecer zero, uma ou muitas mensagens de entrada. Os chamadores também podem escolher entre streaming e não streaming. Vamos nos aprofundar nos diferentes cenários de uso.

Streaming e não streaming

O Microsoft Agent Framework oferece suporte a métodos de streaming e não streaming para executar um agente.

Para não-streaming, use o RunAsync método.

Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?"));

Para streaming, use o RunStreamingAsync método.

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.Write(update);
}

Para não-streaming, use o run método.

result = await agent.run("What is the weather like in Amsterdam?")
print(result.text)

Para streaming, use o 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)

Opções de execução do agente

A abstração do agente base permite passar um objeto de opções para cada execução do agente, no entanto, a capacidade de personalizar uma execução no nível de abstração é bastante limitada. Os agentes podem variar significativamente e, portanto, não há opções de personalização realmente comuns.

Para os casos em que o chamador sabe o tipo de agente com o qual está trabalhando, é possível passar opções específicas do tipo para permitir a personalização da execução.

Por exemplo, aqui o agente é um ChatClientAgent e é possível passar um ChatClientAgentRunOptions objeto que herda de AgentRunOptions. Isso permite que o chamador forneça opções personalizadas ChatOptions que são mescladas com quaisquer opções de nível de agente antes de serem passadas para o IChatClient qual o ChatClientAgent é construído.

var chatOptions = new ChatOptions() { Tools = [AIFunctionFactory.Create(GetWeather)] };
Console.WriteLine(await agent.RunAsync("What is the weather like in Amsterdam?", options: new ChatClientAgentRunOptions(chatOptions)));

Os agentes Python suportam a passagem de argumentos de palavra-chave para personalizar cada execução. As opções específicas disponíveis dependem do tipo de agente, mas ChatAgent suportam muitos parâmetros do cliente de chat que podem ser passados para ambos os runrun_stream métodos.

As opções comuns incluem ChatAgent :

max_tokens: Número máximo de tokens a gerar
temperature: Controla a aleatoriedade na geração de respostas
model: Substituir o modelo para esta execução específica
tools: Adicionar ferramentas adicionais apenas para esta execução
response_format: Especifique o formato da resposta (por exemplo, saída estruturada)

# 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)

Quando os padrões no nível do agente e as opções no nível de execução são fornecidos, as opções no nível de execução têm precedência.

Tipos de resposta

As respostas de streaming e não streaming dos agentes contêm todo o conteúdo produzido pelo agente. O conteúdo pode incluir dados que não são o resultado (ou seja, a resposta à pergunta do usuário) do agente. Exemplos de outros dados retornados incluem chamadas de ferramentas de função, resultados de chamadas de ferramentas de função, texto de raciocínio, atualizações de status e muito mais.

Como nem todo o conteúdo retornado é o resultado, é importante procurar tipos de conteúdo específicos ao tentar isolar o resultado do outro conteúdo.

Para extrair o resultado do texto de uma resposta, todos os TextContent itens de todos os ChatMessages itens precisam ser agregados. Para simplificar isso, fornecemos uma Text propriedade em todos os tipos de resposta que agrega todos os TextContent.

Para o caso de não-streaming, tudo é retornado em um AgentRunResponse objeto. AgentRunResponse Permite o acesso às mensagens produzidas através da Messages propriedade.

var response = await agent.RunAsync("What is the weather like in Amsterdam?");
Console.WriteLine(response.Text);
Console.WriteLine(response.Messages.Count);

Para o caso de streaming, AgentRunResponseUpdate os objetos são transmitidos à medida que são produzidos. Cada atualização pode conter uma parte do resultado do agente e também vários outros itens de conteúdo. Semelhante ao caso sem streaming, é possível usar a Text propriedade para obter a parte do resultado contida na atualização e detalhar os detalhes por meio da Contents propriedade.

await foreach (var update in agent.RunStreamingAsync("What is the weather like in Amsterdam?"))
{
    Console.WriteLine(update.Text);
    Console.WriteLine(update.Contents.Count);
}

Para o caso de não-streaming, tudo é retornado em um AgentRunResponse objeto. AgentRunResponse Permite o acesso às mensagens produzidas através da messages propriedade.

Para extrair o resultado do texto de uma resposta, todos os TextContent itens de todos os ChatMessage itens precisam ser agregados. Para simplificar isso, fornecemos uma text propriedade em todos os tipos de resposta que agrega todos os 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 o caso de streaming, AgentRunResponseUpdate os objetos são transmitidos à medida que são produzidos. Cada atualização pode conter uma parte do resultado do agente e também vários outros itens de conteúdo. Semelhante ao caso sem streaming, é possível usar a text propriedade para obter a parte do resultado contida na atualização e detalhar os detalhes por meio da contents propriedade.

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 mensagem

A entrada e a saída dos agentes são representadas como mensagens. As mensagens são subdivididas em itens de conteúdo.

O Microsoft Agent Framework usa os tipos de mensagem e conteúdo fornecidos pelas Microsoft.Extensions.AI abstrações. As mensagens são representadas ChatMessage pela classe e todas as classes de conteúdo herdam da classe base AIContent .

Existem várias AIContent subclasses que são usadas para representar diferentes tipos de conteúdo. Alguns são fornecidos como parte das abstrações de base Microsoft.Extensions.AI , mas os provedores também podem adicionar seus próprios tipos, quando necessário.

Aqui estão alguns tipos populares de Microsoft.Extensions.AI:

Tipo	Description
Conteúdo de texto	Conteúdo textual que pode ser tanto de entrada, por exemplo, de um usuário ou desenvolvedor, quanto de saída do agente. Normalmente, contém o resultado de texto de um agente.
Conteúdo de dados	Conteúdo binário que pode ser entrada e saída. Pode ser usado para passar dados de imagem, áudio ou vídeo de e para o agente (quando suportado).
UriContent	Um url que normalmente aponta para conteúdo hospedado, como uma imagem, áudio ou vídeo.
FunctionCallContent	Uma solicitação de um serviço de inferência para invocar uma ferramenta de função.
FunctionResultContent	O resultado de uma chamada de ferramenta de função.

O Python Agent Framework usa tipos de mensagem e conteúdo do agent_framework pacote. As mensagens são representadas ChatMessage pela classe e todas as classes de conteúdo herdam da classe base BaseContent .

Existem várias BaseContent subclasses que são usadas para representar diferentes tipos de conteúdo:

Tipo	Description
`TextContent`	Conteúdo textual que pode ser entrada e saída do agente. Normalmente, contém o resultado de texto de um agente.
`DataContent`	Conteúdo binário representado como um URI de dados (por exemplo, imagens codificadas em base64). Pode ser usado para passar dados binários de e para o agente.
`UriContent`	Um URI que aponta para conteúdo hospedado, como uma imagem, arquivo de áudio ou documento.
`FunctionCallContent`	Uma solicitação de um serviço de IA para invocar uma ferramenta de função.
`FunctionResultContent`	O resultado de uma chamada de ferramenta de função.
`ErrorContent`	Informações de erro quando o processamento falha.
`UsageContent`	Informações de uso e faturamento de tokens do serviço de IA.

Veja como trabalhar com diferentes tipos de conteúdo:

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}")

Próximos passos

Conversas com Múltiplas Voltas e Threading

Feedback

Esta página foi útil?

Last updated on 2025-10-01