第一次學 Kotlin Koog AI 就上手 Day 06：調校你的 AI：深入解析 Agent 核心參數

val agent = AIAgent(
    executor = simpleOpenAIExecutor(apiKey),
    systemPrompt = "你是一個友善的 AI 助手",
    llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
)

suspend fun main() {
    // 測試問題：讓 AI 為新咖啡店想三個店名
    val question = "請為一家新開的咖啡店推薦三個店名"

    // 低溫度 Agent：保守、穩定的回應
    val conservativeAgent = AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = "你是一個專業的品牌顧問",
        temperature = 0.1, // 極低溫度，追求穩定性
        llmModel = OpenAIModels.Chat.GPT4_1mini
    )

    // 高溫度 Agent：創意、多樣的回應
    val creativeAgent = AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = "你是一個專業的品牌顧問",
        temperature = 1.2, // 高溫度，追求創造性
        llmModel = OpenAIModels.Chat.GPT4_1mini
    )

    println("=== 🔒 保守型 AI (Temperature: 0.1) ===")
    val conservativeResult = conservativeAgent.run(question)
    println(conservativeResult)

    println("\n=== 🎨 創意型 AI (Temperature: 1.2) ===")
    val creativeResult = creativeAgent.run(question)
    println(creativeResult)
}

// 場景 1：數學計算助手 - 需要精確性
fun createMathTutorAgent(): AIAgent {
    return AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = """
            你是一個數學老師，需要提供準確的數學解答。
            請一步一步解釋計算過程，確保答案的正確性。
        """.trimIndent(),
        temperature = 0.1, // 低溫度確保答案的一致性和準確性
        llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
    )
}

// 場景 2：創意寫作助手 - 需要想像力
fun createCreativeWriterAgent(): AIAgent {
    return AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = """
            你是一個富有想像力的創意寫作導師。
            幫助用戶發揮創意，提供多元化的寫作靈感和想法。
        """.trimIndent(),
        temperature = 1.0, // 高溫度激發創造力和多樣性
        llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
    )
}

// 場景 3：客服助手 - 需要平衡專業性與親和力
fun createCustomerServiceAgent(): AIAgent {
    return AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = """
            你是一個專業的客服助手，既要保持專業性
            又要展現親和力，為客戶提供有幫助的服務。
        """.trimIndent(),
        temperature = 0.6, // 中等溫度平衡穩定性和靈活性
        llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
    )
}

suspend fun demonstrateScenarios() {
    val mathAgent = createMathTutorAgent()
    val creativeAgent = createCreativeWriterAgent()
    val serviceAgent = createCustomerServiceAgent()

    println("=== 數學計算 (Temperature: 0.1) ===")
    println(mathAgent.run("請解釋 2x + 5 = 15 的解法"))

    println("\n=== 創意寫作 (Temperature: 1.0) ===")
    println(creativeAgent.run("請用「雨夜」作為主題，寫一個短故事的開頭"))

    println("\n=== 客服對話 (Temperature: 0.6) ===")
    println(serviceAgent.run("我的訂單還沒收到，能幫我查詢一下嗎？"))
}

=== 數學計算 (Temperature: 0.1) ===
當然可以！我們來一步一步解這個方程式：

方程式是：
\[ 2x + 5 = 15 \]

**步驟 1：將常數項移到等號右邊**
我們想把含有 \( x \) 的項留在左邊，常數項移到右邊。
所以從兩邊都減去 5：
\[ 2x + 5 - 5 = 15 - 5 \]
簡化後：
\[ 2x = 10 \]

**步驟 2：將 \( x \) 的係數消掉**
現在 \( 2x = 10 \)，我們要讓 \( x \) 單獨在左邊。
因為 \( x \) 乘以 2，所以兩邊同時除以 2：
\[ \frac{2x}{2} = \frac{10}{2} \]
簡化後：
\[ x = 5 \]

**答案：**
\[ x = 5 \]

你可以把 \( x = 5 \) 代回原方程式驗證：
\[ 2(5) + 5 = 10 + 5 = 15 \]，等式成立，解答正確。

=== 創意寫作 (Temperature: 1.0) ===
雨夜，城市的燈光在濕漉漉的街道上拉長了影子，像是無數跳動的心跳。林雨走在窄巷中，手中的傘早已被風雨打得歪斜，身旁的水窪倒映出遠處那座老舊鐘樓的輪廓。她感覺身後有人跟著，但每當她回頭，雨幕中只有模糊的黑影與滴落的水珠。這個雨夜，似乎藏著某個秘密，等待著她去揭開……

=== 客服對話 (Temperature: 0.6) ===
您好，感謝您的聯繫！請您提供訂單號碼或下單時使用的姓名和聯絡電話，這樣我可以幫您查詢訂單狀態，盡快為您解決問題。期待您的回覆！

=== 數學計算 (Temperature: 0.1) ===
當然可以！我們來一步一步解這個方程式：

方程式是：
\[ 2x + 5 = 15 \]

**目標**：找出 \( x \) 的值。

---

### 第一步：將方程式中的常數移到等號另一邊

我們想把含有 \( x \) 的項目單獨留在等號一邊，先把 +5 移到右邊。
因為 +5 在左邊，我們用減法來消掉它：
\[ 2x + 5 - 5 = 15 - 5 \]
簡化後：
\[ 2x = 10 \]

---

### 第二步：將 \( x \) 的係數消掉

現在方程式是：
\[ 2x = 10 \]

因為 \( x \) 被乘以 2，我們用除法來消掉 2：
\[ \frac{2x}{2} = \frac{10}{2} \]
簡化後：
\[ x = 5 \]

---

### 答案：

\[ x = 5 \]

---

### 驗證：

把 \( x = 5 \) 代回原方程式：
\[ 2(5) + 5 = 10 + 5 = 15 \]
等式成立，答案正確。

---

如果還有其他問題，歡迎隨時問我！

=== 創意寫作 (Temperature: 1.0) ===
雨夜，城市彷彿陷入了一場靜謐的夢魘。街燈被無盡的雨絲模糊，點點燈光如同迷離的眼睛，注視著孤獨行走在街角的她。每一步鞋跟敲擊著濕滑的人行道，迴響在空蕩的巷弄裡，彷彿在訴說著一段誰也未曾聽過的秘密。今晚，雨水不僅洗刷著城市的塵埃，也悄悄揭開了一個深藏已久的謎團……

=== 客服對話 (Temperature: 0.6) ===
您好，感謝您的聯繫！為了幫您查詢訂單狀態，請您提供一下訂單號碼或下單時使用的姓名和電話號碼，這樣我能更快幫您確認。期待您的回覆！

suspend fun demonstrateMaxIterations() {
    val toolRegistry = ToolRegistry {
        tool(SayToUser)
    }

    // 設定較少的迭代次數 - 適合簡單任務
    val quickAgent = AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = """
            你是一個快速回應助手。收到問題後，直接給出簡潔的答案，
            不需要過度思考或使用工具。
        """.trimIndent(),
        toolRegistry = toolRegistry,
        maxIterations = 30, // 最多 30 個步驟
        llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
    )

    // 設定較多的迭代次數 - 適合需要深度思考的任務
    val thoughtfulAgent = AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        systemPrompt = """
            你是一個深思熟慮的助手。對於複雜問題，你會：
            1. 先用 SayToUser 說明你的思考過程
            2. 分析問題的不同面向
            3. 最後提供完整的建議
        """.trimIndent(),
        toolRegistry = toolRegistry,
        maxIterations = 100, // 允許更多思考步驟
        llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
    )

    val question = "如何提升工作效率？"

    println("=== ⚡ 快速回應模式 (MaxIterations: 30) ===")
    quickAgent.run(question)

    println("\n=== 🤔 深度思考模式 (MaxIterations: 100) ===")
    thoughtfulAgent.run(question)
}

=== ⚡ 快速回應模式 (MaxIterations: 30) ===
Agent says: 提升工作效率的方法包括：
1. 制定明確目標和計劃。
2. 使用待辦事項清單管理任務。
3. 避免多工，專注完成一件事。
4. 利用時間區塊安排工作。
5. 消除干擾，如關閉不必要通知。
6. 定期休息，保持精神集中。
7. 利用工具和軟體提升自動化和協作。
8. 持續學習和優化工作流程。

=== 🤔 深度思考模式 (MaxIterations: 100) ===
Agent says: 提升工作效率是一個涉及多個層面的問題，我會先分析不同方法的利弊，然後提供一套具體可行的建議。
Agent says: 提升工作效率可以從時間管理、工作環境、工具運用、工作習慣和心理狀態等方面入手。我將分別說明這些面向，並給出相應的建議。
Agent says: 1. 時間管理：建立明確的工作計劃，運用番茄工作法等技術，避免拖延。
Agent says: 2. 工作環境：保持工作空間整潔，避免干擾，營造專注的氛圍。
Agent says: 3. 工具運用：善用各類效率工具，如日程管理軟體、任務追蹤工具和自動化工具。
Agent says: 4. 工作習慣：養成專注、有效率的工作習慣，例如分段工作、定期休息、設定優先順序。
Agent says: 5. 心理狀態：保持積極心態，適當減壓，培養動力和耐心面對挑戰。

Exception in thread "main" ai.koog.agents.core.agent.AIAgentMaxNumberOfIterationsReachedException: AI Agent has run into a problem: Agent couldn't finish in given number of steps (3). Please, consider increasing `maxAgentIterations` value in agent's configuration

data class AgentProfile(
    val name: String,
    val temperature: Double,
    val maxIterations: Int,
    val description: String
)

// 預設的 Agent 配置檔案
val agentProfiles = mapOf(
    "calculator" to AgentProfile(
        name = "計算專家",
        temperature = 0.1,
        maxIterations = 30,
        description = "精確計算，不需要複雜思考"
    ),
    "advisor" to AgentProfile(
        name = "商業顧問",
        temperature = 0.4,
        maxIterations = 40,
        description = "需要分析但保持專業"
    ),
    "creative" to AgentProfile(
        name = "創意夥伴",
        temperature = 1.1,
        maxIterations = 50,
        description = "發揮創意，允許深度發想"
    )
)

fun createOptimizedAgent(profileKey: String): AIAgent {
    val profile = agentProfiles[profileKey]
        ?: error("未知的 Agent 類型: $profileKey")

    return AIAgent(
        executor = simpleOpenAIExecutor(ApiKeyManager.openAIKey),
        toolRegistry = ToolRegistry {
            tool(SayToUser)
        },
        systemPrompt = """
            你是一個${profile.name}，專門提供${profile.description}的服務。
            請根據你的專業特性回應用戶的請求。
        """.trimIndent(),
        temperature = profile.temperature,
        maxIterations = profile.maxIterations,
        llmModel = OpenAIModels.CostOptimized.GPT4_1Mini
    )
}

suspend fun main() {
    println("=== 🧮 計算專家 (溫度: 0.1, 迭代: 30) ===")
    val calculatorAgent = createOptimizedAgent("calculator")
    calculatorAgent.run("計算 25% 的 360 是多少？")

    println("\n=== 💼 商業顧問 (溫度: 0.4, 迭代: 40) ===")
    val advisorAgent = createOptimizedAgent("advisor")
    advisorAgent.run("小型餐廳如何增加客流量？")

    println("\n=== 🎨 創意夥伴 (溫度: 1.1, 迭代: 50) ===")
    val creativeAgent = createOptimizedAgent("creative")
    creativeAgent.run("為環保主題設計一個有趣的廣告標語")
}

=== 🧮 計算專家 (溫度: 1, 迭代: 30) ===
Agent says: 25% 的 360 是 90。

=== 💼 商業顧問 (溫度: 0.4, 迭代: 40) ===
Agent says: 小型餐廳增加客流量可以從多方面著手，以下是一些建議：

1. 提升餐品質與服務：確保食物美味且服務周到，讓顧客願意回訪並推薦給他人。
2. 社群媒體行銷：利用Facebook、Instagram等平台發布吸引人的餐點照片和促銷活動，增加曝光度。
3. 舉辦主題活動：如美食節、特價日、會員專屬活動，吸引不同客群。
4. 合作推廣：與附近商家或外送平台合作，擴大客源。
5. 優惠促銷：推出折扣、套餐或集點活動，吸引新客和回頭客。
6. 改善用餐環境：營造舒適氛圍，讓顧客有良好用餐體驗。

如果需要，我可以針對某一方面提供更詳細的策略與執行建議。

=== 🎨 創意夥伴 (溫度: 1.1, 迭代: 50) ===
Agent says: 「愛地球，從我做起，讓綠色成為未來的主色調！」這是一個有趣且富有啟發性的環保廣告標語，您覺得如何？如果需要，我也可以提供更多不同風格的選擇！

// 根據任務特性選擇適當的溫度
fun getRecommendedTemperature(taskType: String): Double {
    return when (taskType) {
        "calculation", "factual" -> 0.1 // 需要精確性
        "analysis", "explanation" -> 0.4 // 需要邏輯但保持靈活
        "conversation", "advice" -> 0.7 // 平衡專業與親和
        "creative", "brainstorm" -> 1.0 // 需要創意和多樣性
        else -> 0.6                     // 通用設定
    }
}

// 根據任務複雜度設定迭代次數
fun getRecommendedIterations(complexity: String): Int {
    return when (complexity) {
        "simple" -> 30     // 簡單問答的安全最低值
        "moderate" -> 40   // 一般業務邏輯
        "complex" -> 60    // 需要深度分析
        else -> 50         // 通用設定（預設值）
    }
}