퀵스타트

이 가이드는 프로젝트에서 Koog를 사용하기 시작하는 방법을 안내합니다.

사전 준비 사항

환경과 프로젝트가 다음 요구 사항을 충족하는지 확인하세요:

JDK 17+
Kotlin 2.2.0+
Gradle 8.0+ 또는 Maven 3.8+

Koog 설치하기

Koog 패키지를 의존성으로 추가하세요:

Gradle (Kotlin)Gradle (Groovy)Maven


dependencies {

    // 안정 버전

    implementation("ai.koog:koog-agents:1.2.0")

    // 베타 버전

    implementation("ai.koog:koog-agents-additions:1.2.0-beta")

}


dependencies {

    // 안정 버전

    implementation 'ai.koog:koog-agents:1.2.0'

    // 베타 버전

    implementation 'ai.koog:koog-agents-additions:1.2.0-beta'

}

xml


<dependency>

    <!-- 안정 버전 -->

    <dependency>

        <groupId>ai.koog</groupId>

        <artifactId>koog-agents-jvm</artifactId>

        <version>1.2.0</version>

    </dependency>

    <!-- 베타 버전 -->

    <dependency>

        <groupId>ai.koog</groupId>

        <artifactId>koog-agents-additions-jvm</artifactId>

        <version>1.2.0-beta</version>

    </dependency>

</dependency>

모듈 버전 관리 (Module Versioning)

Koog는 유의적 버전(Semantic Versioning, X.Y.Z)을 따릅니다. 안정적인 모듈(예: 1.0.0)은 보장된 API를 가지며, 베타 모듈(예: 1.0.0-beta)은 실험적이며 릴리스 간에 변경될 수 있습니다.

자세한 내용은 모듈 버전 관리를 참조하세요.

나이틀리 빌드 (Nightly builds)

develop 브랜치의 나이틀리 빌드는 JetBrains Grazie Maven 저장소에 배포됩니다.

나이틀리 빌드를 사용하려면 빌드 구성에 다음 저장소를 추가하세요: https://packages.jetbrains.team/maven/p/grazi/grazie-platform-public.

그 다음 Koog 의존성을 원하는 나이틀리 버전으로 업데이트하세요. 나이틀리 버전은 다음과 같은 형식을 따릅니다: [next-major-version]-develop-[date]-[time].

사용 가능한 나이틀리 빌드는 여기에서 확인할 수 있습니다.

API 키 설정하기

Koog를 사용하려면 지원되는 LLM 제공자의 API 키 또는 로컬에서 실행 중인 LLM이 필요합니다.

경고

소스 코드에 API 키를 하드코딩하지 마세요. API 키를 저장하려면 환경 변수를 사용하세요.

OpenAIAnthropicGoogle βDeepSeek βOpenRouterBedrockMistral βOllama

OpenAI API 키를 발급받아 OPENAI_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export OPENAI_API_KEY=your-api-key

cmd

setx OPENAI_API_KEY "your-api-key"

Anthropic API 키를 발급받아 ANTHROPIC_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export ANTHROPIC_API_KEY=your-api-key

cmd

setx ANTHROPIC_API_KEY "your-api-key"

Gemini API 키를 발급받아 GOOGLE_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export GOOGLE_API_KEY=your-api-key

cmd

setx GOOGLE_API_KEY "your-api-key"

DeepSeek API 키를 발급받아 DEEPSEEK_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export DEEPSEEK_API_KEY=your-api-key

cmd

setx DEEPSEEK_API_KEY "your-api-key"

OpenRouter API 키를 발급받아 OPENROUTER_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export OPENROUTER_API_KEY=your-api-key

cmd

setx OPENROUTER_API_KEY "your-api-key"

Amazon Bedrock API 키를 생성하고 이를 BEDROCK_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export BEDROCK_API_KEY=your-api-key

cmd

setx BEDROCK_API_KEY "your-api-key"

Mistral API 키를 발급받아 MISTRAL_API_KEY 환경 변수에 할당하세요.

Linux/macOSWindows

shell

export MISTRAL_API_KEY=your-api-key

cmd

setx MISTRAL_API_KEY "your-api-key"

Ollama 문서의 설명에 따라 Ollama에서 로컬 LLM을 실행하세요.

첫 번째 Koog 에이전트 만들기

OpenAIAnthropicGoogle βDeepSeek βOpenRouterBedrockMistral βOllama

다음 예제는 OpenAI API를 통해 GPT-4o 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // OPENAI_API_KEY 환경 변수에서 OpenAI API 키를 가져옵니다.
    val apiKey = System.getenv("OPENAI_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(OpenAILLMClient(apiKey)),
        llmModel = OpenAIModels.Chat.GPT4o
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// OPENAI_API_KEY 환경 변수에서 OpenAI API 키를 가져옵니다.
String apiKey = System.getenv("OPENAI_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(openAIClient(apiKey)))
    .llmModel(OpenAIModels.Chat.GPT4o)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

안녕하세요! 무엇이든 도와드릴 준비가 되어 있습니다. 제가 도와드릴 수 있는 몇 가지 사항은 다음과 같습니다:

- 질문에 답변하기.
- 궁금한 개념이나 주제 설명하기.
- 작업에 대한 단계별 지침 제공하기.
- 조언, 메모 또는 아이디어 제안하기.
- 조사 업무 지원 또는 복잡한 자료 요약하기.
- 텍스트, 이메일 또는 기타 문서 작성 및 편집하기.
- 창의적인 프로젝트나 솔루션 브레인스토밍하기.
- 문제 풀이 또는 계산 수행하기.

도움이 필요한 것이 있다면 말씀해 주세요. 제가 여기 있습니다!

다음 예제는 Anthropic API를 통해 Claude Opus 4.1 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // ANTHROPIC_API_KEY 환경 변수에서 Anthropic API 키를 가져옵니다.
    val apiKey = System.getenv("ANTHROPIC_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(AnthropicLLMClient(apiKey)),
        llmModel = AnthropicModels.Opus_4_1
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// ANTHROPIC_API_KEY 환경 변수에서 Anthropic API 키를 가져옵니다.
String apiKey = System.getenv("ANTHROPIC_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(anthropicClient(apiKey)))
    .llmModel(AnthropicModels.Opus_4_1)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

안녕하세요! 다음과 같은 일들을 도와드릴 수 있습니다:

- **질문 답변** 및 주제 설명
- **글쓰기** - 초안 작성, 편집, 교정
- **학습** - 과제, 수학, 학습 보조
- **문제 해결** 및 브레인스토밍
- **조사** 및 정보 검색
- **일반적인 작업** - 지침 제공, 계획 수립, 추천

오늘은 어떤 도움이 필요하신가요?

다음 예제는 Gemini API를 통해 Gemini 2.5 Pro 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // GOOGLE_API_KEY 환경 변수에서 Gemini API 키를 가져옵니다.
    val apiKey = System.getenv("GOOGLE_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(GoogleLLMClient(apiKey)),
        llmModel = GoogleModels.Gemini2_5Pro
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// GOOGLE_API_KEY 환경 변수에서 Gemini API 키를 가져옵니다.
String apiKey = System.getenv("GOOGLE_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(googleClient(apiKey)))
    .llmModel(GoogleModels.Gemini2_5Pro)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

저는 언어 및 정보와 관련된 작업을 도와드릴 수 있는 AI입니다. 저에게 다음과 같은 것들을 요청하실 수 있습니다:

*   **질문 답변**
*   **텍스트 작성 및 편집** (이메일, 이야기, 코드 등)
*   **아이디어 브레인스토밍**
*   **긴 문서 요약**
*   **계획 수립** (여행이나 프로젝트 등)
*   **창의적인 파트너 역할**

필요한 것이 있다면 말씀해 주세요.

다음 예제는 DeepSeek API를 통해 deepseek-v4-flash 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // DEEPSEEK_API_KEY 환경 변수에서 DeepSeek API 키를 가져옵니다.
    val apiKey = System.getenv("DEEPSEEK_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(DeepSeekLLMClient(apiKey)),
        llmModel = DeepSeekModels.DeepSeekV4Flash
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// DEEPSEEK_API_KEY 환경 변수에서 DeepSeek API 키를 가져옵니다.
String apiKey = System.getenv("DEEPSEEK_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(deepSeekClient(apiKey)))
    .llmModel(DeepSeekModels.DeepSeekV4Flash)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

안녕하세요! 질문 답변, 정보 제공, 문제 해결 지원, 창의적인 아이디어 제안, 그리고 간단한 대화까지 폭넓은 작업을 도와드릴 수 있습니다. 조사, 글쓰기, 새로운 학습에 도움이 필요하시거나 단순히 특정 주제에 대해 이야기하고 싶으시다면 언제든 편하게 말씀해 주세요. 기꺼이 도와드리겠습니다! 😊

다음 예제는 OpenRouter API를 통해 GPT-4o 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // OPENROUTER_API_KEY 환경 변수에서 OpenRouter API 키를 가져옵니다.
    val apiKey = System.getenv("OPENROUTER_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(OpenRouterLLMClient(apiKey)),
        llmModel = OpenRouterModels.GPT4o
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// OPENROUTER_API_KEY 환경 변수에서 OpenRouter API 키를 가져옵니다.
String apiKey = System.getenv("OPENROUTER_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(openRouterClient(apiKey)))
    .llmModel(OpenRouterModels.GPT4o)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

질문에 답하고, 글쓰기를 돕고, 문제를 해결하고, 작업을 정리하는 등 다양한 일을 도와드릴 수 있습니다. 무엇이 필요한지 알려주세요!

다음 예제는 Bedrock API를 통해 Claude Sonnet 4.5 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // BEDROCK_API_KEY 환경 변수에서 Bedrock API 키를 가져옵니다.
    val apiKey = System.getenv("BEDROCK_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(
            BedrockLLMClient(
                StaticBearerTokenProvider(apiKey),
                BedrockClientSettings()
            )
        ),
        llmModel = BedrockModels.AnthropicClaude4_5Sonnet
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// BEDROCK_API_KEY 환경 변수에서 Bedrock API 키를 가져옵니다.
String apiKey = System.getenv("BEDROCK_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(simpleBedrockExecutorWithBearerToken(apiKey, new BedrockClientSettings()))
    .llmModel(BedrockModels.INSTANCE.getAnthropicClaude4_5Sonnet())
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

안녕하세요! 저는 여러분을 돕는 보조자이며 다음과 같은 다양한 방법으로 도움을 드릴 수 있습니다:

- **질문 답변** - 광범위한 주제(과학, 역사, 기술 등)에 대한 답변
- **글쓰기 지원** - 이메일, 에세이, 창의적 콘텐츠 초안 작성 또는 텍스트 편집
- **문제 해결** - 수학 문제 풀이, 논리 퍼즐 또는 문제 해결 지원
- **학습 지원** - 개념 설명, 학습 노트 제공 또는 튜터링
- **계획 및 정리** - 프로젝트, 일정 관리 또는 작업 세분화 지원
- **코딩 지원** - 프로그래밍 개념 설명 또는 코드 디버깅 지원
- **창의적 브레인스토밍** - 프로젝트, 이야기 또는 솔루션을 위한 아이디어 생성
- **일반 대화** - 주제 토론 또는 일상적인 대화

 오늘은 어떤 도움을 드릴까요?

다음 예제는 Mistral AI API를 통해 Mistral Medium 3.1 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // MISTRAL_API_KEY 환경 변수에서 Mistral AI API 키를 가져옵니다.
    val apiKey = System.getenv("MISTRAL_API_KEY")
        ?: error("API 키가 설정되지 않았습니다.")

    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(MistralAILLMClient(apiKey)),
        llmModel = MistralAIModels.Chat.MistralMedium31
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// MISTRAL_API_KEY 환경 변수에서 Mistral AI API 키를 가져옵니다.
String apiKey = System.getenv("MISTRAL_API_KEY");
if (apiKey == null) {
    throw new RuntimeException("API 키가 설정되지 않았습니다.");
}

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(mistralAIClient(apiKey)))
    .llmModel(MistralAIModels.Chat.MistralMedium31)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

다양한 주제와 작업을 도와드릴 수 있습니다. 예시는 다음과 같습니다:

1. **질문 답변**: 역사, 과학, 기술, 문학 등 다양한 분야의 정보를 제공할 수 있습니다.
2. **정의 제공**: 단어나 구절의 의미가 확실하지 않을 때 정의를 도와드릴 수 있습니다.
3. **텍스트 생성**: 이메일 작성, 소셜 미디어 콘텐츠 제작, 이야기 구성 등 텍스트 생성을 도울 수 있습니다.
4. **번역**: 텍스트를 한 언어에서 다른 언어로 번역할 수 있습니다.
5. **대화**: 관심 있는 주제에 대해 대화하고 그에 맞춰 응답할 수 있습니다.
6. **언어 연습**: 새로운 언어를 배우고 있다면 발음, 문법, 어휘 연습을 도울 수 있습니다.
7. **브레인스토밍**: 문제에 부딪혔거나 프로젝트 아이디어가 필요할 때 해결책을 함께 고민할 수 있습니다.
8. **요약**: 긴 텍스트를 요약하고 싶을 때 핵심 내용을 압축해 드릴 수 있습니다.

지금 무슨 생각을 하고 계신가요? 특별히 도움이 필요한 부분이 있나요?

다음 예제는 Ollama를 통해 로컬에서 실행되는 llama3.2 모델을 사용하는 간단한 Koog 에이전트를 생성하고 실행합니다.

KotlinJava

kotlin

fun main() = runBlocking {
    // 에이전트 생성
    val agent = AIAgent(
        promptExecutor = MultiLLMPromptExecutor(OllamaClient()),
        llmModel = OllamaModels.Meta.LLAMA_3_2
    )

    // 에이전트 실행
    val result = agent.run("Hello! How can you help me?")
    println(result)
}

java

// 에이전트 생성
AIAgent<String, String> agent = AIAgent.builder()
    .promptExecutor(new MultiLLMPromptExecutor(ollamaClient("http://localhost:11434")))
    .llmModel(OllamaModels.Meta.LLAMA_3_2)
    .build();

// 에이전트 실행
String result = agent.run("Hello! How can you help me?");
System.out.println(result);

이 예제는 다음과 같은 출력을 생성할 수 있습니다:

질문 답변, 정보 제공, 그리고 교정이나 글쓰기 제안과 같은 언어 관련 작업 등 다양한 업무를 도와드릴 수 있습니다. 오늘 어떤 도움이 필요하신가요?

다음 단계

에이전트 유형에 대해 자세히 알아보기

개요

에이전트

플래너 에이전트

프롬프트

프롬프트 만들기

프롬프트 실행

도구

기능

채팅 메모리

OpenTelemetry

A2A 프로토콜

서브그래프

퀵스타트

사전 준비 사항

Koog 설치하기

API 키 설정하기

첫 번째 Koog 에이전트 만들기

다음 단계

플래너 에이전트

프롬프트 만들기

채팅 메모리

OpenTelemetry

퀵스타트 ​

사전 준비 사항 ​

Koog 설치하기 ​

API 키 설정하기 ​

첫 번째 Koog 에이전트 만들기 ​

다음 단계 ​

퀵스타트

사전 준비 사항

Koog 설치하기

API 키 설정하기

첫 번째 Koog 에이전트 만들기

다음 단계