블로그 | 모하지?

원문: Koog Documentation — tools-overview 이 글은 Koog 공식 문서의 tools-overview 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

개요

에이전트는 도구를 사용하여 특정 작업을 수행하거나 외부 시스템에 액세스합니다.

도구 작업 흐름

Koog 프레임워크는 Kotlin 및 Java 도구 작업을 위해 다음과 같은 워크플로를 제공합니다.

사용자 정의 도구를 만들거나 내장된 도구 중 하나를 사용하세요.
도구 레지스트리에 도구를 추가합니다.
도구 레지스트리를 에이전트에 전달합니다.
에이전트와 함께 도구를 사용하십시오.

사용 가능한 도구 유형

Koog 프레임워크에는 세 가지 유형의 도구가 있습니다.

에이전트-사용자 상호 작용 및 대화 관리를 위한 기능을 제공하는 기본 제공 도구입니다. 자세한 내용은 Built-in tools을 참조하세요.
기능을 LLM에 도구로 노출할 수 있는 주석 기반 사용자 정의 도구입니다. 자세한 내용은 Annotation-based tools을 참조하세요.
도구 매개변수, 메타데이터, 실행 논리, 등록 및 호출 방법을 제어할 수 있는 사용자 정의 도구입니다. 자세한 내용은 [클래스 기반 도구](클래스 기반-tools.md).

도구 레지스트리

에이전트에서 도구를 사용하려면 먼저 도구 레지스트리에 도구를 추가해야 합니다. 도구 레지스트리는 에이전트에서 사용할 수 있는 모든 도구를 관리합니다.

도구 레지스트리의 주요 기능:

도구를 정리합니다.
여러 도구 레지스트리의 병합을 지원합니다.
이름이나 유형별로 도구를 검색하는 메서드를 제공합니다.

자세한 내용은 ToolRegistry을 참조하세요.

다음은 도구 레지스트리를 생성하고 여기에 도구를 추가하는 방법의 예입니다.

코틀린

1val toolRegistry = ToolRegistry {2    tools(myTool)3}

자바

1// Create an instance of your ToolSet2MyToolSet myTool = new MyToolSet();34// Build the ToolRegistry and register tools from the ToolSet5ToolRegistry toolRegistry = ToolRegistry.builder()6    .tools(myTool)7    .build();

여러 도구 레지스트리를 병합하려면 다음을 수행하십시오.

코틀린

1val firstToolRegistry = ToolRegistry {2    tools(firstSampleTool)3}45val secondToolRegistry = ToolRegistry {6    tools(secondSampleTool)7}89val newRegistry = firstToolRegistry + secondToolRegistry

자바

1// Create instances of your ToolSets2FirstToolSet firstSampleTool = new FirstToolSet();3SecondToolSet secondSampleTool = new SecondToolSet();45// Build separate tool registries6ToolRegistry firstToolRegistry = ToolRegistry.builder()7    .tools(firstSampleTool)8    .build();910ToolRegistry secondToolRegistry = ToolRegistry.builder()11    .tools(secondSampleTool)12    .build();1314ToolRegistry newRegistry = firstToolRegistry.plus(secondToolRegistry);

에이전트에게 도구 전달

에이전트가 도구를 사용할 수 있도록 하려면 에이전트를 생성할 때 이 도구를 인수로 포함하는 도구 레지스트리를 제공해야 합니다.

코틀린

1// Agent initialization2val agent = AIAgent(3    promptExecutor = simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")),4    systemPrompt = "You are a helpful assistant with strong mathematical skills.",5    llmModel = OpenAIModels.Chat.GPT4o,6    // Pass your tool registry to the agent7    toolRegistry = toolRegistry8)

자바

1AIAgent<String, String> agent = AIAgent.builder()2    .promptExecutor(simpleOpenAIExecutor(System.getenv("OPENAI_API_KEY")))3    .systemPrompt("You are a helpful assistant with strong mathematical skills.")4    .llmModel(OpenAIModels.Chat.GPT4o)5    .toolRegistry(ToolRegistry.builder()6        .tools(secondSampleTool)7        .build()8    )9    .build();

호출 도구

에이전트 코드 내에서 도구를 호출하는 방법에는 여러 가지가 있습니다. 권장되는 접근 방식은 제공된 방법을 사용하는 것입니다. 도구를 직접 호출하는 대신 에이전트 컨텍스트에서 이를 통해 에이전트 내에서 도구 작업을 적절하게 처리할 수 있습니다. 에이전트 환경.

참고 에이전트 오류를 방지하려면 도구에 적절한 error handling을 구현했는지 확인하세요.

도구는 AIAgentLLMWriteSession으로 표시되는 특정 세션 컨텍스트 내에서 호출됩니다. 다음과 같은 작업을 수행할 수 있도록 도구를 호출하는 여러 가지 방법을 제공합니다.

주어진 인수로 도구를 호출합니다.
이름과 주어진 인수로 도구를 호출합니다.
제공된 도구 클래스 및 인수로 도구를 호출합니다.
주어진 인수를 사용하여 지정된 유형의 도구를 호출합니다.
원시 문자열 결과를 반환하는 도구를 호출합니다.

자세한 내용은 AIAgentLLMWriteSession에 대한 API 참조를 참조하세요.

병렬 도구 호출

toParallelToolCallsRaw 확장을 사용하여 도구를 병렬로 호출할 수도 있습니다. 예를 들어:

코틀린

1@Serializable2data class Book(3    val title: String,4    val author: String,5    val description: String6)78class BookTool() : SimpleTool<Book>(9    argsType = typeToken<Book>(),10    name = NAME,11    description = "A tool to parse book information from Markdown"12) {13    companion object {14        const val NAME = "book"15    }1617    override suspend fun execute(args: Book): String {18        println("${args.title} by ${args.author}:\n ${args.description}")19        return "Done"20    }21}2223val strategy = strategy<Unit, Unit>("strategy-name") {2425    /*...*/2627    val myNode by node<Unit, Unit> { _ ->28        llm.writeSession {29            flow {30                emit(Book("Book 1", "Author 1", "Description 1"))31            }.toParallelToolCallsRaw(BookTool::class).collect()32        }33    }34}35

자바

노드에서 도구 호출

노드로 에이전트 워크플로를 구축할 때 특수 노드를 사용하여 도구를 호출할 수 있습니다.

nodeExecuteTool: 단일 도구 호출을 호출하고 그 결과를 반환합니다. 자세한 내용은 API reference을 참조하세요.
제공된 인수를 사용하여 특정 도구를 호출하는 nodeExecuteSingleTool 자세한 내용은 API reference을 참조하세요.
여러 도구 호출을 수행하고 결과를 반환하는 nodeExecuteMultipleTools 자세한 내용은 API reference을 참조하세요.
nodeLLMSendToolResult는 도구 결과를 LLM에 보내고 응답을 받습니다. 자세한 내용은 API reference을 참조하세요.
nodeLLMSendMultipleToolResults는 여러 도구 결과를 LLM으로 보냅니다. 자세한 내용은 API reference을 참조하세요.

1// Create a specialized agent service, responsible for creating financial analysis agents.2val analysisAgentService = AIAgentService(3    promptExecutor = simpleOpenAIExecutor(apiKey),4    llmModel = OpenAIModels.Chat.GPT4o,5    systemPrompt = "You are a financial analysis specialist.",6    toolRegistry = analysisToolRegistry7)89// Create a tool that would run financial analysis agent once called.10val analysisAgentTool = analysisAgentService.createAgentTool(11    agentName = "analyzeTransactions",12    agentDescription = "Performs financial transaction analysis",13    inputDescription = "Transaction analysis request",14    inputType = typeToken<String>(),15)

1// Create a coordinator agent that can use specialized agents as tools2val coordinatorAgent = AIAgent(3    promptExecutor = simpleOpenAIExecutor(apiKey),4    llmModel = OpenAIModels.Chat.GPT4o,5    systemPrompt = "You coordinate different specialized services.",6    toolRegistry = ToolRegistry {7        tool(analysisAgentTool)8        // Add other tools as needed9    }10)

자바

에이전트 도구 실행

에이전트 도구가 호출되면:

인수는 입력 설명자에 따라 역직렬화됩니다.
래핑된 에이전트는 역직렬화된 입력으로 실행됩니다.
에이전트의 출력은 직렬화되어 도구 결과로 반환됩니다.

도구로서의 에이전트의 이점

모듈화: 복잡한 워크플로를 전문 에이전트로 분리합니다.
재사용성: 여러 코디네이터 에이전트에서 동일한 특수 에이전트를 사용합니다.
관심사 분리: 각 에이전트는 특정 도메인에 집중할 수 있습니다.

개요

개요