概觀

代理程式使用工具來執行特定任務或存取外部系統。

工具工作流程

Koog 框架為使用工具提供以下工作流程：

1. 建立自訂工具或使用內建工具之一。
2. 將工具新增至工具註冊表。
3. 將工具註冊表傳遞給代理程式。
4. 與代理程式一同使用工具。

可用的工具類型

Koog 框架中有三種類型的工具：

• 內建工具，為代理程式與使用者互動以及對話管理提供功能。有關詳細資訊，請參閱 內建工具。
• 基於註解的自訂工具，可讓您將函數作為工具暴露給 LLM。有關詳細資訊，請參閱 基於註解的工具。
• 自訂工具，可讓您控制工具參數、中繼資料、執行邏輯以及其註冊和呼叫方式。有關詳細資訊，請參閱 基於類別的工具。

工具註冊表

在代理程式中使用工具之前，您必須將其新增至工具註冊表。 工具註冊表管理代理程式可用的所有工具。

工具註冊表的主要功能：

• 組織工具。
• 支援合併多個工具註冊表。
• 提供依名稱或類型檢索工具的方法。

要了解更多資訊，請參閱 ToolRegistry。

以下是建立工具註冊表並將工具新增至其中的範例：

val toolRegistry = ToolRegistry {
    tool(SayToUser)
}

若要合併多個工具註冊表，請執行以下操作：

val firstToolRegistry = ToolRegistry {
    tool(FirstSampleTool)
}

val secondToolRegistry = ToolRegistry {
    tool(SecondSampleTool)
}

val newRegistry = firstToolRegistry + secondToolRegistry

將工具傳遞給代理程式

為了使代理程式能夠使用工具，您需要在建立代理程式時提供一個包含該工具的工具註冊表作為引數：

// Agent initialization
val agent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),
    systemPrompt = "You are a helpful assistant with strong mathematical skills.",
    llmModel = OpenAIModels.Chat.GPT4o,
    // Pass your tool registry to the agent
    toolRegistry = toolRegistry
)

呼叫工具

在您的代理程式程式碼中有數種呼叫工具的方式。建議的方法是使用代理程式環境中提供的方法，而不是直接呼叫工具，因為這可確保工具操作在代理程式環境中得到正確處理。

TIP

請確保您已在工具中實作正確的 錯誤處理 以防止代理程式失敗。

這些工具是在由 AIAgentLLMWriteSession 表示的特定會話上下文內呼叫的。 它提供了數種呼叫工具的方法，以便您可以：

• 呼叫帶有給定引數的工具。
• 依其名稱和給定引數呼叫工具。
• 依提供的工具類別和引數呼叫工具。
• 呼叫指定類型的工具，並帶有給定引數。
• 呼叫返回原始字串結果的工具。

有關更多詳細資訊，請參閱 API 參考。

平行工具呼叫

您還可以使用 toParallelToolCallsRaw 擴展函數來平行呼叫工具。例如：

@Serializable
data class Book(
    val title: String,
    val author: String,
    val description: String
) : ToolArgs

class BookTool() : SimpleTool<Book>() {
    companion object {
        const val NAME = "book"
    }

    override suspend fun doExecute(args: Book): String {
        println("${args.title} by ${args.author}:
 ${args.description}")
        return "Done"
    }

    override val argsSerializer: KSerializer<Book>
        get() = Book.serializer()

    override val descriptor: ToolDescriptor
        get() = ToolDescriptor(
            name = NAME,
            description = "A tool to parse book information from Markdown",
            requiredParameters = listOf(),
            optionalParameters = listOf()
        )
}

val strategy = strategy<Unit, Unit>("strategy-name") {

    /*...*/

    val myNode by node<Unit, Unit> { _ ->
        llm.writeSession {
            flow {
                emit(Book("Book 1", "Author 1", "Description 1"))
            }.toParallelToolCallsRaw(BookTool::class).collect()
        }
    }
}

從節點呼叫工具

當使用節點建立代理程式工作流程時，您可以使用特殊節點來呼叫工具：

• nodeExecuteTool：呼叫單一工具並返回其結果。有關詳細資訊，請參閱 API 參考。

• nodeExecuteSingleTool：呼叫帶有提供引數的特定工具。有關詳細資訊，請參閱 API 參考。

• nodeExecuteMultipleTools：執行多個工具呼叫並返回其結果。有關詳細資訊，請參閱 API 參考。

• nodeLLMSendToolResult：將工具結果發送給 LLM 並取得回應。有關詳細資訊，請參閱 API 參考。

• nodeLLMSendMultipleToolResults：將多個工具結果發送給 LLM。有關詳細資訊，請參閱 API 參考。

將代理程式作為工具使用

該框架提供將任何 AI 代理程式轉換為可供其他代理程式使用的工具的能力。 這項強大的功能可讓您建立分層代理程式架構，其中專業代理程式可以被更高層次的協調代理程式作為工具呼叫。

將代理程式轉換為工具

若要將代理程式轉換為工具，請使用 asTool() 擴展函數：

// Create a specialized agent
val analysisAgent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = "You are a financial analysis specialist.",
    toolRegistry = analysisToolRegistry
)

// Convert the agent to a tool
val analysisAgentTool = analysisAgent.asTool(
    agentName = "analyzeTransactions",
    agentDescription = "執行金融交易分析",
    inputDescriptor = ToolParameterDescriptor(
        name = "request",
        description = "交易分析請求",
        type = ToolParameterType.String
    )
)

在其他代理程式中使用代理程式工具

一旦轉換為工具，您可以將代理程式工具新增至另一個代理程式的工具註冊表：

// Create a coordinator agent that can use specialized agents as tools
val coordinatorAgent = AIAgent(
    promptExecutor = simpleOpenAIExecutor(apiKey),
    llmModel = OpenAIModels.Chat.GPT4o,
    systemPrompt = "You coordinate different specialized services.",
    toolRegistry = ToolRegistry {
        tool(analysisAgentTool)
        // Add other tools as needed
    }
)

代理程式工具執行

當呼叫代理程式工具時：

1. 引數會根據輸入描述符反序列化。
2. 封裝的代理程式會使用反序列化輸入來執行。
3. 代理程式的輸出會序列化並作為工具結果傳回。

將代理程式作為工具的好處

• 模組化：將複雜的工作流程分解為專業代理程式。
• 可重用性：在多個協調代理程式中重複使用相同的專業代理程式。
• 職責分離：每個代理程式都可以專注於其特定領域。