# Metacognição em Agentes de IA

## Introdução

Bem-vindo à lição sobre metacognição em agentes de IA! Este capítulo foi projetado para iniciantes curiosos sobre como agentes de IA podem pensar sobre seus próprios processos de pensamento. Ao final desta lição, você entenderá os conceitos-chave e estará equipado com exemplos práticos para aplicar metacognição no design de agentes de IA.

## Objetivos de Aprendizagem

Após completar esta lição, você será capaz de:

1. Compreender as implicações de loops de raciocínio em definições de agentes.
2. Usar técnicas de planejamento e avaliação para ajudar agentes a se autocorrigirem.
3. Criar seus próprios agentes capazes de manipular código para realizar tarefas.

## Introdução à Metacognição

Metacognição refere-se aos processos cognitivos de ordem superior que envolvem pensar sobre o próprio pensamento. Para agentes de IA, isso significa ser capaz de avaliar e ajustar suas ações com base na autoconsciência e em experiências passadas.

### O que é Metacognição?

Metacognição, ou "pensar sobre o pensamento", é um processo cognitivo de ordem superior que envolve autoconsciência e autorregulação dos próprios processos cognitivos. No domínio da IA, a metacognição capacita agentes a avaliar e adaptar suas estratégias e ações, levando a capacidades aprimoradas de resolução de problemas e tomada de decisão. Ao entender a metacognição, você pode projetar agentes de IA que sejam não apenas mais inteligentes, mas também mais adaptáveis e eficientes.

### Importância da Metacognição em Agentes de IA

A metacognição desempenha um papel crucial no design de agentes de IA por várias razões:

![Importância da Metacognição](../../../09-metacognition/images/importance-of-metacognition.png)

- **Autorreflexão**: Agentes podem avaliar seu próprio desempenho e identificar áreas para melhoria.
- **Adaptabilidade**: Agentes podem modificar suas estratégias com base em experiências passadas e ambientes em mudança.
- **Correção de Erros**: Agentes podem detectar e corrigir erros de forma autônoma, levando a resultados mais precisos.
- **Gestão de Recursos**: Agentes podem otimizar o uso de recursos, como tempo e poder computacional, planejando e avaliando suas ações.

## Componentes de um Agente de IA

Antes de mergulhar nos processos metacognitivos, é essencial entender os componentes básicos de um agente de IA. Um agente de IA normalmente consiste em:

- **Persona**: A personalidade e características do agente, que definem como ele interage com os usuários.
- **Ferramentas**: As capacidades e funções que o agente pode executar.
- **Habilidades**: O conhecimento e a expertise que o agente possui.

Esses componentes trabalham juntos para criar uma "unidade de expertise" que pode realizar tarefas específicas.

**Exemplo**: Considere um agente de viagens, que não apenas planeja suas férias, mas também ajusta seu percurso com base em dados em tempo real e experiências de jornadas de clientes anteriores.

### Exemplo: Metacognição em um Serviço de Agente de Viagens

Imagine que você está projetando um serviço de agente de viagens movido por IA. Este agente, "Agente de Viagens", auxilia os usuários no planejamento de suas férias. Para incorporar metacognição, o Agente de Viagens precisa avaliar e ajustar suas ações com base na autoconsciência e em experiências passadas. Veja como a metacognição pode desempenhar um papel:

#### Tarefa Atual

A tarefa atual é ajudar um usuário a planejar uma viagem para Paris.

#### Etapas para Completar a Tarefa

1. **Coletar Preferências do Usuário**: Perguntar ao usuário sobre suas datas de viagem, orçamento, interesses (por exemplo, museus, culinária, compras) e quaisquer requisitos específicos.
2. **Recuperar Informações**: Buscar opções de voos, acomodações, atrações e restaurantes que correspondam às preferências do usuário.
3. **Gerar Recomendações**: Fornecer um itinerário personalizado com detalhes de voos, reservas de hotéis e atividades sugeridas.
4. **Ajustar com Base no Feedback**: Solicitar feedback do usuário sobre as recomendações e fazer os ajustes necessários.

#### Recursos Necessários

- Acesso a bancos de dados de reservas de voos e hotéis.
- Informações sobre atrações e restaurantes em Paris.
- Dados de feedback de usuários de interações anteriores.

#### Experiência e Autorreflexão

O Agente de Viagens usa metacognição para avaliar seu desempenho e aprender com experiências passadas. Por exemplo:

1. **Analisando Feedback do Usuário**: O Agente de Viagens revisa o feedback do usuário para determinar quais recomendações foram bem recebidas e quais não foram. Ele ajusta suas sugestões futuras de acordo.
2. **Adaptabilidade**: Se um usuário mencionou anteriormente que não gosta de lugares lotados, o Agente de Viagens evitará recomendar pontos turísticos populares durante horários de pico no futuro.
3. **Correção de Erros**: Se o Agente de Viagens cometeu um erro em uma reserva anterior, como sugerir um hotel que estava totalmente reservado, ele aprende a verificar a disponibilidade de forma mais rigorosa antes de fazer recomendações.

#### Exemplo Prático para Desenvolvedores

Aqui está um exemplo simplificado de como o código do Agente de Viagens poderia ser estruturado ao incorporar metacognição:

```python
class Travel_Agent:
    def __init__(self):
        self.user_preferences = {}
        self.experience_data = []

    def gather_preferences(self, preferences):
        self.user_preferences = preferences

    def retrieve_information(self):
        # Search for flights, hotels, and attractions based on preferences
        flights = search_flights(self.user_preferences)
        hotels = search_hotels(self.user_preferences)
        attractions = search_attractions(self.user_preferences)
        return flights, hotels, attractions

    def generate_recommendations(self):
        flights, hotels, attractions = self.retrieve_information()
        itinerary = create_itinerary(flights, hotels, attractions)
        return itinerary

    def adjust_based_on_feedback(self, feedback):
        self.experience_data.append(feedback)
        # Analyze feedback and adjust future recommendations
        self.user_preferences = adjust_preferences(self.user_preferences, feedback)

# Example usage
travel_agent = Travel_Agent()
preferences = {
    "destination": "Paris",
    "dates": "2025-04-01 to 2025-04-10",
    "budget": "moderate",
    "interests": ["museums", "cuisine"]
}
travel_agent.gather_preferences(preferences)
itinerary = travel_agent.generate_recommendations()
print("Suggested Itinerary:", itinerary)
feedback = {"liked": ["Louvre Museum"], "disliked": ["Eiffel Tower (too crowded)"]}
travel_agent.adjust_based_on_feedback(feedback)
```

#### Por que a Metacognição é Importante

- **Autorreflexão**: Agentes podem analisar seu desempenho e identificar áreas para melhoria.
- **Adaptabilidade**: Agentes podem modificar estratégias com base em feedback e condições em mudança.
- **Correção de Erros**: Agentes podem detectar e corrigir erros de forma autônoma.
- **Gestão de Recursos**: Agentes podem otimizar o uso de recursos, como tempo e poder computacional.

Ao incorporar metacognição, o Agente de Viagens pode fornecer recomendações de viagem mais personalizadas e precisas, melhorando a experiência geral do usuário.

---

## 2. Planejamento em Agentes

Planejamento é um componente crítico do comportamento de agentes de IA. Envolve delinear os passos necessários para alcançar um objetivo, considerando o estado atual, recursos e possíveis obstáculos.

### Elementos do Planejamento

- **Tarefa Atual**: Definir claramente a tarefa.
- **Etapas para Completar a Tarefa**: Dividir a tarefa em etapas gerenciáveis.
- **Recursos Necessários**: Identificar os recursos necessários.
- **Experiência**: Utilizar experiências passadas para informar o planejamento.

**Exemplo**: Aqui estão os passos que o Agente de Viagens precisa seguir para ajudar um usuário a planejar sua viagem de forma eficaz:

### Etapas para o Agente de Viagens

1. **Coletar Preferências do Usuário**
   - Perguntar ao usuário detalhes sobre suas datas de viagem, orçamento, interesses e quaisquer requisitos específicos.
   - Exemplos: "Quando você planeja viajar?" "Qual é a sua faixa de orçamento?" "Quais atividades você gosta de fazer nas férias?"

2. **Recuperar Informações**
   - Buscar opções de viagem relevantes com base nas preferências do usuário.
   - **Voos**: Procurar voos disponíveis dentro do orçamento e datas preferidas do usuário.
   - **Acomodações**: Encontrar hotéis ou propriedades para aluguel que correspondam às preferências do usuário em localização, preço e comodidades.
   - **Atrações e Restaurantes**: Identificar atrações populares, atividades e opções de refeições que estejam alinhadas com os interesses do usuário.

3. **Gerar Recomendações**
   - Compilar as informações recuperadas em um itinerário personalizado.
   - Fornecer detalhes como opções de voos, reservas de hotéis e atividades sugeridas, garantindo que as recomendações sejam adaptadas às preferências do usuário.

4. **Apresentar o Itinerário ao Usuário**
   - Compartilhar o itinerário proposto com o usuário para sua revisão.
   - Exemplo: "Aqui está um itinerário sugerido para sua viagem a Paris. Inclui detalhes de voos, reservas de hotéis e uma lista de atividades e restaurantes recomendados. Deixe-me saber o que acha!"

5. **Coletar Feedback**
   - Perguntar ao usuário sobre o itinerário proposto.
   - Exemplos: "Você gostou das opções de voos?" "O hotel é adequado às suas necessidades?" "Há alguma atividade que você gostaria de adicionar ou remover?"

6. **Ajustar com Base no Feedback**
   - Modificar o itinerário com base no feedback do usuário.
   - Fazer as alterações necessárias nas recomendações de voos, acomodações e atividades para melhor atender às preferências do usuário.

7. **Confirmação Final**
   - Apresentar o itinerário atualizado ao usuário para confirmação final.
   - Exemplo: "Fiz os ajustes com base no seu feedback. Aqui está o itinerário atualizado. Tudo parece bom para você?"

8. **Reservar e Confirmar**
   - Após a aprovação do usuário, proceder com a reserva de voos, acomodações e quaisquer atividades pré-planejadas.
   - Enviar os detalhes de confirmação ao usuário.

9. **Fornecer Suporte Contínuo**
   - Permanecer disponível para ajudar o usuário com quaisquer alterações ou solicitações adicionais antes e durante a viagem.
   - Exemplo: "Se precisar de mais assistência durante sua viagem, sinta-se à vontade para entrar em contato comigo a qualquer momento!"

### Exemplo de Interação

```python
class Travel_Agent:
    def __init__(self):
        self.user_preferences = {}
        self.experience_data = []

    def gather_preferences(self, preferences):
        self.user_preferences = preferences

    def retrieve_information(self):
        flights = search_flights(self.user_preferences)
        hotels = search_hotels(self.user_preferences)
        attractions = search_attractions(self.user_preferences)
        return flights, hotels, attractions

    def generate_recommendations(self):
        flights, hotels, attractions = self.retrieve_information()
        itinerary = create_itinerary(flights, hotels, attractions)
        return itinerary

    def adjust_based_on_feedback(self, feedback):
        self.experience_data.append(feedback)
        self.user_preferences = adjust_preferences(self.user_preferences, feedback)

# Example usage within a booing request
travel_agent = Travel_Agent()
preferences = {
    "destination": "Paris",
    "dates": "2025-04-01 to 2025-04-10",
    "budget": "moderate",
    "interests": ["museums", "cuisine"]
}
travel_agent.gather_preferences(preferences)
itinerary = travel_agent.generate_recommendations()
print("Suggested Itinerary:", itinerary)
feedback = {"liked": ["Louvre Museum"], "disliked": ["Eiffel Tower (too crowded)"]}
travel_agent.adjust_based_on_feedback(feedback)
```
```
```markdown
O Agente de Viagens formula novas consultas de pesquisa com base no feedback do usuário.
- Exemplo: ```python
       if "disliked" in feedback:
           preferences["avoid"] = feedback["disliked"]
       ```
- **Ferramenta**: O Agente de Viagens utiliza algoritmos para classificar e filtrar novos resultados de pesquisa, enfatizando a relevância com base no feedback do usuário.
- Exemplo: ```python
       new_attractions = search_attractions(preferences)
       new_itinerary = create_itinerary(flights, hotels, new_attractions)
       print("Updated Itinerary:", new_itinerary)
       ```
- **Avaliação**: O Agente de Viagens avalia continuamente a relevância e a precisão de suas recomendações, analisando o feedback do usuário e fazendo os ajustes necessários.
- Exemplo: ```python
       def adjust_preferences(preferences, feedback):
           if "liked" in feedback:
               preferences["favorites"] = feedback["liked"]
           if "disliked" in feedback:
               preferences["avoid"] = feedback["disliked"]
           return preferences

       preferences = adjust_preferences(preferences, feedback)
       ```

#### Exemplo Prático
Aqui está um exemplo simplificado de código Python que incorpora a abordagem RAG Corretiva no Agente de Viagens:
```python
class Travel_Agent:
    def __init__(self):
        self.user_preferences = {}
        self.experience_data = []

    def gather_preferences(self, preferences):
        self.user_preferences = preferences

    def retrieve_information(self):
        flights = search_flights(self.user_preferences)
        hotels = search_hotels(self.user_preferences)
        attractions = search_attractions(self.user_preferences)
        return flights, hotels, attractions

    def generate_recommendations(self):
        flights, hotels, attractions = self.retrieve_information()
        itinerary = create_itinerary(flights, hotels, attractions)
        return itinerary

    def adjust_based_on_feedback(self, feedback):
        self.experience_data.append(feedback)
        self.user_preferences = adjust_preferences(self.user_preferences, feedback)
        new_itinerary = self.generate_recommendations()
        return new_itinerary

# Example usage
travel_agent = Travel_Agent()
preferences = {
    "destination": "Paris",
    "dates": "2025-04-01 to 2025-04-10",
    "budget": "moderate",
    "interests": ["museums", "cuisine"]
}
travel_agent.gather_preferences(preferences)
itinerary = travel_agent.generate_recommendations()
print("Suggested Itinerary:", itinerary)
feedback = {"liked": ["Louvre Museum"], "disliked": ["Eiffel Tower (too crowded)"]}
new_itinerary = travel_agent.adjust_based_on_feedback(feedback)
print("Updated Itinerary:", new_itinerary)
```

### Carregamento de Contexto Pré-Emptivo
O Carregamento de Contexto Pré-Emptivo envolve carregar informações de contexto ou antecedentes relevantes no modelo antes de processar uma consulta. Isso significa que o modelo tem acesso a essas informações desde o início, o que pode ajudá-lo a gerar respostas mais informadas sem a necessidade de recuperar dados adicionais durante o processo.

Aqui está um exemplo simplificado de como um carregamento de contexto pré-emptivo pode ser implementado em uma aplicação de agente de viagens em Python:
```python
class TravelAgent:
    def __init__(self):
        # Pre-load popular destinations and their information
        self.context = {
            "Paris": {"country": "France", "currency": "Euro", "language": "French", "attractions": ["Eiffel Tower", "Louvre Museum"]},
            "Tokyo": {"country": "Japan", "currency": "Yen", "language": "Japanese", "attractions": ["Tokyo Tower", "Shibuya Crossing"]},
            "New York": {"country": "USA", "currency": "Dollar", "language": "English", "attractions": ["Statue of Liberty", "Times Square"]},
            "Sydney": {"country": "Australia", "currency": "Dollar", "language": "English", "attractions": ["Sydney Opera House", "Bondi Beach"]}
        }

    def get_destination_info(self, destination):
        # Fetch destination information from pre-loaded context
        info = self.context.get(destination)
        if info:
            return f"{destination}:\nCountry: {info['country']}\nCurrency: {info['currency']}\nLanguage: {info['language']}\nAttractions: {', '.join(info['attractions'])}"
        else:
            return f"Sorry, we don't have information on {destination}."

# Example usage
travel_agent = TravelAgent()
print(travel_agent.get_destination_info("Paris"))
print(travel_agent.get_destination_info("Tokyo"))
```

#### Explicação
1. **Inicialização (`__init__` method)**: The `TravelAgent` class pre-loads a dictionary containing information about popular destinations such as Paris, Tokyo, New York, and Sydney. This dictionary includes details like the country, currency, language, and major attractions for each destination.

2. **Retrieving Information (`get_destination_info` method)**: When a user queries about a specific destination, the `get_destination_info` method)**: Este método busca as informações relevantes no dicionário de contexto pré-carregado. Ao pré-carregar o contexto, a aplicação do agente de viagens pode responder rapidamente às consultas do usuário sem precisar recuperar essas informações de uma fonte externa em tempo real. Isso torna a aplicação mais eficiente e responsiva.

### Inicializando o Plano com um Objetivo Antes de Iterar
Inicializar um plano com um objetivo envolve começar com um objetivo claro ou resultado desejado em mente. Definindo esse objetivo desde o início, o modelo pode usá-lo como um princípio orientador ao longo do processo iterativo. Isso ajuda a garantir que cada iteração avance em direção ao resultado desejado, tornando o processo mais eficiente e focado.

Aqui está um exemplo de como você pode inicializar um plano de viagem com um objetivo antes de iterar para um agente de viagens em Python:

### Cenário
Um agente de viagens deseja planejar umas férias personalizadas para um cliente. O objetivo é criar um itinerário de viagem que maximize a satisfação do cliente com base em suas preferências e orçamento.

### Etapas
1. Defina as preferências e o orçamento do cliente.
2. Inicialize o plano inicial com base nessas preferências.
3. Itere para refinar o plano, otimizando a satisfação do cliente.

#### Código Python
```python
class TravelAgent:
    def __init__(self, destinations):
        self.destinations = destinations

    def bootstrap_plan(self, preferences, budget):
        plan = []
        total_cost = 0

        for destination in self.destinations:
            if total_cost + destination['cost'] <= budget and self.match_preferences(destination, preferences):
                plan.append(destination)
                total_cost += destination['cost']

        return plan

    def match_preferences(self, destination, preferences):
        for key, value in preferences.items():
            if destination.get(key) != value:
                return False
        return True

    def iterate_plan(self, plan, preferences, budget):
        for i in range(len(plan)):
            for destination in self.destinations:
                if destination not in plan and self.match_preferences(destination, preferences) and self.calculate_cost(plan, destination) <= budget:
                    plan[i] = destination
                    break
        return plan

    def calculate_cost(self, plan, new_destination):
        return sum(destination['cost'] for destination in plan) + new_destination['cost']

# Example usage
destinations = [
    {"name": "Paris", "cost": 1000, "activity": "sightseeing"},
    {"name": "Tokyo", "cost": 1200, "activity": "shopping"},
    {"name": "New York", "cost": 900, "activity": "sightseeing"},
    {"name": "Sydney", "cost": 1100, "activity": "beach"},
]

preferences = {"activity": "sightseeing"}
budget = 2000

travel_agent = TravelAgent(destinations)
initial_plan = travel_agent.bootstrap_plan(preferences, budget)
print("Initial Plan:", initial_plan)

refined_plan = travel_agent.iterate_plan(initial_plan, preferences, budget)
print("Refined Plan:", refined_plan)
```

#### Explicação do Código
1. **Inicialização (`__init__` method)**: The `TravelAgent` class is initialized with a list of potential destinations, each having attributes like name, cost, and activity type.

2. **Bootstrapping the Plan (`bootstrap_plan` method)**: This method creates an initial travel plan based on the client's preferences and budget. It iterates through the list of destinations and adds them to the plan if they match the client's preferences and fit within the budget.

3. **Matching Preferences (`match_preferences` method)**: This method checks if a destination matches the client's preferences.

4. **Iterating the Plan (`iterate_plan` method)**: This method refines the initial plan by trying to replace each destination in the plan with a better match, considering the client's preferences and budget constraints.

5. **Calculating Cost (`calculate_cost` method)**: Este método calcula o custo total do plano atual, incluindo um possível novo destino.

#### Uso de Exemplo
- **Plano Inicial**: O agente de viagens cria um plano inicial com base nas preferências do cliente por pontos turísticos e um orçamento de $2000.
- **Plano Refinado**: O agente de viagens itera o plano, otimizando para as preferências e o orçamento do cliente.

Ao inicializar o plano com um objetivo claro (por exemplo, maximizar a satisfação do cliente) e iterar para refiná-lo, o agente de viagens pode criar um itinerário de viagem personalizado e otimizado para o cliente. Essa abordagem garante que o plano de viagem esteja alinhado com as preferências e o orçamento do cliente desde o início e melhore a cada iteração.

### Aproveitando LLM para Reclassificação e Pontuação
Modelos de Linguagem de Grande Escala (LLMs) podem ser usados para reclassificação e pontuação ao avaliar a relevância e a qualidade de documentos recuperados ou respostas geradas. Veja como funciona:

**Recuperação:** A etapa inicial de recuperação busca um conjunto de documentos ou respostas candidatas com base na consulta.
**Reclassificação:** O LLM avalia esses candidatos e os reclassifica com base em sua relevância e qualidade. Essa etapa garante que as informações mais relevantes e de alta qualidade sejam apresentadas primeiro.
**Pontuação:** O LLM atribui pontuações a cada candidato, refletindo sua relevância e qualidade. Isso ajuda na seleção da melhor resposta ou documento para o usuário.

Ao aproveitar os LLMs para reclassificação e pontuação, o sistema pode fornecer informações mais precisas e contextualmente relevantes, melhorando a experiência geral do usuário.

Aqui está um exemplo de como um agente de viagens pode usar um Modelo de Linguagem de Grande Escala (LLM) para reclassificar e pontuar destinos de viagem com base nas preferências do usuário em Python:

#### Cenário - Viagem com Base nas Preferências
Um agente de viagens deseja recomendar os melhores destinos de viagem para um cliente com base em suas preferências. O LLM ajudará a reclassificar e pontuar os destinos para garantir que as opções mais relevantes sejam apresentadas.

#### Etapas:
1. Coletar as preferências do usuário.
2. Recuperar uma lista de destinos de viagem potenciais.
3. Usar o LLM para reclassificar e pontuar os destinos com base nas preferências do usuário.

Aqui está como você pode atualizar o exemplo anterior para usar os Serviços Azure OpenAI:

#### Requisitos
1. Você precisa de uma assinatura do Azure.
2. Criar um recurso Azure OpenAI e obter sua chave de API.

#### Código Python de Exemplo
```python
import requests
import json

class TravelAgent:
    def __init__(self, destinations):
        self.destinations = destinations

    def get_recommendations(self, preferences, api_key, endpoint):
        # Generate a prompt for the Azure OpenAI
        prompt = self.generate_prompt(preferences)

        # Define headers and payload for the request
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f'Bearer {api_key}'
        }
        payload = {
            "prompt": prompt,
            "max_tokens": 150,
            "temperature": 0.7
        }

        # Call the Azure OpenAI API to get the re-ranked and scored destinations
        response = requests.post(endpoint, headers=headers, json=payload)
        response_data = response.json()

        # Extract and return the recommendations
        recommendations = response_data['choices'][0]['text'].strip().split('\n')
        return recommendations

    def generate_prompt(self, preferences):
        prompt = "Here are the travel destinations ranked and scored based on the following user preferences:\n"
        for key, value in preferences.items():
            prompt += f"{key}: {value}\n"
        prompt += "\nDestinations:\n"
        for destination in self.destinations:
            prompt += f"- {destination['name']}: {destination['description']}\n"
        return prompt

# Example usage
destinations = [
    {"name": "Paris", "description": "City of lights, known for its art, fashion, and culture."},
    {"name": "Tokyo", "description": "Vibrant city, famous for its modernity and traditional temples."},
    {"name": "New York", "description": "The city that never sleeps, with iconic landmarks and diverse culture."},
    {"name": "Sydney", "description": "Beautiful harbour city, known for its opera house and stunning beaches."},
]

preferences = {"activity": "sightseeing", "culture": "diverse"}
api_key = 'your_azure_openai_api_key'
endpoint = 'https://your-endpoint.com/openai/deployments/your-deployment-name/completions?api-version=2022-12-01'

travel_agent = TravelAgent(destinations)
recommendations = travel_agent.get_recommendations(preferences, api_key, endpoint)
print("Recommended Destinations:")
for rec in recommendations:
    print(rec)
```

#### Explicação do Código - Preference Booker
1. **Inicialização**: Substitua `TravelAgent` class is initialized with a list of potential travel destinations, each having attributes like name and description.

2. **Getting Recommendations (`get_recommendations` method)**: This method generates a prompt for the Azure OpenAI service based on the user's preferences and makes an HTTP POST request to the Azure OpenAI API to get re-ranked and scored destinations.

3. **Generating Prompt (`generate_prompt` method)**: This method constructs a prompt for the Azure OpenAI, including the user's preferences and the list of destinations. The prompt guides the model to re-rank and score the destinations based on the provided preferences.

4. **API Call**: The `requests` library is used to make an HTTP POST request to the Azure OpenAI API endpoint. The response contains the re-ranked and scored destinations.

5. **Example Usage**: The travel agent collects user preferences (e.g., interest in sightseeing and diverse culture) and uses the Azure OpenAI service to get re-ranked and scored recommendations for travel destinations.

Make sure to replace `your_azure_openai_api_key` with your actual Azure OpenAI API key and `https://your-endpoint.com/...` pela URL do endpoint real de sua implantação do Azure OpenAI.

Ao aproveitar o LLM para reclassificação e pontuação, o agente de viagens pode fornecer recomendações de viagem mais personalizadas e relevantes para os clientes, melhorando sua experiência geral.

### RAG: Técnica de Prompt vs Ferramenta
A Geração Incrementada por Recuperação (RAG) pode ser tanto uma técnica de prompt quanto uma ferramenta no desenvolvimento de agentes de IA. Compreender a distinção entre os dois pode ajudá-lo a aproveitar o RAG de forma mais eficaz em seus projetos.

#### RAG como Técnica de Prompt
**O que é?**
- Como técnica de prompt, o RAG envolve a formulação de consultas ou prompts específicos para guiar a recuperação de informações relevantes de um grande corpus ou banco de dados. Essas informações são então usadas para gerar respostas ou ações.

**Como funciona:**
1. **Formular Prompts**: Crie prompts ou consultas bem estruturados com base na tarefa ou na entrada do usuário.
2. **Recuperar Informações**: Use os prompts para buscar dados relevantes de uma base de conhecimento ou conjunto de dados preexistente.
3. **Gerar Resposta**: Combine as informações recuperadas com modelos de IA generativos para produzir uma resposta abrangente e coerente.

**Exemplo em Agente de Viagens**:
- Entrada do Usuário: "Quero visitar museus em Paris."
- Prompt: "Encontre os principais museus em Paris."
- Informações Recuperadas: Detalhes sobre o Museu do Louvre, Musée d'Orsay, etc.
- Resposta Gerada: "Aqui estão alguns dos principais museus em Paris: Museu do Louvre, Musée d'Orsay e Centro Pompidou."

#### RAG como Ferramenta
**O que é?**
- Como ferramenta, o RAG é um sistema integrado que automatiza o processo de recuperação e geração, facilitando a implementação de funcionalidades complexas de IA sem a necessidade de criar prompts manualmente para cada consulta.

**Como funciona:**
1. **Integração**: Incorpore o RAG na arquitetura do agente de IA, permitindo que ele lide automaticamente com as tarefas de recuperação e geração.
2. **Automação**: A ferramenta gerencia todo o processo, desde receber a entrada do usuário até gerar a resposta final, sem exigir prompts explícitos para cada etapa.
3. **Eficiência**: Melhora o desempenho do agente ao simplificar o processo de recuperação e geração, permitindo respostas mais rápidas e precisas.

**Exemplo em Agente de Viagens**:
- Entrada do Usuário: "Quero visitar museus em Paris."
- Ferramenta RAG: Recupera automaticamente informações sobre museus e gera uma resposta.
- Resposta Gerada: "Aqui estão alguns dos principais museus em Paris: Museu do Louvre, Musée d'Orsay e Centro Pompidou."

### Comparação
| Aspecto                | Técnica de Prompt                                         | Ferramenta                                           |
|------------------------|----------------------------------------------------------|-----------------------------------------------------|
| **Manual vs Automático** | Formulação manual de prompts para cada consulta.         | Processo automatizado para recuperação e geração.   |
| **Controle**           | Oferece mais controle sobre o processo de recuperação.    | Simplifica e automatiza a recuperação e geração.    |
| **Flexibilidade**      | Permite prompts personalizados com base em necessidades específicas. | Mais eficiente para implementações em larga escala. |
| **Complexidade**       | Requer criação e ajuste de prompts.                       | Mais fácil de integrar na arquitetura de um agente de IA. |

### Exemplos Práticos
**Exemplo de Técnica de Prompt:**
```python
def search_museums_in_paris():
    prompt = "Find top museums in Paris"
    search_results = search_web(prompt)
    return search_results

museums = search_museums_in_paris()
print("Top Museums in Paris:", museums)
```

**Exemplo de Ferramenta:**
```python
class Travel_Agent:
    def __init__(self):
        self.rag_tool = RAGTool()

    def get_museums_in_paris(self):
        user_input = "I want to visit museums in Paris."
        response = self.rag_tool.retrieve_and_generate(user_input)
        return response

travel_agent = Travel_Agent()
museums = travel_agent.get_museums_in_paris()
print("Top Museums in Paris:", museums)
```

### Avaliando Relevância
Avaliar relevância é um aspecto crucial do desempenho de agentes de IA. Isso garante que as informações recuperadas e geradas pelo agente sejam apropriadas, precisas e úteis para o usuário. Vamos explorar como avaliar relevância em agentes de IA, incluindo exemplos práticos e técnicas.

#### Conceitos-Chave na Avaliação de Relevância
1. **Consciência de Contexto**:
   - O agente deve entender o contexto da consulta do usuário para recuperar e gerar informações relevantes.
   - Exemplo: Se um usuário perguntar "melhores restaurantes em Paris", o agente deve considerar as preferências do usuário, como tipo de cozinha e orçamento.
2. **Precisão**:
   - As informações fornecidas pelo agente devem ser factualmente corretas e atualizadas.
   - Exemplo: Recomendar restaurantes abertos atualmente com boas avaliações em vez de opções desatualizadas ou fechadas.
3. **Intenção do Usuário**:
   - O agente deve inferir a intenção do usuário por trás da consulta para fornecer as informações mais relevantes.
   - Exemplo: Se um usuário perguntar por "hotéis econômicos", o agente deve priorizar opções acessíveis.
4. **Ciclo de Feedback**:
   - Coletar e analisar continuamente o feedback do usuário ajuda o agente a refinar seu processo de avaliação de relevância.
   - Exemplo: Incorporar classificações e feedback de usuários sobre recomendações anteriores para melhorar respostas futuras.

#### Técnicas Práticas para Avaliação de Relevância
1. **Pontuação de Relevância**:
   - Atribuir uma pontuação de relevância a cada item recuperado com base em quão bem ele corresponde à consulta e preferências do usuário.
   - Exemplo: ```python
     def relevance_score(item, query):
         score = 0
         if item['category'] in query['interests']:
             score += 1
         if item['price'] <= query['budget']:
             score += 1
         if item['location'] == query['destination']:
             score += 1
         return score
     ```
2. **Filtragem e Classificação**:
   - Filtrar itens irrelevantes e classificar os restantes com base em suas pontuações de relevância.
   - Exemplo: ```python
     def filter_and_rank(items, query):
         ranked_items = sorted(items, key=lambda item: relevance_score(item, query), reverse=True)
         return ranked_items[:10]  # Return top 10 relevant items
     ```
3. **Processamento de Linguagem Natural (NLP)**:
   - Usar técnicas de NLP para entender a consulta do usuário e recuperar informações relevantes.
   - Exemplo: ```python
     def process_query(query):
         # Use NLP to extract key information from the user's query
         processed_query = nlp(query)
         return processed_query
     ```
4. **Integração de Feedback do Usuário**:
   - Coletar feedback do usuário sobre as recomendações fornecidas e usá-lo para ajustar avaliações futuras de relevância.
   - Exemplo: ```python
     def adjust_based_on_feedback(feedback, items):
         for item in items:
             if item['name'] in feedback['liked']:
                 item['relevance'] += 1
             if item['name'] in feedback['disliked']:
                 item['relevance'] -= 1
         return items
     ```

#### Exemplo: Avaliando Relevância no Agente de Viagens
Aqui está um exemplo prático de como o Agente de Viagens pode avaliar a relevância de recomendações de viagem:
```python
class Travel_Agent:
    def __init__(self):
        self.user_preferences = {}
        self.experience_data = []

    def gather_preferences(self, preferences):
        self.user_preferences = preferences

    def retrieve_information(self):
        flights = search_flights(self.user_preferences)
        hotels = search_hotels(self.user_preferences)
        attractions = search_attractions(self.user_preferences)
        return flights, hotels, attractions

    def generate_recommendations(self):
        flights, hotels, attractions = self.retrieve_information()
        ranked_hotels = self.filter_and_rank(hotels, self.user_preferences)
        itinerary = create_itinerary(flights, ranked_hotels, attractions)
        return itinerary

    def filter_and_rank(self, items, query):
        ranked_items = sorted(items, key=lambda item: self.relevance_score(item, query), reverse=True)
        return ranked_items[:10]  # Return top 10 relevant items

    def relevance_score(self, item, query):
        score = 0
        if item['category'] in query['interests']:
            score += 1
        if item['price'] <= query['budget']:
            score += 1
        if item['location'] == query['destination']:
            score += 1
        return score

    def adjust_based_on_feedback(self, feedback, items):
        for item in items:
            if item['name'] in feedback['liked']:
                item['relevance'] += 1
            if item['name'] in feedback['disliked']:
                item['relevance'] -= 1
        return items

# Example usage
travel_agent = Travel_Agent()
preferences = {
    "destination": "Paris",
    "dates": "2025-04-01 to 2025-04-10",
    "budget": "moderate",
    "interests": ["museums", "cuisine"]
}
travel_agent.gather_preferences(preferences)
itinerary = travel_agent.generate_recommendations()
print("Suggested Itinerary:", itinerary)
feedback = {"liked": ["Louvre Museum"], "disliked": ["Eiffel Tower (too crowded)"]}
updated_items = travel_agent.adjust_based_on_feedback(feedback, itinerary['hotels'])
print("Updated Itinerary with Feedback:", updated_items)
```

### Pesquisa com Intenção
Pesquisar com intenção envolve entender e interpretar o propósito ou objetivo subjacente à consulta do usuário para recuperar e gerar as informações mais relevantes e úteis. Essa abordagem vai além de simplesmente corresponder palavras-chave, focando em compreender as reais necessidades e contexto do usuário.

#### Conceitos-Chave na Pesquisa com Intenção
1. **Compreensão da Intenção do Usuário**:
   - A intenção do usuário pode ser categorizada em três tipos principais: informacional, navegacional e transacional.
   - **Intenção Informacional**: O usuário busca informações sobre um tópico (ex.: "Quais são...").
```
```markdown
os melhores museus em Paris?"). - **Intenção de Navegação**: O usuário deseja navegar para um site ou página específica (por exemplo, "site oficial do Museu do Louvre"). - **Intenção Transacional**: O usuário pretende realizar uma transação, como reservar um voo ou fazer uma compra (por exemplo, "Reservar um voo para Paris"). 2. **Consciência de Contexto**: - Analisar o contexto da consulta do usuário ajuda a identificar com precisão sua intenção. Isso inclui considerar interações anteriores, preferências do usuário e os detalhes específicos da consulta atual. 3. **Processamento de Linguagem Natural (PLN)**: - Técnicas de PLN são empregadas para entender e interpretar as consultas em linguagem natural fornecidas pelos usuários. Isso inclui tarefas como reconhecimento de entidades, análise de sentimentos e interpretação de consultas. 4. **Personalização**: - Personalizar os resultados da pesquisa com base no histórico, nas preferências e no feedback do usuário aumenta a relevância das informações recuperadas. #### Exemplo Prático: Pesquisa com Intenção no Agente de Viagem Vamos usar o Agente de Viagem como exemplo para ver como a pesquisa com intenção pode ser implementada. 1. **Coleta de Preferências do Usuário** ```python
   class Travel_Agent:
       def __init__(self):
           self.user_preferences = {}

       def gather_preferences(self, preferences):
           self.user_preferences = preferences
   ``` 2. **Entendimento da Intenção do Usuário** ```python
   def identify_intent(query):
       if "book" in query or "purchase" in query:
           return "transactional"
       elif "website" in query or "official" in query:
           return "navigational"
       else:
           return "informational"
   ``` 3. **Consciência de Contexto** ```python
   def analyze_context(query, user_history):
       # Combine current query with user history to understand context
       context = {
           "current_query": query,
           "user_history": user_history
       }
       return context
   ``` 4. **Pesquisar e Personalizar Resultados** ```python
   def search_with_intent(query, preferences, user_history):
       intent = identify_intent(query)
       context = analyze_context(query, user_history)
       if intent == "informational":
           search_results = search_information(query, preferences)
       elif intent == "navigational":
           search_results = search_navigation(query)
       elif intent == "transactional":
           search_results = search_transaction(query, preferences)
       personalized_results = personalize_results(search_results, user_history)
       return personalized_results

   def search_information(query, preferences):
       # Example search logic for informational intent
       results = search_web(f"best {preferences['interests']} in {preferences['destination']}")
       return results

   def search_navigation(query):
       # Example search logic for navigational intent
       results = search_web(query)
       return results

   def search_transaction(query, preferences):
       # Example search logic for transactional intent
       results = search_web(f"book {query} to {preferences['destination']}")
       return results

   def personalize_results(results, user_history):
       # Example personalization logic
       personalized = [result for result in results if result not in user_history]
       return personalized[:10]  # Return top 10 personalized results
   ``` 5. **Exemplo de Uso** ```python
   travel_agent = Travel_Agent()
   preferences = {
       "destination": "Paris",
       "interests": ["museums", "cuisine"]
   }
   travel_agent.gather_preferences(preferences)
   user_history = ["Louvre Museum website", "Book flight to Paris"]
   query = "best museums in Paris"
   results = search_with_intent(query, preferences, user_history)
   print("Search Results:", results)
   ``` --- ## 4. Gerando Código como uma Ferramenta Agentes geradores de código usam modelos de IA para escrever e executar código, resolvendo problemas complexos e automatizando tarefas. ### Agentes Geradores de Código Agentes geradores de código usam modelos de IA generativa para escrever e executar código. Esses agentes podem resolver problemas complexos, automatizar tarefas e fornecer insights valiosos gerando e executando código em várias linguagens de programação. #### Aplicações Práticas 1. **Geração Automática de Código**: Gerar trechos de código para tarefas específicas, como análise de dados, web scraping ou aprendizado de máquina. 2. **SQL como RAG**: Usar consultas SQL para recuperar e manipular dados de bancos de dados. 3. **Resolução de Problemas**: Criar e executar código para resolver problemas específicos, como otimização de algoritmos ou análise de dados. #### Exemplo: Agente Gerador de Código para Análise de Dados Imagine que você está projetando um agente gerador de código. Veja como ele pode funcionar: 1. **Tarefa**: Analisar um conjunto de dados para identificar tendências e padrões. 2. **Etapas**: - Carregar o conjunto de dados em uma ferramenta de análise de dados. - Gerar consultas SQL para filtrar e agregar os dados. - Executar as consultas e recuperar os resultados. - Usar os resultados para gerar visualizações e insights. 3. **Recursos Necessários**: Acesso ao conjunto de dados, ferramentas de análise de dados e capacidades SQL. 4. **Experiência**: Usar resultados de análises anteriores para melhorar a precisão e a relevância das análises futuras. ### Exemplo: Agente Gerador de Código para Agente de Viagem Neste exemplo, projetaremos um agente gerador de código, Agente de Viagem, para ajudar os usuários a planejar suas viagens gerando e executando código. Este agente pode lidar com tarefas como buscar opções de viagem, filtrar resultados e compilar um itinerário usando IA generativa. #### Visão Geral do Agente Gerador de Código 1. **Coleta de Preferências do Usuário**: Coleta entradas do usuário, como destino, datas de viagem, orçamento e interesses. 2. **Geração de Código para Buscar Dados**: Gera trechos de código para recuperar dados sobre voos, hotéis e atrações. 3. **Execução do Código Gerado**: Executa o código gerado para buscar informações em tempo real. 4. **Geração de Itinerário**: Compila os dados recuperados em um plano de viagem personalizado. 5. **Ajuste com Base no Feedback**: Recebe feedback do usuário e regenera o código, se necessário, para refinar os resultados. #### Implementação Passo a Passo 1. **Coleta de Preferências do Usuário** ```python
   class Travel_Agent:
       def __init__(self):
           self.user_preferences = {}

       def gather_preferences(self, preferences):
           self.user_preferences = preferences
   ``` 2. **Geração de Código para Buscar Dados** ```python
   def generate_code_to_fetch_data(preferences):
       # Example: Generate code to search for flights based on user preferences
       code = f"""
       def search_flights():
           import requests
           response = requests.get('https://api.example.com/flights', params={preferences})
           return response.json()
       """
       return code

   def generate_code_to_fetch_hotels(preferences):
       # Example: Generate code to search for hotels
       code = f"""
       def search_hotels():
           import requests
           response = requests.get('https://api.example.com/hotels', params={preferences})
           return response.json()
       """
       return code
   ``` 3. **Execução do Código Gerado** ```python
   def execute_code(code):
       # Execute the generated code using exec
       exec(code)
       result = locals()
       return result

   travel_agent = Travel_Agent()
   preferences = {
       "destination": "Paris",
       "dates": "2025-04-01 to 2025-04-10",
       "budget": "moderate",
       "interests": ["museums", "cuisine"]
   }
   travel_agent.gather_preferences(preferences)

   flight_code = generate_code_to_fetch_data(preferences)
   hotel_code = generate_code_to_fetch_hotels(preferences)

   flights = execute_code(flight_code)
   hotels = execute_code(hotel_code)

   print("Flight Options:", flights)
   print("Hotel Options:", hotels)
   ``` 4. **Geração de Itinerário** ```python
   def generate_itinerary(flights, hotels, attractions):
       itinerary = {
           "flights": flights,
           "hotels": hotels,
           "attractions": attractions
       }
       return itinerary

   attractions = search_attractions(preferences)
   itinerary = generate_itinerary(flights, hotels, attractions)
   print("Suggested Itinerary:", itinerary)
   ``` 5. **Ajuste com Base no Feedback** ```python
   def adjust_based_on_feedback(feedback, preferences):
       # Adjust preferences based on user feedback
       if "liked" in feedback:
           preferences["favorites"] = feedback["liked"]
       if "disliked" in feedback:
           preferences["avoid"] = feedback["disliked"]
       return preferences

   feedback = {"liked": ["Louvre Museum"], "disliked": ["Eiffel Tower (too crowded)"]}
   updated_preferences = adjust_based_on_feedback(feedback, preferences)

   # Regenerate and execute code with updated preferences
   updated_flight_code = generate_code_to_fetch_data(updated_preferences)
   updated_hotel_code = generate_code_to_fetch_hotels(updated_preferences)

   updated_flights = execute_code(updated_flight_code)
   updated_hotels = execute_code(updated_hotel_code)

   updated_itinerary = generate_itinerary(updated_flights, updated_hotels, attractions)
   print("Updated Itinerary:", updated_itinerary)
   ``` ### Aproveitando a Consciência do Ambiente e o Raciocínio Com base no esquema da tabela, é possível melhorar o processo de geração de consultas aproveitando a consciência do ambiente e o raciocínio. Aqui está um exemplo de como isso pode ser feito: 1. **Entendimento do Esquema**: O sistema entenderá o esquema da tabela e usará essas informações para fundamentar a geração de consultas. 2. **Ajuste com Base no Feedback**: O sistema ajustará as preferências do usuário com base no feedback e raciocinará sobre quais campos no esquema precisam ser atualizados. 3. **Geração e Execução de Consultas**: O sistema gerará e executará consultas para buscar dados atualizados de voos e hotéis com base nas novas preferências. Aqui está um exemplo atualizado de código Python que incorpora esses conceitos: ```python
def adjust_based_on_feedback(feedback, preferences, schema):
    # Adjust preferences based on user feedback
    if "liked" in feedback:
        preferences["favorites"] = feedback["liked"]
    if "disliked" in feedback:
        preferences["avoid"] = feedback["disliked"]
    # Reasoning based on schema to adjust other related preferences
    for field in schema:
        if field in preferences:
            preferences[field] = adjust_based_on_environment(feedback, field, schema)
    return preferences

def adjust_based_on_environment(feedback, field, schema):
    # Custom logic to adjust preferences based on schema and feedback
    if field in feedback["liked"]:
        return schema[field]["positive_adjustment"]
    elif field in feedback["disliked"]:
        return schema[field]["negative_adjustment"]
    return schema[field]["default"]

def generate_code_to_fetch_data(preferences):
    # Generate code to fetch flight data based on updated preferences
    return f"fetch_flights(preferences={preferences})"

def generate_code_to_fetch_hotels(preferences):
    # Generate code to fetch hotel data based on updated preferences
    return f"fetch_hotels(preferences={preferences})"

def execute_code(code):
    # Simulate execution of code and return mock data
    return {"data": f"Executed: {code}"}

def generate_itinerary(flights, hotels, attractions):
    # Generate itinerary based on flights, hotels, and attractions
    return {"flights": flights, "hotels": hotels, "attractions": attractions}

# Example schema
schema = {
    "favorites": {"positive_adjustment": "increase", "negative_adjustment": "decrease", "default": "neutral"},
    "avoid": {"positive_adjustment": "decrease", "negative_adjustment": "increase", "default": "neutral"}
}

# Example usage
preferences = {"favorites": "sightseeing", "avoid": "crowded places"}
feedback = {"liked": ["Louvre Museum"], "disliked": ["Eiffel Tower (too crowded)"]}
updated_preferences = adjust_based_on_feedback(feedback, preferences, schema)

# Regenerate and execute code with updated preferences
updated_flight_code = generate_code_to_fetch_data(updated_preferences)
updated_hotel_code = generate_code_to_fetch_hotels(updated_preferences)

updated_flights = execute_code(updated_flight_code)
updated_hotels = execute_code(updated_hotel_code)

updated_itinerary = generate_itinerary(updated_flights, updated_hotels, feedback["liked"])
print("Updated Itinerary:", updated_itinerary)
``` #### Explicação - Reserva com Base no Feedback 1. **Consciência do Esquema**: O método `schema` dictionary defines how preferences should be adjusted based on feedback. It includes fields like `favorites` and `avoid`, with corresponding adjustments.
2. **Adjusting Preferences (`adjust_based_on_feedback` method)**: This method adjusts preferences based on user feedback and the schema.
3. **Environment-Based Adjustments (`adjust_based_on_environment`): Este método personaliza os ajustes com base no esquema e no feedback. 4. **Geração e Execução de Consultas**: O sistema gera código para buscar dados atualizados de voos e hotéis com base nas preferências ajustadas e simula a execução dessas consultas. 5. **Geração de Itinerário**: O sistema cria um itinerário atualizado com base nos novos dados de voos, hotéis e atrações. Ao tornar o sistema ciente do ambiente e raciocinar com base no esquema, ele pode gerar consultas mais precisas e relevantes, levando a melhores recomendações de viagem e uma experiência mais personalizada para o usuário. ### Usando SQL como uma Técnica de Recuperação-Baseada em Geração (RAG) SQL (Structured Query Language) é uma ferramenta poderosa para interagir com bancos de dados. Quando usada como parte de uma abordagem de Recuperação-Baseada em Geração (RAG), o SQL pode recuperar dados relevantes de bancos de dados para informar e gerar respostas ou ações em agentes de IA. Vamos explorar como o SQL pode ser usado como uma técnica RAG no contexto do Agente de Viagem. #### Conceitos-Chave 1. **Interação com Banco de Dados**: - O SQL é usado para consultar bancos de dados, recuperar informações relevantes e manipular dados. - Exemplo: Buscar detalhes de voos, informações de hotéis e atrações de um banco de dados de viagens. 2. **Integração com RAG**: - Consultas SQL são geradas com base nas entradas e preferências do usuário. - Os dados recuperados são então usados para gerar recomendações ou ações personalizadas. 3. **Geração Dinâmica de Consultas**: - O agente de IA gera consultas SQL dinâmicas com base no contexto e nas necessidades do usuário. - Exemplo: Personalizar consultas SQL para filtrar resultados com base no orçamento, datas e interesses. #### Aplicações - **Geração Automática de Código**: Gerar trechos de código para tarefas específicas. - **SQL como RAG**: Usar consultas SQL para manipular dados. - **Resolução de Problemas**: Criar e executar código para resolver problemas. **Exemplo**: Um agente de análise de dados: 1. **Tarefa**: Analisar um conjunto de dados para encontrar tendências. 2. **Etapas**: - Carregar o conjunto de dados. - Gerar consultas SQL para filtrar dados. - Executar consultas e recuperar resultados. - Gerar visualizações e insights. 3. **Recursos**: Acesso ao conjunto de dados, capacidades SQL. 4. **Experiência**: Usar resultados anteriores para melhorar análises futuras. #### Exemplo Prático: Usando SQL no Agente de Viagem 1. **Coleta de Preferências do Usuário** ```python
   class Travel_Agent:
       def __init__(self):
           self.user_preferences = {}

       def gather_preferences(self, preferences):
           self.user_preferences = preferences
   ``` 2. **Geração de Consultas SQL** ```python
   def generate_sql_query(table, preferences):
       query = f"SELECT * FROM {table} WHERE "
       conditions = []
       for key, value in preferences.items():
           conditions.append(f"{key}='{value}'")
       query += " AND ".join(conditions)
       return query
   ``` 3. **Execução de Consultas SQL** ```python
   import sqlite3

   def execute_sql_query(query, database="travel.db"):
       connection = sqlite3.connect(database)
       cursor = connection.cursor()
       cursor.execute(query)
       results = cursor.fetchall()
       connection.close()
       return results
   ``` 4. **Geração de Recomendações** ```python
   def generate_recommendations(preferences):
       flight_query = generate_sql_query("flights", preferences)
       hotel_query = generate_sql_query("hotels", preferences)
       attraction_query = generate_sql_query("attractions", preferences)

       flights = execute_sql_query(flight_query)
       hotels = execute_sql_query(hotel_query)
       attractions = execute_sql_query(attraction_query)

       itinerary = {
           "flights": flights,
           "hotels": hotels,
           "attractions": attractions
       }
       return itinerary

   travel_agent = Travel_Agent()
   preferences = {
       "destination": "Paris",
       "dates": "2025-04-01 to 2025-04-10",
       "budget": "moderate",
       "interests": ["museums", "cuisine"]
   }
   travel_agent.gather_preferences(preferences)
   itinerary = generate_recommendations(preferences)
   print("Suggested Itinerary:", itinerary)
   ``` #### Exemplos de Consultas SQL 1. **Consulta de Voo** ```sql
   SELECT * FROM flights WHERE destination='Paris' AND dates='2025-04-01 to 2025-04-10' AND budget='moderate';
   ``` 2. **Consulta de Hotel** ```sql
   SELECT * FROM hotels WHERE destination='Paris' AND budget='moderate';
   ``` 3. **Consulta de Atração** ```sql
   SELECT * FROM attractions WHERE destination='Paris' AND interests='museums, cuisine';
   ``` Ao aproveitar o SQL como parte da técnica de Recuperação-Baseada em Geração (RAG), agentes de IA como o Agente de Viagem podem recuperar e utilizar dinamicamente dados relevantes para fornecer recomendações precisas e personalizadas. ### Conclusão A metacognição é uma ferramenta poderosa que pode melhorar significativamente as capacidades dos agentes de IA. Ao incorporar processos metacognitivos, você pode projetar agentes mais inteligentes, adaptáveis e eficientes. Use os recursos adicionais para explorar mais sobre o fascinante mundo da metacognição em agentes de IA.
```

**Aviso Legal**:
Este documento foi traduzido utilizando serviços de tradução automática por IA. 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 oficial. Para informações críticas, recomenda-se a tradução profissional humana. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.


# Agentes de IA em Produção

## Introdução

Esta lição abordará:

- Como planejar de forma eficaz a implantação do seu Agente de IA em produção.
- Erros e problemas comuns que você pode enfrentar ao implantar seu Agente de IA em produção.
- Como gerenciar custos mantendo o desempenho do seu Agente de IA.

## Objetivos de Aprendizado

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

- Técnicas para melhorar o desempenho, os custos e a eficácia de um sistema de Agente de IA em produção.
- O que avaliar e como avaliar seus Agentes de IA.
- Como controlar custos ao implantar Agentes de IA em produção.

É importante implantar Agentes de IA que sejam confiáveis. Confira a lição "Construindo Agentes de IA Confiáveis" para saber mais.

## Avaliando Agentes de IA

Antes, durante e depois de implantar Agentes de IA, é fundamental ter um sistema adequado para avaliá-los. Isso garantirá que seu sistema esteja alinhado com seus objetivos e os de seus usuários.

Para avaliar um Agente de IA, é importante ter a capacidade de avaliar não apenas o resultado do agente, mas todo o sistema em que ele opera. Isso inclui, mas não se limita a:

- A solicitação inicial ao modelo.
- A capacidade do agente de identificar a intenção do usuário.
- A capacidade do agente de identificar a ferramenta certa para realizar a tarefa.
- A resposta da ferramenta à solicitação do agente.
- A capacidade do agente de interpretar a resposta da ferramenta.
- O feedback do usuário à resposta do agente.

Isso permite identificar áreas de melhoria de forma mais modular. Assim, você pode monitorar o impacto de mudanças nos modelos, prompts, ferramentas e outros componentes com maior eficiência.

## Problemas Comuns e Soluções Potenciais com Agentes de IA

| **Problema**                                   | **Solução Potencial**                                                                                |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agente de IA não realiza tarefas de forma consistente | - Refinar o prompt fornecido ao Agente de IA; seja claro sobre os objetivos.
- Identificar onde dividir as tarefas em subtarefas e delegá-las a múltiplos agentes pode ser útil.                                         |
| Agente de IA entrando em loops contínuos       | - Certifique-se de ter condições e termos de encerramento claros para que o Agente saiba quando parar o processo.
- Para tarefas complexas que exigem raciocínio e planejamento, utilize um modelo maior especializado nessas tarefas. |
| Chamadas de ferramentas pelo Agente de IA não estão funcionando bem | - Teste e valide a saída da ferramenta fora do sistema do agente.
- Refine os parâmetros definidos, prompts e nomes das ferramentas.                                                                                |
| Sistema de múltiplos agentes não está funcionando de forma consistente | - Refinar os prompts fornecidos a cada agente para garantir que sejam específicos e distintos entre si.
- Construir um sistema hierárquico usando um agente "roteador" ou controlador para determinar qual agente é o mais adequado. |

## Gerenciamento de Custos

Aqui estão algumas estratégias para gerenciar os custos ao implantar Agentes de IA em produção:

- **Cachear Respostas** - Identificar solicitações e tarefas comuns e fornecer as respostas antes que elas passem pelo seu sistema de agentes é uma boa maneira de reduzir o volume de solicitações semelhantes. Você pode até implementar um fluxo para identificar quão semelhante uma solicitação é em relação às solicitações em cache, usando modelos de IA mais básicos.

- **Usar Modelos Menores** - Modelos de Linguagem Pequenos (SLMs) podem ter um bom desempenho em certos casos de uso de agentes e reduzirão significativamente os custos. Como mencionado anteriormente, construir um sistema de avaliação para determinar e comparar o desempenho em relação a modelos maiores é a melhor maneira de entender quão bem um SLM funcionará no seu caso de uso.

- **Usar um Modelo Roteador** - Uma estratégia semelhante é usar uma diversidade de modelos e tamanhos. Você pode usar um LLM/SLM ou uma função serverless para rotear solicitações com base na complexidade para os modelos mais adequados. Isso ajudará a reduzir custos enquanto garante o desempenho nas tarefas certas.

## Parabéns

Esta é, atualmente, a última lição de "Agentes de IA para Iniciantes".

Planejamos continuar adicionando lições com base no feedback e nas mudanças desta indústria em constante crescimento, então volte a nos visitar em breve.

Se você deseja continuar aprendendo e desenvolvendo com Agentes de IA, participe do [Azure AI Community Discord](https://discord.gg/kzRShWzttr).

Realizamos workshops, mesas-redondas da comunidade e sessões de "pergunte-me qualquer coisa" por lá.

Também temos uma coleção de aprendizado com materiais adicionais que podem ajudar você a começar a construir Agentes de IA em produção.

**Aviso Legal**:
Este documento foi traduzido utilizando serviços de tradução baseados em IA. 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 oficial. Para informações críticas, recomenda-se uma tradução profissional feita por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações equivocadas decorrentes do uso desta tradução.

10 Lessons to Get Started Building AI Agents


# 課程設置

## 簡介

本課程將介紹如何運行本課程中的程式範例。

## 需求

- 一個 GitHub 帳號
- Python 3.12+ 版本

## 複製或分叉這個倉庫

首先，請複製（clone）或分叉（fork）GitHub 倉庫。這樣可以建立您自己的課程資料副本，方便您運行、測試以及調整程式碼！

您可以透過點擊此連結 [fork the repo](https://github.com/microsoft/ai-agents-for-beginners/fork) 來完成操作。

完成後，您應該會有一個如下所示的分叉版本：

![Forked Repo](../../../translated_images/forked-repo.eea246a73044cc984a1e462349e36e7336204f00785e3187b7399905feeada07.tw.png)

## 獲取您的 GitHub 個人訪問令牌（PAT）

目前，本課程使用 GitHub Models Marketplace 提供免費的大型語言模型（LLMs）存取權，這些模型將用於創建 AI Agents。

要使用此服務，您需要建立一個 GitHub 個人訪問令牌（Personal Access Token）。

您可以前往您的 GitHub 帳號中的 [Personal Access Tokens settings](https://github.com/settings/personal-access-tokens) 進行設定。

在螢幕左側選擇 `Fine-grained tokens` 選項。

接著選擇 `Generate new token`。

![Generate Token](../../../translated_images/generate-token.361ec40abe59b84ac68d63c23e2b6854d6fad82bd4e41feb98fc0e6f030e8ef7.tw.png)

複製您剛剛建立的新令牌。接下來，您需要將它添加到課程中提供的 `.env` 文件中。

## 將令牌添加到環境變數

要建立您的 `.env` 文件，請在終端機中運行以下指令：

```bash
cp .env.example .env
```

這將複製範例文件並在您的目錄中建立一個 `.env` 文件。

打開該文件，將您創建的令牌粘貼到 .env 文件的 `GITHUB_TOKEN=` 欄位中。

## 安裝必要的套件

為了確保您擁有運行程式所需的所有 Python 套件，請在終端機中運行以下指令。

我們建議建立一個 Python 虛擬環境，以避免任何衝突或問題。

```bash
pip install -r requirements.txt
```

這應該會安裝所有必要的 Python 套件。

現在，您已準備好運行程式碼，祝您學習 AI Agents 的世界愉快！

如果您在設置過程中遇到任何問題，請加入我們的 [Azure AI 社群 Discord](https://discord.gg/kzRShWzttr) 或 [建立問題單](https://github.com/microsoft/ai-agents-for-beginners/issues?WT.mc_id=academic-105485-koreyst)。
```

**免責聲明**：
本文檔是使用機器翻譯的人工智慧翻譯服務完成的。我們雖然努力確保翻譯的準確性，但請注意，自動翻譯可能會包含錯誤或不精確之處。應以原文檔的原始語言版本作為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或誤讀概不負責。


# AI代理與應用案例介紹

歡迎來到「AI代理入門」課程！本課程旨在為您提供AI代理的基礎知識以及應用範例，幫助您學習如何構建AI代理。

加入 [Azure AI Discord 社群](https://discord.gg/kzRShWzttr)，與其他學員以及AI代理開發者交流，並隨時提出您在學習過程中的問題。

在開始本課程之前，我們將首先了解什麼是AI代理，以及如何將它們應用於我們的應用程式和工作流程中。

## 課程介紹

本課程涵蓋以下內容：

- 什麼是AI代理？有哪些不同類型的代理？
- AI代理最適合的應用場景有哪些？它們如何幫助我們？
- 設計代理解決方案時需要考慮的基本組成部分有哪些？

## 學習目標

完成本課程後，您應該能夠：

- 理解AI代理的概念，並了解它們與其他AI解決方案的不同之處。
- 有效地應用AI代理。
- 為用戶與客戶高效設計代理解決方案。

## 定義AI代理與代理類型

### 什麼是AI代理？

AI代理是**系統**，它通過為**大型語言模型（LLMs）**提供**工具**和**知識的訪問權限**，使其能夠執行**操作**，從而擴展其能力。

讓我們將這個定義分解為更小的部分：

- **系統** - AI代理不僅僅是單一組件，而是一個由多個組件組成的系統。基本上，AI代理的組件包括：
  - **環境** - 定義AI代理運行的空間。例如，若我們有一個旅行預訂AI代理，環境可能是AI代理用來完成任務的旅行預訂系統。
  - **感應器** - 環境提供信息和反饋。AI代理使用感應器來收集並解讀環境當前狀態的信息。在旅行預訂代理的例子中，旅行預訂系統可以提供如酒店空房情況或機票價格等信息。
  - **執行器** - 當AI代理獲取環境的當前狀態後，針對當前任務決定執行的操作，以改變環境。對於旅行預訂代理來說，可能的操作是為用戶預訂一間可用的房間。

![什麼是AI代理？](../../../translated_images/what-are-ai-agents.125520f55950b252a429b04a9f41e0152d4dafa1f1bd9081f4f574631acb759e.tw.png?WT.mc_id=academic-105485-koreyst))

**大型語言模型** - 代理的概念早於LLMs的誕生而存在。使用LLMs構建AI代理的優勢在於它們能夠解讀人類語言和數據的能力。這種能力使LLMs能夠解讀環境信息並制定改變環境的計劃。

**執行操作** - 在AI代理系統之外，LLMs的操作通常限於根據用戶提示生成內容或信息。而在AI代理系統內，LLMs能夠通過解讀用戶請求並使用環境中可用的工具來完成任務。

**工具的訪問權限** - LLM可訪問的工具由以下兩個因素決定：1）它運行的環境，2）AI代理的開發者。例如，在旅行代理的案例中，代理的工具可能受限於預訂系統中的操作，或者開發者可以限制代理只能訪問航班相關的工具。

**知識** - 除了環境提供的信息外，AI代理還可以從其他系統、服務、工具甚至其他代理中獲取知識。在旅行代理的例子中，這些知識可能是存儲在客戶數據庫中的用戶旅行偏好信息。

### 不同類型的代理

現在我們已經了解了AI代理的一般定義，接下來讓我們看看一些具體的代理類型，以及它們如何應用於旅行預訂AI代理。

| **代理類型**                  | **描述**                                                                                | **範例**                                                                                |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **簡單反射代理**              | 根據預定義規則執行即時操作。                                                                                | 旅行代理解讀電子郵件內容，並將旅行投訴轉發給客戶服務部門。                                                                                |
| **基於模型的反射代理**        | 根據世界模型及其變化執行操作。                                                                                | 旅行代理根據歷史價格數據的訪問權限，優先處理價格有重大變動的路線。                                                                                |
| **目標導向代理**              | 通過解讀目標並確定達成目標所需的行動，來制定計劃實現特定目標。                                                                       | 旅行代理根據當前位置到目的地，確定所需的旅行安排（如汽車、公共交通、航班）並完成預訂。                                                                                |
| **效用導向代理**              | 考慮偏好並數值化權衡，以確定如何達成目標。                                                                                | 旅行代理在便利性與成本之間進行權衡，以最大化效用並完成旅行預訂。                                                                                |
| **學習代理**                  | 通過回應反饋並相應地調整行動來不斷改進。                                                                                | 旅行代理根據客戶在旅行後調查中的反饋，改進未來的預訂策略。                                                                                |
| **分層代理**                  | 包含多個代理的分層系統，高層代理將任務分解為子任務，由低層代理完成。                                                                 | 旅行代理通過將任務分解為子任務（例如取消具體預訂），由低層代理完成並回報給高層代理來實現取消行程。                                                                                |
| **多代理系統（MAS）**         | 多個代理獨立完成任務，可以是合作或競爭關係。                                                                                | 合作：多個代理分別預訂具體的旅行服務，如酒店、航班和娛樂活動。競爭：多個代理管理並競爭共享的酒店預訂日曆，以為客戶安排酒店入住。                                                        |

## 何時使用AI代理

在之前的部分中，我們使用旅行代理的案例說明了不同類型的代理如何應用於旅行預訂的不同場景。在整個課程中，我們將繼續使用這個應用作為示例。

接下來，讓我們看看AI代理最適合的應用場景：

![何時使用AI代理？](../../../translated_images/when-to-use-ai-agents.912b9a02e9e0e2af45a3e24faa4e912e334ec23f21f0cf5cb040b7e899b09cd0.tw.png?WT.mc_id=academic-105485-koreyst)

- **開放性問題** - 允許LLM自行決定完成任務所需的步驟，因為這些步驟無法總是硬編碼到工作流程中。
- **多步驟流程** - 涉及一定複雜度的任務，AI代理需要在多次交互中使用工具或信息，而不是一次性檢索。
- **隨時間改進** - 任務需要代理通過來自環境或用戶的反饋，不斷改進以提供更高的效用。

在《構建可信任的AI代理》課程中，我們將更深入探討使用AI代理的考量因素。

## 代理解決方案的基礎

### 代理開發

設計AI代理系統的第一步是定義工具、行動和行為。在本課程中，我們專注於使用 **Azure AI Agent Service** 來定義我們的代理。該服務提供以下功能：

- 選擇開放模型，例如OpenAI、Mistral和Llama。
- 通過Tripadvisor等提供商使用授權數據。
- 使用標準化的OpenAPI 3.0工具。

### 代理模式

與LLM的交互是通過提示完成的。由於AI代理的半自主性質，並非總是需要或可能在環境變化後手動重新提示LLM。我們使用 **代理模式**，允許我們在多個步驟中以更具規模化的方式提示LLM。

本課程將介紹當前一些流行的代理模式。

### 代理框架

代理框架允許開發者通過代碼實現代理模式。這些框架提供模板、插件和工具，幫助實現更好的AI代理協作。這些優勢使得AI代理系統更易於觀察和排查問題。

在本課程中，我們將探討基於研究的AutoGen框架，以及Semantic Kernel提供的生產級Agent框架。

**免責聲明**：
本文件是使用機器翻譯AI服務進行翻譯的。我們努力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原文文件為最具權威性的來源。對於關鍵信息，建議尋求專業人工翻譯。我們對因使用此翻譯而產生的任何誤解或誤讀概不負責。


# 探索 AI Agent 框架

AI Agent 框架是為了簡化 AI agent 的創建、部署和管理而設計的軟體平台。這些框架為開發者提供了預先構建的組件、抽象層和工具，從而加速複雜 AI 系統的開發過程。

透過提供標準化的方法來解決 AI agent 開發中的常見挑戰，這些框架讓開發者能專注於應用程式的獨特面向。同時，它們提升了 AI 系統的可擴展性、可存取性和效率。

## 簡介

本課程將涵蓋以下內容：

- 什麼是 AI Agent 框架？它能讓開發者完成哪些事情？
- 團隊如何利用這些框架快速原型化、迭代和提升 agent 的能力？
- 微軟的框架與工具（[Autogen](https://aka.ms/ai-agents/autogen)、[Semantic Kernel](https://aka.ms/ai-agents-beginners/semantic-kernel)、[Azure AI Agent Service](https://aka.ms/ai-agents-beginners/ai-agent-service)）之間的差異是什麼？
- 我可以直接整合現有的 Azure 生態系統工具，還是需要獨立的解決方案？
- 什麼是 Azure AI Agents 服務，它能如何幫助我？

## 學習目標

本課程的目標是幫助您了解：

- AI Agent 框架在 AI 開發中的角色。
- 如何利用 AI Agent 框架來構建智慧型 agent。
- AI Agent 框架所啟用的核心功能。
- Autogen、Semantic Kernel 和 Azure AI Agent Service 的差異。

## 什麼是 AI Agent 框架？它能讓開發者完成哪些事情？

傳統的 AI 框架可以幫助您將 AI 整合到應用程式中，並透過以下方式提升應用程式的功能：

- **個性化**：AI 能分析用戶行為和偏好，提供個性化的推薦、內容和體驗。
  範例：像 Netflix 這樣的串流服務利用 AI 根據觀看歷史推薦電影和節目，提升用戶參與度和滿意度。

- **自動化與效率**：AI 能自動化重複性任務、簡化工作流程並提升運營效率。
  範例：客戶服務應用程式利用 AI 驅動的聊天機器人處理常見問題，縮短回應時間，讓人類客服專注於更複雜的問題。

- **提升用戶體驗**：AI 能提供智慧功能，例如語音識別、自然語言處理和預測性文字輸入，改善整體用戶體驗。
  範例：像 Siri 和 Google Assistant 這樣的虛擬助手利用 AI 理解並回應語音指令，讓用戶更輕鬆地與裝置互動。

### 聽起來很棒對吧，那為什麼我們還需要 AI Agent 框架？

AI Agent 框架不僅僅是 AI 框架，它們旨在創建能與用戶、其他 agent 和環境互動以達成特定目標的智慧型 agent。這些 agent 能展現自主行為、做出決策並適應變化中的環境。我們來看看 AI Agent 框架啟用的一些關鍵功能：

- **Agent 的協作與協調**：能創建多個 AI agent，它們可以協作、溝通並共同解決複雜任務。
- **任務自動化與管理**：提供機制來自動化多步驟的工作流程、任務分配和動態任務管理。
- **上下文理解與適應**：讓 agent 具備理解上下文、適應變化環境並根據即時資訊做出決策的能力。

總而言之，這些 agent 能幫助您完成更多工作，將自動化提升到新層次，並創建能從環境中學習和適應的智慧系統。

## 如何快速原型化、迭代並提升 agent 的能力？

這是一個快速變化的領域，但大多數 AI Agent 框架中有一些共同的元素，能幫助您快速原型化和迭代，主要包括模組化組件、協作工具和即時學習。我們來深入了解這些元素：

- **使用模組化組件**：AI 框架提供預構建的組件，例如提示、解析器和記憶管理。
- **利用協作工具**：設計具有特定角色和任務的 agent，測試並完善協作工作流程。
- **即時學習**：實施反饋循環，讓 agent 從互動中學習並動態調整行為。

### 使用模組化組件

像 LangChain 和 Microsoft Semantic Kernel 這樣的框架提供了預構建的組件，例如提示、解析器和記憶管理。

**團隊如何使用**：團隊可以快速組裝這些組件來創建功能原型，無需從零開始，從而進行快速實驗和迭代。

**實際運作方式**：您可以使用預構建的解析器從用戶輸入中提取資訊，使用記憶模組來儲存和檢索數據，並使用提示生成器與用戶互動，無需自行構建這些組件。

**範例代碼**：以下是如何使用預構建的解析器從用戶輸入中提取資訊的範例：

```python
from langchain import Parser

parser = Parser()
user_input = "Book a flight from New York to London on July 15th"

parsed_data = parser.parse(user_input)

print(parsed_data)
# Output: {'origin': 'New York', 'destination': 'London', 'date': 'July 15th'}
```

從這個範例可以看出，如何利用預構建的解析器從用戶輸入中提取關鍵資訊，例如航班預訂請求的出發地、目的地和日期。這種模組化方法讓您能專注於高層次邏輯。

### 利用協作工具

像 CrewAI 和 Microsoft Autogen 這樣的框架可以幫助創建多個能協作的 agent。

**團隊如何使用**：團隊可以設計具有特定功能和任務的 agent，測試並完善協作工作流程，提升整體系統效率。

**實際運作方式**：您可以創建一組 agent，其中每個 agent 都有專門的功能，例如數據檢索、分析或決策。這些 agent 能溝通並分享資訊，以完成共同目標，例如回答用戶查詢或完成任務。

**範例代碼（Autogen）**：

```python
# creating agents, then create a round robin schedule where they can work together, in this case in order

# Data Retrieval Agent
# Data Analysis Agent
# Decision Making Agent

agent_retrieve = AssistantAgent(
    name="dataretrieval",
    model_client=model_client,
    tools=[retrieve_tool],
    system_message="Use tools to solve tasks."
)

agent_analyze = AssistantAgent(
    name="dataanalysis",
    model_client=model_client,
    tools=[analyze_tool],
    system_message="Use tools to solve tasks."
)

# conversation ends when user says "APPROVE"
termination = TextMentionTermination("APPROVE")

user_proxy = UserProxyAgent("user_proxy", input_func=input)

team = RoundRobinGroupChat([agent_retrieve, agent_analyze, user_proxy], termination_condition=termination)

stream = team.run_stream(task="Analyze data", max_turns=10)
# Use asyncio.run(...) when running in a script.
await Console(stream)
```

上述代碼展示了如何創建一個任務，涉及多個 agent 協作完成數據分析。每個 agent 執行特定功能，透過協調這些 agent 的行動來實現目標。透過創建具有專業角色的專屬 agent，您可以提升任務效率和性能。

### 即時學習

進階框架提供了即時上下文理解和適應的能力。

**團隊如何使用**：團隊可以實施反饋循環，讓 agent 從互動中學習並動態調整行為，實現持續改進和能力優化。

**實際運作方式**：agent 可以分析用戶反饋、環境數據和任務結果，更新其知識庫、調整決策演算法並提升性能。這種迭代學習過程讓 agent 能適應變化的條件和用戶偏好，增強整體系統的效能。

## Autogen、Semantic Kernel 和 Azure AI Agent Service 之間有什麼差異？

這些框架之間有許多比較方式，但我們可以從設計、功能和目標使用案例的角度來看一些關鍵差異：

### Autogen

這是一個由微軟研究院 AI Frontiers Lab 開發的開源框架，專注於事件驅動的分散式 *agentic* 應用程式，支持多個 LLM 和 SLM、工具以及進階的多 agent 設計模式。

Autogen 的核心概念是 agent，也就是能感知環境、做出決策並採取行動以達成特定目標的自主實體。agent 透過非同步訊息進行溝通，使其能獨立且並行工作，提升系統的可擴展性和響應性。

... (請參閱原始文件中的完整詳細說明，內容過多，無法一次列出)

### Semantic Kernel + Agent Framework

Semantic Kernel 包含兩部分：Semantic Kernel Agent Framework 和 Semantic Kernel 本身。

... (請參閱原始文件中的完整詳細說明)

### Azure AI Agent Service

Azure AI Agent Service 是最近推出的服務（於 Microsoft Ignite 2024 發表）。它允許使用更靈活的模型來開發和部署 AI agent，例如直接調用開源 LLM（如 Llama 3、Mistral 和 Cohere）。

... (請參閱原始文件中的完整詳細說明)

---

### 哪個框架適合您的使用案例？

以下是一些常見使用案例的建議：

> **Q**: 我的團隊正在開發一個涉及自動化代碼生成和數據分析任務的項目，我們應該使用哪個框架？
> **A**: Autogen 是一個不錯的選擇，因為它專注於事件驅動的分散式 *agentic* 應用程式，並支持進階的多 agent 設計模式。

... (請參閱原始文件中的完整對話內容)

---

希望這些資訊能幫助您更好地選擇適合您需求的 AI Agent 框架！
根據項目目標。適用於自然語言理解和內容生成。
- **Azure AI Agent Service**：靈活的模型、企業安全機制、數據存儲方法。適用於在企業應用中部署安全、可擴展且靈活的 AI 代理。

## 我可以直接整合現有的 Azure 生態系統工具，還是需要獨立的解決方案？
答案是肯定的，您可以直接將現有的 Azure 生態系統工具與 Azure AI Agent Service 整合，特別是因為它被設計為能與其他 Azure 服務無縫協作。例如，您可以整合 Bing、Azure AI Search 和 Azure Functions。此外，還可以與 Azure AI Foundry 深度整合。

對於 Autogen 和 Semantic Kernel，您也可以與 Azure 服務整合，但可能需要從您的代碼中調用 Azure 服務。另一種整合方式是使用 Azure SDK 從您的代理與 Azure 服務交互。此外，如前所述，您可以使用 Azure AI Agent Service 作為基於 Autogen 或 Semantic Kernel 構建的代理的協調器，從而輕鬆訪問 Azure 生態系統。

## 參考資料
- [1] - [Azure Agent Service](https://techcommunity.microsoft.com/blog/azure-ai-services-blog/introducing-azure-ai-agent-service/4298357)
- [2] - [Semantic Kernel and Autogen](https://devblogs.microsoft.com/semantic-kernel/microsofts-agentic-ai-frameworks-autogen-and-semantic-kernel/)
- [3] - [Semantic Kernel Agent Framework](https://learn.microsoft.com/semantic-kernel/frameworks/agent/?pivots=programming-language-csharp)
- [4] - [Azure AI Agent service](https://learn.microsoft.com/azure/ai-services/agents/overview)
- [5] - [Using Azure AI Agent Service with AutoGen / Semantic Kernel to build a multi-agent's solution](https://techcommunity.microsoft.com/blog/educatordeveloperblog/using-azure-ai-agent-service-with-autogen--semantic-kernel-to-build-a-multi-agen/4363121)

**免責聲明**：
本文件使用基於機器的人工智能翻譯服務進行翻譯。儘管我們努力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。原文檔的母語版本應被視為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們對使用此翻譯所引起的任何誤解或錯誤解讀概不負責。


# AI 代理設計原則

## 簡介

打造 AI 代理系統有許多不同的思路。由於在生成式 AI 設計中，模糊性是一種特性而非缺陷，工程師有時可能會不知道從何開始。我們制定了一套以人為中心的使用者體驗設計原則，幫助開發者建立以客戶需求為核心的代理系統，解決業務問題。這些設計原則並非具體的架構指導，而是為定義和構建代理體驗的團隊提供的一個起點。

一般來說，代理應該：

- 擴展並放大人類的能力（如腦力激盪、問題解決、自動化等）
- 填補知識空白（如讓我快速掌握某個知識領域、翻譯等）
- 促進並支持我們以個人偏好的方式與他人合作
- 幫助我們成為更好的自己（例如：生活教練/任務管理者，幫助我們學習情緒調節與正念技巧，建立韌性等）

## 本課程將涵蓋

- 什麼是代理設計原則
- 在實施這些設計原則時應遵循的指導方針
- 運用這些設計原則的範例

## 學習目標

完成本課程後，您將能夠：

1. 解釋什麼是代理設計原則
2. 說明如何應用代理設計原則的指導方針
3. 瞭解如何使用代理設計原則構建代理

## 代理設計原則

![Agentic Design Principles](../../../translated_images/agentic-design-principles.9f32a64bb6e2aa5a1bdffb70111aa724058bc248b1a3dd3c6661344015604cff.tw.png?WT.mc_id=academic-105485-koreyst)

### 代理（空間）

這是代理運行的環境。這些原則指導我們如何設計代理以便在物理和數位世界中互動。

- **連結，而非取代** – 幫助人們連結其他人、事件和可行的知識，促進協作與聯繫。
  - 代理協助連結事件、知識和人。
  - 代理拉近人與人之間的距離，而非取代或貶低人類。
- **易於存取但偶爾隱形** – 代理主要在背景中運行，僅在相關且適當時才提醒我們。
  - 代理對授權使用者在任何裝置或平台上都容易發現和存取。
  - 代理支持多模態的輸入與輸出（如聲音、語音、文字等）。
  - 代理可以根據使用者需求無縫切換前景與背景模式，或主動與被動狀態。
  - 代理可能以隱形形式運行，但其背景運作過程及與其他代理的協作對使用者是透明且可控的。

### 代理（時間）

這是代理隨時間運行的方式。這些原則指導我們如何設計代理在過去、現在和未來的互動。

- **過去**：反映歷史，包括狀態和上下文。
  - 代理基於更豐富的歷史數據分析提供更相關的結果，而不僅限於事件、人或狀態。
  - 代理從過去的事件中建立連結，並主動反思記憶以應對當前情境。
- **現在**：提示，而非僅僅通知。
  - 代理採取全面的方式與人互動。當事件發生時，代理不僅是靜態通知或形式化，而是簡化流程或動態生成提示，引導使用者在適當時刻專注。
  - 代理根據上下文環境、社會與文化變化，以及使用者意圖提供資訊。
  - 代理的互動可以是漸進的，隨著時間推移逐漸增強其複雜度，以賦能使用者。
- **未來**：適應與演進。
  - 代理適應不同裝置、平台和模式。
  - 代理適應使用者行為和無障礙需求，並可自由定制。
  - 代理通過持續的使用者互動來塑造並演進。

### 代理（核心）

這是代理設計核心的關鍵元素。

- **擁抱不確定性但建立信任**。
  - 代理的不確定性是可以預期的。不確定性是代理設計中的一個關鍵要素。
  - 信任與透明是代理設計的基礎層。
  - 人類可以控制代理的開啟/關閉，代理狀態始終清晰可見。

## 實施這些原則的指導方針

在使用上述設計原則時，請遵循以下指導方針：

1. **透明性**：告知使用者 AI 的參與方式、其運作原理（包括過去的行為），以及如何提供反饋和修改系統。
2. **控制權**：讓使用者能夠自訂、設定偏好並個性化，並擁有對系統及其屬性的控制權（包括忘記的能力）。
3. **一致性**：目標是在裝置與端點之間提供一致的多模態體驗。儘量使用熟悉的 UI/UX 元素（例如，語音互動的麥克風圖示），並盡可能減少使用者的認知負擔（例如，提供簡潔的回應、視覺輔助以及“瞭解更多”內容）。

## 如何運用這些原則和指導方針設計旅行代理

假設您正在設計一個旅行代理，以下是如何運用設計原則和指導方針的思路：

1. **透明性** – 告訴使用者旅行代理是一個 AI 驅動的代理。提供一些基本的使用說明（例如，“Hello”訊息，範例提示）。在產品頁面上清楚記載。顯示使用者過去詢問的提示列表。明確說明如何提供反饋（例如，讚/踩按鈕、發送反饋按鈕等）。清楚說明代理是否有使用或主題限制。
2. **控制權** – 明確告訴使用者如何在代理創建後進行修改，例如系統提示。讓使用者選擇代理的詳細程度、寫作風格，以及代理不應談論的內容限制。允許使用者檢視和刪除任何相關的檔案或數據、提示和過去的對話。
3. **一致性** – 確保分享提示、添加檔案或照片，以及標記某人或某物的圖示是標準且易識別的。使用回形針圖示表示檔案上傳/分享功能，使用圖片圖示表示圖形上傳功能。

## 其他資源
- [Practices for Governing Agentic AI Systems | OpenAI](https://openai.com)
- [The HAX Toolkit Project - Microsoft Research](https://microsoft.com)
- [Responsible AI Toolbox](https://responsibleaitoolbox.ai)

**免責聲明**：
本文件使用基於機器的人工智能翻譯服務進行翻譯。儘管我們努力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原始語言的文件作為權威來源。對於關鍵信息，建議尋求專業的人工作翻譯。我們對因使用此翻譯而產生的任何誤解或誤讀概不負責。


# 工具使用設計模式

## 介紹

在這節課中，我們將回答以下問題：

- 什麼是工具使用設計模式？
- 它可以應用於哪些使用案例？
- 實現這種設計模式需要哪些要素/組件？
- 使用工具使用設計模式來構建可信任的 AI 代理時需要注意哪些特別考量？

## 學習目標

完成本課程後，您將能夠：

- 定義工具使用設計模式及其目的。
- 辨識適用於工具使用設計模式的使用案例。
- 理解實現該設計模式所需的關鍵要素。
- 了解確保使用此設計模式的 AI 代理可信任的考量。

## 什麼是工具使用設計模式？

**工具使用設計模式**專注於賦予大型語言模型（LLMs）與外部工具互動的能力，以達成特定目標。工具是可由代理執行的程式碼，可以是簡單的函數（例如計算器），也可以是第三方服務的 API 呼叫（例如股票價格查詢或天氣預報）。在 AI 代理的上下文中，工具被設計為由代理根據**模型生成的函數呼叫**來執行。

## 它可以應用於哪些使用案例？

AI 代理可以利用工具完成複雜任務、檢索資訊或做出決策。工具使用設計模式通常用於需要與外部系統動態互動的場景，例如資料庫、網路服務或程式碼解釋器。這種能力適用於多種使用案例，包括但不限於：

- **動態資訊檢索：** 代理可以查詢外部 API 或資料庫以獲取最新數據（例如，查詢 SQLite 資料庫進行數據分析、獲取股票價格或天氣資訊）。
- **程式碼執行與解釋：** 代理可以執行程式碼或腳本來解決數學問題、生成報告或進行模擬。
- **工作流程自動化：** 通過整合任務排程器、電子郵件服務或數據管道等工具，自動化重複性或多步驟的工作流程。
- **客戶支持：** 代理可以與 CRM 系統、工單平台或知識庫互動，解決用戶問題。
- **內容生成與編輯：** 代理可以利用工具（如文法檢查器、文本摘要工具或內容安全評估器）協助完成內容創建任務。

## 實現工具使用設計模式需要哪些要素/組件？

### 函數/工具呼叫

函數呼叫是讓大型語言模型（LLMs）與工具互動的主要方式。您經常會看到「函數」和「工具」這兩個詞互換使用，因為「函數」（可重用的程式碼塊）就是代理用來執行任務的「工具」。為了讓函數的程式碼被調用，LLM 必須將用戶的請求與函數的描述進行比較。為此，需要向 LLM 傳送包含所有可用函數描述的架構（schema）。LLM 然後選擇最適合任務的函數，並返回其名稱和參數。選定的函數被調用，其響應會返回給 LLM，LLM 使用這些資訊來回應用戶的請求。

開發人員若要為代理實現函數呼叫，您需要：

1. 支援函數呼叫的 LLM 模型
2. 包含函數描述的架構
3. 每個描述函數的程式碼

讓我們用一個獲取城市當前時間的例子來說明：

- **初始化支援函數呼叫的 LLM：**

    並非所有模型都支援函數呼叫，因此檢查您使用的 LLM 是否支援此功能非常重要。[Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/how-to/function-calling) 支援函數呼叫。我們可以從初始化 Azure OpenAI 客戶端開始。

    ```python
    # Initialize the Azure OpenAI client
    client = AzureOpenAI(
        azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"),
        api_key=os.getenv("AZURE_OPENAI_API_KEY"),
        api_version="2024-05-01-preview"
    )
    ```

- **創建函數架構：**

    接下來，我們將定義一個包含函數名稱、函數用途描述以及函數參數名稱和描述的 JSON 架構。我們將此架構與用戶的請求一同傳遞給上述創建的客戶端，以查找舊金山的時間。需要注意的是，返回的是**工具呼叫**，而**不是**問題的最終答案。如前所述，LLM 返回的是它為任務選擇的函數名稱及其參數。

    ```python
    # Function description for the model to read
    tools = [
        {
            "type": "function",
            "function": {
                "name": "get_current_time",
                "description": "Get the current time in a given location",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "The city name, e.g. San Francisco",
                        },
                    },
                    "required": ["location"],
                },
            }
        }
    ]
    ```

    ```python

    # Initial user message
    messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

    # First API call: Ask the model to use the function
      response = client.chat.completions.create(
          model=deployment_name,
          messages=messages,
          tools=tools,
          tool_choice="auto",
      )

      # Process the model's response
      response_message = response.choices[0].message
      messages.append(response_message)

      print("Model's response:")

      print(response_message)

    ```

    ```bash
    Model's response:
    ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_pOsKdUlqvdyttYB67MOj434b', function=Function(arguments='{"location":"San Francisco"}', name='get_current_time'), type='function')])
    ```

- **執行任務所需的函數程式碼：**

    現在，LLM 已選擇需要執行的函數，接下來需要實現並執行執行任務的程式碼。我們可以使用 Python 實現獲取當前時間的程式碼，還需要編寫程式碼來從 `response_message` 中提取名稱和參數以獲取最終結果。

    ```python
      def get_current_time(location):
        """Get the current time for a given location"""
        print(f"get_current_time called with location: {location}")
        location_lower = location.lower()

        for key, timezone in TIMEZONE_DATA.items():
            if key in location_lower:
                print(f"Timezone found for {key}")
                current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
                return json.dumps({
                    "location": location,
                    "current_time": current_time
                })

        print(f"No timezone data found for {location_lower}")
        return json.dumps({"location": location, "current_time": "unknown"})
    ```

     ```python
     # Handle function calls
      if response_message.tool_calls:
          for tool_call in response_message.tool_calls:
              if tool_call.function.name == "get_current_time":

                  function_args = json.loads(tool_call.function.arguments)

                  time_response = get_current_time(
                      location=function_args.get("location")
                  )

                  messages.append({
                      "tool_call_id": tool_call.id,
                      "role": "tool",
                      "name": "get_current_time",
                      "content": time_response,
                  })
      else:
          print("No tool calls were made by the model.")

      # Second API call: Get the final response from the model
      final_response = client.chat.completions.create(
          model=deployment_name,
          messages=messages,
      )

      return final_response.choices[0].message.content
     ```

     ```bash
      get_current_time called with location: San Francisco
      Timezone found for san francisco
      The current time in San Francisco is 09:24 AM.
     ```

函數呼叫是大多數（如果不是全部的話）代理工具使用設計的核心，然而從零開始實現它有時可能會具有挑戰性。如我們在 [第 2 課](../../../02-explore-agentic-frameworks) 中學到的，代理框架為我們提供了實現工具使用的預構建組件。

### 使用代理框架的工具使用範例

- ### **[Semantic Kernel](https://learn.microsoft.com/azure/ai-services/agents/overview)**

    Semantic Kernel 是一個為 .NET、Python 和 Java 開發者設計的開源 AI 框架，用於與大型語言模型（LLMs）協作。它通過一個稱為[序列化](https://learn.microsoft.com/semantic-kernel/concepts/ai-services/chat-completion/function-calling/?pivots=programming-language-python#1-serializing-the-functions)的過程，自動向模型描述函數及其參數，簡化了函數呼叫的過程。它還處理模型與程式碼之間的交互。使用像 Semantic Kernel 這樣的代理框架的另一個優勢是，您可以訪問預構建的工具，例如 [File Search](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step4_assistant_tool_file_search.py) 和 [Code Interpreter](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step3_assistant_tool_code_interpreter.py)。

    下圖說明了使用 Semantic Kernel 進行函數呼叫的過程：

    ![函數呼叫](../../../translated_images/functioncalling-diagram.b5493ea5154ad8e3e4940d2e36a49101eec1398948e5d1039942203b4f5a4209.tw.png)

    在 Semantic Kernel 中，函數/工具被稱為 [Plugins](https://learn.microsoft.com/semantic-kernel/concepts/plugins/?pivots=programming-language-python)。我們可以將函數 `get_current_time` function we saw earlier into a plugin by turning it into a class with the function in it. We can also import the `kernel_function` 裝飾器，這需要提供函數的描述。當您使用 GetCurrentTimePlugin 創建一個 kernel 時，kernel 將自動序列化該函數及其參數，並在此過程中創建發送給 LLM 的架構。

    ```python
    from semantic_kernel.functions import kernel_function

    class GetCurrentTimePlugin:
        async def __init__(self, location):
            self.location = location

        @kernel_function(
            description="Get the current time for a given location"
        )
        def get_current_time(location: str = ""):
            ...

    ```

    ```python
    from semantic_kernel import Kernel

    # Create the kernel
    kernel = Kernel()

    # Create the plugin
    get_current_time_plugin = GetCurrentTimePlugin(location)

    # Add the plugin to the kernel
    kernel.add_plugin(get_current_time_plugin)
    ```

- ### **[Azure AI Agent Service](https://learn.microsoft.com/azure/ai-services/agents/overview)**

    Azure AI Agent Service 是一個新型代理框架，旨在幫助開發者安全地構建、部署和擴展高質量且可擴展的 AI 代理，而無需管理底層的計算和存儲資源。它對於企業應用特別有用，因為它是一個具有企業級安全性的完全託管服務。

    與直接使用 LLM API 開發相比，Azure AI Agent Service 提供了一些優勢，包括：
  - 自動工具呼叫——無需解析工具呼叫、調用工具並處理響應；所有這些現在都在伺服器端完成。
  - 安全管理數據——您可以依靠線程存儲所需的所有資訊，而無需管理自己的對話狀態。
  - 現成的工具——您可以使用這些工具與數據源交互，例如 Bing、Azure AI Search 和 Azure Functions。

    Azure AI Agent Service 中的工具可以分為兩類：

    1. 知識工具：
        - [使用 Bing 搜索進行基礎設置](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/bing-grounding?tabs=python&pivots=overview)
        - [文件搜索](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/file-search?tabs=python&pivots=overview)
        - [Azure AI Search](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/azure-ai-search?tabs=azurecli%2Cpython&pivots=overview-azure-ai-search)

    2. 行動工具：
        - [函數呼叫](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/function-calling?tabs=python&pivots=overview)
        - [程式碼解釋器](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/code-interpreter?tabs=python&pivots=overview)
        - [OpenAI 定義的工具](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/openapi-spec?tabs=python&pivots=overview)
        - [Azure Functions](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/azure-functions?pivots=overview)

    Agent Service 允許我們將這些工具作為一個 `toolset`. It also utilizes `threads` which keep track of the history of messages from a particular conversation.

    Imagine you are a sales agent at a company called Contoso. You want to develop a conversational agent that can answer questions about your sales data.

    The image below illustrates how you could use Azure AI Agent Service to analyze your sales data:

    ![Agentic Service In Action](../../../translated_images/agent-service-in-action.8c2d8aa8e9d91feeb29549b3fde529f8332b243875154d03907616a69198afbc.tw.jpg?WT.mc_id=academic-105485-koreyst)

    To use any of these tools with the service we can create a client and define a tool or toolset. To implement this practically we can use the Python code below. The LLM will be able to look at the toolset and decide whether to use the user created function, `fetch_sales_data_using_sqlite_query` 或者根據用戶請求使用預構建的程式碼解釋器。

    ```python
    import os
    from azure.ai.projects import AIProjectClient
    from azure.identity import DefaultAzureCredential
    from fecth_sales_data_functions import fetch_sales_data_using_sqlite_query # fetch_sales_data_using_sqlite_query function which can be found in a fecth_sales_data_functions.py file.
    from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

    project_client = AIProjectClient.from_connection_string(
        credential=DefaultAzureCredential(),
        conn_str=os.environ["PROJECT_CONNECTION_STRING"],
    )

    # Initialize function calling agent with the fetch_sales_data_using_sqlite_query function and adding it to the toolset
    fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
    toolset = ToolSet()
    toolset.add(fetch_data_function)

    # Initialize Code Interpreter tool and adding it to the toolset.
    code_interpreter = code_interpreter = CodeInterpreterTool()
    toolset = ToolSet()
    toolset.add(code_interpreter)

    agent = project_client.agents.create_agent(
        model="gpt-4o-mini", name="my-agent", instructions="You are helpful agent",
        toolset=toolset
    )
    ```

## 使用工具使用設計模式構建可信任 AI 代理的特別考量是什麼？

LLM 動態生成的 SQL 一個常見的問題是安全性，尤其是 SQL 注入或惡意行為的風險，例如刪除或篡改資料庫。儘管這些擔憂是合理的，但可以通過適當配置資料庫訪問權限有效減輕。對於大多數資料庫，這涉及將資料庫配置為只讀模式。對於像 PostgreSQL 或 Azure SQL 這樣的資料庫服務，應為應用程式分配只讀（SELECT）角色。

在安全環境中運行應用進一步增強了保護。在企業場景中，數據通常從操作系統中提取並轉換為只讀資料庫或數據倉庫，並配有用戶友好的架構。這種方法確保了數據的安全性、性能優化和可訪問性，並且應用程式具有受限的只讀訪問權限。

## 其他資源

- [Azure AI Agents Service Workshop](https://microsoft.github.io/build-your-first-agent-with-azure-ai-agent-service-workshop/)
- [Contoso Creative Writer Multi-Agent Workshop](https://github.com/Azure-Samples/contoso-creative-writer/tree/main/docs/workshop)
- [Semantic Kernel Function Calling Tutorial](https://learn.microsoft.com/semantic-kernel/concepts/ai-services/chat-completion/function-calling/?pivots=programming-language-python#1-serializing-the-functions)
- [Semantic Kernel Code Interpreter](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step3_assistant_tool_code_interpreter.py)
- [Autogen Tools](https://microsoft.github.io/autogen/dev/user-guide/core-user-guide/components/tools.html)
```

**免責聲明**：
本文件是使用基於機器的人工智能翻譯服務進行翻譯的。儘管我們努力確保翻譯的準確性，但請注意，自動翻譯可能會包含錯誤或不準確之處。應以原始語言的文件作為權威來源。對於關鍵信息，建議使用專業的人工作翻譯。我們對因使用此翻譯而引起的任何誤解或誤讀不承擔責任。


# Agentic RAG

本課程提供對「代理型檢索增強生成」（Agentic Retrieval-Augmented Generation, Agentic RAG）的全面概述。這是一種新興的 AI 範式，讓大型語言模型（LLM）在拉取外部資訊的同時，能夠自主規劃下一步行動。與傳統靜態的檢索後閱讀模式不同，Agentic RAG 包含對 LLM 的多次迭代調用，並穿插工具或函數調用以及結構化輸出。系統會評估結果、改進查詢、在必要時調用額外工具，並持續此循環直到找到滿意的解決方案。

## 課程介紹

本課程將涵蓋以下內容：

- **理解 Agentic RAG：** 了解這種 AI 新範式，讓大型語言模型（LLM）在拉取外部數據的同時，能夠自主規劃下一步行動。
- **掌握迭代式製作者-檢查者模式：** 理解 LLM 的迭代調用循環，穿插工具或函數調用以及結構化輸出，旨在提升正確性並處理格式不正確的查詢。
- **探索實際應用場景：** 找出 Agentic RAG 的亮點應用場景，例如以正確性為優先的環境、複雜的數據庫互動以及延伸工作流程。

## 學習目標

完成本課程後，您將能夠：

- **理解 Agentic RAG：** 學習這種新興 AI 範式，讓大型語言模型（LLM）在拉取外部數據的同時，能夠自主規劃下一步行動。
- **迭代式製作者-檢查者模式：** 掌握 LLM 的迭代調用循環，穿插工具或函數調用以及結構化輸出，旨在提升正確性並處理格式不正確的查詢。
- **掌控推理過程：** 理解系統如何自主掌控推理過程，決定解決問題的方法，而不依賴預先定義的路徑。
- **工作流程：** 瞭解代理型模型如何自主決定檢索市場趨勢報告、識別競爭對手數據、關聯內部銷售指標、綜合分析結果並評估策略。
- **迭代循環、工具整合與記憶：** 學習系統如何依賴循環互動模式，跨步驟維持狀態與記憶，避免重複循環並做出明智的決策。
- **處理失敗模式與自我修正：** 探索系統的強大自我修正機制，包括迭代和重新查詢、使用診斷工具以及依靠人類監督。
- **代理的界限：** 理解 Agentic RAG 的限制，聚焦於特定領域的自主性、基礎設施依賴以及對安全框架的遵守。
- **實際應用場景與價值：** 找出 Agentic RAG 的亮點應用場景，例如以正確性為優先的環境、複雜的數據庫互動以及延伸工作流程。
- **治理、透明性與信任：** 學習治理與透明性的重要性，包括可解釋的推理、偏差控制以及人類監督。

## 什麼是 Agentic RAG？

代理型檢索增強生成（Agentic Retrieval-Augmented Generation, Agentic RAG）是一種新興的 AI 範式，讓大型語言模型（LLM）在拉取外部資訊的同時，能夠自主規劃下一步行動。與靜態的檢索後閱讀模式不同，Agentic RAG 包含對 LLM 的多次迭代調用，並穿插工具或函數調用以及結構化輸出。系統會評估結果、改進查詢、在必要時調用額外工具，並持續此循環直到找到滿意的解決方案。

這種迭代的「製作者-檢查者」操作模式能提升正確性，處理結構化數據庫（例如 NL2SQL）中格式不正確的查詢，並確保高品質的結果。系統會主動掌控推理過程，重寫失敗的查詢、選擇不同的檢索方法並整合多種工具，例如 Azure AI Search 的向量檢索、SQL 數據庫或自定義 API，然後再完成答案。代理型系統的獨特之處在於它能自主掌控推理過程，而不是依賴預定義的路徑。

## 定義代理型檢索增強生成（Agentic RAG）

代理型檢索增強生成（Agentic RAG）是一種 AI 開發的新興範式，讓 LLM 不僅能從外部數據來源中拉取資訊，還能自主規劃下一步行動。與靜態的檢索後閱讀模式或精心編排的提示序列不同，Agentic RAG 包含一個迭代循環，穿插工具或函數調用以及結構化輸出。在每個階段，系統會評估已獲得的結果，決定是否改進查詢、調用額外工具，並持續此循環直到達成滿意的解決方案。

這種迭代的「製作者-檢查者」操作模式旨在提升正確性，處理結構化數據庫中格式不正確的查詢（例如 NL2SQL），並確保平衡且高品質的結果。與僅依賴精心設計的提示鏈不同，系統會主動掌控推理過程。它能重寫失敗的查詢、選擇不同的檢索方法，並整合多種工具，例如 Azure AI Search 的向量檢索、SQL 數據庫或自定義 API，然後再完成答案。這樣可以減少對過於複雜的編排框架的需求，僅需一個相對簡單的「LLM 調用 → 工具使用 → LLM 調用 → …」循環即可產生高級且有根據的輸出。

![Agentic RAG 核心循環](../../../translated_images/agentic-rag-core-loop.2224925a913fb3439f518bda61a40096ddf6aa432a11c9b5bba8d0d625e47b79.tw.png)

## 掌控推理過程

讓系統成為「代理型」的關鍵特性是其自主掌控推理過程的能力。傳統的 RAG 實現通常依賴人類預先定義的路徑：例如指定檢索什麼內容以及何時檢索的思路鏈。
但真正的代理型系統能內部決定如何解決問題。它不只是執行腳本，而是基於找到的資訊質量，自主決定步驟的順序。
例如，當被要求制定產品發佈策略時，它不會僅依賴一個列出整個研究和決策工作流程的提示，而是自主決定：

1. 使用 Bing Web Grounding 檢索當前市場趨勢報告。
2. 利用 Azure AI Search 識別相關的競爭對手數據。
3. 使用 Azure SQL Database 關聯歷史內部銷售指標。
4. 通過 Azure OpenAI Service 將調研結果綜合成一個連貫的策略。
5. 評估策略中的漏洞或不一致之處，必要時啟動新一輪的檢索。

所有這些步驟——改進查詢、選擇數據來源、反覆迭代直到「滿意」為止——都是由模型決定的，而非人類預先編寫的腳本。

## 迭代循環、工具整合與記憶

![工具整合架構](../../../translated_images/tool-integration.7b05a923e3278bf1fd2972faa228fb2ac725f166ed084362b031a24bffd26287.tw.png)

代理型系統依賴於一種循環互動模式：

- **初始調用：** 用戶的目標（即用戶提示）被提交給 LLM。
- **工具調用：** 如果模型發現缺少資訊或指令不明確，它會選擇一個工具或檢索方法，例如向量數據庫查詢（例如 Azure AI Search 的混合搜索）或結構化 SQL 調用，來獲取更多上下文。
- **評估與改進：** 在審查返回的數據後，模型決定這些資訊是否足夠。如果不足，它會改進查詢、嘗試不同的工具或調整方法。
- **重複直到滿意：** 此循環持續進行，直到模型認為它擁有足夠的清晰度和證據來提供一個最終的、經過充分推理的回應。
- **記憶與狀態：** 系統會跨步驟維持狀態和記憶，因此可以回憶起之前的嘗試及其結果，避免重複循環並在過程中做出更明智的決策。

隨著時間的推移，這種模式會形成一種逐步深入理解的感覺，讓模型能夠在無需人類不斷干預或重新編寫提示的情況下，完成複雜的多步任務。

## 處理失敗模式與自我修正

Agentic RAG 的自主性還包括強大的自我修正機制。當系統遇到死胡同，例如檢索到無關文件或遇到格式不正確的查詢時，它可以：

- **迭代與重新查詢：** 模型不會返回低價值的回應，而是嘗試新的搜索策略、重寫數據庫查詢或查找替代數據集。
- **使用診斷工具：** 系統可能調用額外的功能來幫助它調試推理步驟或確認檢索數據的正確性。像 Azure AI Tracing 這樣的工具對於實現健全的可觀察性和監控至關重要。
- **依靠人類監督：** 在高風險或多次失敗的場景中，模型可能會標記不確定性並請求人類指導。一旦人類提供了糾正性反饋，模型可以在後續操作中吸收這一教訓。

這種迭代且動態的方法讓模型能夠持續改進，確保它不僅僅是一個「一次性」的系統，而是一個能夠在特定會話中從錯誤中學習的系統。

![自我修正機制](../../../translated_images/self-correction.3d42c31baf4a476bb89313cec58efb196b0e97959c04d7439cc23d27ef1242ac.tw.png)

## 代理的界限

儘管在任務中具備自主性，Agentic RAG 並不等同於通用人工智慧（AGI）。其「代理型」能力被限制在開發者提供的工具、數據來源和政策範圍內。它無法自行創建工具或超越既定的領域邊界，而是擅長動態編排現有資源。

與更高級的 AI 形式相比，其主要差異包括：

1. **特定領域的自主性：** Agentic RAG 系統專注於在已知領域內實現用戶定義的目標，採用查詢重寫或工具選擇等策略來提升結果。
2. **依賴基礎設施：** 系統的能力取決於開發者整合的工具和數據。它無法在沒有人工干預的情況下超越這些邊界。
3. **遵守安全框架：** 道德指導方針、合規規則和業務政策仍然至關重要。代理的自由度始終受到安全措施和監管機制的限制（希望如此？）。

## 實際應用場景與價值

Agentic RAG 在需要迭代改進和高精度的場景中表現尤為突出：

1. **以正確性為優先的環境：** 在合規檢查、法規分析或法律研究中，代理型模型可以反覆驗證事實、諮詢多個來源並重寫查詢，直到產生經過充分審核的答案。
2. **複雜的數據庫互動：** 當處理結構化數據時，查詢可能經常失敗或需要調整，系統可以利用 Azure SQL 或 Microsoft Fabric OneLake 自主改進查詢，確保最終檢索與用戶意圖一致。
3. **延伸工作流程：** 當新的資訊浮現時，長時間運行的會話可能會隨之演變。Agentic RAG 能夠持續整合新數據，並根據對問題空間的進一步了解調整策略。

## 治理、透明性與信任

隨著這些系統在推理上變得更加自主，治理與透明性至關重要：

- **可解釋的推理：** 模型可以提供一個查詢記錄，包括它進行的查詢、諮詢的來源以及它採取的推理步驟。像 Azure AI Content Safety 和 Azure AI Tracing / GenAIOps 這樣的工具有助於保持透明性並減少風險。
- **偏差控制與平衡檢索：** 開發者可以調整檢索策略以確保考慮到平衡且具代表性的數據來源，並定期審核輸出以檢測偏差或偏向模式，這對於使用 Azure Machine Learning 的高級數據科學組織尤其重要。
- **人類監督與合規：** 對於敏感任務，人類審核仍然是必要的。Agentic RAG 不會取代人類在高風險決策中的判斷，而是通過提供經過充分審核的選項來輔助人類。

擁有能夠清楚記錄操作的工具至關重要。否則，調試多步驟過程可能會非常困難。以下是 Literal AI（Chainlit 背後的公司）提供的一個代理運行範例：

![代理運行範例](../../../translated_images/AgentRunExample.27e2df23ad898772d1b3e7a3e3cd4615378e10dfda87ae8f06b4748bf8eea97d.tw.png)

![代理運行範例2](../../../translated_images/AgentRunExample2.c0e8c78b1f2540a641515e60035abcc6a9c5e3688bae143eb6c559dd37cdee9f.tw.png)

## 結論

Agentic RAG 代表了 AI 系統處理複雜數據密集型任務的一種自然演進。通過採用循環互動模式、自主選擇工具並改進查詢直到達到高品質結果，該系統超越了靜態的提示執行，成為一個更具適應性和上下文感知的決策者。儘管仍然受到人類定義的基礎設施和道德準則的約束，這些代理型能力為企業和最終用戶帶來了更豐富、更動態、最終更有用的 AI 互動。

## 其他資源

- 使用 Azure OpenAI Service 實現檢索增強生成（RAG）：學習如何使用您自己的數據與 Azure OpenAI Service。[此 Microsoft Learn 模組提供了實現 RAG 的全面指南](https://learn.microsoft.com/training/modules/use-own-data-azure-openai)
- 使用 Azure AI Foundry 評估生成式 AI 應用：本文涵蓋了在公開數據集上評估和比較模型的方法，包括 [代理型 AI 應用與 RAG 架構](https://learn.microsoft.com/azure/ai-studio/concepts/evaluation-approach-gen-ai)
- [什麼是 Agentic RAG | Weaviate](https://weaviate.io/blog/what-is-agentic-rag)
- [Agentic RAG：代理型檢索增強生成的完整指南 – generation RAG 的新聞](https://ragaboutit.com/agentic-rag-a-complete-guide-to-agent-based-retrieval-augmented-generation/)
- [Agentic RAG：通過查詢重構和自查提升 RAG！Hugging Face 開源 AI 實用手冊](https://huggingface.co/learn/cookbook/agent_rag)
- [為 RAG 添加代理層](https://youtu.be/aQ4yQXeB1Ss?si=2HUqBzHoeB5tR04U)
- [知識助理的未來：Jerry Liu](https://www.youtube.com/watch?v=zeAyuLc_f3Q&t=244s)
- [如何構建 Agentic RAG 系統](https://www.youtube.com/watch?v=AOSjiXP1jmQ)
- [使用 Azure AI Foundry Agent Service 擴展您的 AI 代理](https://ignite.microsoft.com/sessions/BRK102?source=sessions)

### 學術論文

- [2303.17651 Self-Refine: Iterative Refinement with Self-Feedback](https://arxiv.org/abs/2303.17651)
- [2303.11366 Reflexion: Language Agents with Verbal Reinforcement Learning](https://arxiv.org/abs/2303.11366)
- [2305.11738 CRITIC: Large Language Models Can Self-Correct with Tool-Interactive Critiquing](https://arxiv.org/abs/2305.11738)

**免責聲明**：
本文件使用基於機器的人工智能翻譯服務進行翻譯。儘管我們努力確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原始語言的文件為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們對因使用本翻譯而產生的任何誤解或錯誤解釋不承擔責任。