Agent 初始化與工具註冊 — 15 種智能工具的完整配置 (4)

在前三篇，我們了解了 LangChain Agent 的系統架構、SystemTools 的設計，以及自定義 Gemini LLM 包裝器。今天，我們要探討整個智能助手的「神經中樞」：Agent 初始化與工具註冊系統。

這個系統決定了 AI 助手能夠執行哪些任務，以及如何智能地選擇合適的工具。

功能簡介

Agent 初始化與工具註冊系統包含：

• 多種智能工具的完整配置：涵蓋應用程式控制、內容生成、檔案處理等功能
• 智能工具選擇機制：Agent 能根據用戶輸入自動選擇最適合的工具
• 系統提示優化：引導 Agent 做出更智能的決策

核心程式碼解析

工具定義與註冊

def _initialize_langchain(self):
    """初始化 LangChain 組件"""
    try:
        # Gemini API 設定
        api_key = os.getenv('API_KEY')
        
        # 創建自定義 LLM
        self.gemini_llm = GeminiLLM(
            api_key=api_key, 
            model_name=os.environ.get("GEMINI_MODEL", "models/gemini-2.5-flash")
        )
        
        # 初始化系統工具
        self.system_tools = SystemTools(app_instance=self)
        
        # 定義工具
        tools = [
            # 內容生成工具
            Tool(
                name="內容生成工具",
                func=self.system_tools.generate_content_tool,
                description="生成創意內容，如文章、心得、故事等。輸入主題或要求即可。"
            ),
            
            # 應用程式控制工具群
            Tool(
                name="開啟小畫家",
                func=self.system_tools.open_paint_tool,
                description="開啟Windows小畫家應用程式"
            ),
            Tool(
                name="開啟記事本",
                func=self.system_tools.open_notepad_tool,
                description="開啟Windows記事本應用程式"
            ),
            
            # Word 操作工具群 (6個工具)
            Tool(
                name="開啟空白Word",
                func=self.system_tools.open_blank_word_tool,
                description="純粹開啟一個空白的Word應用程式。用於：用戶只是想開啟Word但不需要立即寫入內容的情況。"
            ),
            Tool(
                name="開啟Word並輸入內容",
                func=self.system_tools.open_word_tool,
                description="開啟Word並輸入指定的內容。用於：1)將特定內容直接寫入Word；2)將之前的分析結果/解答寫入Word。"
            ),
            Tool(
                name="將已生成內容寫入Word",
                func=self.system_tools.write_generated_to_word_tool,
                description="將最近的內容寫入Word，包括：1)生成的內容；2)分析結果；3)翻譯結果；4)上傳檔案內容。"
            ),
            Tool(
                name="寫內容到Word",
                func=self.system_tools.write_to_word_tool,
                description="根據指定主題重新生成內容並寫入Word。用於創作新的文章、小說、報告等。"
            ),
            Tool(
                name="修改Word內容",
                func=self.system_tools.modify_word_tool,
                description="修改已開啟的Word文件內容"
            ),
            Tool(
                name="儲存Word文件",
                func=self.system_tools.save_word_tool,
                description="儲存Word文件。如果用戶只說'存檔'而沒有指定檔名，應該詢問檔案名稱。"
            ),
            Tool(
                name="檢查Word狀態",
                func=self.system_tools.check_word_status_tool,
                description="檢查Word應用程式的當前狀態"
            ),
            
            # 狀態管理工具
            Tool(
                name="檢查內容狀態",
                func=self.system_tools.check_available_content_tool,
                description="檢查當前系統中有哪些內容可以寫入Word，包括生成內容、分析結果、上傳檔案等。"
            ),
            
            # 檔案處理工具群
            Tool(
                name="檔案上傳分析",
                func=self.system_tools.upload_file_tool,
                description="上傳檔案並顯示上傳成功訊息，然後詢問用戶要做什麼。支援多種檔案格式。"
            ),
            Tool(
                name="檔案內容分析",
                func=self.system_tools.analyze_file_content_tool,
                description="對已上傳的檔案進行各種分析。可以進行：詳細分析、總結摘要、提取重點、翻譯內容、寫心得感想等。"
            ),
        ]

工具分類與功能架構

1. 應用程式控制層

# 基礎應用程式工具
- 開啟小畫家      # Windows Paint
- 開啟記事本      # Notepad

2. Word 文件操作層

# Word 核心操作鏈
開啟空白Word → 開啟Word並輸入內容 → 修改Word內容 → 儲存Word文件
     ↓              ↓                    ↓           ↓
   純開啟        寫入特定內容         編輯現有文件    檔案存檔

# Word 智能操作
- 將已生成內容寫入Word  # 智能選擇最新內容
- 寫內容到Word         # 重新生成並寫入
- 檢查Word狀態         # 狀態監控

3. 內容管理層

# 內容生命週期管理
內容生成工具 → 檢查內容狀態 → 將已生成內容寫入Word
     ↓              ↓                ↓
  創建內容        狀態查詢          內容寫入

4. 檔案處理層

# 檔案處理流程
檔案上傳分析 → 檔案內容分析 → 將已生成內容寫入Word
     ↓              ↓                ↓
   檔案上傳        專家分析          結果輸出

Agent 配置與系統提示

Agent 初始化配置

# 創建系統提示
system_prompt = """你是一個智能助手，專門幫助用戶處理各種任務。

重要指導原則：
1. 當用戶說"寫入Word"、"輸入Word"、"把XX寫入Word"時，要理解他們想寫入已有的內容
2. 如果系統剛剛完成了檔案分析、解題、翻譯等任務，用戶要求寫入Word時，他們指的是這些結果
3. 在執行Word寫入操作前，可以先使用「檢查內容狀態」工具確認有什麼內容可用
4. 優先使用「將已生成內容寫入Word」工具，它會自動選擇最新的內容
5. 不要過度詢問用戶，要根據上下文智能判斷用戶意圖

請根據這些原則協助用戶。"""

# 初始化 Agent
self.agent = initialize_agent(
    tools, 
    self.gemini_llm, 
    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, 
    verbose=True,
    max_iterations=3,           # 最大執行次數
    max_execution_time=30,      # 最大執行時間
    early_stopping_method="generate",
    handle_parsing_errors=custom_error_handler,
    agent_kwargs={"prefix": system_prompt}
)

自定義錯誤處理機制

核心錯誤處理策略

def custom_error_handler(error) -> str:
    """自定義錯誤處理函數，嘗試解析並執行動作"""
    error_msg = str(error)
    print(f"[DEBUG] 解析錯誤，嘗試自定義處理: {error_msg}")
    
    # 應用程式開啟請求處理
    if "Action: 開啟小畫家" in error_msg:
        try:
            result = self.system_tools.open_paint_tool("")
            return f"小畫家應用程式已成功開啟，您可以開始繪圖了。實際結果：{result}"
        except Exception as e:
            return f"開啟小畫家時發生錯誤: {e}"
    
    # Word操作請求處理
    if ("Action: 開啟Word並輸入內容" in error_msg or "Action: 開啟Word" in error_msg):
        try:
            result = self.system_tools.open_word_tool("")
            return f"Word應用程式已成功開啟，您可以開始編輯文件了。實際結果：{result}"
        except Exception as e:
            return f"開啟Word時發生錯誤: {e}"
    
    # 智能Word寫入處理
    elif ("寫入word" in error_msg.lower() or "寫入Word" in error_msg):
        # 防重複調用機制
        import time
        current_time = time.time()
        if hasattr(self, '_last_word_open_time'):
            time_diff = current_time - self._last_word_open_time
            if time_diff < 5:
                return "Word剛開啟過，內容已經寫入完成。"
        
        # 智能內容來源判斷
        has_existing_content = False
        content_source = ""
        
        if (hasattr(self, 'last_analysis_result') and 
            self.last_analysis_result and 
            self.last_analysis_result.strip()):
            has_existing_content = True
            content_source = "分析結果"
        
        if has_existing_content:
            result = self.system_tools.write_generated_to_word_tool("")
            return f"已將{content_source}寫入Word。{result}"
    
    # 檔案分析請求處理
    elif "檔案內容分析" in error_msg or "檔案分析" in error_msg:
        try:
            analysis_type = "詳細分析"
            if "總結" in error_msg:
                analysis_type = "總結"
            elif "重點" in error_msg:
                analysis_type = "重點"
            elif "翻譯" in error_msg:
                analysis_type = "翻譯"
            
            result = self.system_tools.analyze_file_content_tool(analysis_type)
            return result
        except Exception as e:
            return f"檔案分析失敗: {e}"
    
    # Final Answer 提取
    elif "Final Answer:" in error_msg:
        try:
            final_answer_part = error_msg.split("Final Answer:")[-1].strip()
            if "For troubleshooting" in final_answer_part:
                final_answer_part = final_answer_part.split("For troubleshooting")[0].strip()
            return final_answer_part
        except Exception as e:
            return "很抱歉，我無法理解您的問題。請提供更具體的問題或需求。"
    
    # 預設錯誤處理
    return f"很抱歉，我無法理解您的問題。請提供更具體的問題或需求。"

智能工具選擇機制

工具描述的設計策略

# 精確的使用場景描述
Tool(
    name="開啟空白Word",
    description="純粹開啟一個空白的Word應用程式。用於：用戶只是想開啟Word但不需要立即寫入內容的情況。"
)

Tool(
    name="將已生成內容寫入Word",
    description="將最近的內容寫入Word，包括：1)生成的內容；2)分析結果；3)翻譯結果；4)上傳檔案內容。用於當用戶說'把剛才的內容寫入Word'、'將解題結果寫入Word'等。"
)

設計原則：

• 明確的使用時機：何時使用這個工具
• 具體的關鍵詞匹配：用戶可能的表達方式
• 功能邊界清楚：避免工具功能重疊

Agent 決策流程

用戶輸入 → LLM 理解意圖 → 工具描述匹配 → 選擇最佳工具 → 執行操作
    ↓              ↓              ↓              ↓          ↓
  自然語言      語義分析      描述比對      智能選擇    實際執行

1. 分層工具架構

• 基礎層：應用程式控制
• 核心層：Word 文件操作
• 智能層：內容管理和檔案處理
• 狀態層：系統狀態監控

2. 防重複執行機制

import time
current_time = time.time()
if hasattr(self.system_tools, '_last_word_operation_time'):
    time_diff = current_time - self.system_tools._last_word_operation_time
    if time_diff < 1.5:
        return "Word剛開啟過，請稍候..."

3. 智能內容流轉

# 時間戳追蹤
self.app_instance.last_generated_time = time.time()
self.app_instance.last_analysis_time = time.time()
self.app_instance.last_upload_time = time.time()

# 自動選擇最新內容
latest_time = max(gen_time, analysis_time, upload_time)

4. 容錯與自愈能力

• 格式錯誤自動修正：處理 LLM 輸出格式不正確
• 執行失敗自動重試：使用備用執行方法
• 智能錯誤恢復：從錯誤中提取有用信息

實際應用場景

文檔處理工作流

檔案上傳分析 → 檔案內容分析 → 將已生成內容寫入Word → 儲存Word文件

創意寫作工作流

內容生成工具 → 檢查內容狀態 → 將已生成內容寫入Word → 修改Word內容 → 儲存Word文件

專家分析工作流

檔案上傳分析 → (用戶指定分析類型) → 檔案內容分析 → 將已生成內容寫入Word

Agent 效能優化

執行控制參數

max_iterations=3,           # 防止無限循環
max_execution_time=30,      # 防止超時
early_stopping_method="generate"  # 早期停止策略

記憶體管理

# 清理舊的分析結果
if ("小說" in final_answer_part and "數學" not in final_answer_part):
    self.system_tools.last_analysis_result = ""

總結

Agent 初始化與工具註冊系統是整個智能助手的「指揮中心」，它：

• 統一管理 15 種智能工具，形成完整的功能生態系統
• 實現智能工具選擇，根據用戶意圖自動匹配最適合的工具
• 提供強大的容錯機制，確保系統在各種異常情況下都能正常運作
• 支援複雜工作流程，從簡單操作到多步驟任務處理

這個系統將分散的工具整合成一個有機的整體，讓 AI 助手真正具備了「思考」和「行動」的能力。

下一篇，我們將深入探討內容生成引擎，看看 AI 如何創作文章、故事與心得。

工具清單總覽