Koog 문서 번역 05: Quickstart
·13분 읽기
원문: Koog Documentation — Quickstart 이 글은 Koog 공식 문서의 Quickstart 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.
빠른 시작
이 가이드는 프로젝트에서 Koog를 사용하는 데 도움이 될 것입니다.
전제 조건
환경과 프로젝트가 다음 요구 사항을 충족하는지 확인하세요.
- JDK 17+
- 코틀린 2.2.0+
- Gradle 8.0+ 또는 Maven 3.8+
쿠그 설치
Koog 패키지을 종속성으로 추가합니다.
그레이들(코틀린)
1dependencies {2 implementation("ai.koog:koog-agents:0.7.1")3}그레이들(그루비)
1dependencies {2 implementation 'ai.koog:koog-agents:0.7.1'3}메이븐
1<dependency>2 <groupId>ai.koog</groupId>3 <artifactId>koog-agents-jvm</artifactId>4 <version>0.7.1</version>5</dependency>참고: Nightly builds
개발 브랜치의 Nightly 빌드는 JetBrains Grazie Maven 저장소에 게시됩니다.
야간 빌드를 사용하려면 빌드 구성에 다음 저장소를 추가하세요.
https://packages.jetbrains.team/maven/p/grazi/grazie-platform-public.
그런 다음 Koog 종속성을 원하는 야간 버전으로 업데이트하세요. Nightly 버전은 패턴을 따릅니다.
[next-major-version]-develop-[date]-[time].
사용 가능한 야간 빌드 여기을 찾아볼 수 있습니다.
API 키 설정
Koog에는 지원되는 LLM 제공업체의 API 키 또는 로컬로 실행되는 LLM이 필요합니다.
참고 소스 코드에 API 키를 하드코딩하지 마세요. 환경 변수를 사용하여 API 키를 저장합니다.
OpenAI
OpenAI API 키을 가져와 OPENAI_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export OPENAI_API_KEY=your-api-keyWindows
1setx OPENAI_API_KEY "your-api-key"Anthropic
Anthropic API 키을 가져와 ANTHROPIC_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export ANTHROPIC_API_KEY=your-api-keyWindows
1setx ANTHROPIC_API_KEY "your-api-key"Gemini API 키을 가져와 GOOGLE_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export GOOGLE_API_KEY=your-api-keyWindows
1setx GOOGLE_API_KEY "your-api-key"DeepSeek
DeepSeek API 키을 가져와 DEEPSEEK_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export DEEPSEEK_API_KEY=your-api-keyWindows
1setx DEEPSEEK_API_KEY "your-api-key"OpenRouter
OpenRouter API 키을 가져와 OPENROUTER_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export OPENROUTER_API_KEY=your-api-keyWindows
1setx OPENROUTER_API_KEY "your-api-key"Bedrock
Generate an Amazon Bedrock API key을 선택하고 이를 BEDROCK_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export BEDROCK_API_KEY=your-api-keyWindows
1setx BEDROCK_API_KEY "your-api-key"Mistral
Mistral API key을 가져와 MISTRAL_API_KEY 환경 변수에 할당합니다.
Linux/macOS
1export MISTRAL_API_KEY=your-api-keyWindows
1setx MISTRAL_API_KEY "your-api-key"Ollama
Ollama documentation에 설명된 대로 Ollama에서 로컬 LLM을 실행합니다.
첫 번째 Koog 에이전트 만들기
OpenAI
다음 예에서는 OpenAI API를 통해 GPT-4o 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the OpenAI API key from the OPENAI_API_KEY environment variable3 val apiKey = System.getenv("OPENAI_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an agent7 val agent = AIAgent(8 promptExecutor = simpleOpenAIExecutor(apiKey),9 llmModel = OpenAIModels.Chat.GPT4o10 )1112 // Run the agent13 val result = agent.run("Hello! How can you help me?")14 println(result)15}자바
1// Get the OpenAI API key from the OPENAI_API_KEY environment variable2String apiKey = System.getenv("OPENAI_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an agent8AIAgent<String, String> agent = AIAgent.builder()9 .promptExecutor(simpleOpenAIExecutor(apiKey))10 .llmModel(OpenAIModels.Chat.GPT4o)11 .build();1213// Run the agent14String result = agent.run("Hello! How can you help me?");15System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1Hello! I'm here to help you with whatever you need. Here are just a few things I can do:23- Answer questions.4- Explain concepts or topics you're curious about.5- Provide step-by-step instructions for tasks.6- Offer advice, notes, or ideas.7- Help with research or summarize complex material.8- Write or edit text, emails, or other documents.9- Brainstorm creative projects or solutions.10- Solve problems or calculations.1112Let me know what you need help with—I’m here for you!Anthropic
다음 예에서는 Anthropic API를 통해 Claude Opus 4.1 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the Anthropic API key from the ANTHROPIC_API_KEY environment variable3 val apiKey = System.getenv("ANTHROPIC_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an agent7 val agent = AIAgent(8 promptExecutor = simpleAnthropicExecutor(apiKey),9 llmModel = AnthropicModels.Opus_4_110 )1112 // Run the agent13 val result = agent.run("Hello! How can you help me?")14 println(result)15}자바
1// Get the Anthropic API key from the ANTHROPIC_API_KEY environment variable2String apiKey = System.getenv("ANTHROPIC_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an agent8AIAgent<String, String> agent = AIAgent.builder()9 .promptExecutor(simpleAnthropicExecutor(apiKey))10 .llmModel(AnthropicModels.Opus_4_1)11 .build();1213// Run the agent14String result = agent.run("Hello! How can you help me?");15System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1Hello! I can help you with:23- **Answering questions** and explaining topics4- **Writing** - drafting, editing, proofreading5- **Learning** - homework, math, study help6- **Problem-solving** and brainstorming7- **Research** and information finding8- **General tasks** - instructions, planning, recommendations910What do you need help with today?다음 예에서는 Gemini API를 통해 Gemini 2.5 Pro 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the Gemini API key from the GOOGLE_API_KEY environment variable3 val apiKey = System.getenv("GOOGLE_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an agent7 val agent = AIAgent(8 promptExecutor = simpleGoogleAIExecutor(apiKey),9 llmModel = GoogleModels.Gemini2_5Pro10 )1112 // Run the agent13 val result = agent.run("Hello! How can you help me?")14 println(result)15}자바
1// Get the Gemini API key from the GOOGLE_API_KEY environment variable2String apiKey = System.getenv("GOOGLE_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an agent8AIAgent<String, String> agent = AIAgent.builder()9 .promptExecutor(simpleGoogleAIExecutor(apiKey))10 .llmModel(GoogleModels.Gemini2_5Pro)11 .build();1213// Run the agent14String result = agent.run("Hello! How can you help me?");15System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1I'm an AI that can help you with tasks involving language and information. You can ask me to:23* **Answer questions**4* **Write or edit text** (emails, stories, code, etc.)5* **Brainstorm ideas**6* **Summarize long documents**7* **Plan things** (like trips or projects)8* **Be a creative partner**910Just tell me what you needDeepSeek
다음 예에서는 DeepSeek API를 통해 deepseek-chat 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the DeepSeek API key from the DEEPSEEK_API_KEY environment variable3 val apiKey = System.getenv("DEEPSEEK_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an LLM client7 val deepSeekClient = DeepSeekLLMClient(apiKey)89 // Create an agent10 val agent = AIAgent(11 // Create a prompt executor using the LLM client12 promptExecutor = MultiLLMPromptExecutor(deepSeekClient),13 // Provide a model14 llmModel = DeepSeekModels.DeepSeekChat15 )1617 // Run the agent18 val result = agent.run("Hello! How can you help me?")19 println(result)20}자바
1// Get the DeepSeek API key from the DEEPSEEK_API_KEY environment variable2String apiKey = System.getenv("DEEPSEEK_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an LLM client8DeepSeekLLMClient deepSeekClient = new DeepSeekLLMClient(apiKey);910// Create an agent11AIAgent<String, String> agent = AIAgent.builder()12 // Create a prompt executor using the LLM client13 .promptExecutor(new MultiLLMPromptExecutor(deepSeekClient))14 // Provide a model15 .llmModel(DeepSeekModels.DeepSeekChat)16 .build();1718// Run the agent19String result = agent.run("Hello! How can you help me?");20System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1Hello! I'm here to assist you with a wide range of tasks, including answering questions, providing information, helping with problem-solving, offering creative ideas, and even just chatting. Whether you need help with research, writing, learning something new, or simply want to discuss a topic, feel free to ask—I’m happy to help! 😊OpenRouter
다음 예에서는 OpenRouter API를 통해 GPT-4o 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the OpenRouter API key from the OPENROUTER_API_KEY environment variable3 val apiKey = System.getenv("OPENROUTER_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an agent7 val agent = AIAgent(8 promptExecutor = simpleOpenRouterExecutor(apiKey),9 llmModel = OpenRouterModels.GPT4o10 )1112 // Run the agent13 val result = agent.run("Hello! How can you help me?")14 println(result)15}자바
1// Get the OpenRouter API key from the OPENROUTER_API_KEY environment variable2String apiKey = System.getenv("OPENROUTER_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an agent8AIAgent<String, String> agent = AIAgent.builder()9 .promptExecutor(simpleOpenRouterExecutor(apiKey))10 .llmModel(OpenRouterModels.GPT4o)11 .build();1213// Run the agent14String result = agent.run("Hello! How can you help me?");15System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1I can answer questions, help with writing, solve problems, organize tasks, and more—just let me know what you need!Bedrock
다음 예에서는 Bedrock API를 통해 Claude Sonnet 4.5 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the Bedrock API key from the BEDROCK_API_KEY environment variable3 val apiKey = System.getenv("BEDROCK_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an agent7 val agent = AIAgent(8 promptExecutor = simpleBedrockExecutorWithBearerToken(apiKey),9 llmModel = BedrockModels.AnthropicClaude4_5Sonnet10 )1112 // Run the agent13 val result = agent.run("Hello! How can you help me?")14 println(result)15}자바
1// Get the Bedrock API key from the BEDROCK_API_KEY environment variable2String apiKey = System.getenv("BEDROCK_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an agent8AIAgent<String, String> agent = AIAgent.builder()9 .promptExecutor(simpleBedrockExecutorWithBearerToken(apiKey, new BedrockClientSettings()))10 .llmModel(BedrockModels.INSTANCE.getAnthropicClaude4_5Sonnet())11 .build();1213// Run the agent14String result = agent.run("Hello! How can you help me?");15System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1Hello! I'm a helpful assistant and I can assist you in many ways, including:23- **Answering questions** on a wide range of topics (science, history, technology, etc.)4- **Writing help** - drafting emails, essays, creative content, or editing text5- **Problem-solving** - working through math problems, logic puzzles, or troubleshooting issues6- **Learning support** - explaining concepts, providing study notes, or tutoring7- **Planning & organizing** - helping with projects, schedules, or breaking down tasks8- **Coding assistance** - explaining programming concepts or helping debug code9- **Creative brainstorming** - generating ideas for projects, stories, or solutions10- **General conversation** - discussing topics or just chatting1112 What would you like help with today?Mistral
다음 예에서는 Mistral AI API를 통해 Mistral Medium 3.1 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Get the Mistral AI API key from the MISTRAL_API_KEY environment variable3 val apiKey = System.getenv("MISTRAL_API_KEY")4 ?: error("The API key is not set.")5 6 // Create an agent7 val agent = AIAgent(8 promptExecutor = simpleMistralAIExecutor(apiKey),9 llmModel = MistralAIModels.Chat.MistralMedium3110 )1112 // Run the agent13 val result = agent.run("Hello! How can you help me?")14 println(result)15}자바
1// Get the Mistral AI API key from the MISTRAL_API_KEY environment variable2String apiKey = System.getenv("MISTRAL_API_KEY");3if (apiKey == null) {4 throw new RuntimeException("The API key is not set.");5}67// Create an agent8AIAgent<String, String> agent = AIAgent.builder()9 .promptExecutor(simpleMistralAIExecutor(apiKey))10 .llmModel(MistralAIModels.Chat.MistralMedium31)11 .build();1213// Run the agent14String result = agent.run("Hello! How can you help me?");15System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1I can assist you with a wide range of topics and tasks. Here are some examples:231. **Answering questions**: I can provide information on various subjects, including history, science, technology, literature, and more.42. **Providing definitions**: If you're unsure about the meaning of a word or phrase, I can help define it for you.53. **Generating text**: Whether it's writing an email, creating content for social media, or composing a story, I can help with text generation.64. **Translation**: I can translate text from one language to another.75. **Conversation**: We can have a chat about any topic that interests you, and I'll respond accordingly.86. **Language practice**: If you're learning a new language, I can help with pronunciation, grammar, and vocabulary practice.97. **Brainstorming**: If you're stuck on a problem or need ideas for a project, I can help brainstorm solutions.108. **Summarization**: If you have a long piece of text and want a summary, I can condense it for you.1112What's on your mind? Is there something specific you'd like help with?Ollama
다음 예에서는 Ollama를 통해 로컬로 실행되는 llama3.2 모델을 사용하여 간단한 Koog 에이전트를 생성하고 실행합니다.
코틀린
1fun main() = runBlocking {2 // Create an agent3 val agent = AIAgent(4 promptExecutor = simpleOllamaAIExecutor(),5 llmModel = OllamaModels.Meta.LLAMA_3_26 )78 // Run the agent9 val result = agent.run("Hello! How can you help me?")10 println(result)11}자바
1// Create an agent2AIAgent<String, String> agent = AIAgent.builder()3 .promptExecutor(simpleOllamaAIExecutor("http://localhost:11434"))4 .llmModel(OllamaModels.Meta.LLAMA_3_2)5 .build();67// Run the agent8String result = agent.run("Hello! How can you help me?");9System.out.println(result);이 예에서는 다음과 같은 출력을 생성할 수 있습니다.
1I can assist with various tasks such as answering questions, providing information, and even helping with language-related tasks like proofreading or writing suggestions. What's on your mind today?다음 단계
- agent types에 대해 자세히 알아보기