ai-agents-for-beginners

如何設計良好的 AI 代理

(點擊上方圖片觀看本課程影片)

工具使用設計模式

工具很有趣，因為它們允許 AI 代理擁有更廣泛的能力。代理不再僅有有限的行動集合，而是透過添加工具，代理現在可以執行各種操作。在本章中，我們將探討工具使用設計模式，描述 AI 代理如何使用特定工具達成目標。

簡介

在本課程中，我們致力於解答以下問題：

學習目標

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

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

工具使用設計模式專注於賦予大型語言模型（LLM）與外部工具互動以達成特定目標的能力。工具是代理可執行的程式碼以完成動作。工具可以是簡單的函數，例如計算機，或是第三方服務的 API 呼叫，例如股價查詢或天氣預報。在 AI 代理的語境中，工具設計為代理在回應模型生成的函數呼叫時執行。

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

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

實現工具使用設計模式需要哪些元素／建構方塊？

這些建構方塊允許 AI 代理執行多元任務。以下是實現工具使用設計模式所需的關鍵元素：

接下來，我們將更詳細探討函數／工具呼叫。

函數／工具呼叫

函數呼叫是使大型語言模型（LLM）與工具互動的主要方式。您會常看到「函數」與「工具」互換使用，因為「函數」（可重用的程式碼區塊）即為代理執行任務用的「工具」。為了呼叫函數的程式碼，LLM 必須將用戶請求與函數描述比對。為此，所有可用函數的描述會以結構架構（schema）形式傳遞給 LLM。LLM 再從中選出最適合任務的函數，並回傳函數名稱及參數。選定函數被呼叫後，其回應會送回 LLM，LLM 利用該資訊回應用戶請求。

開發者若要實作代理的函數呼叫，需要：

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

以下以取得城市當前時間為例說明：

  1. 初始化支援函數呼叫的 LLM：

    不是所有模型都支援函數呼叫，因此需確認所使用的 LLM 是否支援。Azure OpenAI 支援函數呼叫。我們可先啟用 Azure OpenAI 用戶端。

     # 初始化 Azure OpenAI 客戶端
 client = AzureOpenAI(
     azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"), 
     api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
     api_version="2024-05-01-preview"
 )

  2. 建立函數結構架構：

    接著定義一個 JSON 結構，包含函數名稱、函數功能描述，以及參數名稱與描述。然後將此結構與用戶要求（查詢舊金山時間）傳給先前建立的用戶端。重要的是要注意，回傳的是工具呼叫，而非問題的最終答案。正如前述，LLM 回傳選中執行任務的函數名與傳入參數。

     # 模型閱讀的功能描述
 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"],
             },
         }
     }
 ]

      
 # 初始用戶訊息
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}] 
  
 # 第一次 API 調用：請模型使用函數
   response = client.chat.completions.create(
       model=deployment_name,
       messages=messages,
       tools=tools,
       tool_choice="auto",
   )
  
   # 處理模型的回應
   response_message = response.choices[0].message
   messages.append(response_message)
  
   print("Model's response:")  

   print(response_message)
  

     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')])

  3. 執行任務所需的函數程式碼：

    LLM 選定要執行的函數後，需要實作並執行該函數程式碼。我們可以用 Python 實作取得當前時間的代碼，並撰寫程式碼從 response_message 取出函數名稱及參數，得到最終結果。

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

      # 處理函數調用
   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.")  
  
   # 第二次 API 調用：從模型獲取最終回應
   final_response = client.chat.completions.create(
       model=deployment_name,
       messages=messages,
   )
  
   return final_response.choices[0].message.content

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

函數呼叫是大多數（若非全部）代理工具使用設計的核心，但從零實作有時會具挑戰性。 如 第二課 所示，代理框架為我們提供了建構工具使用的預建建構方塊。

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

以下示範如何使用不同代理框架實作工具使用設計模式：

Semantic Kernel

Semantic Kernel 是為 .NET、Python 和 Java 開發者打造的開源 AI 框架，專門使用大型語言模型（LLM）。它透過稱為序列化的過程，自動將您的函數及其參數描述傳給模型，簡化了函數呼叫流程。它也處理模型與程式碼之間的來回通訊。使用如 Semantic Kernel 等代理框架的另一優點是，可存取預建工具，如檔案搜尋與程式碼解譯器。

下圖說明 Semantic Kernel 函數呼叫的流程：

function calling

在 Semantic Kernel 中，函數／工具稱為外掛程式（Plugins）。我們可以將先前的 get_current_time 函數改為外掛，將其包裝成含該函數的類別，並匯入 kernel_function 裝飾器，裝飾器接收函數描述。建立帶有 GetCurrentTimePlugin 的 kernel 時，kernel 會自動序列化函數及其參數，過程中產生發送給 LLM 的結構架構。

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 = ""):
        ...


from semantic_kernel import Kernel

# 建立核心
kernel = Kernel()

# 建立插件
get_current_time_plugin = GetCurrentTimePlugin(location)

# 將插件加入到核心
kernel.add_plugin(get_current_time_plugin)

Azure AI Agent Service

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

與直接使用 LLM API 開發相比，Azure AI Agent Service 具備以下優勢：

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

  1. 知識工具：
  2. 行動工具：

代理服務允許我們將這些工具合為 toolset 使用，也利用 threads 追蹤特定對話的訊息歷史。

想像您是 Contoso 公司的銷售員工，想開發可以回答銷售數據問題的對話代理。

下圖展示如何使用 Azure AI Agent Service 來分析銷售數據：

Agentic Service In Action

要在服務中使用這些工具，我們可以創建用戶端並定義工具或工具組。下列 Python 程式碼演示實作。LLM 會檢視工具組並根據使用者請求決定使用使用者自行建立的函數 fetch_sales_data_using_sqlite_query 還是預建的程式碼解譯器。

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from fetch_sales_data_functions import fetch_sales_data_using_sqlite_query # fetch_sales_data_using_sqlite_query 函數，可以在 fetch_sales_data_functions.py 文件中找到。
from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

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

# 初始化工具組
toolset = ToolSet()

# 使用 fetch_sales_data_using_sqlite_query 函數初始化函數調用代理，並將其添加到工具組中
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# 初始化程式碼解釋器工具並將其添加到工具組中。
code_interpreter = code_interpreter = CodeInterpreterTool()
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 Foundry Discord 與其他學習者交流，參加辦公時間，並獲取 AI Agents 的問題解答。

其他資源

上一課

理解 Agentic 設計模式

下一課

Agentic RAG

免責聲明： 本文件已使用 AI 翻譯服務 Co-op Translator 進行翻譯。儘管我們努力追求準確性，請注意自動翻譯可能包含錯誤或不準確之處。原始文件之母語版本應被視為權威來源。對於關鍵資訊，建議使用專業人工翻譯。本公司不對因使用本翻譯版本而引致的任何誤解或曲解承擔責任。

This site is open source. Improve this page.