ai-agents-for-beginners

Explorando o Microsoft Agent Framework

Agent Framework

Introdução

Esta lição abordará:

Objetivos de Aprendizagem

Após concluir esta lição, você saberá como:

Exemplos de Código

Exemplos de código para Microsoft Agent Framework (MAF) podem ser encontrados neste repositório nos arquivos xx-python-agent-framework e xx-dotnet-agent-framework.

Compreendendo o Microsoft Agent Framework

Framework Intro

O Microsoft Agent Framework (MAF) é baseado na experiência e nos aprendizados do Semantic Kernel e AutoGen. Ele oferece flexibilidade para atender à ampla variedade de casos de uso de agentes observados em ambientes de produção e pesquisa, incluindo:

Para entregar Agentes de IA em Produção, o MAF também inclui recursos para:

O Microsoft Agent Framework também se concentra em ser interoperável por:

Vamos ver como esses recursos são aplicados a alguns dos conceitos fundamentais do Microsoft Agent Framework.

Conceitos Fundamentais do Microsoft Agent Framework

Agentes

Agent Framework

Criando Agentes

A criação de agentes é feita definindo o serviço de inferência (Provedor LLM), um conjunto de instruções para o Agente de IA seguir e um nome atribuído:

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at recommending trips to customers based on their preferences.", name="TripRecommender" )

O exemplo acima usa Azure OpenAI, mas agentes podem ser criados usando uma variedade de serviços, incluindo Azure AI Foundry Agent Service:

AzureAIAgentClient(async_credential=credential).create_agent( name="HelperAgent", instructions="You are a helpful assistant." ) as agent

APIs de Responses e ChatCompletion do OpenAI

agent = OpenAIResponsesClient().create_agent( name="WeatherBot", instructions="You are a helpful weather assistant.", )

agent = OpenAIChatClient().create_agent( name="HelpfulAssistant", instructions="You are a helpful assistant.", )

ou agentes remotos usando o protocolo A2A:

agent = A2AAgent( name=agent_card.name, description=agent_card.description, agent_card=agent_card, url="https://your-a2a-agent-host" )

Executando Agentes

Os agentes são executados usando os métodos .run ou .run_stream para respostas não-streaming ou streaming.

result = await agent.run("What are good places to visit in Amsterdam?")
print(result.text)

async for update in agent.run_stream("What are the good places to visit in Amsterdam?"):
    if update.text:
        print(update.text, end="", flush=True)

Cada execução de agente também pode ter opções para personalizar parâmetros, como max_tokens usados pelo agente, tools que o agente pode chamar e até mesmo o próprio model usado pelo agente.

Isso é útil em casos onde modelos ou ferramentas específicas são necessárias para concluir a tarefa do usuário.

Ferramentas

Ferramentas podem ser definidas tanto ao definir o agente:

def get_attractions( location: Annotated[str, Field(description="The location to get the top tourist attractions for")], ) -> str: """Get the top tourist attractions for a given location.""" return f"The top attractions for {location} are." 


# When creating a ChatAgent directly 

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

quanto ao executar o agente:


result1 = await agent.run( "What's the best place to visit in Seattle?", tools=[get_attractions] # Tool provided for this run only )

Threads de Agentes

Threads de Agentes são usados para lidar com conversas de múltiplas interações. Threads podem ser criados de duas formas:

Para criar um thread, o código é assim:

# Create a new thread. 
thread = agent.get_new_thread() # Run the agent with the thread. 
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Você pode então serializar o thread para ser armazenado para uso posterior:

# Create a new thread. 
thread = agent.get_new_thread() 

# Run the agent with the thread. 

response = await agent.run("Hello, how are you?", thread=thread) 

# Serialize the thread for storage. 

serialized_thread = await thread.serialize() 

# Deserialize the thread state after loading from storage. 

resumed_thread = await agent.deserialize_thread(serialized_thread)

Middleware de Agentes

Agentes interagem com ferramentas e LLMs para concluir as tarefas dos usuários. Em certos cenários, queremos executar ou rastrear ações entre essas interações. O middleware de agentes nos permite fazer isso por meio de:

Middleware de Função

Este middleware nos permite executar uma ação entre o agente e uma função/ferramenta que ele chamará. Um exemplo de uso seria quando você deseja registrar informações sobre a chamada da função.

No código abaixo, next define se o próximo middleware ou a função real deve ser chamado.

async def logging_function_middleware(
    context: FunctionInvocationContext,
    next: Callable[[FunctionInvocationContext], Awaitable[None]],
) -> None:
    """Function middleware that logs function execution."""
    # Pre-processing: Log before function execution
    print(f"[Function] Calling {context.function.name}")

    # Continue to next middleware or function execution
    await next(context)

    # Post-processing: Log after function execution
    print(f"[Function] {context.function.name} completed")

Middleware de Chat

Este middleware nos permite executar ou registrar uma ação entre o agente e as solicitações entre o LLM.

Isso contém informações importantes, como as messages que estão sendo enviadas ao serviço de IA.

async def logging_chat_middleware(
    context: ChatContext,
    next: Callable[[ChatContext], Awaitable[None]],
) -> None:
    """Chat middleware that logs AI interactions."""
    # Pre-processing: Log before AI call
    print(f"[Chat] Sending {len(context.messages)} messages to AI")

    # Continue to next middleware or AI service
    await next(context)

    # Post-processing: Log after AI response
    print("[Chat] AI response received")

Memória de Agentes

Como abordado na lição de Agentic Memory, a memória é um elemento importante para permitir que o agente opere em diferentes contextos. O MAF oferece vários tipos de memórias:

Armazenamento em Memória

Esta é a memória armazenada em threads durante o tempo de execução da aplicação.

# Create a new thread. 
thread = agent.get_new_thread() # Run the agent with the thread. 
response = await agent.run("Hello, I am here to help you book travel. Where would you like to go?", thread=thread)

Mensagens Persistentes

Esta memória é usada ao armazenar o histórico de conversas entre diferentes sessões. É definida usando o chat_message_store_factory:

from agent_framework import ChatMessageStore

# Create a custom message store
def create_message_store():
    return ChatMessageStore()

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a Travel assistant.",
    chat_message_store_factory=create_message_store
)

Memória Dinâmica

Esta memória é adicionada ao contexto antes de os agentes serem executados. Essas memórias podem ser armazenadas em serviços externos, como mem0:

from agent_framework.mem0 import Mem0Provider

# Using Mem0 for advanced memory capabilities
memory_provider = Mem0Provider(
    api_key="your-mem0-api-key",
    user_id="user_123",
    application_id="my_app"
)

agent = ChatAgent(
    chat_client=OpenAIChatClient(),
    instructions="You are a helpful assistant with memory.",
    context_providers=memory_provider
)

Observabilidade de Agentes

A observabilidade é importante para construir sistemas de agentes confiáveis e fáceis de manter. O MAF integra-se ao OpenTelemetry para fornecer rastreamento e medidores para melhor observabilidade.

from agent_framework.observability import get_tracer, get_meter

tracer = get_tracer()
meter = get_meter()
with tracer.start_as_current_span("my_custom_span"):
    # do something
    pass
counter = meter.create_counter("my_custom_counter")
counter.add(1, {"key": "value"})

Fluxos de Trabalho

O MAF oferece fluxos de trabalho que são etapas pré-definidas para concluir uma tarefa e incluem agentes de IA como componentes nessas etapas.

Os fluxos de trabalho são compostos por diferentes componentes que permitem melhor controle de fluxo. Eles também possibilitam orquestração de múltiplos agentes e checkpointing para salvar estados de fluxo de trabalho.

Os componentes principais de um fluxo de trabalho são:

Executores

Executores recebem mensagens de entrada, realizam suas tarefas atribuídas e produzem uma mensagem de saída. Isso move o fluxo de trabalho em direção à conclusão da tarefa maior. Os executores podem ser agentes de IA ou lógica personalizada.

Edges

Edges são usados para definir o fluxo de mensagens em um fluxo de trabalho. Eles podem ser:

Edges Diretos - Conexões simples de um para um entre executores:

from agent_framework import WorkflowBuilder

builder = WorkflowBuilder()
builder.add_edge(source_executor, target_executor)
builder.set_start_executor(source_executor)
workflow = builder.build()

Edges Condicionais - Ativados após uma condição específica ser atendida. Por exemplo, quando quartos de hotel estão indisponíveis, um executor pode sugerir outras opções.

Edges Switch-case - Roteiam mensagens para diferentes executores com base em condições definidas. Por exemplo, se um cliente de viagem tem acesso prioritário, suas tarefas serão tratadas por outro fluxo de trabalho.

Edges Fan-out - Enviam uma mensagem para vários destinos.

Edges Fan-in - Coletam várias mensagens de diferentes executores e enviam para um único destino.

Eventos

Para oferecer melhor observabilidade nos fluxos de trabalho, o MAF oferece eventos integrados para execução, incluindo:

Migrando de Outros Frameworks (Semantic Kernel e AutoGen)

Diferenças entre MAF e Semantic Kernel

Criação Simplificada de Agentes

O Semantic Kernel exige a criação de uma instância de Kernel para cada agente. O MAF utiliza uma abordagem simplificada por meio de extensões para os principais provedores.

agent = AzureOpenAIChatClient(credential=AzureCliCredential()).create_agent( instructions="You are good at reccomending trips to customers based on their preferences.", name="TripRecommender" )

Criação de Threads de Agentes

O Semantic Kernel exige que os threads sejam criados manualmente. No MAF, o agente é diretamente atribuído a um thread.

thread = agent.get_new_thread() # Run the agent with the thread.

Registro de Ferramentas

No Semantic Kernel, as ferramentas são registradas no Kernel, que é então passado para o agente. No MAF, as ferramentas são registradas diretamente durante o processo de criação do agente.

agent = ChatAgent( chat_client=OpenAIChatClient(), instructions="You are a helpful assistant", tools=[get_attractions]

Diferenças entre MAF e AutoGen

Equipes vs Fluxos de Trabalho

Teams são a estrutura de eventos para atividades orientadas por eventos com agentes no AutoGen. O MAF usa Workflows, que roteiam dados para executores por meio de uma arquitetura baseada em gráficos.

Criação de Ferramentas

O AutoGen usa FunctionTool para encapsular funções que os agentes podem chamar. O MAF usa @ai_function, que opera de forma semelhante, mas também infere automaticamente os esquemas para cada função.

Comportamento de Agentes

Os agentes são agentes de uma única interação por padrão no AutoGen, a menos que max_tool_iterations seja configurado para um valor maior. No MAF, o ChatAgent é multi-interação por padrão, o que significa que continuará chamando ferramentas até que a tarefa do usuário seja concluída.

Exemplos de Código

Exemplos de código para o Microsoft Agent Framework podem ser encontrados neste repositório nos arquivos xx-python-agent-framework e xx-dotnet-agent-framework.

Tem Mais Perguntas Sobre o Microsoft Agent Framework?

Participe do Discord do Azure AI Foundry para se conectar com outros aprendizes, participar de horários de atendimento e tirar suas dúvidas sobre Agentes de IA.

Aviso Legal:
Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos para garantir a precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autoritativa. Para informações críticas, recomenda-se a tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.

This site is open source. Improve this page.