{"owner":"JetBrains","repo":"koog","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Koog AI Agent Framework\n\nKoog is a Kotlin multiplatform framework for building AI agents with graph-based workflows.\nIt supports JVM and JS targets and integrates with multiple LLM providers\n(OpenAI, Anthropic, Google, OpenRouter, Ollama) and Model Context Protocol (MCP).\n\n## Project Structure\n\nThe project follows a modular architecture with a clear separation of concerns:\n\n```\nkoog/\n├── agents/\n│   ├── agents-core/           # Core abstractions (AIAgent, AIAgentStrategy, AIAgentEnvironment)\n│   ├── agents-tools/          # Tool infrastructure (Tool<TArgs, TResult>, ToolRegistry, AIAgentTool)\n│   ├── agents-features-*/     # Feature implementations (memory, tracing, event handling)\n│   ├── agents-mcp/           # Model Context Protocol integration\n│   └── agents-test/          # Testing utilities and framework\n├── prompt-*/                 # LLM interaction layer (executors, models, structured data)\n├── embeddings-*/             # Vector embedding support\n├── examples/                 # Reference implementations and usage patterns\n└── build.gradle.kts          # Root build configuration\n```\n\n## Build & Commands\n\n### Development Commands\n\n```bash\n# Full build including tests\n./gradlew build\n\n# Build without tests\n./gradlew assemble\n\n# Run all JVM tests\n./gradlew jvmTest\n\n# Run all JS tests  \n./gradlew jsTest\n\n# Test specific module\n./gradlew :agents:agents-core:jvmTest\n\n# Run specific test class\n./gradlew jvmTest --tests \"ai.koog.agents.test.SimpleAgentMockedTest\"\n\n# Run specific test method  \n./gradlew jvmTest --tests \"ai.koog.agents.test.SimpleAgentMockedTest.test AIAgent doesn't call tools by default\"\n\n# Compile test classes only (for faster iteration)\n./gradlew jvmTestClasses jsTestClasses\n```\n\n### Development Environment\n\n- **JDK**: 17+ required for JVM target\n- **Build System**: Gradle with version catalogs for dependency management\n- **Targets**: JVM, JavaScript (Kotlin Multiplatform), WASM\n- **IDE**: IntelliJ IDEA recommended with Kotlin plugin\n\n## Code Style\n\n- Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html)\n- Use four spaces for indentation (consistent across all files)\n- Name test functions as `testXxx` (no backticks for readability)\n- Use descriptive variable and function names\n- Prefer functional programming patterns where appropriate\n- Use type-safe builders and DSLs for configuration\n- Document public APIs with KDoc comments\n- NEVER suppress compiler warnings without a good reason\n\n## Quality Gates\nRead and follow the Quality Gates section in /TESTING.md before considering any code change complete.\n\n## Architecture\n\n### Core Framework Components\n\n**AIAgent** — Main orchestrator that executes strategies in coroutine scopes, manages tools via ToolRegistry,\nruns features through AIAgentPipeline, and handles LLM communication via PromptExecutor.\n\n**AIAgentStrategy** — Graph-based execution logic that defines workflows as subgraphs with start/finish nodes,\nmanages tool selection strategy, and handles termination/error reporting.\n\n**ToolRegistry** — Centralized, type-safe tool management using a builder pattern: `ToolRegistry { tool(MyTool()) }`.\nSupports registry merging with `+` operator.\n\n**AIAgentFeature** — Extensible capabilities installed into AIAgentPipeline with configuration.\nFeatures have unique storage keys and can intercept agent lifecycle events.\n\n### Module Organization\n\n1. **agents-core**: Core abstractions (`AIAgent`, `AIAgentStrategy`, `AIAgentEnvironment`)\n2. **agents-tools**: Tool infrastructure (`Tool<TArgs, TResult>`, `ToolRegistry`, `AIAgentTool`)\n3. **agents-features-***: Feature implementations (memory, tracing, event handling)\n4. **agents-mcp**: Model Context Protocol integration\n5. **prompt-***: LLM interaction layer (executors, models, structured data)\n6. **embeddings-***: Vector embedding support\n7. **examples**: Reference implementations and usage patterns\n\n### Key Architectural Patterns\n\n- **State Machine Graphs**: Agents execute as node graphs with typed edges\n- **Feature Pipeline**: Extensible behavior via installable features with lifecycle hooks\n- **Environment Abstraction**: Safe tool execution context preventing direct tool calls\n- **Type Safety**: Generics ensure compile-time correctness for tool arguments/results\n- **Builder Patterns**: Fluent APIs for configuration throughout the framework\n\n## Testing\n\nThe framework provides comprehensive testing utilities in `agents-test` module:\n\n### LLM Response Mocking\n\n```kotlin\nval mockLLMApi = getMockExecutor(toolRegistry, eventHandler) {\n    mockLLMAnswer(\"Hello!\") onRequestContains \"Hello\"\n    mockLLMToolCall(CreateTool, CreateTool.Args(\"solve\")) onRequestEquals \"Solve task\"\n    mockLLMAnswer(\"Default response\").asDefaultResponse\n}\n```\n\n### Tool Behavior Mocking\n\n```kotlin\n// Simple return value\nmockTool(PositiveToneTool) alwaysReturns \"The text has a positive tone.\"\n\n// With additional actions\nmockTool(NegativeToneTool) alwaysTells {\n    println(\"Tool called\")\n    \"The text has a negative tone.\"\n}\n\n// Conditional responses\nmockTool(SearchTool) returns SearchTool.Result(\"Found\") onArgumentsMatching {\n    args.query.contains(\"important\")\n}\n```\n\n### Graph Structure Testing\n\n```kotlin\nAIAgent(...) {\n    withTesting()\n\n    testGraph(\"test\") {\n        val firstSubgraph = assertSubgraphByName<String, String>(\"first\")\n        val secondSubgraph = assertSubgraphByName<String, String>(\"second\")\n\n        assertEdges {\n            startNode() alwaysGoesTo firstSubgraph\n            firstSubgraph alwaysGoesTo secondSubgraph\n        }\n\n        verifySubgraph(firstSubgraph) {\n            val askLLM = assertNodeByName<String, Message.Response>(\"callLLM\")\n            assertNodes {\n                askLLM withInput \"Hello\" outputs Message.Assistant(\"Hello!\")\n            }\n        }\n    }\n}\n```\n\nFor comprehensive testing examples, see `agents/agents-test/TESTING.md`.\n\n## Security\n\n### API Key Management\n\n- **NEVER** commit API keys or secrets to the repository\n- Use environment variables for all sensitive configuration\n- Store test API keys in a local environment only\n- Required environment variables for integration tests:\n    - `ANTHROPIC_API_TEST_KEY`\n    - `GEMINI_API_TEST_KEY`\n    - `MISTRAL_AI_API_TEST_KEY`\n    - `OLLAMA_IMAGE_URL`\n    - `OPEN_AI_API_TEST_KEY`\n    - `OPEN_ROUTER_API_TEST_KEY`\n\n### Tool Execution Safety\n\n- Tools execute within controlled `AIAgentEnvironment` contexts\n- Direct tool calls are prevented outside agent execution\n- Use type-safe tool arguments to prevent injection attacks\n- Validate all external inputs in tool implementations\n\n### Dependency Security\n\n- Regularly update dependencies using Gradle version catalogs\n- Use specific version ranges to avoid supply chain attacks\n- Review dependencies for known vulnerabilities\n- Follow the principle of the least privilege in tool implementations\n\n## Configuration\n\n### Environment Setup\n\nSet environment variables for integration testing (never commit API keys):\n\n```bash\n# Export in your shell or IDE run configuration\nexport ANTHROPIC_API_TEST_KEY=your_key_here\nexport DEEPSEEK_API_TEST_KEY=your_key_here\nexport GEMINI_API_TEST_KEY=your_key_here\nexport MISTRAL_AI_API_TEST_KEY=your_key_here\nexport OLLAMA_IMAGE_URL=http://localhost:11434\nexport OPEN_AI_API_TEST_KEY=your_key_here\nexport OPEN_ROUTER_API_TEST_KEY=your_key_here\n\n# Or add to ~/.bashrc, ~/.zshrc, or IDE environment variables\n```\n\n### Gradle Configuration\n\n- Uses version catalogs (`gradle/libs.versions.toml`) for dependency management\n- Multiplatform configuration in `build.gradle.kts`\n- Test configuration supports both JVM and JS targets\n\n### Development Environment Requirements\n\n- **JDK**: 17+ (OpenJDK recommended)\n- **IDE**: IntelliJ IDEA with Kotlin Multiplatform plugin\n- **Optional**: Docker for Ollama local testing\n\n## Development Workflow\n\n### Branch Strategy\n\n- **develop**: All development (features and bug fixes)\n- **main**: Released versions only\n- Base all PRs against `develop` branch\n- Use descriptive branch names: `feature/agent-memory`, `fix/tool-registry-bug`\n\n### Code Quality\n\n- **ALWAYS** run `./gradlew build` before submitting PRs\n- Ensure all tests pass on JVM, JS, WASM targets\n- Follow established patterns in existing code\n- Add tests for new functionality\n- Update documentation for API changes\n\n### Commit Guidelines\n\n- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`\n- Include issue references where applicable\n- Keep commits focused and atomic\n"},"files":{"AGENTS.md":"# Koog AI Agent Framework\n\nKoog is a Kotlin multiplatform framework for building AI agents with graph-based workflows.\nIt supports JVM and JS targets and integrates with multiple LLM providers\n(OpenAI, Anthropic, Google, OpenRouter, Ollama) and Model Context Protocol (MCP).\n\n## Project Structure\n\nThe project follows a modular architecture with a clear separation of concerns:\n\n```\nkoog/\n├── agents/\n│   ├── agents-core/           # Core abstractions (AIAgent, AIAgentStrategy, AIAgentEnvironment)\n│   ├── agents-tools/          # Tool infrastructure (Tool<TArgs, TResult>, ToolRegistry, AIAgentTool)\n│   ├── agents-features-*/     # Feature implementations (memory, tracing, event handling)\n│   ├── agents-mcp/           # Model Context Protocol integration\n│   └── agents-test/          # Testing utilities and framework\n├── prompt-*/                 # LLM interaction layer (executors, models, structured data)\n├── embeddings-*/             # Vector embedding support\n├── examples/                 # Reference implementations and usage patterns\n└── build.gradle.kts          # Root build configuration\n```\n\n## Build & Commands\n\n### Development Commands\n\n```bash\n# Full build including tests\n./gradlew build\n\n# Build without tests\n./gradlew assemble\n\n# Run all JVM tests\n./gradlew jvmTest\n\n# Run all JS tests  \n./gradlew jsTest\n\n# Test specific module\n./gradlew :agents:agents-core:jvmTest\n\n# Run specific test class\n./gradlew jvmTest --tests \"ai.koog.agents.test.SimpleAgentMockedTest\"\n\n# Run specific test method  \n./gradlew jvmTest --tests \"ai.koog.agents.test.SimpleAgentMockedTest.test AIAgent doesn't call tools by default\"\n\n# Compile test classes only (for faster iteration)\n./gradlew jvmTestClasses jsTestClasses\n```\n\n### Development Environment\n\n- **JDK**: 17+ required for JVM target\n- **Build System**: Gradle with version catalogs for dependency management\n- **Targets**: JVM, JavaScript (Kotlin Multiplatform), WASM\n- **IDE**: IntelliJ IDEA recommended with Kotlin plugin\n\n## Code Style\n\n- Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html)\n- Use four spaces for indentation (consistent across all files)\n- Name test functions as `testXxx` (no backticks for readability)\n- Use descriptive variable and function names\n- Prefer functional programming patterns where appropriate\n- Use type-safe builders and DSLs for configuration\n- Document public APIs with KDoc comments\n- NEVER suppress compiler warnings without a good reason\n\n## Quality Gates\nRead and follow the Quality Gates section in /TESTING.md before considering any code change complete.\n\n## Architecture\n\n### Core Framework Components\n\n**AIAgent** — Main orchestrator that executes strategies in coroutine scopes, manages tools via ToolRegistry,\nruns features through AIAgentPipeline, and handles LLM communication via PromptExecutor.\n\n**AIAgentStrategy** — Graph-based execution logic that defines workflows as subgraphs with start/finish nodes,\nmanages tool selection strategy, and handles termination/error reporting.\n\n**ToolRegistry** — Centralized, type-safe tool management using a builder pattern: `ToolRegistry { tool(MyTool()) }`.\nSupports registry merging with `+` operator.\n\n**AIAgentFeature** — Extensible capabilities installed into AIAgentPipeline with configuration.\nFeatures have unique storage keys and can intercept agent lifecycle events.\n\n### Module Organization\n\n1. **agents-core**: Core abstractions (`AIAgent`, `AIAgentStrategy`, `AIAgentEnvironment`)\n2. **agents-tools**: Tool infrastructure (`Tool<TArgs, TResult>`, `ToolRegistry`, `AIAgentTool`)\n3. **agents-features-***: Feature implementations (memory, tracing, event handling)\n4. **agents-mcp**: Model Context Protocol integration\n5. **prompt-***: LLM interaction layer (executors, models, structured data)\n6. **embeddings-***: Vector embedding support\n7. **examples**: Reference implementations and usage patterns\n\n### Key Architectural Patterns\n\n- **State Machine Graphs**: Agents execute as node graphs with typed edges\n- **Feature Pipeline**: Extensible behavior via installable features with lifecycle hooks\n- **Environment Abstraction**: Safe tool execution context preventing direct tool calls\n- **Type Safety**: Generics ensure compile-time correctness for tool arguments/results\n- **Builder Patterns**: Fluent APIs for configuration throughout the framework\n\n## Testing\n\nThe framework provides comprehensive testing utilities in `agents-test` module:\n\n### LLM Response Mocking\n\n```kotlin\nval mockLLMApi = getMockExecutor(toolRegistry, eventHandler) {\n    mockLLMAnswer(\"Hello!\") onRequestContains \"Hello\"\n    mockLLMToolCall(CreateTool, CreateTool.Args(\"solve\")) onRequestEquals \"Solve task\"\n    mockLLMAnswer(\"Default response\").asDefaultResponse\n}\n```\n\n### Tool Behavior Mocking\n\n```kotlin\n// Simple return value\nmockTool(PositiveToneTool) alwaysReturns \"The text has a positive tone.\"\n\n// With additional actions\nmockTool(NegativeToneTool) alwaysTells {\n    println(\"Tool called\")\n    \"The text has a negative tone.\"\n}\n\n// Conditional responses\nmockTool(SearchTool) returns SearchTool.Result(\"Found\") onArgumentsMatching {\n    args.query.contains(\"important\")\n}\n```\n\n### Graph Structure Testing\n\n```kotlin\nAIAgent(...) {\n    withTesting()\n\n    testGraph(\"test\") {\n        val firstSubgraph = assertSubgraphByName<String, String>(\"first\")\n        val secondSubgraph = assertSubgraphByName<String, String>(\"second\")\n\n        assertEdges {\n            startNode() alwaysGoesTo firstSubgraph\n            firstSubgraph alwaysGoesTo secondSubgraph\n        }\n\n        verifySubgraph(firstSubgraph) {\n            val askLLM = assertNodeByName<String, Message.Response>(\"callLLM\")\n            assertNodes {\n                askLLM withInput \"Hello\" outputs Message.Assistant(\"Hello!\")\n            }\n        }\n    }\n}\n```\n\nFor comprehensive testing examples, see `agents/agents-test/TESTING.md`.\n\n## Security\n\n### API Key Management\n\n- **NEVER** commit API keys or secrets to the repository\n- Use environment variables for all sensitive configuration\n- Store test API keys in a local environment only\n- Required environment variables for integration tests:\n    - `ANTHROPIC_API_TEST_KEY`\n    - `GEMINI_API_TEST_KEY`\n    - `MISTRAL_AI_API_TEST_KEY`\n    - `OLLAMA_IMAGE_URL`\n    - `OPEN_AI_API_TEST_KEY`\n    - `OPEN_ROUTER_API_TEST_KEY`\n\n### Tool Execution Safety\n\n- Tools execute within controlled `AIAgentEnvironment` contexts\n- Direct tool calls are prevented outside agent execution\n- Use type-safe tool arguments to prevent injection attacks\n- Validate all external inputs in tool implementations\n\n### Dependency Security\n\n- Regularly update dependencies using Gradle version catalogs\n- Use specific version ranges to avoid supply chain attacks\n- Review dependencies for known vulnerabilities\n- Follow the principle of the least privilege in tool implementations\n\n## Configuration\n\n### Environment Setup\n\nSet environment variables for integration testing (never commit API keys):\n\n```bash\n# Export in your shell or IDE run configuration\nexport ANTHROPIC_API_TEST_KEY=your_key_here\nexport DEEPSEEK_API_TEST_KEY=your_key_here\nexport GEMINI_API_TEST_KEY=your_key_here\nexport MISTRAL_AI_API_TEST_KEY=your_key_here\nexport OLLAMA_IMAGE_URL=http://localhost:11434\nexport OPEN_AI_API_TEST_KEY=your_key_here\nexport OPEN_ROUTER_API_TEST_KEY=your_key_here\n\n# Or add to ~/.bashrc, ~/.zshrc, or IDE environment variables\n```\n\n### Gradle Configuration\n\n- Uses version catalogs (`gradle/libs.versions.toml`) for dependency management\n- Multiplatform configuration in `build.gradle.kts`\n- Test configuration supports both JVM and JS targets\n\n### Development Environment Requirements\n\n- **JDK**: 17+ (OpenJDK recommended)\n- **IDE**: IntelliJ IDEA with Kotlin Multiplatform plugin\n- **Optional**: Docker for Ollama local testing\n\n## Development Workflow\n\n### Branch Strategy\n\n- **develop**: All development (features and bug fixes)\n- **main**: Released versions only\n- Base all PRs against `develop` branch\n- Use descriptive branch names: `feature/agent-memory`, `fix/tool-registry-bug`\n\n### Code Quality\n\n- **ALWAYS** run `./gradlew build` before submitting PRs\n- Ensure all tests pass on JVM, JS, WASM targets\n- Follow established patterns in existing code\n- Add tests for new functionality\n- Update documentation for API changes\n\n### Commit Guidelines\n\n- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`\n- Include issue references where applicable\n- Keep commits focused and atomic\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Koog AI Agent Framework\n\nKoog is a Kotlin multiplatform framework for building AI agents with graph-based workflows.\nIt supports JVM and JS targets and integrates with multiple LLM providers\n(OpenAI, Anthropic, Google, OpenRouter, Ollama) and Model Context Protocol (MCP).\n\n## Project Structure\n\nThe project follows a modular architecture with a clear separation of concerns:\n\n```\nkoog/\n├── agents/\n│   ├── agents-core/           # Core abstractions (AIAgent, AIAgentStrategy, AIAgentEnvironment)\n│   ├── agents-tools/          # Tool infrastructure (Tool<TArgs, TResult>, ToolRegistry, AIAgentTool)\n│   ├── agents-features-*/     # Feature implementations (memory, tracing, event handling)\n│   ├── agents-mcp/           # Model Context Protocol integration\n│   └── agents-test/          # Testing utilities and framework\n├── prompt-*/                 # LLM interaction layer (executors, models, structured data)\n├── embeddings-*/             # Vector embedding support\n├── examples/                 # Reference implementations and usage patterns\n└── build.gradle.kts          # Root build configuration\n```\n\n## Build & Commands\n\n### Development Commands\n\n```bash\n# Full build including tests\n./gradlew build\n\n# Build without tests\n./gradlew assemble\n\n# Run all JVM tests\n./gradlew jvmTest\n\n# Run all JS tests  \n./gradlew jsTest\n\n# Test specific module\n./gradlew :agents:agents-core:jvmTest\n\n# Run specific test class\n./gradlew jvmTest --tests \"ai.koog.agents.test.SimpleAgentMockedTest\"\n\n# Run specific test method  \n./gradlew jvmTest --tests \"ai.koog.agents.test.SimpleAgentMockedTest.test AIAgent doesn't call tools by default\"\n\n# Compile test classes only (for faster iteration)\n./gradlew jvmTestClasses jsTestClasses\n```\n\n### Development Environment\n\n- **JDK**: 17+ required for JVM target\n- **Build System**: Gradle with version catalogs for dependency management\n- **Targets**: JVM, JavaScript (Kotlin Multiplatform), WASM\n- **IDE**: IntelliJ IDEA recommended with Kotlin plugin\n\n## Code Style\n\n- Follow [Kotlin Coding Conventions](https://kotlinlang.org/docs/coding-conventions.html)\n- Use four spaces for indentation (consistent across all files)\n- Name test functions as `testXxx` (no backticks for readability)\n- Use descriptive variable and function names\n- Prefer functional programming patterns where appropriate\n- Use type-safe builders and DSLs for configuration\n- Document public APIs with KDoc comments\n- NEVER suppress compiler warnings without a good reason\n\n## Quality Gates\nRead and follow the Quality Gates section in /TESTING.md before considering any code change complete.\n\n## Architecture\n\n### Core Framework Components\n\n**AIAgent** — Main orchestrator that executes strategies in coroutine scopes, manages tools via ToolRegistry,\nruns features through AIAgentPipeline, and handles LLM communication via PromptExecutor.\n\n**AIAgentStrategy** — Graph-based execution logic that defines workflows as subgraphs with start/finish nodes,\nmanages tool selection strategy, and handles termination/error reporting.\n\n**ToolRegistry** — Centralized, type-safe tool management using a builder pattern: `ToolRegistry { tool(MyTool()) }`.\nSupports registry merging with `+` operator.\n\n**AIAgentFeature** — Extensible capabilities installed into AIAgentPipeline with configuration.\nFeatures have unique storage keys and can intercept agent lifecycle events.\n\n### Module Organization\n\n1. **agents-core**: Core abstractions (`AIAgent`, `AIAgentStrategy`, `AIAgentEnvironment`)\n2. **agents-tools**: Tool infrastructure (`Tool<TArgs, TResult>`, `ToolRegistry`, `AIAgentTool`)\n3. **agents-features-***: Feature implementations (memory, tracing, event handling)\n4. **agents-mcp**: Model Context Protocol integration\n5. **prompt-***: LLM interaction layer (executors, models, structured data)\n6. **embeddings-***: Vector embedding support\n7. **examples**: Reference implementations and usage patterns\n\n### Key Architectural Patterns\n\n- **State Machine Graphs**: Agents execute as node graphs with typed edges\n- **Feature Pipeline**: Extensible behavior via installable features with lifecycle hooks\n- **Environment Abstraction**: Safe tool execution context preventing direct tool calls\n- **Type Safety**: Generics ensure compile-time correctness for tool arguments/results\n- **Builder Patterns**: Fluent APIs for configuration throughout the framework\n\n## Testing\n\nThe framework provides comprehensive testing utilities in `agents-test` module:\n\n### LLM Response Mocking\n\n```kotlin\nval mockLLMApi = getMockExecutor(toolRegistry, eventHandler) {\n    mockLLMAnswer(\"Hello!\") onRequestContains \"Hello\"\n    mockLLMToolCall(CreateTool, CreateTool.Args(\"solve\")) onRequestEquals \"Solve task\"\n    mockLLMAnswer(\"Default response\").asDefaultResponse\n}\n```\n\n### Tool Behavior Mocking\n\n```kotlin\n// Simple return value\nmockTool(PositiveToneTool) alwaysReturns \"The text has a positive tone.\"\n\n// With additional actions\nmockTool(NegativeToneTool) alwaysTells {\n    println(\"Tool called\")\n    \"The text has a negative tone.\"\n}\n\n// Conditional responses\nmockTool(SearchTool) returns SearchTool.Result(\"Found\") onArgumentsMatching {\n    args.query.contains(\"important\")\n}\n```\n\n### Graph Structure Testing\n\n```kotlin\nAIAgent(...) {\n    withTesting()\n\n    testGraph(\"test\") {\n        val firstSubgraph = assertSubgraphByName<String, String>(\"first\")\n        val secondSubgraph = assertSubgraphByName<String, String>(\"second\")\n\n        assertEdges {\n            startNode() alwaysGoesTo firstSubgraph\n            firstSubgraph alwaysGoesTo secondSubgraph\n        }\n\n        verifySubgraph(firstSubgraph) {\n            val askLLM = assertNodeByName<String, Message.Response>(\"callLLM\")\n            assertNodes {\n                askLLM withInput \"Hello\" outputs Message.Assistant(\"Hello!\")\n            }\n        }\n    }\n}\n```\n\nFor comprehensive testing examples, see `agents/agents-test/TESTING.md`.\n\n## Security\n\n### API Key Management\n\n- **NEVER** commit API keys or secrets to the repository\n- Use environment variables for all sensitive configuration\n- Store test API keys in a local environment only\n- Required environment variables for integration tests:\n    - `ANTHROPIC_API_TEST_KEY`\n    - `GEMINI_API_TEST_KEY`\n    - `MISTRAL_AI_API_TEST_KEY`\n    - `OLLAMA_IMAGE_URL`\n    - `OPEN_AI_API_TEST_KEY`\n    - `OPEN_ROUTER_API_TEST_KEY`\n\n### Tool Execution Safety\n\n- Tools execute within controlled `AIAgentEnvironment` contexts\n- Direct tool calls are prevented outside agent execution\n- Use type-safe tool arguments to prevent injection attacks\n- Validate all external inputs in tool implementations\n\n### Dependency Security\n\n- Regularly update dependencies using Gradle version catalogs\n- Use specific version ranges to avoid supply chain attacks\n- Review dependencies for known vulnerabilities\n- Follow the principle of the least privilege in tool implementations\n\n## Configuration\n\n### Environment Setup\n\nSet environment variables for integration testing (never commit API keys):\n\n```bash\n# Export in your shell or IDE run configuration\nexport ANTHROPIC_API_TEST_KEY=your_key_here\nexport DEEPSEEK_API_TEST_KEY=your_key_here\nexport GEMINI_API_TEST_KEY=your_key_here\nexport MISTRAL_AI_API_TEST_KEY=your_key_here\nexport OLLAMA_IMAGE_URL=http://localhost:11434\nexport OPEN_AI_API_TEST_KEY=your_key_here\nexport OPEN_ROUTER_API_TEST_KEY=your_key_here\n\n# Or add to ~/.bashrc, ~/.zshrc, or IDE environment variables\n```\n\n### Gradle Configuration\n\n- Uses version catalogs (`gradle/libs.versions.toml`) for dependency management\n- Multiplatform configuration in `build.gradle.kts`\n- Test configuration supports both JVM and JS targets\n\n### Development Environment Requirements\n\n- **JDK**: 17+ (OpenJDK recommended)\n- **IDE**: IntelliJ IDEA with Kotlin Multiplatform plugin\n- **Optional**: Docker for Ollama local testing\n\n## Development Workflow\n\n### Branch Strategy\n\n- **develop**: All development (features and bug fixes)\n- **main**: Released versions only\n- Base all PRs against `develop` branch\n- Use descriptive branch names: `feature/agent-memory`, `fix/tool-registry-bug`\n\n### Code Quality\n\n- **ALWAYS** run `./gradlew build` before submitting PRs\n- Ensure all tests pass on JVM, JS, WASM targets\n- Follow established patterns in existing code\n- Add tests for new functionality\n- Update documentation for API changes\n\n### Commit Guidelines\n\n- Use conventional commit format: `feat:`, `fix:`, `docs:`, `test:`\n- Include issue references where applicable\n- Keep commits focused and atomic\n","category":"root","tokens":2120}]}