예제
Koog 프레임워크는 다양한 유스케이스(use case)에 맞는 AI 에이전트 구현 방법을 이해하는 데 도움이 되는 예제들을 제공합니다. 예제는 Kotlin과 Java로 모두 제공됩니다. 이 예제들은 여러분의 애플리케이션에 적용할 수 있는 주요 기능과 패턴을 보여줍니다.
아래의 예제들을 살펴보고 링크를 클릭하여 GitHub의 소스 코드를 확인해 보세요.
=== "Kotlin"
| 예제 | 설명 |
|-------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Attachments](examples/Attachments.md) | 프롬프트에서 구조화된 Markdown 및 첨부 파일을 사용하는 방법을 배웁니다. 이미지를 포함하는 프롬프트를 작성하고 OpenAI 모델을 사용하여 인스타그램 게시물용 창의적인 콘텐츠를 생성합니다. |
| [Banking](examples/Banking.md) | 정교한 그래프 기반 전략을 통해 송금 및 거래 분석을 처리할 수 있는 라우팅 기능이 포함된 종합 AI 뱅킹 어시스턴트를 구축합니다. 도메인 모델링, 도구 생성 및 에이전트 구성 패턴을 포함합니다. |
| [BedrockAgent](examples/BedrockAgent.md) | AWS Bedrock 연동과 Koog 프레임워크를 사용하여 지능형 AI 에이전트를 생성합니다. 커스텀 도구를 정의하고, AWS Bedrock을 설정하며, 장치 제어를 위한 자연어 명령을 이해하는 대화형 에이전트를 구축하는 방법을 배웁니다. |
| [Calculator](examples/Calculator.md) | 덧셈, 뺄셈, 곱셈, 나눗셈 도구를 사용하여 산술 연산을 수행하는 계산기 에이전트를 구축합니다. 병렬 도구 호출(parallel tool calls), 이벤트 로깅 및 다중 실행기(executor) 지원(OpenAI 및 Ollama)을 보여줍니다. |
| [Chess](examples/Chess.md) | 복잡한 도메인 모델링, 커스텀 도구, 메모리 최적화 기술 및 대화형 선택 기능을 갖춘 지능형 체스 플레이 에이전트를 구축합니다. 고급 에이전트 전략, 게임 상태 관리 및 인간-AI 협업 패턴을 보여줍니다. |
| [GoogleMapsMcp](examples/GoogleMapsMcp.md) | Docker를 통해 Koog를 Google Maps MCP 서버에 연결합니다. Kotlin Notebook 환경에서 실제 지리 API와 AI 에이전트를 사용하여 도구를 검색하고, 주소를 지오코딩하며, 고도 데이터를 가져옵니다. |
| [Guesser](examples/Guesser.md) | 타겟 질문을 던지는 도구를 사용하여 이진 탐색(binary search) 전략을 구현하는 숫자 맞추기 에이전트를 구축합니다. 에이전트는 전략적인 질문을 통해 사용자의 숫자를 효율적으로 좁혀 나가며 도구 기반 상호작용 패턴을 보여줍니다. |
| [Langfuse](examples/Langfuse.md) | OpenTelemetry를 사용하여 Koog 에이전트 트레이스(trace)를 Langfuse로 내보내는 방법을 배웁니다. 환경 변수를 설정하고, 에이전트를 실행하며, 포괄적인 관측성(observability)을 위해 Langfuse 인스턴스에서 스팬(span)과 트레이스를 검사합니다. |
| [MCP](https://github.com/JetBrains/koog/tree/develop/examples/src/main/kotlin/ai/koog/agents/example/mcp) | Model Context Protocol 통합 예제로, 지리 데이터를 위한 `GoogleMapsMcpClient`와 브라우저 자동화를 위한 `PlaywrightMcpClient`를 다룹니다. |
| [Memory](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/memory) | 메모리 시스템 사용법을 보여주는 고객 지원 에이전트입니다. 에이전트는 암호화된 로컬 스토리지와 주체(subject) 및 범위(scope)를 사용한 적절한 메모리 구성을 통해 사용자의 대화 기본 설정, 장치 진단 및 조직별 정보를 추적합니다. |
| [OpenTelemetry](examples/OpenTelemetry.md) | Koog AI 에이전트에 OpenTelemetry 기반 트레이싱을 추가합니다. 디버깅을 위해 콘솔로 스팬을 내보내고 Jaeger에서 확인하기 위해 OpenTelemetry Collector로 트레이스를 내보내는 방법을 배웁니다. Docker 설정 및 문제 해결 가이드를 포함합니다. |
| [Planner](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/planner) | 병렬 및 순차 실행 노드를 사용하여 실행 트리(execution tree)를 구축하고, 복잡한 워크플로우를 위한 실행 계획을 동적으로 구성하는 작업 계획 시스템입니다. |
| [PlaywrightMcp](examples/PlaywrightMcp.md) | Playwright MCP와 Koog를 사용하여 브라우저를 구동합니다. Playwright MCP 서버를 실행하고 SSE를 통해 연결하여, AI 에이전트가 자연어 명령을 통해 탐색, 쿠키 수락 및 UI 상호작용과 같은 웹 작업을 자동화하도록 합니다. |
| [SimpleAPI](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/simpleapi) | Koog를 시작하기 위한 채팅 에이전트와 간단한 API 패턴을 가진 기본 에이전트 예제들입니다. |
| [StructuredData](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/structuredoutput) | 복잡한 중첩 클래스, 다형성(polymorphism)을 포함한 JSON 기반 구조화된 데이터 출력과 에이전트 응답에서 타입이 지정된 데이터(typed data)를 다루는 방법을 보여주는 일기 예보 예제입니다. |
| [SubgraphWithTask](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/subgraphwithtask) | 하위 그래프(subgraph) 전략을 사용하여 생성, 삭제 및 명령 실행을 포함한 파일 및 디렉토리 작업을 보여주는 프로젝트 생성 도구입니다. |
| [Tone](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/tone) | 입력 텍스트에서 긍정, 부정 또는 중립 톤을 식별하기 위해 특화된 도구를 사용하는 텍스트 톤 분석 에이전트로, 감성 분석(sentiment analysis) 기능을 보여줍니다. |
| [UnityMcp](examples/UnityMcp.md) | Unity MCP 서버 통합을 사용하여 AI 에이전트로 Unity 게임 개발을 수행합니다. stdio를 통해 Unity에 연결하고 사용 가능한 도구를 검색하며, 에이전트가 자연어 명령을 통해 씬(scene)을 수정하고 오브젝트를 배치하며 게임 개발 작업을 실행하도록 합니다. |
| [VaccumAgent](examples/VaccumAgent.md) | Koog 프레임워크를 사용한 기본 반사 에이전트(reflex agent) 구현입니다. 단순한 2칸 세계(two-cell world)에서 자동 청소 작업을 위한 환경 모델링, 도구 생성 및 에이전트 동작을 다룹니다. |
| [Weave](examples/Weave.md) | OpenTelemetry(OTLP)를 사용하여 Koog 에이전트를 W&B Weave로 트레이싱하는 방법을 배웁니다. 환경 변수를 설정하고 에이전트를 실행하며, 포괄적인 모니터링 및 디버깅을 위해 Weave UI에서 풍부한 트레이스를 확인합니다. |
| [A2A](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples/src/main/kotlin/ai/koog/agents/example/a2a) | Koog 프레임워크를 사용한 에이전트 간(A2A) 통신을 보여줍니다. AI 에이전트 간의 양방향 통신을 설정하고, 협업 문제 해결을 가능하게 하며, 적절한 메시지 라우팅 및 조정을 통해 다중 에이전트 워크플로우를 관리하는 방법을 보여줍니다. |
=== "Java"
| 예제 | 설명 |
|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Calculator](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/calculator/Calculator.java) | 그래프 기반의 계산기 에이전트를 구축합니다. `ToolSet`을 사용하여 정의된 도구, 타입이 지정된 엣지(typed edges)가 있는 다중 노드 그래프 전략, 조건부 라우팅, 자동 기록 압축, 이벤트 처리 및 다중 실행기(executor) 지원(OpenAI 및 Ollama)을 보여줍니다. |
| [FunctionalAgentChat](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/chat/FunctionalAgentChat.java) | [함수형 전략(functional strategy)](agents/functional-agents.md)을 사용하여 대화형 채팅 에이전트를 구축합니다. Llama 3.2 모델을 기반으로 지속적인 대화 루프를 실행하며, `/bye`가 입력될 때까지 사용자 입력을 받습니다. |
| [ChatMemoryJdbc](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/chatmemory/ChatMemoryJdbcExample.java) | JDBC PostgreSQL 공급자를 기반으로 하는 [`ChatMemory`](features/chat-memory/index.md) 기능을 사용하여 세션 간에 대화 기록을 유지합니다. 24시간 TTL을 갖춘 JDBC 기반 채팅 기록 공급자 생성, 스키마 마이그레이션 및 채팅 메모리가 포함된 에이전트 구축을 보여줍니다. 로컬 또는 Docker를 통해 실행 중인 PostgreSQL이 필요합니다. |
| [FunctionalStrategy](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/strategies/functional/FunctionalStrategyExample.java) | 타입이 지정된 하위 작업(subtask), 단계별 도구 범위 지정(tool scoping), 검증된 솔루션을 생성하기 위한 반복적인 확인 및 수정 루프를 포함하는 다단계 함수형 전략을 구현합니다. |
| [GoapStrategy](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/strategies/GoapStrategyExample.java) | GOAP(Goal-Oriented Action Planning, 목표 지향적 행동 계획)를 사용하여 플래너 기반 에이전트를 구축합니다. 반복적인 문제 해결 및 자기 수정을 안내하기 위해 타입이 지정된 신념 상태(belief states), 작업 전제 조건 및 목표 조건을 정의합니다. |
| [GraphStrategy](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/strategies/GraphStrategyExample.java) | 조건부 엣지로 연결된 타입 지정 하위 그래프(subgraph)를 사용하여 그래프 기반 문제 해결 에이전트를 구축합니다. 솔루션을 검증하기 위해 LLM-as-a-judge를 사용하는 문제 해결 파이프라인을 구현합니다. |
| [CustomSubgraph](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/subgraphs/CustomSubgraphExample.java) | 다중 하위 그래프 에이전트 전략을 구축합니다. 웹 검색 도구를 사용한 조사, 개요 계획, 최종 기사 요약 작성을 순차적으로 처리하는 3개의 하위 그래프를 구현합니다. |
| [OpenTelemetry](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/features/opentelemetry/OpenTelemetryExample.java) | Koog AI 에이전트에 OpenTelemetry 기반 트레이싱을 추가합니다. 로컬 디버깅을 위한 콘솔 로깅 내보내기(exporter)와 Jaeger에서 스팬(span)을 확인하기 위한 OTLP/gRPC 내보내기를 구성합니다. Docker 설정이 포함되어 있습니다. |
| [Langfuse](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/features/opentelemetry/langfuse/LangfuseExample.java) | OpenTelemetry를 통해 Koog 에이전트 트레이스를 Langfuse로 내보냅니다. 향상된 관측성(observability)을 위해 세션 ID 및 트레이스 태그와 같은 커스텀 속성을 구성하는 방법을 보여줍니다. |
| [Weave](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/features/opentelemetry/weave/WeaveExample.java) | OpenTelemetry(OTLP)를 사용하여 Koog 에이전트를 W&B Weave로 트레이싱합니다. 환경 변수를 설정하고 에이전트를 실행하며 Weave UI에서 풍부한 트레이스를 확인합니다. |
| [PersistenceJdbc](https://github.com/JetBrains/koog/tree/develop/examples/simple-examples-java/src/main/java/ai/koog/agents/example/snapshot/PersistenceJdbcExample.java) | JDBC PostgreSQL 공급자를 기반으로 하는 `Persistence` 기능이 포함된 에이전트를 구축합니다. Persistence 기능은 각 노드 실행 후 자동으로 체크포인트를 생성하여 에이전트가 재시작 후에도 중단된 지점부터 다시 시작할 수 있도록 합니다. 로컬 또는 Docker를 통해 실행 중인 PostgreSQL이 필요합니다. |