Koog를 활용한 AI 뱅킹 어시스턴트 구축하기
이 튜토리얼에서는 Kotlin에서 Koog 에이전트를 사용하여 소형 뱅킹 어시스턴트를 구축해 보겠습니다. 다음 내용을 배우게 됩니다:
- 도메인 모델 및 샘플 데이터 정의
- 송금 및 거래 분석을 위한 기능 중심 도구 노출
- 사용자 의도 분류 (송금 vs 분석)
- 두 가지 스타일의 호출 오케스트레이션:
- 그래프/서브그래프 전략
- “도구로서의 에이전트(agents as tools)”
완료하고 나면, 자유 형식의 사용자 요청을 올바른 도구로 라우팅하고 도움이 되며 감사가 가능한 응답을 생성할 수 있게 됩니다.
설정 및 의존성
Kotlin Notebook 커널을 사용합니다. Koog 아티팩트가 Maven Central에서 확인 가능한지, 그리고 LLM 제공자 키가 OPENAI_API_KEY 환경 변수를 통해 사용 가능한지 확인하세요.
kotlin
%useLatestDescriptors
%use datetime
// Maven Central의 koog를 사용하려면 이 주석을 해제하세요
// %use koogkotlin
import ai.koog.prompt.executor.llms.all.simpleOpenAIExecutor
val apiKey = System.getenv("OPENAI_API_KEY") ?: error("Please set OPENAI_API_KEY environment variable")
val openAIExecutor = simpleOpenAIExecutor(apiKey)시스템 프롬프트 정의
잘 작성된 시스템 프롬프트는 AI가 자신의 역할과 제약 사항을 이해하는 데 도움이 됩니다. 이 프롬프트는 모든 에이전트의 동작을 가이드합니다.
kotlin
val bankingAssistantSystemPrompt = """
|You are a banking assistant interacting with a user (userId=123).
|Your goal is to understand the user's request and determine whether it can be fulfilled using the available tools.
|
|If the task can be accomplished with the provided tools, proceed accordingly,
|at the end of the conversation respond with: "Task completed successfully."
|If the task cannot be performed with the tools available, respond with: "Can't perform the task."
""".trimMargin()도메인 모델 및 샘플 데이터
먼저, 도메인 모델과 샘플 데이터를 정의해 보겠습니다. 직렬화(serialization)를 지원하는 Kotlin의 데이터 클래스를 사용합니다.
kotlin
import kotlinx.serialization.Serializable
@Serializable
data class Contact(
val id: Int,
val name: String,
val surname: String? = null,
val phoneNumber: String
)
val contactList = listOf(
Contact(100, "Alice", "Smith", "+1 415 555 1234"),
Contact(101, "Bob", "Johnson", "+49 151 23456789"),
Contact(102, "Charlie", "Williams", "+36 20 123 4567"),
Contact(103, "Daniel", "Anderson", "+46 70 123 45 67"),
Contact(104, "Daniel", "Garcia", "+34 612 345 678"),
)
val contactById = contactList.associateBy(Contact::id)도구: 송금
도구는 순수(pure)하고 예측 가능해야 합니다.
두 가지 "소프트 계약(soft contracts)"을 모델링합니다:
chooseRecipient는 모호함이 감지될 때 후보군을 반환합니다.sendMoney는confirmed플래그를 지원합니다.false인 경우, 에이전트에게 사용자에게 확인을 요청하도록 요구합니다.
kotlin
import ai.koog.agents.core.tools.annotations.LLMDescription
import ai.koog.agents.core.tools.annotations.Tool
import ai.koog.agents.core.tools.reflect.ToolSet
@LLMDescription("Tools for money transfer operations.")
class MoneyTransferTools : ToolSet {
@Tool
@LLMDescription(
"""
Returns the list of contacts for the given user.
The user in this demo is always userId=123.
"""
)
fun getContacts(
@LLMDescription("The unique identifier of the user whose contact list is requested.") userId: Int
): String = buildString {
contactList.forEach { c ->
appendLine("${c.id}: ${c.name} ${c.surname ?: ""} (${c.phoneNumber})")
}
}.trimEnd()
@Tool
@LLMDescription("Returns the current balance (demo value).")
fun getBalance(
@LLMDescription("The unique identifier of the user.") userId: Int
): String = "Balance: 200.00 EUR"
@Tool
@LLMDescription("Returns the default user currency (demo value).")
fun getDefaultCurrency(
@LLMDescription("The unique identifier of the user.") userId: Int
): String = "EUR"
@Tool
@LLMDescription("Returns a demo FX rate between two ISO currencies (e.g. EUR→USD).")
fun getExchangeRate(
@LLMDescription("Base currency (e.g., EUR).") from: String,
@LLMDescription("Target currency (e.g., USD).") to: String
): String = when (from.uppercase() to to.uppercase()) {
"EUR" to "USD" -> "1.10"
"EUR" to "GBP" -> "0.86"
"GBP" to "EUR" -> "1.16"
"USD" to "EUR" -> "0.90"
else -> "No information about exchange rate available."
}
@Tool
@LLMDescription(
"""
Returns a ranked list of possible recipients for an ambiguous name.
The agent should ask the user to pick one and then use the selected contact id.
"""
)
fun chooseRecipient(
@LLMDescription("An ambiguous or partial contact name.") confusingRecipientName: String
): String {
val matches = contactList.filter { c ->
c.name.contains(confusingRecipientName, ignoreCase = true) ||
(c.surname?.contains(confusingRecipientName, ignoreCase = true) ?: false)
}
if (matches.isEmpty()) {
return "No candidates found for '$confusingRecipientName'. Use getContacts and ask the user to choose."
}
return matches.mapIndexed { idx, c ->
"${idx + 1}. ${c.id}: ${c.name} ${c.surname ?: ""} (${c.phoneNumber})"
}.joinToString("
")
}
@Tool
@LLMDescription(
"""
Sends money from the user to a contact.
If confirmed=false, return "REQUIRES_CONFIRMATION" with a human-readable summary.
The agent should confirm with the user before retrying with confirmed=true.
"""
)
fun sendMoney(
@LLMDescription("Sender user id.") senderId: Int,
@LLMDescription("Amount in sender's default currency.") amount: Double,
@LLMDescription("Recipient contact id.") recipientId: Int,
@LLMDescription("Short purpose/description.") purpose: String,
@LLMDescription("Whether the user already confirmed this transfer.") confirmed: Boolean = false
): String {
val recipient = contactById[recipientId] ?: return "Invalid recipient."
val summary = "Transfer €%.2f to %s %s (%s) for \"%s\"."
.format(amount, recipient.name, recipient.surname ?: "", recipient.phoneNumber, purpose)
if (!confirmed) {
return "REQUIRES_CONFIRMATION: $summary"
}
// 실제 시스템에서는 여기서 결제 API를 호출합니다.
return "Money was sent. $summary"
}
}첫 번째 에이전트 만들기
이제 송금 도구를 사용하는 에이전트를 만들어 보겠습니다. 에이전트는 작업을 완수하기 위해 LLM과 도구를 결합합니다.
kotlin
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.AIAgentService
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.core.tools.reflect.asTools
import ai.koog.agents.ext.tool.AskUser
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import kotlinx.coroutines.runBlocking
val transferAgentService = AIAgentService(
executor = openAIExecutor,
llmModel = OpenAIModels.Chat.GPT4oMini,
systemPrompt = bankingAssistantSystemPrompt,
temperature = 0.0, // 금융 작업을 위해 결정론적 응답 사용
toolRegistry = ToolRegistry {
tool(AskUser)
tools(MoneyTransferTools().asTools())
}
)
// 다양한 시나리오로 에이전트 테스트
println("Banking Assistant started")
val message = "Send 25 euros to Daniel for dinner at the restaurant."
// 시도해 볼 수 있는 다른 테스트 메시지:
// - "Send 50 euros to Alice for the concert tickets"
// - "What's my current balance?"
// - "Transfer 100 euros to Bob for the shared vacation expenses"
runBlocking {
val result = transferAgentService.createAgentAndRun(message)
result
}Banking Assistant started
There are two contacts named Daniel. Please confirm which one you would like to send money to:
1. Daniel Anderson (+46 70 123 45 67)
2. Daniel Garcia (+34 612 345 678)
Please confirm the transfer of €25.00 to Daniel Garcia (+34 612 345 678) for "Dinner at the restaurant".
Task completed successfully.
거래 분석 기능 추가
거래 분석 도구를 추가하여 어시스턴트의 기능을 확장해 보겠습니다. 먼저 거래 도메인 모델을 정의합니다.
kotlin
@Serializable
enum class TransactionCategory(val title: String) {
FOOD_AND_DINING("Food & Dining"),
SHOPPING("Shopping"),
TRANSPORTATION("Transportation"),
ENTERTAINMENT("Entertainment"),
GROCERIES("Groceries"),
HEALTH("Health"),
UTILITIES("Utilities"),
HOME_IMPROVEMENT("Home Improvement");
companion object {
fun fromString(value: String): TransactionCategory? =
entries.find { it.title.equals(value, ignoreCase = true) }
fun availableCategories(): String =
entries.joinToString(", ") { it.title }
}
}
@Serializable
data class Transaction(
val merchant: String,
val amount: Double,
val category: TransactionCategory,
val date: LocalDateTime
)샘플 거래 데이터
kotlin
val transactionAnalysisPrompt = """
Today is 2025-05-22.
Available categories for transactions: ${TransactionCategory.availableCategories()}
"""
val sampleTransactions = listOf(
Transaction("Starbucks", 5.99, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 22, 8, 30, 0, 0)),
Transaction("Amazon", 129.99, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 22, 10, 15, 0, 0)),
Transaction(
"Shell Gas Station",
45.50,
TransactionCategory.TRANSPORTATION,
LocalDateTime(2025, 5, 21, 18, 45, 0, 0)
),
Transaction("Netflix", 15.99, TransactionCategory.ENTERTAINMENT, LocalDateTime(2025, 5, 21, 12, 0, 0, 0)),
Transaction("AMC Theaters", 32.50, TransactionCategory.ENTERTAINMENT, LocalDateTime(2025, 5, 20, 19, 30, 0, 0)),
Transaction("Whole Foods", 89.75, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 20, 16, 20, 0, 0)),
Transaction("Target", 67.32, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 20, 14, 30, 0, 0)),
Transaction("CVS Pharmacy", 23.45, TransactionCategory.HEALTH, LocalDateTime(2025, 5, 19, 11, 25, 0, 0)),
Transaction("Subway", 12.49, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 19, 13, 15, 0, 0)),
Transaction("Spotify Premium", 9.99, TransactionCategory.ENTERTAINMENT, LocalDateTime(2025, 5, 19, 14, 15, 0, 0)),
Transaction("AT&T", 85.00, TransactionCategory.UTILITIES, LocalDateTime(2025, 5, 18, 9, 0, 0, 0)),
Transaction("Home Depot", 156.78, TransactionCategory.HOME_IMPROVEMENT, LocalDateTime(2025, 5, 18, 15, 45, 0, 0)),
Transaction("Amazon", 129.99, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 17, 10, 15, 0, 0)),
Transaction("Starbucks", 5.99, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 17, 8, 30, 0, 0)),
Transaction("Whole Foods", 89.75, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 16, 16, 20, 0, 0)),
Transaction("CVS Pharmacy", 23.45, TransactionCategory.HEALTH, LocalDateTime(2025, 5, 15, 11, 25, 0, 0)),
Transaction("AT&T", 85.00, TransactionCategory.UTILITIES, LocalDateTime(2025, 5, 14, 9, 0, 0, 0)),
Transaction("Xbox Game Pass", 14.99, TransactionCategory.ENTERTAINMENT, LocalDateTime(2025, 5, 14, 16, 45, 0, 0)),
Transaction("Aldi", 76.45, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 13, 17, 30, 0, 0)),
Transaction("Chipotle", 15.75, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 13, 12, 45, 0, 0)),
Transaction("Best Buy", 299.99, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 12, 14, 20, 0, 0)),
Transaction("Olive Garden", 89.50, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 12, 19, 15, 0, 0)),
Transaction("Whole Foods", 112.34, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 11, 10, 30, 0, 0)),
Transaction("Old Navy", 45.99, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 11, 13, 45, 0, 0)),
Transaction("Panera Bread", 18.25, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 10, 11, 30, 0, 0)),
Transaction("Costco", 245.67, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 10, 15, 20, 0, 0)),
Transaction("Five Guys", 22.50, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 9, 18, 30, 0, 0)),
Transaction("Macy's", 156.78, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 9, 14, 15, 0, 0)),
Transaction("Hulu Plus", 12.99, TransactionCategory.ENTERTAINMENT, LocalDateTime(2025, 5, 8, 20, 0, 0, 0)),
Transaction("Whole Foods", 94.23, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 8, 16, 45, 0, 0)),
Transaction("Texas Roadhouse", 78.90, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 8, 19, 30, 0, 0)),
Transaction("Walmart", 167.89, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 7, 11, 20, 0, 0)),
Transaction("Chick-fil-A", 14.75, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 7, 12, 30, 0, 0)),
Transaction("Aldi", 82.45, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 6, 15, 45, 0, 0)),
Transaction("TJ Maxx", 67.90, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 6, 13, 20, 0, 0)),
Transaction("P.F. Chang's", 95.40, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 5, 19, 15, 0, 0)),
Transaction("Whole Foods", 78.34, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 4, 14, 30, 0, 0)),
Transaction("H&M", 89.99, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 3, 16, 20, 0, 0)),
Transaction("Red Lobster", 112.45, TransactionCategory.FOOD_AND_DINING, LocalDateTime(2025, 5, 2, 18, 45, 0, 0)),
Transaction("Whole Foods", 67.23, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 2, 11, 30, 0, 0)),
Transaction("Marshalls", 123.45, TransactionCategory.SHOPPING, LocalDateTime(2025, 5, 1, 15, 20, 0, 0)),
Transaction(
"Buffalo Wild Wings",
45.67,
TransactionCategory.FOOD_AND_DINING,
LocalDateTime(2025, 5, 1, 19, 30, 0, 0)
),
Transaction("Aldi", 145.78, TransactionCategory.GROCERIES, LocalDateTime(2025, 5, 1, 10, 15, 0, 0))
)거래 분석 도구
kotlin
@LLMDescription("Tools for analyzing transaction history")
class TransactionAnalysisTools : ToolSet {
@Tool
@LLMDescription(
"""
Retrieves transactions filtered by userId, category, start date, and end date.
All parameters are optional. If no parameters are provided, all transactions are returned.
Dates should be in the format YYYY-MM-DD.
"""
)
fun getTransactions(
@LLMDescription("The ID of the user whose transactions to retrieve.")
userId: String? = null,
@LLMDescription("The category to filter transactions by (e.g., 'Food & Dining').")
category: String? = null,
@LLMDescription("The start date to filter transactions by, in the format YYYY-MM-DD.")
startDate: String? = null,
@LLMDescription("The end date to filter transactions by, in the format YYYY-MM-DD.")
endDate: String? = null
): String {
var filteredTransactions = sampleTransactions
// userId 검증 (프로덕션 환경에서는 실제 데이터베이스를 쿼리함)
if (userId != null && userId != "123") {
return "No transactions found for user $userId."
}
// 카테고리 필터 적용
category?.let { cat ->
val categoryEnum = TransactionCategory.fromString(cat)
?: return "Invalid category: $cat. Available: ${TransactionCategory.availableCategories()}"
filteredTransactions = filteredTransactions.filter { it.category == categoryEnum }
}
// 날짜 범위 필터 적용
startDate?.let { date ->
val startDateTime = parseDate(date, startOfDay = true)
filteredTransactions = filteredTransactions.filter { it.date >= startDateTime }
}
endDate?.let { date ->
val endDateTime = parseDate(date, startOfDay = false)
filteredTransactions = filteredTransactions.filter { it.date <= endDateTime }
}
if (filteredTransactions.isEmpty()) {
return "No transactions found matching the specified criteria."
}
return filteredTransactions.joinToString("
") { transaction ->
"${transaction.date}: ${transaction.merchant} - " +
"${transaction.amount} (${transaction.category.title})"
}
}
@Tool
@LLMDescription("Calculates the sum of an array of double numbers.")
fun sumArray(
@LLMDescription("Comma-separated list of double numbers to sum (e.g., '1.5,2.3,4.7').")
numbers: String
): String {
val numbersList = numbers.split(",")
.mapNotNull { it.trim().toDoubleOrNull() }
val sum = numbersList.sum()
return "Sum: $%.2f".format(sum)
}
// 날짜 파싱을 위한 헬퍼 함수
private fun parseDate(dateStr: String, startOfDay: Boolean): LocalDateTime {
val parts = dateStr.split("-").map { it.toInt() }
require(parts.size == 3) { "Invalid date format. Use YYYY-MM-DD" }
return if (startOfDay) {
LocalDateTime(parts[0], parts[1], parts[2], 0, 0, 0, 0)
} else {
LocalDateTime(parts[0], parts[1], parts[2], 23, 59, 59, 999999999)
}
}
}kotlin
val analysisAgentService = AIAgentService(
executor = openAIExecutor,
llmModel = OpenAIModels.Chat.GPT4oMini,
systemPrompt = "$bankingAssistantSystemPrompt
$transactionAnalysisPrompt",
temperature = 0.0,
toolRegistry = ToolRegistry {
tools(TransactionAnalysisTools().asTools())
}
)
println("Transaction Analysis Assistant started")
val analysisMessage = "How much have I spent on restaurants this month?"
// 시도해 볼 수 있는 다른 쿼리:
// - "What's my maximum check at a restaurant this month?"
// - "How much did I spend on groceries in the first week of May?"
// - "What's my total spending on entertainment in May?"
// - "Show me all transactions from last week"
runBlocking {
val result = analysisAgentService.createAgentAndRun(analysisMessage)
result
}Transaction Analysis Assistant started
You have spent a total of $517.64 on restaurants this month.
Task completed successfully.
그래프를 사용한 에이전트 구축
이제 전문화된 에이전트들을 그래프 에이전트로 결합하여 요청을 적절한 핸들러로 라우팅할 수 있도록 만들어 보겠습니다.
요청 분류
먼저, 들어오는 요청을 분류할 방법이 필요합니다:
kotlin
import ai.koog.agents.core.tools.annotations.LLMDescription
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
@Suppress("unused")
@SerialName("UserRequestType")
@Serializable
@LLMDescription("Type of user request: Transfer or Analytics")
enum class RequestType { Transfer, Analytics }
@Serializable
@LLMDescription("The bank request that was classified by the agent.")
data class ClassifiedBankRequest(
@property:LLMDescription("Type of request: Transfer or Analytics")
val requestType: RequestType,
@property:LLMDescription("Actual request to be performed by the banking application")
val userRequest: String
)공유 도구 레지스트리
kotlin
// 멀티 에이전트 시스템을 위한 포괄적인 도구 레지스트리 생성
val toolRegistry = ToolRegistry {
tool(AskUser) // 에이전트가 설명을 요청할 수 있도록 허용
tools(MoneyTransferTools().asTools())
tools(TransactionAnalysisTools().asTools())
}에이전트 전략
이제 여러 노드를 오케스트레이션하는 전략을 만들어 보겠습니다:
kotlin
import ai.koog.agents.core.dsl.builder.forwardTo
import ai.koog.agents.core.dsl.builder.strategy
import ai.koog.agents.core.dsl.extension.*
import ai.koog.agents.ext.agent.subgraphWithTask
import ai.koog.prompt.structure.StructureFixingParser
val strategy = strategy<String, String>("banking assistant") {
// 사용자 요청 분류를 위한 서브그래프
val classifyRequest by subgraph<String, ClassifiedBankRequest>(
tools = listOf(AskUser)
) {
// 적절한 분류를 보장하기 위해 구조화된 출력(structured output) 사용
val requestClassification by nodeLLMRequestStructured<ClassifiedBankRequest>(
examples = listOf(
ClassifiedBankRequest(
requestType = RequestType.Transfer,
userRequest = "Send 25 euros to Daniel for dinner at the restaurant."
),
ClassifiedBankRequest(
requestType = RequestType.Analytics,
userRequest = "Provide transaction overview for the last month"
)
),
fixingParser = StructureFixingParser(
model = OpenAIModels.Chat.GPT4oMini,
retries = 2,
)
)
val callLLM by nodeLLMRequest()
val callAskUserTool by nodeExecuteTool()
// 흐름 정의
edge(nodeStart forwardTo requestClassification)
edge(
requestClassification forwardTo nodeFinish
onCondition { it.isSuccess }
transformed { it.getOrThrow().data }
)
edge(
requestClassification forwardTo callLLM
onCondition { it.isFailure }
transformed { "Failed to understand the user's intent" }
)
edge(callLLM forwardTo callAskUserTool onToolCall { true })
edge(
callLLM forwardTo callLLM onAssistantMessage { true }
transformed { "Please call `${AskUser.name}` tool instead of chatting" }
)
edge(callAskUserTool forwardTo requestClassification
transformed { it.result.toString() })
}
// 송금 처리를 위한 서브그래프
val transferMoney by subgraphWithTask<ClassifiedBankRequest, String>(
tools = MoneyTransferTools().asTools() + AskUser,
llmModel = OpenAIModels.Chat.GPT4o // 송금에는 더 뛰어난 모델 사용
) { request ->
"""
$bankingAssistantSystemPrompt
Specifically, you need to help with the following request:
${request.userRequest}
""".trimIndent()
}
// 거래 분석을 위한 서브그래프
val transactionAnalysis by subgraphWithTask<ClassifiedBankRequest, String>(
tools = TransactionAnalysisTools().asTools() + AskUser,
) { request ->
"""
$bankingAssistantSystemPrompt
$transactionAnalysisPrompt
Specifically, you need to help with the following request:
${request.userRequest}
""".trimIndent()
}
// 서브그래프 연결
edge(nodeStart forwardTo classifyRequest)
edge(classifyRequest forwardTo transferMoney
onCondition { it.requestType == RequestType.Transfer })
edge(classifyRequest forwardTo transactionAnalysis
onCondition { it.requestType == RequestType.Analytics })
// 결과를 finish 노드로 라우팅
edge(transferMoney forwardTo nodeFinish)
edge(transactionAnalysis forwardTo nodeFinish)
}kotlin
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.prompt.dsl.prompt
val agentConfig = AIAgentConfig(
prompt = prompt(id = "banking assistant") {
system("$bankingAssistantSystemPrompt
$transactionAnalysisPrompt")
},
model = OpenAIModels.Chat.GPT4o,
maxAgentIterations = 50 // 복잡한 멀티스텝 작업 허용
)
val agent = AIAgent<String, String>(
promptExecutor = openAIExecutor,
strategy = strategy,
agentConfig = agentConfig,
toolRegistry = toolRegistry,
)그래프 에이전트 실행
kotlin
println("Banking Assistant started")
val testMessage = "Send 25 euros to Daniel for dinner at the restaurant."
// 다양한 시나리오 테스트:
// 송금 요청:
// - "Send 50 euros to Alice for the concert tickets"
// - "Transfer 100 to Bob for groceries"
// - "What's my current balance?"
//
// 분석 요청:
// - "How much have I spent on restaurants this month?"
// - "What's my maximum check at a restaurant this month?"
// - "How much did I spend on groceries in the first week of May?"
// - "What's my total spending on entertainment in May?"
runBlocking {
val result = agent.run(testMessage)
"Result: $result"
}Banking Assistant started
I found multiple contacts with the name Daniel. Please choose the correct one:
1. Daniel Anderson (+46 70 123 45 67)
2. Daniel Garcia (+34 612 345 678)
Please specify the number of the correct recipient.
Please confirm if you would like to proceed with sending €25 to Daniel Garcia for "dinner at the restaurant."
Result: Task completed successfully.
에이전트 구성 — 에이전트를 도구로 사용하기
Koog를 사용하면 에이전트를 다른 에이전트 내부의 도구로 사용할 수 있어 강력한 구성 패턴이 가능해집니다.
kotlin
import ai.koog.agents.core.agent.createAgentTool
import ai.koog.agents.core.tools.ToolParameterDescriptor
import ai.koog.agents.core.tools.ToolParameterType
val classifierAgent = AIAgent(
executor = openAIExecutor,
llmModel = OpenAIModels.Chat.GPT4oMini,
toolRegistry = ToolRegistry {
tool(AskUser)
// 에이전트를 도구로 변환
tool(
transferAgentService.createAgentTool(
agentName = "transferMoney",
agentDescription = "Transfers money and handles all related operations",
inputDescriptor = ToolParameterDescriptor(
name = "request",
description = "Transfer request from the user",
type = ToolParameterType.String
)
)
)
tool(
analysisAgentService.createAgentTool(
agentName = "analyzeTransactions",
agentDescription = "Performs analytics on user transactions",
inputDescriptor = ToolParameterDescriptor(
name = "request",
description = "Transaction analytics request",
type = ToolParameterType.String
)
)
)
},
systemPrompt = "$bankingAssistantSystemPrompt
$transactionAnalysisPrompt"
)구성된 에이전트 실행
kotlin
println("Banking Assistant started")
val composedMessage = "Send 25 euros to Daniel for dinner at the restaurant."
runBlocking {
val result = classifierAgent.run(composedMessage)
"Result: $result"
}Banking Assistant started
There are two contacts named Daniel. Please confirm which one you would like to send money to:
1. Daniel Anderson (+46 70 123 45 67)
2. Daniel Garcia (+34 612 345 678)
Please confirm the transfer of €25.00 to Daniel Anderson (+46 70 123 45 67) for "Dinner at the restaurant".
Result: Can't perform the task.
요약
이 튜토리얼에서 배운 내용은 다음과 같습니다:
- AI가 언제 어떻게 사용해야 하는지 이해할 수 있도록 명확한 설명이 포함된 LLM 기반 도구 만들기
- 특정 작업을 수행하기 위해 LLM과 도구를 결합한 단일 목적 에이전트 구축
- 복잡한 워크플로우를 위해 전략과 서브그래프를 사용하는 그래프 에이전트 구현
- 에이전트를 다른 에이전트 내의 도구로 사용하여 에이전트 구성하기
- 확인 및 모호성 해소를 포함한 사용자 상호작용 처리
베스트 프랙티스
- 명확한 도구 설명: AI가 도구 사용법을 이해할 수 있도록 상세한
LLMDescription어노테이션을 작성하세요. - 관용적인 Kotlin: 데이터 클래스, 확장 함수, 스코프 함수와 같은 Kotlin의 기능을 활용하세요.
- 에러 핸들링: 항상 입력을 검증하고 의미 있는 에러 메시지를 제공하세요.
- 사용자 경험: 송금과 같은 중요한 작업에는 사용자 확인 단계를 포함하세요.
- 모듈성: 유지보수성을 높이기 위해 관심사를 서로 다른 도구와 에이전트로 분리하세요.