Architecture-first blueprints for building secure, observable, and maintainable AI agent systems with Koog.

An independent community project exploring secure, observable, and engineering-focused AI agent architectures through runnable Kotlin examples, engineering guidance, and practical reference implementations.

• Runnable Kotlin examples built with Koog
• Runtime policy enforcement for AI agent tools
• Deterministic safety regression coverage for guarded workflows
• Agent capability-diff testing for policy changes
• Secure workspace filesystem patterns
• Architecture-first engineering guidance
• Threat modeling and observability documentation
• Practical evaluation checklist for agent systems

This repository explores how AI agent systems can be designed to be modular, observable, secure, and maintainable within JVM applications.

Rather than focusing on specific APIs or model providers, the goal is to examine architectural patterns, operational concerns, and engineering trade-offs that emerge as agent systems become part of larger software platforms.

The repository is intended as a community resource for engineers, researchers, and developers interested in engineering-focused Koog-based agent architectures.

This repository is intended for:

• JVM developers building AI agent systems
• Engineers exploring Koog architecture
• Researchers interested in agent engineering
• Contributors interested in architecture-first design

git clone https://github.com/karanverma/koog-community-blueprints.git
cd koog-community-blueprints
cd examples/03-guarded-tool-agent
./gradlew test

Each example in examples/ is a standalone Gradle project. The guarded-tool example includes the runtime policy engine, while the safety regression suite in examples/04-safety-regression-suite exercises the same behavior deterministically without requiring LLMs or API keys.

.
├── .github/
│   └── workflows/
├── docs/
│   ├── assets/
│   │   ├── koog-high-level-architecture.png
│   │   └── request-lifecycle.png
│   ├── architecture-overview.md
│   ├── edge-agent.md
│   ├── evaluation-checklist.md
│   ├── infrastructure-middleware.md
│   ├── observability.md
│   └── threat-model.md
├── examples/
│   ├── 01-minimal-agent/
│   ├── 02-safe-tool-agent/
│   ├── 03-guarded-tool-agent/
│   ├── 04-safety-regression-suite/
│   └── 05-agent-capability-diff/
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── ROADMAP.md
└── SECURITY.md

Runnable examples complement the architecture documentation by demonstrating key Koog concepts in practice.

Five runnable examples are currently included:

A standalone Kotlin example demonstrating Koog agent initialization, OpenAI integration, and a simple local workflow.

→ Minimal Koog Agent

A runnable Kotlin example demonstrating policy-enforced filesystem operations for AI agents and tool-calling systems.

Highlights include:

• Workspace boundary enforcement
• Path traversal prevention
• Hidden file blocking
• Sensitive filename protection
• Symbolic-link escape prevention
• Explicit deletion confirmation
• Runnable demo
• Unit tests

→ Safe Workspace Tools

A guarded tool example demonstrating a reusable runtime policy engine, approval gating, structured auditing, and a minimal Koog adapter around workspace operations. The implementation stays deterministic and composable without depending on an LLM for authorization decisions.

→ Guarded Tool Agent

A deterministic regression harness for detecting safety-policy regressions in guarded agent workflows without requiring an LLM or API key.

It includes 20 scenarios covering:

• Safe reads and writes
• Approval and rejection flows
• Workspace traversal
• Hidden paths
• Sensitive path segments
• Symbolic-link escapes
• Policy precedence
• Post-approval safety rechecks

→ Safety Regression Suite

A deterministic evaluation pattern for comparing effective authorization decisions across baseline and candidate agent policies.

It identifies:

• Capability expansions
• Policy tightenings
• Unchanged behavior
• Unexpected policy-change outcomes

The comparison uses the real runtime policy engine and does not require an LLM or API key.

→ Agent Capability Diff

Provides a high-level overview of the repository, its design philosophy, and the relationships between the individual blueprints.

→ Architecture Overview

Explores local-first agent architectures including:

• LiteRT integration
• Offline workflows
• Local model execution
• Privacy-focused deployments
• Selective cloud interaction

→ Edge Agent

Explores architectural patterns for integrating agents into JVM applications, including:

• Agent orchestration
• Authentication
• Tool management
• Memory integration
• Service communication
• Failure handling

→ Infrastructure Middleware

Explores operational visibility through:

• OpenTelemetry
• Metrics
• Tracing
• Workflow inspection
• Performance monitoring
• Debugging

→ Observability

A practical checklist for evaluating agent systems before deployment.

Topics include:

• Functional evaluation
• Reliability
• Security
• Observability
• Performance
• Deployment readiness

→ Evaluation Checklist

Introduces high-level security considerations for agent architectures, including:

• Trust boundaries
• Prompt injection
• Tool misuse
• Data exposure
• Mitigation strategies

→ Threat Model

The repository is guided by several recurring architectural principles:

• Modular system design
• Explicit architectural boundaries
• Security by design
• Secure tool execution
• Observable agent systems
• Evaluation before deployment

This repository currently focuses on:

• Architecture documentation
• Engineering guidance
• Community exploration
• Runnable reference examples

It does not currently provide:

• Production-ready implementations
• Security guarantees
• Performance benchmarks
• Official Koog extensions

The repository currently includes five runnable reference examples, including deterministic runtime policy enforcement, safety regression testing, and agent capability-diff evaluation, alongside architecture documentation and engineering guidance.

Planned future work includes:

• Additional secure tool examples
• Multi-agent workflows
• Observability reference implementations
• Evaluation tooling
• JVM framework integrations

See the complete project roadmap:

→ ROADMAP.md

Ideas, architecture discussions, documentation improvements, runnable examples, and constructive feedback are welcome.

Please read the contribution guidelines before opening a Pull Request.

→ CONTRIBUTING.md

This repository is an independent community project created for architectural exploration, education, and experimentation.

It is not affiliated with, endorsed by, or maintained by JetBrains or the official Koog project.