# 設計規劃

## 簡介

呢堂課會講解以下內容：

* 點樣清晰咁定義一個整體目標，並將複雜嘅任務拆解成可管理嘅細項。
* 善用結構化輸出，提供更可靠同機器可讀嘅回應。
* 採用事件驅動嘅方法，應對動態任務同突發輸入。

## 學習目標

完成呢堂課後，你將會了解：

* 點樣為 AI agent 設定清晰嘅整體目標，確保佢知道需要達成咩。
* 將複雜嘅任務分解成可管理嘅子任務，並用邏輯次序組織好。
* 為 agents 配備合適嘅工具（例如搜尋工具或數據分析工具），決定幾時同點樣使用，並處理出現嘅突發情況。
* 評估子任務嘅結果，衡量表現，並對行動進行迭代改進，以提升最終輸出。

## 定義整體目標同拆解任務

![定義目標同任務](../../../translated_images/defining-goals-tasks.dcc1181bbdb194704ae0fb3363371562949e8b03fd2fadc256218aaadf84a9f4.hk.png)

大部分現實世界嘅任務都太過複雜，唔可以一步完成。AI agent 需要一個簡明嘅目標嚟指導佢嘅規劃同行動。例如，考慮以下目標：

    "生成一個 3 日嘅旅遊行程表。"

雖然目標簡單易明，但仍然需要進一步細化。目標越清晰，agent（同人類協作者）越能專注於實現正確嘅結果，例如創建一個全面嘅行程表，包括航班選擇、酒店推薦同活動建議。

### 任務分解

大或者複雜嘅任務可以拆分成細小、針對目標嘅子任務，咁樣會更加易處理。
以旅遊行程表為例，你可以將目標分解成以下部分：

* 機票預訂
* 酒店預訂
* 汽車租賃
* 個人化設定

每個子任務可以交畀專門嘅 agents 或流程處理。例如，一個 agent 可以專注於搜尋最佳機票優惠，另一個則負責酒店預訂，等等。之後，一個協調或者“下游”agent 可以將呢啲結果整合成一個完整嘅行程表提供畀用戶。

呢種模組化嘅方法仲方便逐步改進。例如，你可以加入專門處理美食推薦或者當地活動建議嘅 agents，隨時間優化行程表。

### 結構化輸出

大型語言模型（LLMs）可以生成結構化輸出（例如 JSON），更容易畀下游嘅 agents 或服務進一步解析同處理。呢個特別適合多 agent 嘅場景，當規劃結果生成後，可以即刻執行呢啲任務。參考呢篇 [blogpost](https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/cookbook/structured-output-agent.html) 可以快速了解。

以下係一段 Python 範例代碼，展示咗一個簡單嘅規劃 agent 點樣將目標分解成子任務並生成結構化嘅計劃：

### 多 Agent 協調嘅規劃 Agent

呢個例子中，一個 Semantic Router Agent 接收用戶請求（例如，“我需要一個針對我旅行嘅酒店計劃。”）。

規劃器會：

* 接收酒店計劃：規劃器根據用戶嘅信息，結合系統提示（包括可用 agent 嘅詳情），生成一個結構化嘅旅遊計劃。
* 列出 Agents 同佢哋嘅工具：agent 註冊表會保存一個 agents 嘅列表（例如航班、酒店、汽車租賃同活動），以及佢哋提供嘅功能或工具。
* 將計劃分配畀相關嘅 Agents：根據子任務數量，規劃器會直接將信息發送畀專屬 agent（單一任務情況），或者透過群組聊天管理器協調多 agent 嘅合作。
* 總結結果：最後，規劃器會將生成嘅計劃進行總結，方便理解。

以下係示例代碼展示咗呢啲步驟：

```python

from pydantic import BaseModel

from enum import Enum
from typing import List, Optional, Union

class AgentEnum(str, Enum):
    FlightBooking = "flight_booking"
    HotelBooking = "hotel_booking"
    CarRental = "car_rental"
    ActivitiesBooking = "activities_booking"
    DestinationInfo = "destination_info"
    DefaultAgent = "default_agent"
    GroupChatManager = "group_chat_manager"

# Travel SubTask Model

class TravelSubTask(BaseModel):
    task_details: str
    assigned_agent: AgentEnum # we want to assign the task to the agent

class TravelPlan(BaseModel):
    main_task: str
    subtasks: List[TravelSubTask]
    is_greeting: bool
import json
import os
from typing import Optional

from autogen_core.models import UserMessage, SystemMessage, AssistantMessage
from autogen_ext.models.openai import AzureOpenAIChatCompletionClient

# Create the client with type-checked environment variables

client = AzureOpenAIChatCompletionClient(
    azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
    model=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
)

from pprint import pprint

# Define the user message

messages = [
    SystemMessage(content="""You are an planner agent.
    Your job is to decide which agents to run based on the user's request.
    Below are the available agents specialised in different tasks:
    - FlightBooking: For booking flights and providing flight information
    - HotelBooking: For booking hotels and providing hotel information
    - CarRental: For booking cars and providing car rental information
    - ActivitiesBooking: For booking activities and providing activity information
    - DestinationInfo: For providing information about destinations
    - DefaultAgent: For handling general requests""", source="system"),
    UserMessage(content="Create a travel plan for a family of 2 kids from Singapore to Melbourne", source="user"),
]

response = await client.create(messages=messages, extra_create_args={"response_format": TravelPlan})

# Ensure the response content is a valid JSON string before loading it

response_content: Optional[str] = response.content if isinstance(response.content, str) else None
if response_content is None:
    raise ValueError("Response content is not a valid JSON string")

# Print the response content after loading it as JSON

pprint(json.loads(response_content))
```

以上代碼嘅輸出如下，之後你可以用呢個結構化輸出分配畀 `assigned_agent`，並將旅遊計劃總結畀用戶。

```json
{
    "is_greeting": "False",
    "main_task": "Plan a family trip from Singapore to Melbourne.",
    "subtasks": [
        {
            "assigned_agent": "flight_booking",
            "task_details": "Book round-trip flights from Singapore to Melbourne."
        },
        {
            "assigned_agent": "hotel_booking",
            "task_details": "Find family-friendly hotels in Melbourne."
        },
        {
            "assigned_agent": "car_rental",
            "task_details": "Arrange a car rental suitable for a family of four in Melbourne."
        },
        {
            "assigned_agent": "activities_booking",
            "task_details": "List family-friendly activities in Melbourne."
        },
        {
            "assigned_agent": "destination_info",
            "task_details": "Provide information about Melbourne as a travel destination."
        }
    ]
}
```

你可以喺呢度搵到包含上述代碼示例嘅 notebook：[07-autogen.ipynb](../../../07-planning-design/code_samples/07-autogen.ipynb)。

### 迭代規劃

有啲任務需要反覆修改或者重新規劃，因為某個子任務嘅結果可能會影響下一步。例如，當 agent 發現預訂航班時數據格式出乎意料，可能需要調整策略，然後再處理酒店預訂。

另外，用戶嘅反饋（例如用戶決定佢更想搭早啲嘅航班）亦可能觸發部分重新規劃。呢種動態、迭代嘅方法可以確保最終解決方案符合現實世界嘅限制同用戶不斷變化嘅需求。

例如以下代碼：

    ```python
    from autogen_core.models import UserMessage, SystemMessage, AssistantMessage
    #.. same as previous code and pass on the user history, current plan
    messages = [
        SystemMessage(content="""You are a planner agent to optimize the
        Your job is to decide which agents to run based on the user's request.
        Below are the available agents specialised in different tasks:
        - FlightBooking: For booking flights and providing flight information
        - HotelBooking: For booking hotels and providing hotel information
        - CarRental: For booking cars and providing car rental information
        - ActivitiesBooking: For booking activities and providing activity information
        - DestinationInfo: For providing information about destinations
        - DefaultAgent: For handling general requests""", source="system"),
        UserMessage(content="Create a travel plan for a family of 2 kids from Singapore to Melboune", source="user"),
        AssistantMessage(content=f"Previous travel plan - {TravelPlan}", source="assistant")
    ]
    # .. re-plan and send the tasks to respective agents
    ```

如果想更全面了解規劃，可以參考 Magnetic One [Blogpost](https://www.microsoft.com/research/articles/magentic-one-a-generalist-multi-agent-system-for-solving-complex-tasks)，解釋點樣處理複雜任務。

## 總結

喺呢篇文章中，我哋睇咗一個例子，點樣創建一個規劃器，動態選擇可用嘅 agents。規劃器嘅輸出會分解任務並分配畀 agents 執行。假設 agents 已經有執行任務所需嘅功能/工具。除此之外，你仲可以加入其他模式，例如反思、總結、輪流聊天，進一步自訂化。

## 其他資源

* 使用 o1 推理模型喺規劃複雜任務方面表現相當先進 - TODO: 分享示例？

* Autogen Magnetic One - 一個通用型多 agent 系統，用嚟解決複雜任務，喺多個挑戰性 agent 基準測試中取得咗令人印象深刻嘅結果。參考：[autogen-magentic-one](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-magentic-one)。喺呢個實現中，協調器會創建針對任務嘅計劃，並將呢啲任務分配畀可用嘅 agents。除咗規劃之外，協調器仲會用一個追蹤機制監控任務進度，並喺需要時重新規劃。

**免責聲明**:
本文件是使用機器翻譯服務進行翻譯的。我們致力於提供準確的翻譯，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原始語言的文件作為權威來源。對於關鍵資訊，建議尋求專業的人工作翻譯。我們對因使用此翻譯而引起的任何誤解或誤讀概不負責。


# 多代理設計模式

當你開始處理一個涉及多個代理的項目時，你就需要考慮多代理設計模式。然而，何時切換到多代理模式以及其優勢可能並不立刻明顯。

## 簡介

在這一課中，我們將解答以下問題：

- 哪些場景適用於多代理模式？
- 為什麼使用多代理比單一代理處理多個任務更有優勢？
- 實現多代理設計模式的基本構件是什麼？
- 我們如何掌握多個代理之間的互動情況？

## 學習目標

完成這一課後，你應該能夠：

- 辨識適用於多代理的場景。
- 認識使用多代理相較於單一代理的優勢。
- 理解實現多代理設計模式的基本構件。

更大的圖景是什麼？

*多代理是一種設計模式，允許多個代理協作以實現共同目標。*

這種模式被廣泛應用於各個領域，包括機器人學、自主系統和分布式計算。

## 適用於多代理的場景

那麼，哪些場景適合使用多代理呢？答案是，有許多情況使用多代理是有益的，特別是在以下幾種情況：

- **大量工作負載**：龐大的工作負載可以被拆分為更小的任務，分配給不同的代理，從而實現並行處理並加快完成速度。例如，大型數據處理任務。
- **複雜任務**：與大量工作負載類似，複雜任務可以被分解為更小的子任務，並分配給不同的代理，每個代理專注於任務的特定方面。例如，自主車輛中，不同代理負責導航、障礙物檢測和與其他車輛通信。
- **多元專業知識**：不同代理可以擁有不同的專業知識，使其能比單一代理更有效地處理任務的不同方面。例如，在醫療領域，代理可以分別負責診斷、治療計劃和患者監控。

## 使用多代理相較於單一代理的優勢

單一代理系統對於簡單任務可能運行良好，但對於更複雜的任務，使用多代理可以帶來幾個優勢：

- **專業化**：每個代理可以專注於特定任務。單一代理缺乏專業化，可能導致在面對複雜任務時無所適從。例如，它可能執行了一個它並不擅長的任務。
- **可擴展性**：通過添加更多代理而不是讓單一代理承擔過多負載，更容易擴展系統。
- **容錯性**：如果某個代理失效，其他代理仍然可以繼續運行，從而保證系統的可靠性。

舉個例子，假設為用戶預訂旅行。單一代理系統需要處理旅行預訂過程的所有方面，從查找航班到預訂酒店和租車。為了實現這一點，單一代理需要具備處理所有這些任務的工具，這可能導致系統複雜且難以維護與擴展。而多代理系統則可以有不同的代理分別專注於查找航班、預訂酒店和租車，使系統更加模塊化、易於維護且可擴展。

這就像比較一個夫妻經營的小型旅行社與一個連鎖旅行社。夫妻店中，一個人處理所有預訂過程，而連鎖旅行社則由不同的人員分別處理預訂過程的不同部分。

## 實現多代理設計模式的基本構件

在實現多代理設計模式之前，你需要了解構成該模式的基本構件。

讓我們通過再次查看用戶旅行預訂的例子來具體化這些構件。在這種情況下，基本構件包括：

- **代理通信**：負責查找航班、預訂酒店和租車的代理需要進行通信並共享有關用戶偏好和約束的信息。你需要決定通信的協議和方法。具體來說，查找航班的代理需要與預訂酒店的代理通信，確保酒店預訂的日期與航班日期一致。這意味著代理需要共享用戶的旅行日期信息，因此你需要決定*哪些代理共享信息以及如何共享信息*。
- **協作機制**：代理需要協作以確保滿足用戶的偏好和約束。例如，用戶可能偏好靠近機場的酒店，而租車可能只能在機場提供。這意味著預訂酒店的代理需要與租車的代理協作，確保滿足用戶的偏好和約束。因此，你需要決定*代理如何協作行動*。
- **代理架構**：代理需要具備內部結構以做出決策並從與用戶的互動中學習。例如，查找航班的代理需要具備內部結構以決定向用戶推薦哪些航班。因此，你需要決定*代理如何做出決策並從與用戶的互動中學習*。例如，查找航班的代理可以使用機器學習模型，根據用戶過去的偏好推薦航班。
- **多代理互動的可視性**：你需要掌握多個代理如何互動的情況。這意味著你需要有工具和技術來跟蹤代理的活動和互動，例如日誌記錄與監控工具、可視化工具以及性能指標。
- **多代理模式**：有不同的模式可以用來實現多代理系統，比如集中式、分散式和混合式架構。你需要選擇最適合你的用例的模式。
- **人類介入**：在大多數情況下，你需要有人類介入，並需要指導代理何時尋求人類干預。例如，用戶可能要求推薦代理未建議的特定酒店或航班，或者在預訂航班或酒店之前需要確認。

## 多代理互動的可視性

掌握多個代理如何互動非常重要。這種可視性對於調試、優化和確保整體系統的有效性至關重要。為此，你需要有工具和技術來跟蹤代理的活動和互動，例如日誌記錄與監控工具、可視化工具以及性能指標。

例如，在用戶旅行預訂的案例中，你可以有一個儀表板，顯示每個代理的狀態、用戶的偏好和約束，以及代理之間的互動。這個儀表板可以顯示用戶的旅行日期、航班代理推薦的航班、酒店代理推薦的酒店，以及租車代理推薦的租車選項。這可以讓你清楚地了解代理如何互動以及是否滿足用戶的偏好和約束。

讓我們更詳細地看看這些方面：

- **日誌記錄與監控工具**：你需要記錄每個代理採取的行動。例如，一條日誌記錄可以存儲代理採取的行動、行動的時間以及行動的結果。這些信息可以用於調試、優化等。
- **可視化工具**：可視化工具可以幫助你以更直觀的方式看到代理之間的互動。例如，你可以有一個顯示代理之間信息流的圖表。這可以幫助你識別系統中的瓶頸、低效問題等。
- **性能指標**：性能指標可以幫助你跟蹤多代理系統的有效性。例如，你可以跟蹤完成任務所需的時間、每單位時間完成的任務數量，以及代理推薦的準確性。這些信息可以幫助你識別需要改進的地方並優化系統。

## 多代理模式

讓我們深入探討一些可以用來創建多代理應用的具體模式。以下是一些值得考慮的有趣模式：

### 群組聊天

這種模式適用於創建一個多代理可以互相通信的群組聊天應用。典型的用例包括團隊協作、客戶支持和社交網絡。

在這種模式中，每個代理代表群組聊天中的一個用戶，消息通過消息協議在代理之間交換。代理可以向群組聊天發送消息、接收消息並回應其他代理的消息。

這種模式可以通過集中式架構（所有消息通過中央伺服器路由）或分散式架構（消息直接交換）實現。

![群組聊天](../../../translated_images/multi-agent-group-chat.82d537c5c8dc833abbd252033e60874bc9d00df7193888b3377f8426449a0b20.hk.png)

### 任務交接

這種模式適用於創建一個多代理可以將任務交接給彼此的應用。

典型的用例包括客戶支持、任務管理和工作流自動化。

在這種模式中，每個代理代表工作流中的一個任務或步驟，代理可以根據預定規則將任務交接給其他代理。

![任務交接](../../../translated_images/multi-agent-hand-off.ed4f0a5a58614a8a3e962fc476187e630a3ba309d066e460f017b503d0b84cfc.hk.png)

### 協作過濾

這種模式適用於創建一個多代理可以協作向用戶提供建議的應用。

為什麼需要多代理協作？因為每個代理可以擁有不同的專業知識，並以不同的方式為建議過程作出貢獻。

舉例來說，用戶想要獲得股市上最佳股票的建議：

- **行業專家**：一個代理可能是某個特定行業的專家。
- **技術分析**：另一個代理可能是技術分析的專家。
- **基本面分析**：還有一個代理可能是基本面分析的專家。通過協作，這些代理可以為用戶提供更全面的建議。

![建議](../../../translated_images/multi-agent-filtering.719217d169391ddb118bbb726b19d4d89ee139f960f8749ccb2400efb4d0ce79.hk.png)

## 場景：退款流程

考慮一個客戶試圖為產品獲得退款的場景，這個過程可能涉及許多代理，我們可以將其分為退款流程專用代理和可以用於其他流程的通用代理。

**退款流程專用代理**：

以下是一些可能參與退款流程的代理：

- **客戶代理**：代表客戶，負責啟動退款流程。
- **賣家代理**：代表賣家，負責處理退款。
- **支付代理**：代表支付流程，負責將款項退還給客戶。
- **解決代理**：代表解決流程，負責解決退款過程中出現的問題。
- **合規代理**：代表合規流程，負責確保退款流程符合規範和政策。

**通用代理**：

這些代理可以用於業務的其他部分：

- **物流代理**：代表物流流程，負責將產品退回給賣家。該代理可以用於退款流程，也可以用於購買產品的普通物流。
- **反饋代理**：代表反饋流程，負責收集客戶的反饋。反饋可以在任何時間進行，而不僅限於退款流程。
- **升級代理**：代表升級流程，負責將問題升級到更高級別的支持。這類代理可以用於任何需要升級問題的流程。
- **通知代理**：代表通知流程，負責在退款流程的各個階段向客戶發送通知。
- **分析代理**：代表分析流程，負責分析與退款流程相關的數據。
- **審核代理**：代表審核流程，負責審核退款流程以確保其正確執行。
- **報告代理**：代表報告流程，負責生成有關退款流程的報告。
- **知識代理**：代表知識流程，負責維護與退款流程相關的信息知識庫。該代理可以同時了解退款和業務的其他部分。
- **安全代理**：代表安全流程，負責確保退款流程的安全性。
- **質量代理**：代表質量流程，負責確保退款流程的質量。

上述列出了許多代理，包括退款流程專用代理以及可以用於業務其他部分的通用代理。希望這能為你在多代理系統中選擇代理提供一些靈感。

## 作業

這一課的作業是什麼？

為客戶支持流程設計一個多代理系統。識別流程中涉及的代理、它們的角色和責任，以及它們如何互動。考慮既有針對客戶支持流程的專用代理，也有可以用於業務其他部分的通用代理。

> 在閱讀以下解答之前，先自己思考一下，可能需要的代理比你想像的更多。

> TIP: 思考客戶支持流程的不同階段，並考慮任何系統中需要的代理。

## 解答

[解答](./solution/solution.md)

## 知識檢查

問題：什麼時候應該考慮使用多代理？

- [] A1: 當你有一個小工作負載和簡單任務時。
- [] A2: 當你有一個大工作負載時。
- [] A3: 當你有一個簡單任務時。

[測驗解答](./solution/solution-quiz.md)

## 總結

在這一課中，我們探討了多代理設計模式，包括適用於多代理的場景、使用多代理相較於單一代理的優勢、實現多代理設計模式的基本構件，以及如何掌握多個代理之間的互動情況。

## 其他資源

- [Autogen設計模式](https://microsoft.github.io/autogen/stable/user-guide/core-user-guide/design-patterns/intro.html)
- [Agentic設計模式](https://www.analyticsvidhya.com/blog/2024/10/agentic-design-patterns/)
```

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

10 Lessons to Get Started Building AI Agents


# 元認知於人工智能代理中的應用

## 簡介

歡迎來到關於人工智能代理元認知的課程！本章節專為對人工智能代理如何思考其自身思維過程感興趣的初學者設計。在本課程結束時，您將理解關鍵概念，並能運用實際例子設計具備元認知能力的人工智能代理。

## 學習目標

完成本課程後，您將能夠：
1. 理解代理定義中推理循環的影響。
2. 使用規劃與評估技術幫助代理自我糾正。
3. 創建能夠操控代碼以完成任務的代理。

## 元認知簡介

元認知指的是涉及對自身思維過程進行思考的高階認知過程。對於人工智能代理來說，這意味著能夠基於自我意識和過去經驗評估並調整其行為。

### 什麼是元認知？

元認知，或稱“思考的思考”，是一種高階認知過程，涉及對自身認知過程的自我意識和自我調節。在人工智能領域，元認知使代理能夠評估並適應其策略和行動，從而提升問題解決和決策能力。通過理解元認知，您可以設計出更智能、更具適應性和效率的人工智能代理。

### 元認知在人工智能代理中的重要性

元認知在人工智能代理設計中具有以下幾點重要意義：

![元認知的重要性](../../../09-metacognition/images/importance-of-metacognition.png)

- **自我反思**：代理能夠評估自身表現並找出改進的領域。
- **適應性**：代理能夠根據過去經驗和變化的環境調整其策略。
- **錯誤糾正**：代理能夠自主檢測並糾正錯誤，從而獲得更準確的結果。
- **資源管理**：代理能夠通過規劃和評估行動來優化資源（如時間和計算能力）的使用。

## 人工智能代理的組成

在深入探討元認知過程之前，先了解人工智能代理的基本組成是很重要的。一個人工智能代理通常由以下部分組成：

- **人格**：代理的個性和特徵，定義了它如何與用戶互動。
- **工具**：代理能執行的功能和能力。
- **技能**：代理擁有的知識和專業能力。

這些組成部分共同構建了一個“專業單元”，能夠執行特定任務。

**例子**：考慮一個旅行代理，它不僅計劃您的假期，還能基於實時數據和過往客戶旅程經驗調整路徑。

### 例子：旅行代理服務中的元認知

假設您正在設計一個由人工智能驅動的旅行代理服務。該代理“旅行代理”幫助用戶規劃假期。為了融入元認知，旅行代理需要基於自我意識和過往經驗評估並調整其行動。以下是元認知可能發揮作用的方式：

#### 當前任務

幫助用戶規劃一次巴黎之旅。

#### 完成任務的步驟

1. **收集用戶偏好**：詢問用戶旅行日期、預算、興趣（如博物館、美食、購物）以及任何具體需求。
2. **檢索信息**：搜尋符合用戶偏好的航班選項、住宿、景點和餐廳。
3. **生成推薦**：提供包含航班詳情、酒店預訂和建議活動的個性化行程。
4. **根據反饋調整**：詢問用戶對推薦的反饋並進行必要調整。

#### 所需資源

- 訪問航班和酒店預訂數據庫。
- 關於巴黎景點和餐廳的信息。
- 過往互動中的用戶反饋數據。

#### 經驗與自我反思

旅行代理利用元認知評估其表現並從過去經驗中學習。例如：

1. **分析用戶反饋**：旅行代理回顧用戶反饋，以確定哪些推薦受到歡迎，哪些不受歡迎，並相應地調整未來建議。
2. **適應性**：如果用戶之前提到不喜歡擁擠的地方，旅行代理將避免在高峰時段推薦熱門旅遊景點。
3. **錯誤糾正**：如果旅行代理在過去的預訂中出現錯誤，例如推薦已滿房的酒店，它將學習在推薦之前更嚴格地檢查可用性。

#### 實用開發者示例

以下是一個簡化的示例，展示旅行代理在代碼中如何融入元認知：

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

#### 為什麼元認知很重要

- **自我反思**：代理能分析其表現並找出改進的領域。
- **適應性**：代理能根據反饋和變化條件調整策略。
- **錯誤糾正**：代理能自主檢測並糾正錯誤。
- **資源管理**：代理能優化資源的使用，例如時間和計算能力。

通過融入元認知，旅行代理可以提供更個性化和準確的旅行推薦，提升整體用戶體驗。

---

## 2. 代理中的規劃

規劃是人工智能代理行為的一個關鍵組成部分。它涉及考慮當前狀態、資源和可能的障礙，制定實現目標所需的步驟。

### 規劃的要素

- **當前任務**：明確定義任務。
- **完成任務的步驟**：將任務分解為可管理的步驟。
- **所需資源**：確定必要的資源。
- **經驗**：利用過去經驗指導規劃。

**例子**：以下是旅行代理有效協助用戶規劃旅行所需採取的步驟：

### 旅行代理的步驟

1. **收集用戶偏好**
   - 詢問用戶有關旅行日期、預算、興趣以及任何具體需求的詳細信息。
   - 例子：“您計劃什麼時候旅行？”“您的預算範圍是多少？”“您在度假時喜歡哪些活動？”

2. **檢索信息**
   - 根據用戶偏好搜尋相關旅行選項。
   - **航班**：尋找符合用戶預算和偏好旅行日期的可用航班。
   - **住宿**：尋找符合用戶位置、價格和設施偏好的酒店或租賃物業。
   - **景點和餐廳**：確定符合用戶興趣的熱門景點、活動和餐飲選擇。

3. **生成推薦**
   - 將檢索到的信息編輯成個性化行程。
   - 提供航班選項、酒店預訂和建議活動的詳細信息，確保建議符合用戶偏好。

4. **向用戶展示行程**
   - 與用戶分享建議行程供其審閱。
   - 例子：“這是您巴黎之旅的建議行程，包括航班詳情、酒店預訂以及推薦活動和餐廳。請告訴我您的想法！”

5. **收集反饋**
   - 詢問用戶對建議行程的反饋。
   - 例子：“您喜歡這些航班選項嗎？”“這家酒店是否符合您的需求？”“是否有任何活動需要添加或刪除？”

6. **根據反饋調整**
   - 根據用戶反饋修改行程。
   - 將航班、住宿和活動推薦做必要更改以更好地符合用戶偏好。

7. **最終確認**
   - 向用戶展示更新後的行程供其最終確認。
   - 例子：“我已根據您的反饋進行了調整。這是更新後的行程。一切看起來是否合適？”

8. **預訂並確認**
   - 用戶批准行程後，進行航班、住宿及任何預先計劃活動的預訂。
   - 將確認詳情發送給用戶。

9. **提供持續支持**
   - 在旅行前和旅行期間，隨時為用戶提供幫助或額外需求。
   - 例子：“如果您在旅行期間需要進一步的幫助，隨時聯繫我！”

### 互動示例

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

## 3. 糾正性 RAG 系統

首先，讓我們了解 RAG 工具與預先上下文加載的區別：

![RAG vs Context Loading](../../../09-metacognition/images/rag-vs-context.png)

### 檢索增強生成（RAG）

RAG 將檢索系統與生成模型結合。當查詢被提出時，檢索系統從外部來源獲取相關文檔或數據，並將檢索到的信息用於增強生成模型的輸入。這有助於模型生成更準確和上下文相關的響應。

在 RAG 系統中，代理從知識庫中檢索相關信息並用於生成適當的響應或行動。

### 糾正性 RAG 方法

糾正性 RAG 方法專注於使用 RAG 技術糾正錯誤並提高人工智能代理的準確性。這涉及：

1. **提示技術**：使用特定提示指導代理檢索相關信息。
2. **工具**：實施算法和機制，使代理能夠評估檢索信息的相關性並生成準確的響應。
3. **評估**：持續評估代理的表現並進行調整以提高其準確性和效率。

#### 例子：搜索代理中的糾正性 RAG

考慮一個從網絡檢索信息以回答用戶查詢的搜索代理。糾正性 RAG 方法可能涉及：

1. **提示技術**：根據用戶輸入制定搜索查詢。
2. **工具**：使用自然語言處理和機器學習算法對搜索結果進行排序和過濾。
3. **評估**：分析用戶反饋以識別和糾正檢索信息中的不準確之處。

### 糾正性 RAG 在旅行代理中的應用

糾正性 RAG（檢索增強生成）增強了人工智能在檢索和生成信息時糾正任何不準確的能力。讓我們看看旅行代理如何使用糾正性 RAG 方法提供更準確和相關的旅行建議。這涉及：

- **提示技術**：使用特定提示指導代理檢索相關信息。
- **工具**：實施算法和機制，使代理能夠評估檢索信息的相關性並生成準確的響應。
- **評估**：持續評估代理的表現並進行調整以提高其準確性和效率。

#### 實施糾正性 RAG 的步驟

1. **初次用戶互動**
   - 旅行代理收集用戶的初始偏好，例如目的地、旅行日期、預算和興趣。
   - 例子：```python
     preferences = {
         "destination": "Paris",
         "dates": "2025-04-01 to 2025-04-10",
         "budget": "moderate",
         "interests": ["museums", "cuisine"]
     }
     ```

2. **信息檢索**
   - 旅行代理根據用戶偏好檢索有關航班、住宿、景點和餐廳的信息。
   - 例子：```python
     flights = search_flights(preferences)
     hotels = search_hotels(preferences)
     attractions = search_attractions(preferences)
     ```

3. **生成初始推薦**
   - 旅行代理使用檢索到的信息生成個性化行程。
   - 例子：```python
     itinerary = create_itinerary(flights, hotels, attractions)
     print("Suggested Itinerary:", itinerary)
     ```

4. **收集用戶反饋**
   - 旅行代理詢問用戶對初始推薦的反饋。
   - 例子：```python
     feedback = {
         "liked": ["Louvre Museum"],
         "disliked": ["Eiffel Tower (too crowded)"]
     }
     ```

5. **糾正性 RAG 過程**
   - **提示技術**：請從左到右書寫輸出。
```
```markdown
旅遊代理根據用戶反饋制定新的搜索查詢。
- 範例：```python
       if "disliked" in feedback:
           preferences["avoid"] = feedback["disliked"]
       ```
- **工具**：旅遊代理使用算法對新的搜索結果進行排名和篩選，強調基於用戶反饋的相關性。
- 範例：```python
       new_attractions = search_attractions(preferences)
       new_itinerary = create_itinerary(flights, hotels, new_attractions)
       print("Updated Itinerary:", new_itinerary)
       ```
- **評估**：旅遊代理通過分析用戶反饋並進行必要調整，不斷評估其推薦的相關性和準確性。
- 範例：```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)
       ```

#### 實用範例
以下是一個簡化的 Python 代碼範例，展示了如何在旅遊代理中應用 Corrective RAG 方法：
```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)
```

### 預先加載上下文
預先加載上下文是指在處理查詢之前，將相關的上下文或背景信息加載到模型中。這意味著模型從一開始就能夠訪問這些信息，從而在不需要在過程中檢索額外數據的情況下生成更有根據的回應。

以下是一個展示如何為旅遊代理應用程序在 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"))
```

#### 解釋
1. **初始化 (`__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` 方法)**：該方法從預加載的上下文字典中獲取相關信息。通過預加載上下文，旅遊代理應用程序可以快速響應用戶查詢，而不需要實時從外部源檢索這些信息。這使應用程序更高效且更具響應性。

### 在迭代前用目標啟動計劃
在迭代前用目標啟動計劃是指以清晰的目標或預期結果為起點。通過提前定義這一目標，模型可以將其作為指導原則，貫穿整個迭代過程。這有助於確保每次迭代都朝著實現所需結果的方向邁進，使過程更加高效且聚焦。

以下是一個展示如何在旅遊代理中用目標啟動旅行計劃的 Python 範例：

### 場景
一位旅遊代理希望為客戶制定一個定制化的假期計劃。目標是基於客戶的偏好和預算，創建一個最大化客戶滿意度的旅行行程。

### 步驟
1. 定義客戶的偏好和預算。
2. 基於這些偏好啟動初始計劃。
3. 迭代以完善計劃，優化客戶滿意度。

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

#### 代碼解釋
1. **初始化 (`__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` 方法)**：該方法計算當前計劃的總成本，包括一個潛在的新目的地。

#### 使用範例
- **初始計劃**：旅遊代理基於客戶對觀光的偏好和 $2000 的預算創建初始計劃。
- **優化計劃**：旅遊代理通過迭代完善計劃，優化客戶的偏好和預算。

通過以清晰的目標（例如，最大化客戶滿意度）啟動計劃並進行迭代以完善計劃，旅遊代理可以為客戶創建一個定制化且優化的旅行行程。這種方法確保旅行計劃從一開始就符合客戶的偏好和預算，並在每次迭代中得到改進。

### 利用 LLM 進行重新排序和評分
大型語言模型（LLMs）可以通過評估檢索到的文檔或生成的回應的相關性和質量來進行重新排序和評分。以下是其工作原理：

**檢索**：初始檢索步驟根據查詢獲取一組候選文檔或回應。
**重新排序**：LLM 評估這些候選項，並根據其相關性和質量重新排序。此步驟確保最相關和高質量的信息優先呈現。
**評分**：LLM 為每個候選項分配分數，反映其相關性和質量。這有助於選擇最適合用戶的回應或文檔。

通過利用 LLM 進行重新排序和評分，系統可以提供更準確且具有上下文相關的信息，從而改善整體用戶體驗。

以下是一個展示旅遊代理如何使用大型語言模型（LLM）根據用戶偏好對旅行目的地進行重新排序和評分的 Python 範例：

#### 場景 - 基於偏好的旅行
一位旅遊代理希望根據客戶的偏好推薦最佳旅行目的地。LLM 將幫助重新排序和評分目的地，確保呈現最相關的選項。

#### 步驟：
1. 收集用戶偏好。
2. 檢索潛在旅行目的地的列表。
3. 使用 LLM 根據用戶偏好重新排序和評分目的地。

以下是如何使用 Azure OpenAI 服務更新上述範例：

#### 要求
1. 您需要擁有 Azure 訂閱。
2. 創建 Azure OpenAI 資源並獲取您的 API 密鑰。

#### Python 代碼範例
```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)
```

#### 代碼解釋 - 偏好預訂器
1. **初始化**：將 `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/...` 替換為 Azure OpenAI 部署的實際端點 URL。

通過利用 LLM 進行重新排序和評分，旅遊代理可以為客戶提供更個性化且相關性更高的旅行推薦，從而提升他們的整體體驗。

### RAG：提示技術與工具
檢索增強生成（RAG）既可以作為提示技術，也可以作為 AI 代理開發中的工具。理解兩者的區別有助於您更有效地在項目中利用 RAG。

#### RAG 作為提示技術
**什麼是 RAG？**
- 作為提示技術，RAG 涉及制定特定查詢或提示，以引導從大型語料庫或數據庫中檢索相關信息。這些信息隨後被用於生成回應或採取行動。

**如何運作：**
1. **制定提示**：根據任務或用戶輸入創建結構良好的提示或查詢。
2. **檢索信息**：使用提示從預先存在的知識庫或數據集中搜索相關數據。
3. **生成回應**：將檢索到的信息與生成式 AI 模型結合，生成全面且連貫的回應。

**旅遊代理範例**：
- 用戶輸入：「我想參觀巴黎的博物館。」
- 提示：「查找巴黎的頂級博物館。」
- 檢索信息：關於盧浮宮、奧賽博物館等的詳細信息。
- 生成回應：「以下是巴黎的一些頂級博物館：盧浮宮、奧賽博物館和蓬皮杜中心。」

#### RAG 作為工具
**什麼是 RAG？**
- 作為工具，RAG 是一個集成系統，自動化檢索和生成過程，使開發者能夠更輕鬆地實現複雜的 AI 功能，而無需為每個查詢手動編寫提示。

**如何運作：**
1. **集成**：將 RAG 嵌入到 AI 代理的架構中，使其能夠自動處理檢索和生成任務。
2. **自動化**：工具管理整個過程，從接收用戶輸入到生成最終回應，無需為每一步驟顯式提示。
3. **效率**：通過簡化檢索和生成過程，提高代理的性能，實現更快且更準確的回應。

**旅遊代理範例**：
- 用戶輸入：「我想參觀巴黎的博物館。」
- RAG 工具：自動檢索關於博物館的信息並生成回應。
- 生成回應：「以下是巴黎的一些頂級博物館：盧浮宮、奧賽博物館和蓬皮杜中心。」

### 比較
| **方面**              | **提示技術**                                              | **工具**                                           |
|------------------------|-------------------------------------------------------------|---------------------------------------------------|
| **手動與自動**         | 每個查詢手動制定提示。                                      | 檢索和生成過程自動化。                             |
| **控制**              | 提供對檢索過程的更多控制。                                  | 簡化並自動化檢索和生成過程。                       |
| **靈活性**            | 允許基於特定需求定制提示。                                  | 對於大規模實現更高效。                             |
| **複雜性**            | 需要編寫和調整提示。                                        | 更易於集成到 AI 代理的架構中。                     |

### 實用範例
**提示技術範例：**
```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)
```

**工具範例：**
```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)
```

### 評估相關性
評估相關性是 AI 代理性能的一個關鍵方面。它確保代理檢索和生成的信息對用戶是適當的、準確的且有用的。讓我們探討如何在 AI 代理中評估相關性，包括實用範例和技術。

#### 評估相關性的關鍵概念
1. **上下文意識**：
   - 代理必須理解用戶查詢的上下文，以檢索和生成相關信息。
   - 範例：如果用戶詢問「巴黎最好的餐廳」，代理應考慮用戶的偏好，例如菜系類型和預算。
2. **準確性**：
   - 代理提供的信息應該是事實正確且最新的。
   - 範例：推薦目前營業且評價良好的餐廳，而不是過時或已關閉的選項。
3. **用戶意圖**：
   - 代理應推斷用戶查詢背後的意圖，以提供最相關的信息。
   - 範例：如果用戶詢問「經濟型酒店」，代理應優先考慮價格實惠的選項。
4. **反饋迴路**：
   - 持續收集和分析用戶反饋，有助於代理完善其相關性評估過程。
   - 範例：將用戶對先前推薦的評分和反饋納入，改進未來的回應。

#### 評估相關性的實用技術
1. **相關性評分**：
   - 根據與用戶查詢和偏好的匹配程度，為每個檢索項分配相關性分數。
   - 範例：```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. **篩選和排序**：
   - 篩選掉不相關的項目，並根據相關性分數對剩餘項目進行排序。
   - 範例：```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. **自然語言處理（NLP）**：
   - 使用 NLP 技術來理解用戶查詢並檢索相關信息。
   - 範例：```python
     def process_query(query):
         # Use NLP to extract key information from the user's query
         processed_query = nlp(query)
         return processed_query
     ```
4. **用戶反饋集成**：
   - 收集用戶對推薦的反饋，並用於調整未來的相關性評估。
   - 範例：```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
     ```

#### 範例：在旅遊代理中評估相關性
以下是一個展示旅遊代理如何評估旅行推薦相關性的實用範例：
```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)
```

### 帶有意圖的搜索
帶有意圖的搜索是指理解和解釋用戶查詢背後的潛在目的或目標，以檢索和生成最相關且有用的信息。這種方法超越了簡單的關鍵詞匹配，專注於掌握用戶的實際需求和上下文。

#### 帶有意圖的搜索的關鍵概念
1. **理解用戶意圖**：
   - 用戶意圖可以分為三種主要類型：資訊性、導航性和交易性。
   - **資訊性意圖**：用戶尋求有關某個主題的信息（例如，「什麼是...」）。
```
巴黎最好的博物館？"). - **導航意圖**：用戶希望導航到特定網站或頁面（例如，“盧浮宮官方網站”）。 - **交易意圖**：用戶旨在執行交易，例如預訂航班或進行購買（例如，“預訂飛往巴黎的航班”）。

2. **上下文意識**：
   - 分析用戶查詢的上下文有助於準確識別其意圖。這包括考慮之前的互動、用戶偏好以及當前查詢的具體細節。

3. **自然語言處理 (NLP)**：
   - 採用 NLP 技術來理解和解釋用戶提供的自然語言查詢。這包括實體識別、情感分析和查詢解析等任務。

4. **個性化**：
   - 根據用戶的歷史記錄、偏好和反饋來個性化搜索結果，提高檢索信息的相關性。

#### 實用示例：在旅遊代理中基於意圖的搜索
讓我們以旅遊代理為例，看看如何實現基於意圖的搜索。

1. **收集用戶偏好**
   ```python
   class Travel_Agent:
       def __init__(self):
           self.user_preferences = {}

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

2. **理解用戶意圖**
   ```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. **上下文意識**
   ```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. **搜索並個性化結果**
   ```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. **示例使用**
   ```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. 作為工具的代碼生成
代碼生成代理使用 AI 模型編寫和執行代碼，解決複雜問題並自動化任務。

### 代碼生成代理
代碼生成代理利用生成式 AI 模型來編寫和執行代碼。這些代理可以通過生成和運行多種編程語言的代碼來解決複雜問題、自動化任務並提供有價值的見解。

#### 實用應用
1. **自動代碼生成**：為特定任務生成代碼片段，例如數據分析、網頁抓取或機器學習。
2. **SQL 作為 RAG**：使用 SQL 查詢從數據庫檢索和操作數據。
3. **問題解決**：創建並執行代碼以解決特定問題，例如優化算法或分析數據。

#### 示例：數據分析的代碼生成代理
假設您正在設計一個代碼生成代理。以下是其工作方式：

1. **任務**：分析數據集以識別趨勢和模式。
2. **步驟**：
   - 將數據集加載到數據分析工具中。
   - 生成 SQL 查詢以篩選和聚合數據。
   - 執行查詢並檢索結果。
   - 使用結果生成可視化和見解。
3. **所需資源**：訪問數據集、數據分析工具和 SQL 功能。
4. **經驗**：利用過去的分析結果來提高未來分析的準確性和相關性。

### 示例：旅遊代理的代碼生成代理
在此示例中，我們將設計一個代碼生成代理（旅遊代理），以通過生成和執行代碼來協助用戶規劃旅行。該代理可以處理例如獲取旅行選項、篩選結果和使用生成式 AI 編制行程的任務。

#### 代碼生成代理概述
1. **收集用戶偏好**：收集用戶輸入，如目的地、旅行日期、預算和興趣。
2. **生成代碼以獲取數據**：生成代碼片段以檢索有關航班、酒店和景點的信息。
3. **執行生成的代碼**：運行生成的代碼以獲取實時信息。
4. **生成行程**：將檢索到的數據編制成個性化旅行計劃。
5. **基於反饋進行調整**：接收用戶反饋，並在必要時重新生成代碼以優化結果。

#### 分步實現
1. **收集用戶偏好**
   ```python
   class Travel_Agent:
       def __init__(self):
           self.user_preferences = {}

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

2. **生成代碼以獲取數據**
   ```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. **執行生成的代碼**
   ```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. **生成行程**
   ```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. **基於反饋進行調整**
   ```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)
   ```

### 利用環境感知和推理
基於表格的架構確實可以通過利用環境感知和推理來增強查詢生成過程。以下是如何實現的示例：

1. **理解架構**：系統將理解表格的架構並利用此信息來支持查詢生成。
2. **基於反饋進行調整**：系統將根據反饋調整用戶偏好，並推理需要在架構中更新的字段。
3. **生成和執行查詢**：系統將生成並執行查詢以根據新偏好檢索更新的航班和酒店數據。

以下是包含這些概念的更新 Python 代碼示例：
   ```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)
```

#### 解釋 - 基於反饋進行預訂
1. **架構感知**：
   `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` 方法**：此方法根據架構和反饋定制調整。
4. **生成和執行查詢**：系統生成代碼以根據調整後的偏好檢索更新的航班和酒店數據，並模擬執行這些查詢。
5. **生成行程**：系統基於新的航班、酒店和景點數據創建更新的行程。

通過使系統具備環境感知並基於架構進行推理，它可以生成更準確和相關的查詢，從而提供更好的旅行建議和更個性化的用戶體驗。

### 使用 SQL 作為檢索增強生成 (RAG) 技術
SQL（結構化查詢語言）是與數據庫交互的強大工具。作為檢索增強生成 (RAG) 方法的一部分，SQL 可以從數據庫檢索相關數據，以在 AI 代理中生成響應或執行操作。讓我們探索在旅遊代理上下文中如何使用 SQL 作為 RAG 技術。

#### 關鍵概念
1. **數據庫交互**：
   - 使用 SQL 查詢數據庫，檢索相關信息並操作數據。
   - 示例：從旅遊數據庫中檢索航班詳情、酒店信息和景點。
2. **與 RAG 集成**：
   - 根據用戶輸入和偏好生成 SQL 查詢。
   - 然後使用檢索到的數據生成個性化建議或操作。
3. **動態查詢生成**：
   - AI 代理根據上下文和用戶需求生成動態 SQL 查詢。
   - 示例：定制 SQL 查詢以根據預算、日期和興趣篩選結果。

#### 應用
- **自動代碼生成**：為特定任務生成代碼片段。
- **SQL 作為 RAG**：使用 SQL 查詢操作數據。
- **問題解決**：創建並執行代碼以解決問題。

**示例**：數據分析代理：
1. **任務**：分析數據集以發現趨勢。
2. **步驟**：
   - 加載數據集。
   - 生成 SQL 查詢以篩選數據。
   - 執行查詢並檢索結果。
   - 生成可視化和見解。
3. **資源**：數據集訪問權限、SQL 功能。
4. **經驗**：利用過去的結果改進未來分析。

#### 實用示例：在旅遊代理中使用 SQL
1. **收集用戶偏好**
   ```python
   class Travel_Agent:
       def __init__(self):
           self.user_preferences = {}

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

2. **生成 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. **執行 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. **生成推薦**
   ```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)
   ```

#### 示例 SQL 查詢
1. **航班查詢**
   ```sql
   SELECT * FROM flights WHERE destination='Paris' AND dates='2025-04-01 to 2025-04-10' AND budget='moderate';
   ```

2. **酒店查詢**
   ```sql
   SELECT * FROM hotels WHERE destination='Paris' AND budget='moderate';
   ```

3. **景點查詢**
   ```sql
   SELECT * FROM attractions WHERE destination='Paris' AND interests='museums, cuisine';
   ```

通過將 SQL 作為檢索增強生成 (RAG) 技術的一部分，像旅遊代理這樣的 AI 代理可以動態檢索並利用相關數據，提供準確且個性化的建議。

### 結論
元認知是一種強大的工具，可以顯著增強 AI 代理的能力。通過納入元認知過程，您可以設計出更智能、更適應性和更高效的代理。利用額外資源進一步探索 AI 代理中元認知的迷人世界。

**免責聲明**:
本文件使用基於機器的人工智能翻譯服務進行翻譯。我們雖然致力於確保準確性，但請注意，自動翻譯可能包含錯誤或不準確之處。應以原文文件作為權威來源。對於關鍵資訊，建議尋求專業人工翻譯。我們對因使用此翻譯而引起的任何誤解或錯誤解釋概不負責。


# AI Agents 在生產環境中的應用

## 簡介

本課程將涵蓋：

- 如何有效地計劃將你的 AI Agent 部署到生產環境。
- 部署 AI Agent 到生產環境時可能面臨的常見錯誤和問題。
- 如何在保持 AI Agent 性能的同時管理成本。

## 學習目標

完成本課程後，你將了解如何：

- 提升生產環境中的 AI Agent 系統性能、成本效益和有效性的技術。
- 評估你的 AI Agent 的方法以及具體操作方式。
- 控制 AI Agent 部署到生產環境時的成本。

部署可信任的 AI Agent 非常重要。請參考 "Building Trustworthy AI Agents" 課程以了解更多。

## 評估 AI Agents

在部署 AI Agents 前、中、後，建立一個完善的系統來評估你的 AI Agent 是至關重要的。這將確保你的系統與你和用戶的目標保持一致。

評估 AI Agent 時，不僅需要評估代理的輸出，還需要評估 AI Agent 所運行的整個系統。這包括但不限於：

- 初始模型請求。
- 代理識別用戶意圖的能力。
- 代理選擇正確工具執行任務的能力。
- 工具對代理請求的回應。
- 代理解讀工具回應的能力。
- 用戶對代理回應的反饋。

這樣可以讓你更模塊化地識別改進的空間，並更高效地監控模型、提示詞、工具以及其他組件的變更效果。

## AI Agents 的常見問題與潛在解決方案

| **問題**                                       | **潛在解決方案**                                                                                |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI Agent 無法穩定執行任務                      | - 精煉給 AI Agent 的提示詞，明確目標。
- 確定是否可以將任務分解為子任務，並由多個代理處理。                                                                                |
| AI Agent 進入無限循環                          | - 確保設置清晰的終止條件，讓代理知道何時結束流程。
- 對於需要推理和計劃的複雜任務，使用專為推理任務設計的大型模型。                                                           |
| AI Agent 工具調用效果不佳                      | - 在代理系統外測試並驗證工具的輸出。
- 優化工具的參數設置、提示詞和命名。                                                                                |
| 多代理系統無法穩定運行                         | - 精煉給每個代理的提示詞，確保它們具體且彼此區分明確。
- 構建一個層級系統，使用 "路由" 或控制代理來決定哪個代理最適合處理任務。                                           |

## 成本管理

以下是一些管理 AI Agent 部署成本的策略：

- **緩存回應** - 識別常見的請求和任務，提前提供回應，避免它們經過你的代理系統。你甚至可以實現一個流程，使用更基礎的 AI 模型來判斷請求與緩存請求的相似度。

- **使用小型模型** - 小型語言模型 (SLMs) 在某些代理場景中表現良好，並能顯著降低成本。如前所述，建立一個評估系統來比較小型模型與大型模型的性能，是了解 SLM 是否適合你場景的最佳方法。

- **使用路由模型** - 一種相似的策略是使用多樣化的模型和規模。你可以使用 LLM/SLM 或無伺服器函數根據任務複雜度來路由請求，將其分配給最合適的模型。這樣既能降低成本，又能確保在適當的任務上保持性能。

## 恭喜

這是 "AI Agents for Beginners" 的最後一課。

我們計劃根據反饋和這個快速增長的行業變化繼續添加新課程，請在不久的將來再次訪問。

如果你想繼續學習並構建 AI Agents，歡迎加入 [Azure AI Community Discord](https://discord.gg/kzRShWzttr)。

我們在那裡舉辦工作坊、社區圓桌會議和 "問我任何事" 的互動環節。

我們還有一個學習資源集合，其中包含更多幫助你開始在生產環境中構建 AI Agents 的材料。

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


# コースセットアップ

## はじめに

このレッスンでは、このコースのコードサンプルを実行する方法を説明します。

## 必要条件

- GitHubアカウント
- Python 3.12以上

## このリポジトリをクローンまたはフォークする

まず最初に、GitHubリポジトリをクローンまたはフォークしてください。これにより、コース教材の自分専用のバージョンが作成され、コードを実行、テスト、調整できるようになります。

以下のリンクをクリックして[リポジトリをフォークする](https://github.com/microsoft/ai-agents-for-beginners/fork)ことができます。

これで、以下のように自分専用のフォークされたコースバージョンが作成されます:

![フォークされたリポジトリ](../../../translated_images/forked-repo.eea246a73044cc984a1e462349e36e7336204f00785e3187b7399905feeada07.ja.png)

## GitHubパーソナルアクセストークン（PAT）の取得

現在、このコースではGitHub Models Marketplaceを利用して、AIエージェントを作成するための大規模言語モデル（LLMs）への無料アクセスを提供しています。

このサービスにアクセスするには、GitHubのパーソナルアクセストークンを作成する必要があります。

トークンを作成するには、GitHubアカウントの[Personal Access Tokens設定](https://github.com/settings/personal-access-tokens)にアクセスしてください。

画面左側の `Fine-grained tokens` オプションを選択します。

次に `Generate new token` を選択してください。

![トークンの生成](../../../translated_images/generate-token.361ec40abe59b84ac68d63c23e2b6854d6fad82bd4e41feb98fc0e6f030e8ef7.ja.png)

作成した新しいトークンをコピーしてください。このトークンを、このコースに含まれる `.env` ファイルに追加します。

## 環境変数に追加する

`.env` ファイルを作成するには、以下のコマンドをターミナルで実行してください:

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

これにより、サンプルファイルがコピーされ、ディレクトリ内に `.env` が作成されます。

そのファイルを開き、作成したトークンを `.env` ファイルの `GITHUB_TOKEN=` フィールドに貼り付けてください。

## 必要なパッケージのインストール

コードを実行するために必要なPythonパッケージをすべてインストールするには、以下のコマンドをターミナルに入力してください。

Python仮想環境を作成することをお勧めします。これにより、競合や問題を回避できます。

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

これで必要なPythonパッケージがインストールされます。

これでコードを実行する準備が整いました。AIエージェントの世界について学ぶことを楽しんでください！

セットアップの実行中に問題が発生した場合は、[Azure AI Community Discord](https://discord.gg/kzRShWzttr)に参加するか、[Issueを作成](https://github.com/microsoft/ai-agents-for-beginners/issues?WT.mc_id=academic-105485-koreyst)してください。
```

**免責事項**:
この文書は、AIによる機械翻訳サービスを使用して翻訳されています。正確さを期すよう努めておりますが、自動翻訳には誤りや不正確な部分が含まれる可能性があります。原文（元の言語で記載された文書）が正式な情報源として優先されるべきです。重要な情報については、専門の人間による翻訳をお勧めします。この翻訳の利用により生じた誤解や解釈の相違について、当方は一切の責任を負いません。


# AIエージェントとそのユースケース入門

「初心者向けAIエージェント」コースへようこそ！このコースでは、AIエージェントを構築するための基本的な知識と実践的なサンプルを学べます。

[Azure AI Discord Community](https://discord.gg/kzRShWzttr) に参加して、他の学習者やAIエージェント開発者と交流し、このコースに関する質問を自由にしてください。

このコースを始めるにあたり、まずAIエージェントとは何か、そしてそれを私たちのアプリケーションやワークフローでどのように活用できるかを理解するところから始めます。

## はじめに

このレッスンでは以下を学びます：

- AIエージェントとは何か、そしてその種類にはどのようなものがあるのか？
- AIエージェントが適しているユースケースとは？また、それがどのように役立つのか？
- エージェントソリューションを設計する際の基本的な構成要素は何か？

## 学習目標
このレッスンを修了すると、以下ができるようになります：

- AIエージェントの概念を理解し、他のAIソリューションとの違いを把握する。
- AIエージェントを最も効率的に活用する。
- ユーザーと顧客の両方にとって生産的なエージェントソリューションを設計する。

## AIエージェントの定義と種類

### AIエージェントとは？

AIエージェントは、**大規模言語モデル（LLM）** に **ツールや知識へのアクセス** を提供し、その能力を拡張することで **アクションを実行** できるようにする **システム** です。

この定義を分解してみましょう：

- **システム** - エージェントを単一のコンポーネントとしてではなく、複数のコンポーネントから成るシステムとして考えることが重要です。AIエージェントの基本的な構成要素は以下の通りです：
  - **環境** - AIエージェントが動作する定義された空間。例えば、旅行予約のAIエージェントの場合、環境はエージェントがタスクを完了するために使用する旅行予約システムとなります。
  - **センサー** - 環境には情報があり、フィードバックを提供します。AIエージェントはセンサーを使用して、環境の現在の状態に関する情報を収集・解釈します。旅行予約エージェントの例では、ホテルの空室状況や航空券の価格などの情報を旅行予約システムから取得します。
  - **アクチュエーター** - AIエージェントが環境の現在の状態を受け取った後、そのタスクに応じて環境を変化させるためにどのようなアクションを実行するかを決定します。旅行予約エージェントの場合、ユーザーのために空室を予約するアクションが該当します。

![What Are AI Agents?](../../../translated_images/what-are-ai-agents.125520f55950b252a429b04a9f41e0152d4dafa1f1bd9081f4f574631acb759e.ja.png?WT.mc_id=academic-105485-koreyst)

**大規模言語モデル** - エージェントの概念自体はLLMが誕生する以前から存在していましたが、LLMを用いたAIエージェント構築の利点は、人間の言語やデータを解釈する能力にあります。この能力により、LLMは環境情報を解釈し、環境を変化させるための計画を立てることができます。

**アクションの実行** - AIエージェントシステムの外では、LLMはユーザーのプロンプトに基づいてコンテンツや情報を生成する状況に限定されます。一方で、AIエージェントシステム内では、LLMはユーザーのリクエストを解釈し、環境内で利用可能なツールを使用することでタスクを達成することができます。

**ツールへのアクセス** - LLMがアクセスできるツールは、1) その動作環境と、2) AIエージェントの開発者によって定義されます。旅行エージェントの例では、エージェントのツールは予約システムで利用可能な操作によって制限される場合や、開発者がフライト予約に限定する場合があります。

**知識** - 環境から提供される情報以外にも、AIエージェントは他のシステム、サービス、ツール、さらには他のエージェントから知識を取得することができます。旅行エージェントの例では、顧客データベースに保存されたユーザーの旅行の好みに関する情報が該当します。

### AIエージェントの種類

AIエージェントの一般的な定義を理解したところで、特定のエージェントタイプと、それらが旅行予約AIエージェントにどのように適用されるかを見てみましょう。

| **エージェントタイプ**         | **説明**                                                                                | **例**                                                                                |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **単純反射エージェント**       | 定義されたルールに基づいて即座にアクションを実行します。                                                                            | 旅行エージェントがメールの文脈を解釈し、旅行の苦情をカスタマーサービスに転送します。                                                                                |
| **モデルベース反射エージェント** | 世界のモデルとその変化に基づいてアクションを実行します。                                                                             | 旅行エージェントが過去の価格データへのアクセスを基に、大幅な価格変動があるルートを優先します。                                                                                |
| **目標ベースエージェント**      | 目標を解釈し、それを達成するためのアクションを決定して計画を立てます。                                                               | 旅行エージェントが現在地から目的地までの移動手段（車、公共交通機関、フライト）を決定し、旅行を予約します。                                                                                |
| **効用ベースエージェント**      | 好みを考慮し、数値的にトレードオフを比較して目標を達成する方法を決定します。                                                           | 旅行エージェントが利便性とコストを比較して最大効用を得るように旅行を予約します。                                                                                |
| **学習エージェント**           | フィードバックに応じて行動を調整し、時間とともに改善します。                                                                         | 旅行エージェントが旅行後のアンケートから顧客のフィードバックを利用し、将来の予約を調整して改善します。                                                                                |
| **階層型エージェント**         | 複数のエージェントが階層的に構成され、高次のエージェントがタスクをサブタスクに分割し、下位エージェントがそれを完了します。                                             | 旅行エージェントが旅行をキャンセルする際、タスクを（例えば、特定の予約のキャンセルなど）サブタスクに分割し、下位エージェントがそれを完了し、高次エージェントに報告します。                                                        |
| **マルチエージェントシステム(MAS)** | 協力的または競争的に、エージェントが独立してタスクを完了します。                                                                     | 協力的: 複数のエージェントがホテル、フライト、エンターテイメントなど特定の旅行サービスを予約します。競争的: 複数のエージェントが共有のホテル予約カレンダーを管理し、顧客の予約を競合しながら進めます。                                     |

## AIエージェントを使用するタイミング

前のセクションでは、旅行エージェントのユースケースを使用して、さまざまな種類のエージェントが旅行予約の異なるシナリオでどのように使用されるかを説明しました。このアプリケーションはコース全体で引き続き使用します。

次に、AIエージェントが最適に使用されるユースケースの種類を見てみましょう：

![When to use AI Agents?](../../../translated_images/when-to-use-ai-agents.912b9a02e9e0e2af45a3e24faa4e912e334ec23f21f0cf5cb040b7e899b09cd0.ja.png?WT.mc_id=academic-105485-koreyst)

- **オープンエンドな問題** - ワークフローに常にハードコードできないため、LLMがタスクを完了するために必要なステップを判断する必要がある場合。
- **複数ステップのプロセス** - ツールや情報を複数のターンにわたって使用する必要がある、ある程度の複雑さを持つタスク。
- **時間とともに改善** - 環境やユーザーからのフィードバックを受け取り、より良いユーティリティを提供するために改善できるタスク。

AIエージェントを使用する際のさらなる考慮事項については、「信頼できるAIエージェントの構築」レッスンで詳しく学びます。

## エージェントソリューションの基本

### エージェントの開発

AIエージェントシステムを設計する最初のステップは、ツール、アクション、動作を定義することです。このコースでは、**Azure AI Agent Service** を使用してエージェントを定義する方法に焦点を当てます。このサービスには以下のような特徴があります：

- OpenAI、Mistral、Llamaなどのオープンモデルの選択
- Tripadvisorなどのプロバイダーを通じたライセンスデータの利用
- 標準化されたOpenAPI 3.0ツールの利用

### エージェントパターン

LLMとのコミュニケーションはプロンプトを通じて行われます。AIエージェントは半自律的な性質を持つため、環境の変化後に手動でLLMを再プロンプトする必要がない場合があります。このため、複数ステップでLLMをよりスケーラブルにプロンプトするための **エージェントパターン** を使用します。

このコースでは、現在人気のあるエージェントパターンをいくつか学びます。

### エージェントフレームワーク

エージェントフレームワークを使用すると、開発者はコードを通じてエージェントパターンを実装できます。これらのフレームワークは、テンプレート、プラグイン、ツールを提供し、AIエージェントのコラボレーションをより良くします。これにより、AIエージェントシステムの可観測性やトラブルシューティングの能力が向上します。

このコースでは、研究主導のAutoGenフレームワークと、Semantic Kernelのプロダクション対応エージェントフレームワークを探ります。

**免責事項**:
この文書は、機械翻訳AIサービスを使用して翻訳されています。正確性を追求していますが、自動翻訳には誤りや不正確さが含まれる可能性があります。元の言語で記載された原文が正式な情報源と見なされるべきです。重要な情報については、専門の人間による翻訳を推奨します。この翻訳の利用によって生じる誤解や解釈の誤りについて、当方は一切の責任を負いません。


# AIエージェントフレームワークを探る

AIエージェントフレームワークは、AIエージェントの作成、展開、管理を簡素化するために設計されたソフトウェアプラットフォームです。これらのフレームワークは、開発者にあらかじめ構築されたコンポーネント、抽象化、およびツールを提供し、複雑なAIシステムの開発を効率化します。

これらのフレームワークは、AIエージェント開発における共通の課題に対して標準化されたアプローチを提供することで、開発者がアプリケーションの独自の側面に集中できるようにします。また、AIシステムのスケーラビリティ、アクセシビリティ、効率性を向上させます。

## はじめに

このレッスンでは以下について学びます：

- AIエージェントフレームワークとは何か、そしてそれによって開発者が何を実現できるのか？
- チームがこれらをどのように活用して、エージェントの能力を迅速にプロトタイプ化、反復、改善できるのか？
- Microsoftが提供するフレームワークとツール（[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開発におけるAIエージェントフレームワークの役割。
- AIエージェントフレームワークを活用してインテリジェントエージェントを構築する方法。
- AIエージェントフレームワークによって可能になる主要な機能。
- Autogen、Semantic Kernel、Azure AI Agent Serviceの違い。

## AIエージェントフレームワークとは何か、そしてそれによって開発者が何を実現できるのか？

従来のAIフレームワークは、AIをアプリに統合し、それらのアプリを以下の方法で改善するのに役立ちます：

- **パーソナライズ**: AIはユーザーの行動や好みを分析し、パーソナライズされた推奨、コンテンツ、体験を提供します。
例: Netflixのようなストリーミングサービスは、視聴履歴に基づいて映画や番組を提案し、ユーザーのエンゲージメントと満足度を向上させます。
- **自動化と効率化**: AIは反復的なタスクを自動化し、ワークフローを合理化し、運用効率を向上させます。
例: カスタマーサービスアプリは、AI搭載のチャットボットを使用して一般的な問い合わせを処理し、応答時間を短縮し、人間のエージェントがより複雑な問題に集中できるようにします。
- **ユーザーエクスペリエンスの向上**: AIは音声認識、自然言語処理、予測テキストなどのインテリジェント機能を提供することで、全体的なユーザー体験を向上させます。
例: SiriやGoogleアシスタントのようなバーチャルアシスタントは、AIを使用して音声コマンドを理解し応答し、ユーザーがデバイスと簡単にやり取りできるようにします。

### それは素晴らしいことのように聞こえますが、なぜAIエージェントフレームワークが必要なのでしょうか？

AIエージェントフレームワークは、単なるAIフレームワーク以上のものを表しています。それは、特定の目標を達成するために、ユーザー、他のエージェント、環境とやり取りできるインテリジェントエージェントの作成を可能にするように設計されています。これらのエージェントは、自律的な行動を示し、意思決定を行い、変化する条件に適応することができます。AIエージェントフレームワークによって可能になる主要な機能をいくつか見てみましょう：

- **エージェントの協調と調整**: 複数のAIエージェントを作成し、それらが協力し、通信し、調整して複雑なタスクを解決することを可能にします。
- **タスクの自動化と管理**: 複数ステップのワークフローの自動化、タスクの委任、エージェント間の動的タスク管理の仕組みを提供します。
- **コンテキストの理解と適応**: エージェントがコンテキストを理解し、変化する環境に適応し、リアルタイムの情報に基づいて意思決定を行う能力を備えています。

要するに、エージェントを活用することで、より多くのことを行い、自動化を次のレベルに引き上げ、環境から学び適応できるよりインテリジェントなシステムを作成できるのです。

## エージェントの能力を迅速にプロトタイプ化、反復、改善するには？

この分野は急速に進化していますが、ほとんどのAIエージェントフレームワークに共通する点がいくつかあります。それは、モジュール型コンポーネント、協調ツール、リアルタイム学習です。以下にそれらを詳しく見ていきましょう：

- **モジュール型コンポーネントの利用**: AIフレームワークは、プロンプト、パーサー、メモリ管理などのあらかじめ構築されたコンポーネントを提供します。
- **協調ツールの活用**: 特定の役割やタスクを持つエージェントを設計し、協調的なワークフローをテストして改善します。
- **リアルタイムで学ぶ**: フィードバックループを実装し、エージェントがインタラクションから学び、動的に行動を調整します。

### モジュール型コンポーネントの利用

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のようなフレームワークは、複数のエージェントを作成して連携させることを容易にします。

**チームがこれらを活用する方法**: チームは特定の役割やタスクを持つエージェントを設計し、協調的なワークフローをテストして洗練し、システム全体の効率を向上させることができます。

**実際の動作方法**: データ取得、分析、意思決定などの特定の機能を持つエージェントチームを作成できます。これらのエージェントは通信し、情報を共有して、ユーザーの質問に答えたり、タスクを完了したりする共通の目標を達成します。

**コード例（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)
```

上記のコードでは、複数のエージェントがデータを分析するタスクを協調して実行する例を示しています。それぞれのエージェントが特定の機能を果たし、エージェントを調整して目標を達成します。専用の役割を持つエージェントを作成することで、タスクの効率とパフォーマンスを向上させることができます。

### リアルタイムで学ぶ

高度なフレームワークは、リアルタイムでのコンテキスト理解と適応機能を提供します。

**チームがこれらを活用する方法**: チームはフィードバックループを実装し、エージェントがインタラクションから学び、動的に行動を調整することで、能力の継続的な向上と洗練を実現します。

**実際の動作方法**: エージェントはユーザーのフィードバック、環境データ、タスクの結果を分析して知識ベースを更新し、意思決定アルゴリズムを調整し、時間とともにパフォーマンスを向上させます。この反復学習プロセスにより、エージェントは変化する条件やユーザーの好みに適応し、システム全体の効果を向上させます。

## Autogen、Semantic Kernel、Azure AI Agent Serviceの違いとは？

これらのフレームワークを比較する方法はいくつかありますが、その設計、機能、対象ユースケースに基づいて主な違いを見てみましょう。

### Autogen

Microsoft ResearchのAI Frontiers Labによって開発されたオープンソースフレームワークです。イベント駆動型の分散型エージェンティックアプリケーションに焦点を当てており、複数のLLMやSLM、ツール、高度なマルチエージェント設計パターンをサポートします。

Autogenは、エージェントというコアコンセプトに基づいて構築されています。エージェントとは、環境を認識し、意思決定を行い、特定の目標を達成するために行動を起こす自律的なエンティティです。エージェントは非同期メッセージを通じて通信し、独立して並列に動作することで、システムのスケーラビリティと応答性を向上させます。

エージェントは[アクターモデル](https://en.wikipedia.org/wiki/Actor_model)に基づいています。Wikipediaによると、アクターとは_メッセージを受信した際にローカルな意思決定を行い、新しいアクターを作成し、さらなるメッセージを送信し、次に受信するメッセージへの応答方法を決定できる並行計算の基本構成要素_です。

**ユースケース**: コード生成、データ分析タスクの自動化、計画および研究機能のためのカスタムエージェントの構築。

Autogenの重要なコアコンセプトについて以下に示します：

- **エージェント**
  - エージェントは、メッセージ通信、自身の状態の保持、受信メッセージや状態変化に応じた行動を行います。
  - 例: チャットエージェントの作成

    ```python
    from autogen_agentchat.agents import AssistantAgent
    from autogen_agentchat.messages import TextMessage
    from autogen_ext.models.openai import OpenAIChatCompletionClient

    class MyAssistant(RoutedAgent):
        def __init__(self, name: str) -> None:
            super().__init__(name)
            model_client = OpenAIChatCompletionClient(model="gpt-4o")
            self._delegate = AssistantAgent(name, model_client=model_client)

        @message_handler
        async def handle_my_message_type(self, message: MyMessageType, ctx: MessageContext) -> None:
            print(f"{self.id.type} received message: {message.content}")
            response = await self._delegate.on_messages(
                [TextMessage(content=message.content, source="user")], ctx.cancellation_token
            )
            print(f"{self.id.type} responded: {response.chat_message.content}")
    ```

    ここでは、`MyAssistant`というエージェントが作成されています。

    エージェントタイプをAutogenに登録してプログラムを開始します：

    ```python

    # main.py
    runtime = SingleThreadedAgentRuntime()
    await MyAgent.register(runtime, "my_agent", lambda: MyAgent())

    runtime.start()  # Start processing messages in the background.
    await runtime.send_message(MyMessageType("Hello, World!"), AgentId("my_agent", "default"))
    ```

    上記では、エージェントが登録され、メッセージを送信することで応答を得ています。

- **マルチエージェント**
  - Autogenは複数のエージェントを作成し、それらが連携して複雑なタスクを効率的に解決する仕組みを提供します。

    ```python
    editor_description = "Editor for planning and reviewing the content."

    # Example of declaring an Agent
    editor_agent_type = await EditorAgent.register(
    runtime,
    editor_topic_type,  # Using topic type as the agent type.
    lambda: EditorAgent(
        description=editor_description,
        group_chat_topic_type=group_chat_topic_type,
        model_client=OpenAIChatCompletionClient(
            model="gpt-4o-2024-08-06",
            # api_key="YOUR_API_KEY",
        ),
        ),
    )

    # remaining declarations shortened for brevity

    # Group chat
    group_chat_manager_type = await GroupChatManager.register(
    runtime,
    "group_chat_manager",
    lambda: GroupChatManager(
        participant_topic_types=[writer_topic_type, illustrator_topic_type, editor_topic_type, user_topic_type],
        model_client=OpenAIChatCompletionClient(
            model="gpt-4o-2024-08-06",
            # api_key="YOUR_API_KEY",
        ),
        participant_descriptions=[
            writer_description,
            illustrator_description,
            editor_description,
            user_description
        ],
        ),
    )
    ```

    上記の例では、`GroupChatManager`がエージェント間のやり取りを調整しています。

- **エージェントランタイム**
  - エージェント間の通信、アイデンティティとライフサイクルの管理、セキュリティ境界の強制を行います。

    - **スタンドアロンランタイム**
      単一プロセスアプリケーション向け。

      ![スタンドアロンランタイム](https://microsoft.github.io/autogen/stable/_images/architecture-standalone.svg)

    - **分散エージェントランタイム**
      マルチプロセスアプリケーション向け。

      ![分散ランタイム](https://microsoft.github.io/autogen/stable/_images/architecture-distributed.svg)

### Semantic Kernel + エージェントフレームワーク

Semantic Kernelには以下のコアコンセプトがあります：

- **接続**: 外部AIサービスやデータソースとのインターフェース。

    ```csharp
    using Microsoft.SemanticKernel;

    // Create kernel
    var builder = Kernel.CreateBuilder();

    // Add a chat completion service:
    builder.Services.AddAzureOpenAIChatCompletion(
        "your-resource-name",
        "your-endpoint",
        "your-resource-key",
        "deployment-model");
    var kernel = builder.Build();
    ```

    上記はAzure OpenAI Chat Completionサービスへの接続例です。

- **プラグイン**: アプリケーションで使用可能な関数をカプセル化。

    ```csharp
    var userInput = Console.ReadLine();

    // Define semantic function inline.
    string skPrompt = @"Summarize the provided unstructured text in a sentence that is easy to understand.
                        Text to summarize: {{$userInput}}";

    // Register the function
    kernel.CreateSemanticFunction(
        promptTemplate: skPrompt,
        functionName: "SummarizeText",
        pluginName: "SemanticFunctions"
    );
    ```

    Semantic Kernelは、提供されたセマンティック情報に基づいて適切な関数を呼び出します。

- **ネイティブ関数**: フレームワークが直接呼び出せる関数。

    ```csharp
    public class NativeFunctions {

        [SKFunction, Description("Retrieve content from local file")]
        public async Task<string> RetrieveLocalFile(string fileName, int maxSize = 5000)
        {
            string content = await File.ReadAllTextAsync(fileName);
            if (content.Length <= maxSize) return content;
            return content.Substring(0, maxSize);
        }
    }

    //Import native function
    string plugInName = "NativeFunction";
    string functionName = "RetrieveLocalFile";

    var nativeFunctions = new NativeFunctions();
    kernel.ImportFunctions(nativeFunctions, plugInName);
    ```

- **プランナー**: ユーザー入力に基づいて実行計画を策定。

    ```csharp
    string planDefinition = "Read content from a local file and summarize the content.";
    SequentialPlanner sequentialPlanner = new SequentialPlanner(kernel);

    string assetsFolder = @"../../assets";
    string fileName = Path.Combine(assetsFolder,"docs","06_SemanticKernel", "aci_documentation.txt");

    ContextVariables contextVariables = new ContextVariables();
    contextVariables.Add("fileName", fileName);

    var customPlan = await sequentialPlanner.CreatePlanAsync(planDefinition);

    // Execute the plan
    KernelResult kernelResult = await kernel.RunAsync(contextVariables, customPlan);
    Console.WriteLine($"Summarization: {kernelResult.GetValue<string>()}");
    ```

- **メモリ**: AIアプリケーションのコンテキスト管理を抽象化。

    ```csharp
    var facts = new Dictionary<string,string>();
    facts.Add(
        "Azure Machine Learning; https://learn.microsoft.com/azure/machine-learning/",
        @"Azure Machine Learning is a cloud service for accelerating and
        managing the machine learning project lifecycle. Machine learning professionals,
        data scientists, and engineers can use it in their day-to-day workflows"
    );

    facts.Add(
        "Azure SQL Service; https://learn.microsoft.com/azure/azure-sql/",
        @"Azure SQL is a family of managed, secure, and intelligent products
        that use the SQL Server database engine in the Azure cloud."
    );

    string memoryCollectionName = "SummarizedAzureDocs";

    foreach (var fact in facts) {
        await memoryBuilder.SaveReferenceAsync(
            collection: memoryCollectionName,
            description: fact.Key.Split(";")[1].Trim(),
            text: fact.Value,
            externalId: fact.Key.Split(";")[2].Trim(),
            externalSourceName: "Azure Documentation"
        );
    }
    ```

    メモリコレクションに情報を保存して活用します。

### Azure AI Agent Service

Azure AI Agent Serviceは、Microsoft Ignite 2024で導入された新しいサービスで、オープンソースLLM（例: Llama 3、Mistral、Cohere）の直接呼び出しをサポートします。

- **エージェント**: "スマート"マイクロサービスとして動作。

    ```python
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="my-agent",
        instructions="You are helpful agent",
        tools=code_interpreter.definitions,
        tool_resources=code_interpreter.resources,
    )
    ```

- **スレッドとメッセージ**: 会話やインタラクションを管理。

    ```python
    thread = project_client.agents.create_thread()
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="Could you please create a bar chart for the operating profit using the following data and provide the file to me? Company A: $1.2 million, Company B: $2.5 million, Company C: $3.0 million, Company D: $1.8 million",
    )

    # Ask the agent to perform work on the thread
    run = project_client.agents.create_and_process_run(thread_id=thread.id, agent_id=agent.id)

    # Fetch and log all messages to see the agent's response
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")
    ```

- **他のAIフレームワークとの統合**: AutogenやSemantic Kernelと連携可能。

**ユースケース**: エンタープライズ向けのセキュアでスケーラブルなAIエージェント展開に最適。

## これらのフレームワークの違いとは？

以下の表で主な違いをまとめました：

| フレームワーク       | フォーカス                              | コアコンセプト                        | ユースケース                      |
|----------------------|-----------------------------------------|--------------------------------------|----------------------------------|
| Autogen             | イベント駆動型、分散型エージェンティックアプリケーション | エージェント、ペルソナ、関数、データ | コード生成、データ分析タスク     |
| Semantic Kernel     | 人間のようなテキスト生成と理解           | エージェント、モジュール型コンポーネント、協調 | 自然言語理解、コンテンツ生成    |
| Azure AI Agent Service | 柔軟なモデル、エンタープライズセキュリティ、ツール呼び出し | モジュール性、協調、プロセスオーケストレーション | セキュアでスケーラブルなAI展開 |

### どのフレームワークを選ぶべき？

> **Q**: コード生成やデータ分析タスクを自動化するプロジェクトに取り組んでいます。どのフレームワークを使用すべきですか？
> **A**: Autogenが適しています。イベント駆動型で分散型エージェンティックアプリケーションに特化しており、高度なマルチエージェント設計パターンをサポートしています。

> **Q**: エンタープライズ
プロジェクト目標に基づいています。自然言語理解、コンテンツ生成に最適です。
- **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エージェントシステムを構築する方法はさまざまです。生成AIの設計において曖昧さはバグではなく特徴であるため、エンジニアにとってどこから始めればいいのか分からないことがあります。そこで、私たちは開発者がビジネスニーズを解決するための顧客中心のエージェントシステムを構築できるように、人間中心のUX設計原則を作成しました。これらの設計原則は厳密なアーキテクチャではなく、エージェント体験を定義し構築するチームにとっての出発点です。

一般的に、エージェントは以下を目指すべきです：

- 人間の能力を広げ、スケールさせる（ブレインストーミング、問題解決、自動化など）
- 知識のギャップを埋める（知識分野を短期間で把握する、翻訳など）
- 私たちが個々に他者と協力する際の好みに応じて、コラボレーションを促進しサポートする
- 私たちをより良い自分にしてくれる（例：ライフコーチ/タスクマスターとして、感情の調整やマインドフルネススキルの習得、レジリエンスの構築を助けるなど）

## このレッスンで学ぶこと

- エージェント設計の原則とは何か
- これらの設計原則を実装する際のガイドライン
- 設計原則を活用した具体例

## 学習目標

このレッスンを終えた後、次のことができるようになります：

1. エージェント設計の原則が何であるか説明できる
2. エージェント設計の原則を使用する際のガイドラインを説明できる
3. エージェント設計の原則を活用してエージェントを構築する方法を理解する

## エージェント設計の原則

![エージェント設計の原則](../../../translated_images/agentic-design-principles.9f32a64bb6e2aa5a1bdffb70111aa724058bc248b1a3dd3c6661344015604cff.ja.png?WT.mc_id=academic-105485-koreyst)

### エージェント（空間）

これはエージェントが動作する環境を指します。この原則は、物理的およびデジタルの世界でエージェントを設計する際の指針となります。

- **つなげる、壊さない** – 人々を他の人々、イベント、行動可能な知識につなげ、コラボレーションと接続を可能にする。
  - エージェントはイベント、知識、人々をつなげる役割を果たします。
  - エージェントは人々をより近づけるものであり、人々を置き換えたり軽視するものではありません。
- **簡単にアクセスできるが、時には見えない** – エージェントは主にバックグラウンドで動作し、関連性があり適切なタイミングでのみ私たちに働きかけます。
  - エージェントは、どのデバイスやプラットフォームでも認可されたユーザーが簡単に発見・アクセスできるように設計されています。
  - エージェントは音声、テキストなどのマルチモーダルな入力と出力をサポートします。
  - エージェントは、ユーザーのニーズを感知しながら、前景と背景、能動的と受動的の間をシームレスに移行します。
  - エージェントは見えない形で動作することもありますが、そのバックグラウンドでのプロセスや他のエージェントとのコラボレーションはユーザーにとって透明で制御可能です。

### エージェント（時間）

これはエージェントが時間を通じてどのように動作するかを指します。この原則は、過去、現在、未来にわたるエージェントの設計方法を示します。

- **過去**: 状態とコンテキストを含む履歴を反映する。
  - エージェントは、イベントや人々、状態だけでなく、より豊かな履歴データの分析に基づいて関連性の高い結果を提供します。
  - エージェントは過去のイベントからつながりを生み出し、記憶を積極的に反映して現在の状況に対応します。
- **現在**: 通知以上の働きかけをする。
  - エージェントは、人々とのやり取りに包括的なアプローチを取ります。イベントが発生した際、静的な通知や形式的なものを超えて、ユーザーの注意を適切なタイミングで引きつける動的な指針を生成します。
  - エージェントはコンテキスト環境、社会的・文化的変化、ユーザーの意図に合わせた情報を提供します。
  - エージェントのやり取りは徐々に進化し、長期的にユーザーをエンパワーする複雑さを備えています。
- **未来**: 適応し進化する。
  - エージェントはさまざまなデバイス、プラットフォーム、モダリティに適応します。
  - エージェントはユーザーの行動やアクセシビリティのニーズに適応し、自由にカスタマイズ可能です。
  - エージェントは継続的なユーザーとのやり取りを通じて形成され、進化します。

### エージェント（コア）

これはエージェント設計の中心的な要素です。

- **不確実性を受け入れつつ信頼を構築する**。
  - エージェントの不確実性はある程度予想されるものです。不確実性はエージェント設計の重要な要素です。
  - 信頼と透明性はエージェント設計の基盤となるレイヤーです。
  - エージェントがオン/オフの状態は人間が制御し、エージェントのステータスは常に明確に表示されます。

## これらの原則を実装するためのガイドライン

上記の設計原則を使用する際には、以下のガイドラインを参考にしてください：

1. **透明性**: AIが関与していること、その仕組み（過去のアクションを含む）、フィードバックの方法やシステムの修正方法をユーザーに知らせる。
2. **制御**: ユーザーがシステムやその属性（忘れる機能を含む）をカスタマイズ、好みを指定、個別化し、制御できるようにする。
3. **一貫性**: デバイスやエンドポイント間で一貫したマルチモーダル体験を目指す。可能であれば馴染みのあるUI/UX要素を使用し（例：音声操作のためのマイクアイコン）、ユーザーの認知負荷を可能な限り軽減する（例：簡潔な応答、視覚的補助、‘詳細を学ぶ’コンテンツ）。

## これらの原則とガイドラインを使用して旅行エージェントを設計する方法

旅行エージェントを設計する場合、以下のように設計原則とガイドラインを活用することを考えてみてください：

1. **透明性** – 旅行エージェントがAI対応エージェントであることをユーザーに知らせます。基本的な使い方を説明する（例：「こんにちは」メッセージ、サンプルプロンプト）。これを製品ページに明確に記載します。過去にユーザーが入力したプロンプトのリストを表示します。フィードバック方法（サムズアップ/ダウン、フィードバック送信ボタンなど）を明確にします。エージェントに使用制限やトピック制限がある場合は明確に説明します。
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エージェントを構築する際に、ツール利用デザインパターンを使用する際の特別な考慮事項は何か？

## 学習目標

このレッスンを完了すると、次のことができるようになります：

- ツール利用デザインパターンとその目的を定義する。
- ツール利用デザインパターンが適用可能なユースケースを特定する。
- デザインパターンを実装するために必要な主要要素を理解する。
- このデザインパターンを使用するAIエージェントの信頼性を確保するための考慮事項を認識する。

## ツール利用デザインパターンとは？

**ツール利用デザインパターン**は、LLM（大規模言語モデル）に外部ツールと連携する能力を与え、特定の目標を達成することを目的としています。ツールとは、エージェントがアクションを実行するために使用できるコードのことを指します。ツールは、電卓のような単純な関数や、株価検索や天気予報のようなサードパーティサービスへのAPI呼び出しなどがあります。AIエージェントの文脈では、ツールは**モデル生成の関数呼び出し**に応じてエージェントによって実行されるように設計されています。

## 適用できるユースケースは何か？

AIエージェントはツールを活用して、複雑なタスクを完了したり、情報を取得したり、意思決定を行うことができます。ツール利用デザインパターンは、データベースやウェブサービス、コードインタプリタなどの外部システムとの動的なやり取りを必要とするシナリオでよく使用されます。この能力は、以下のようなさまざまなユースケースで役立ちます：

- **動的な情報取得**：エージェントが外部APIやデータベースをクエリし、最新のデータを取得（例：SQLiteデータベースを使ったデータ分析、株価や天気情報の取得）。
- **コードの実行と解釈**：エージェントがコードやスクリプトを実行し、数学的問題を解いたり、レポートを生成したり、シミュレーションを行う。
- **ワークフローの自動化**：タスクスケジューラ、メールサービス、データパイプラインなどのツールを統合して反復的または多段階のワークフローを自動化。
- **カスタマーサポート**：CRMシステム、チケッティングプラットフォーム、ナレッジベースと連携してユーザーの問い合わせに対応。
- **コンテンツ生成と編集**：文法チェッカー、テキスト要約ツール、コンテンツの安全性評価ツールを活用してコンテンツ作成を支援。

## ツール利用デザインパターンを実装するために必要な要素/構成要素は何か？

### 関数/ツール呼び出し

関数呼び出しは、LLMがツールと連携する主要な方法です。「関数」と「ツール」はしばしば同義で使われます。なぜなら、「関数」（再利用可能なコードブロック）が、エージェントがタスクを実行するために使用する「ツール」だからです。関数のコードを呼び出すためには、LLMがユーザーのリクエストを関数の説明と比較する必要があります。そのため、利用可能なすべての関数の説明を含むスキーマをLLMに送信します。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は、LLMを利用する.NET、Python、Java開発者向けのオープンソースAIフレームワークです。このフレームワークは、関数呼び出しのプロセスを簡素化し、関数とそのパラメータをモデルに自動的に説明する[シリアライズ](https://learn.microsoft.com/semantic-kernel/concepts/ai-services/chat-completion/function-calling/?pivots=programming-language-python#1-serializing-the-functions)というプロセスを通じて実現します。また、モデルとコード間のやり取りを処理する機能も備えています。さらに、Semantic Kernelのようなエージェントフレームワークを使用する利点として、[ファイル検索](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step4_assistant_tool_file_search.py)や[コードインタプリタ](https://github.com/microsoft/semantic-kernel/blob/main/python/samples/getting_started_with_agents/openai_assistant/step3_assistant_tool_code_interpreter.py)などの事前構築されたツールにアクセスできる点があります。

    以下の図は、Semantic Kernelを使用した関数呼び出しのプロセスを示しています：

    ![function calling](../../../translated_images/functioncalling-diagram.b5493ea5154ad8e3e4940d2e36a49101eec1398948e5d1039942203b4f5a4209.ja.png)

    Semantic Kernelでは、関数/ツールは[プラグイン](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`デコレーターを使用して関数の説明を提供できます。このプラグインを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で利用可能なツールは以下の2つのカテゴリに分けられます：

    1. 知識ツール:
        - [Bing Searchによる基盤情報](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.ja.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)11c90e8cda37025bea4db5c4a59d

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

**免責事項**:
この文書は、機械ベースのAI翻訳サービスを使用して翻訳されています。正確性を追求しておりますが、自動翻訳には誤りや不正確さが含まれる可能性があることをご了承ください。元の言語で記載された原文が正式な情報源とみなされるべきです。重要な情報については、専門の人間による翻訳をお勧めします。本翻訳の使用に起因する誤解や解釈の誤りについて、当社は一切の責任を負いません。