Agentes em execução

A abstração base do Agente 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 dá 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 de 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 casos em que o chamador sabe o tipo do agente com o qual está trabalhando, é possível passar opções específicas de 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 um personalizado ChatOptions que seja mesclado com todas as opções de nível de agente antes de ser passado para o IChatClient qual ele ChatClientAgent foi criado.

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 do Python dão suporte à 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 dão suporte a muitos parâmetros de cliente de chat que podem ser passados para ambos run e run_stream métodos.

Opções comuns para ChatAgent incluir:

max_tokens: número máximo de tokens a serem gerados
temperature: controla a aleatoriedade na geração de resposta
model: substitua o modelo para esta execução específica
tools: adicionar ferramentas adicionais somente para esta execução
response_format: especifique o formato de 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 de nível de agente e as opções de nível de execução são fornecidos, as opções de nível de execução têm precedência.

Tipos de resposta

As respostas de streaming e não streaming de 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 para a pergunta do usuário) do agente. Exemplos de outros dados retornados incluem chamadas de ferramenta de função, resultados de chamadas de ferramenta 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 agregam todos.TextContent

Para o caso de não streaming, tudo é retornado em um AgentRunResponse objeto. AgentRunResponse permite o acesso às mensagens produzidas por meio 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 conforme 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 de não 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 por meio 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 agregam 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 o caso de streaming, AgentRunResponseUpdate os objetos são transmitidos conforme 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 de não 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 pela ChatMessage 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 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
TextContent	Conteúdo textual que pode ser de entrada, por exemplo, de um usuário ou desenvolvedor e saída do agente. Normalmente, contém o resultado do texto de um agente.
DataContent	Conteúdo binário que pode ser de entrada e saída. Pode ser usado para passar dados de imagem, áudio ou vídeo de e para o agente (onde há suporte).
UriContent	Uma URL que normalmente aponta para o conteúdo hospedado, como uma imagem, áudio ou vídeo.
FunctionCallContent	Uma solicitação por um serviço de inferência para invocar uma ferramenta de função.
FunctionResultContent	O resultado de uma invocação 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 pela ChatMessage 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 tanto de entrada quanto de saída do agente. Normalmente, contém o resultado do 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 o conteúdo hospedado, como uma imagem, um arquivo de áudio ou um documento.
`FunctionCallContent`	Uma solicitação de um serviço de IA para invocar uma ferramenta de função.
`FunctionResultContent`	O resultado de uma invocação de ferramenta de função.
`ErrorContent`	Informações de erro ao processar falha.
`UsageContent`	Informações de uso e cobrança de token 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óximas etapas

Conversas e threading de várias voltas

Comentários

Esta página foi útil?

Last updated on 2025-10-01