{"id":36702288,"url":"https://github.com/embabel/embabel-agent-examples","last_synced_at":"2026-01-12T11:39:23.137Z","repository":{"id":301239936,"uuid":"999967708","full_name":"embabel/embabel-agent-examples","owner":"embabel","description":"Agent Framework Examples for Java and Kotlin Developers","archived":false,"fork":false,"pushed_at":"2025-12-19T05:07:56.000Z","size":599,"stargazers_count":133,"open_issues_count":4,"forks_count":43,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-12-22T01:36:00.520Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/embabel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-11T04:28:50.000Z","updated_at":"2025-12-22T00:14:06.000Z","dependencies_parsed_at":"2025-06-25T21:36:48.756Z","dependency_job_id":"c30bb76e-e6a6-4890-9fda-9966930a2d92","html_url":"https://github.com/embabel/embabel-agent-examples","commit_stats":null,"previous_names":["embabel/embabel-agent-examples"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/embabel/embabel-agent-examples","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embabel%2Fembabel-agent-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embabel%2Fembabel-agent-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embabel%2Fembabel-agent-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embabel%2Fembabel-agent-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/embabel","download_url":"https://codeload.github.com/embabel/embabel-agent-examples/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/embabel%2Fembabel-agent-examples/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28338971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T10:58:46.209Z","status":"ssl_error","status_checked_at":"2026-01-12T10:58:42.742Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-12T11:39:22.471Z","updated_at":"2026-01-12T11:39:23.128Z","avatar_url":"https://github.com/embabel.png","language":"Java","funding_links":[],"categories":["Examples"],"sub_categories":[],"readme":"# 🤖 Embabel Agent Examples\n\n\u003cimg align=\"left\" src=\"https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/images/315px-Meister_der_Weltenchronik_001.jpg?raw=true\" width=\"180\"\u003e\n\n\n![Build](https://github.com/embabel/embabel-agent-examples/actions/workflows/maven.yml/badge.svg)\n\n[//]: # ([![Quality Gate Status]\u0026#40;https://sonarcloud.io/api/project_badges/measure?project=embabel_embabel-agent\u0026metric=alert_status\u0026token=d275d89d09961c114b8317a4796f84faf509691c\u0026#41;]\u0026#40;https://sonarcloud.io/summary/new_code?id=embabel_embabel-agent\u0026#41;)\n\n[//]: # ([![Bugs]\u0026#40;https://sonarcloud.io/api/project_badges/measure?project=embabel_embabel-agent\u0026metric=bugs\u0026#41;]\u0026#40;https://sonarcloud.io/summary/new_code?id=embabel_embabel-agent\u0026#41;)\n\n![Kotlin](https://img.shields.io/badge/kotlin-%237F52FF.svg?style=for-the-badge\u0026logo=kotlin\u0026logoColor=white)\n![Java](https://img.shields.io/badge/java-%23ED8B00.svg?style=for-the-badge\u0026logo=openjdk\u0026logoColor=white)\n![Spring](https://img.shields.io/badge/spring-%236DB33F.svg?style=for-the-badge\u0026logo=spring\u0026logoColor=white)\n![Apache Tomcat](https://img.shields.io/badge/apache%20tomcat-%23F8DC75.svg?style=for-the-badge\u0026logo=apache-tomcat\u0026logoColor=black)\n![Apache Maven](https://img.shields.io/badge/Apache%20Maven-C71A36?style=for-the-badge\u0026logo=Apache%20Maven\u0026logoColor=white)\n![ChatGPT](https://img.shields.io/badge/chatGPT-74aa9c?style=for-the-badge\u0026logo=openai\u0026logoColor=white)\n![Jinja](https://img.shields.io/badge/jinja-white.svg?style=for-the-badge\u0026logo=jinja\u0026logoColor=black)\n![JSON](https://img.shields.io/badge/JSON-000?logo=json\u0026logoColor=fff)\n![GitHub Actions](https://img.shields.io/badge/github%20actions-%232671E5.svg?style=for-the-badge\u0026logo=githubactions\u0026logoColor=white)\n![SonarQube](https://img.shields.io/badge/SonarQube-black?style=for-the-badge\u0026logo=sonarqube\u0026logoColor=4E9BCD)\n![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![IntelliJ IDEA](https://img.shields.io/badge/IntelliJIDEA-000000.svg?style=for-the-badge\u0026logo=intellij-idea\u0026logoColor=white)\n\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n\n**English** · [简体中文](./README.zh-CN.md)\n\nLearn agentic AI development with **Spring Framework** and **Java** or **Kotlin**. These examples demonstrate building\nintelligent agents that can plan, execute workflows, use tools, and interact with humans.\n\n\u003e This repository uses the latest Embabel snapshots to illustrate current best practice, whereas\n\u003e the [Java](https://github.com/embabel/java-agent-template)\n\u003e and [Kotlin](https://github.com/embabel/kotlin-agent-template)\n\u003e template repositories s use the latest milestone release for greater stability.\n\u003e There may be some minor API incompatilibites and not everything you see here may work in your own project created\n\u003e from one of those templates, unless you upgrade the `embabel-agent.version` property in the POM file, as in this\n\u003e repository.\n\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- **Java 21+**\n- **API Key** (at least one): [OpenAI](https://platform.openai.com/api-keys)\n  or [Anthropic](https://www.anthropic.com/api)\n- **Maven 3.9+** (optional - project includes Maven wrapper)\n\n### 1. Clone \u0026 Build\n\n```bash\ngit clone https://github.com/embabel/embabel-agent-examples.git\ncd embabel-agent-examples\n./mvnw clean install    # Unix/Linux/macOS\nmvnw.cmd clean install  # Windows\n```\n\n### 2. Set API Keys\n\n```bash\n# Required (choose one or both)\nexport OPENAI_API_KEY=\"your_openai_key\"\nexport ANTHROPIC_API_KEY=\"your_anthropic_key\"\n\n```\n\n### 3. Run Examples\n\n#### **Kotlin Examples**\n\n```bash\ncd scripts/kotlin\n./shell.sh                    # Unix/Linux/macOS - With Docker tools (default)\nshell.cmd                     # Windows - With Docker tools (default)\n\n./shell.sh --no-docker-tools  # Unix/Linux/macOS - Basic features only\nshell.cmd --no-docker-tools   # Windows - Basic features only\n```\n\n#### **Java Examples**\n\n```bash\ncd scripts/java\n./shell.sh                    # Unix/Linux/macOS - With Docker tools (default)\nshell.cmd                     # Windows - With Docker tools (default)\n\n./shell.sh --no-docker-tools  # Unix/Linux/macOS - Basic features only\nshell.cmd --no-docker-tools   # Windows - Basic features only\n```\n\n---\n\n### Creating Your Own Project\n\nYou can create your own agent repo from our [Java](https://github.com/embabel/java-agent-template)\nor [Kotlin](https://github.com/embabel/kotlin-agent-template) GitHub template by clicking the \"Use this template\"\nbutton.\n\nYou can also create your own Embabel agent project locally with our quick start tool, which allows some customization:\n\n```\nuvx --from git+https://github.com/embabel/project-creator.git project-creator\n```\n\nChoose Java or Kotlin and specify your project name and package name and you'll have an agent running in under a minute,\nif you already have an `OPENAI_API_KEY` and have Maven installed.\n\n## 🆕 **Spring Boot Integration Architecture**\n\n### **Embabel Agent Starter Guide:**\n\n#### **`embabel-agent-starter`**\n\n- ✅ Application decides on startup mode (console, web application, etc)\n- ✅ Agent discovery and registration\n- ✅ Agent Platform beans are available via Dependency Injection mechanism for Application to use as needed\n- ✅ Progress tracking and logging\n- ✅ Development-friendly error handling\n\n#### **`embabel-agent-starter-shell`**\n\n- ✅ Interactive command-line interface\n- ✅ Agent discovery and registration\n- ✅ Human-in-the-loop capabilities\n- ✅ Progress tracking and logging\n- ✅ Development-friendly error handling\n\n#### **`embabel-agent-starter-mcpserver`**\n\n- ✅ MCP protocol server implementation\n- ✅ Tool registration and discovery\n- ✅ JSON-RPC communication via SSE (Server-Sent Events)\n- ✅ Integration with MCP-compatible clients\n- ✅ Security and sandboxing\n\n### **Application Examples**\n\n#### Shell Mode with Logging Theme\n\n```kotlin\n@SpringBootApplication\n@ConfigurationPropertiesScan(basePackages = [\"com.embabel.example\"])\nclass KotlinAgentShellApplication\n\nfun main(args: Array\u003cString\u003e) {\n    runApplication\u003cKotlinAgentShellApplication\u003e(*args) {\n        setDefaultProperties(\n            mapOf(\"embabel.agent.logging.personality\" to LoggingThemes.STAR_WARS)\n        )\n    }\n}\n```\n\n```java\n// Java version\n@SpringBootApplication\n@ConfigurationPropertiesScan(basePackages = {\"com.embabel.example\"})\npublic class JavaAgentShellApplication {\n    public static void main(String[] args) {\n        SpringApplication app = new SpringApplication(JavaAgentShellApplication.class);\n        app.setDefaultProperties(Map.of(\n            \"embabel.agent.logging.personality\", LoggingThemes.STAR_WARS\n        ));\n        app.run(args);\n    }\n}\n```\n\n#### Shell Mode with MCP Client Support (Docker Tools)\n\n```kotlin\n@SpringBootApplication\n@ConfigurationPropertiesScan(basePackages = [\"com.embabel.example\"])\nclass KotlinAgentShellApplication\n\nfun main(args: Array\u003cString\u003e) {\n    runApplication\u003cKotlinAgentShellApplication\u003e(*args) {\n        setAdditionalProfiles(McpServers.DOCKER)  // Activates application-docker-ce.yml\n        setDefaultProperties(\n            mapOf(\"embabel.agent.logging.personality\" to LoggingThemes.SEVERANCE)\n        )\n    }\n}\n```\n\n#### MCP Server Mode\n\n```kotlin\n@SpringBootApplication\n@ConfigurationPropertiesScan(basePackages = [\"com.embabel.example\"])\nclass KotlinAgentMcpServerApplication\n\nfun main(args: Array\u003cString\u003e) {\n    runApplication\u003cKotlinAgentMcpServerApplication\u003e(*args) {\n        setAdditionalProfiles(McpServers.DOCKER, McpServers.DOCKER_DESKTOP)\n    }\n}\n```\n\n### **Configuration Guide**\n\n#### Logging Personality\n\nSet via the `embabel.agent.logging.personality` property:\n\n- `\"starwars\"` - May the Force be with your logs!\n- `\"severance\"` - Welcome to Lumon Industries (default)\n\n#### MCP Client Integration\n\nConfigure via Spring profiles that define Spring AI MCP client connections in `application-{profile}.yml`:\n\n```yaml\n# application-docker-ce.yml\nspring:\n  ai:\n    mcp:\n      client:\n        type: SYNC\n        stdio:\n          connections:\n            docker-mcp:\n              command: docker\n              args: [mcp, gateway, run]\n```\n\n---\n\n## Setting up MCP Tools\n\nSeveral of the examples use the Model Context Protocol (MCP) to access tools and services.\n\nThe default source is the Docker Desktop MCP server, which is installed with Docker Desktop.\n\nTo ensure tools are available and startup doesn't time out, first pull models with:\n\n```bash\ndocker login\ndocker mcp gateway run\n```\n\nWhen the gateway has come up you can kill it and start the Embabel server.\n\n## 📚 Examples by Learning Level\n\n### 🏆 **Beginner: InjectedComponent**\n\n\u003e **Available in:** Java | **Concept:** Just a Little AI\n\nDemonstrates how you can inject any Spring component with an Embabel `OperationContext`\nand use it to call LLMs with the rich Embabel API.\n\n```java\n\n@Component\npublic record InjectedComponent(Ai ai) {\n\n    public record Joke(String leadup, String punchline) {\n    }\n\n    public String tellJokeAbout(String topic) {\n        return ai\n                .withDefaultLlm()\n                .generateText(\"Tell me a joke about \" + topic);\n    }\n\n    public Joke createJokeObjectAbout(String topic1, String topic2, String voice) {\n        return ai\n                .withLlm(LlmOptions.withDefaultLlm().withTemperature(.8))\n                .createObject(\"\"\"\n                                Tell me a joke about %s and %s.\n                                The voice of the joke should be %s.\n                                The joke should have a leadup and a punchline.\n                                \"\"\".formatted(topic1, topic2, voice),\n                        Joke.class);\n    }\n\n}\n```\n\n### 🌟 **Beginner: Horoscope News Agent**\n\n\u003e **Available in:** Java \u0026 Kotlin | **Concept:** Basic Agent Workflow\n\nA fun introduction to agent development that finds personalized news based on someone's star sign.\n\n**What It Teaches:**\n\n- 📋 **Action-based workflows** with `@Action` annotations\n- 🔍 **Data extraction** from user input using LLMs\n- 🌐 **Web tool integration** for finding news stories\n- 📝 **Content generation** with personality and context\n- 🎯 **Goal achievement** with `@AchievesGoal`\n\n**How It Works:**\n\n1. Extract person's name from user input\n2. Get their star sign (via form if needed)\n3. Retrieve daily horoscope\n4. Search web for relevant news stories\n5. Create amusing writeup combining horoscope + news\n\n**Try It:**\n\nStart the agent shell, then type:\n\n```bash\nx \"Find horoscope news for Alice who is a Gemini\"\n```\n\n`x` is short for `execute`, which triggers the agent to run its workflow.\n\n**Code Comparison:**\n\n- **Kotlin:** `examples-kotlin/src/main/kotlin/com/embabel/example/horoscope/StarNewsFinder.kt`\n- **Java:** `examples-java/src/main/java/com/embabel/example/horoscope/StarNewsFinder.java`\n\n**Key Patterns:**\n\n```kotlin\n@Agent(description = \"Find news based on a person's star sign\")\nclass StarNewsFinder {\n\n    @Action\n    fun extractPerson(userInput: UserInput, context: OperationContext): Person?\n\n    @Action(toolGroups = [CoreToolGroups.WEB])\n    fun findNewsStories(person: StarPerson, horoscope: Horoscope, context: OperationContext): RelevantNewsStories\n\n    @AchievesGoal(description = \"Create an amusing writeup\")\n    @Action\n    fun starNewsWriteup(/* params */): Writeup\n}\n```\n\n---\n\n### 🔬 **Expert: Multi-LLM Research Agent**\n\n\u003e **Available in:** Java, Kotlin | **Concept:** Self-Improving AI Workflows\n\nA sophisticated research agent using multiple AI models with self-critique capabilities.\n\n**What It Teaches:**\n\n- 🧠 **Multi-model consensus** (GPT-4 + Claude working together)\n- 🔍 **Self-improvement loops** with critique and retry\n- ⚙️ **Configuration-driven behavior** with Spring Boot properties\n- 🌊 **Parallel processing** of research tasks\n- 📝 **Quality control** through automated review\n\n**Architecture:**\n\n```kotlin\n@ConfigurationProperties(prefix = \"embabel.examples.researcher\")\ndata class ResearcherProperties(\n    val maxWordCount: Int = 300,\n    val claudeModelName: String = AnthropicModels.CLAUDE_35_HAIKU,\n    val openAiModelName: String = OpenAiModels.GPT_41_MINI\n)\n```\n\n**Self-Improvement Pattern:**\n\n```kotlin\n@Action(outputBinding = \"gpt4Report\")\nfun researchWithGpt4(/* params */): SingleLlmReport\n\n@Action(outputBinding = \"claudeReport\")\nfun researchWithClaude(/* params */): SingleLlmReport\n\n@Action(outputBinding = \"mergedReport\")\nfun mergeReports(gpt4: SingleLlmReport, claude: SingleLlmReport): ResearchReport\n\n@Action\nfun critiqueReport(report: ResearchReport): Critique\n\n@AchievesGoal(description = \"Completes research with quality assurance\")\nfun acceptReport(report: ResearchReport, critique: Critique): ResearchReport\n```\n\n**Try It:**\n\n```bash\n\"Research the latest developments in renewable energy adoption\"\n```\n\n**Location:** `examples-kotlin/src/main/kotlin/com/embabel/example/researcher/`\n\n---\n\n### ✅ **Expert: Fact-Checking Agent (DSL Style)**\n\n\u003e **Available in:** Kotlin | **Concept:** Functional Agent Construction\n\nA fact-verification agent built using Embabel's functional DSL approach instead of annotations.\n\n**What It Teaches:**\n\n- 🔧 **Functional DSL construction** for agents\n- 🔍 **Parallel fact verification** across multiple claims\n- 📊 **Confidence scoring** and source trust evaluation\n- 🌐 **Web research integration** for verification\n- ⚡ **Functional programming patterns** in agent design\n\n**DSL Construction:**\n\n```kotlin\nfun factCheckerAgent(llms: List\u003cLlmOptions\u003e, properties: FactCheckerProperties) =\n    agent(name = \"FactChecker\", description = \"Check content for factual accuracy\") {\n\n        flow {\n            aggregate\u003cUserInput, FactualAssertions, RationalizedFactualAssertions\u003e(\n                transforms = llms.map { llm -\u003e\n                    { context -\u003e /* extract assertions with this LLM */ }\n                },\n                merge = { list, context -\u003e /* rationalize overlapping claims */ }\n            )\n        }\n\n        transformation\u003cRationalizedFactualAssertions, FactCheck\u003e {\n            /* parallel fact-checking */\n        }\n    }\n```\n\n**Domain Model:**\n\n```kotlin\ndata class FactualAssertion(\n    val claim: String,\n    val reasoning: String\n)\n\ndata class AssertionCheck(\n    val assertion: FactualAssertion,\n    val isFactual: Boolean,\n    val confidence: Double,\n    val sources: List\u003cString\u003e\n)\n```\n\n**Try It:**\n\n```bash\n\"Check these facts: The Earth is flat. Paris is the capital of France.\"\n```\n\n**Location:** `examples-kotlin/src/main/kotlin/com/embabel/example/factchecker/`\n\n---\n\n## 🛠️ Core Concepts You'll Learn\n\n### **Spring Framework Integration**\n\n- **Auto-Configuration:** Starters handle all configuration automatically\n- **Profile-Based Configuration:** MCP clients configured via Spring profiles\n- **Maven Profiles:** `enable-shell`, `enable-shell-mcp-client`, `enable-agent-mcp-server`\n- **Dependency Injection:** Constructor-based injection with agents as Spring beans\n- **Configuration Properties:** Type-safe configuration with `@ConfigurationProperties`\n- **Conditional Beans:** Environment-specific components with `@ConditionalOnBean`\n- **Repository Pattern:** Spring Data integration for domain entities\n\n### **Modern Spring Boot Patterns**\n\n- **Auto-Configuration:** Starters handle all configuration automatically\n- **Profile-Based Configuration:** MCP clients configured via Spring profiles\n- **Profile-Based Execution:** Maven profiles control which application class runs\n- **Auto-Configuration Classes:** Understanding Spring Boot's auto-configuration\n- **Conditional Configuration:** Mode-specific bean loading\n- **Theme-Based Customization:** Dynamic behavior based on properties\n\n### **Modern Kotlin Features**\n\n- **Data Classes:** Rich domain models with computed properties\n- **Type Aliases:** Domain-specific types (`typealias OneThroughTen = Int`)\n- **Extension Functions:** Enhanced functionality for existing types\n- **Delegation:** Clean composition patterns\n- **DSL Construction:** Functional agent building\n- **Coroutines:** Parallel execution with structured concurrency\n\n### **Agent Design Patterns**\n\n- **Workflow Orchestration:** Multi-step processes with `@Action` chains\n- **Blackboard Pattern:** Shared workspace for data between actions\n- **Human-in-the-Loop:** User confirmations and form submissions\n- **Self-Improvement:** Critique and retry loops for quality\n- **Multi-Model Consensus:** Combining results from different LLMs\n- **Condition-Based Flow:** Workflow control with `@Condition`\n- **Progress Tracking:** Event publishing for monitoring\n\n---\n\n### Additional Examples\n\nSome of our examples are projects in their own right, and are therefore\nin separate repositories.\n\nSee:\n\n- [Coding Agent](https://www.github.com/embabel/coding-agent): An open source coding agent\n- [Flicker](https://www.github.com/embabel/flicker): A movie recommendation engine that takes into account the user's\n  tastes and what's available to them in their country on the streaming services they subscribe to. Uses external APIs\n  and PostgreSQL via JPA. Illustrates a complex workflow where recommendations are generated until enough available\n  movies have been found.\n- [Decker](https://www.github.com/embabel/decker): An agent to build presentations using Embabel\n- [Tripper](https://www.github.com/embabel/tripper): Travel planning agent. Uses mapping APIs to find routes and places\n  of interest, and generates a travel itinerary. Performs research on points of interest in parallel.\n\n## 🔧 Running Specific Examples\n\n### **Interactive Shell Mode** (Default)\n\n```bash\ncd scripts/kotlin \u0026\u0026 ./shell.sh          # With Docker tools (default)\ncd scripts/kotlin \u0026\u0026 shell.cmd           # With Docker tools (Windows)\n# or\ncd scripts/java \u0026\u0026 ./shell.sh            # With Docker tools (default)\ncd scripts/java \u0026\u0026 shell.cmd             # With Docker tools (Windows)\n```\n\nUses Maven profile: `enable-shell-mcp-client`\n\n### **Shell Without Docker Tools**\n\n```bash\ncd scripts/kotlin \u0026\u0026 ./shell.sh --no-docker-tools     # Basic features only\ncd scripts/kotlin \u0026\u0026 shell.cmd --no-docker-tools      # Basic features (Windows)\n# or\ncd scripts/java \u0026\u0026 ./shell.sh --no-docker-tools       # Basic features only\ncd scripts/java \u0026\u0026 shell.cmd --no-docker-tools        # Basic features (Windows)\n```\n\nUses Maven profile: `enable-shell`\n\n### **With Observability (Zipkin Tracing)**\n\nEnable distributed tracing with Zipkin by adding the `--observability` flag:\n\n```bash\ncd scripts/kotlin \u0026\u0026 ./shell.sh --observability    # Enable observability\ncd scripts/kotlin \u0026\u0026 shell.cmd --observability     # Enable observability (Windows)\n# or\ncd scripts/java \u0026\u0026 ./shell.sh --observability      # Enable observability\ncd scripts/java \u0026\u0026 shell.cmd --observability       # Enable observability (Windows)\n```\n\nMake sure to run `docker compose up` in the project root to start Zipkin trace collector:\n\n```bash\ndocker compose up\n```\nYou should be able to access Zipkin Console: http://127.0.0.1:9411/zipkin/\n\n### **MCP Server Mode**\n\n```bash\ncd scripts/kotlin \u0026\u0026 ./mcp_server.sh\ncd scripts/kotlin \u0026\u0026 mcp_server.cmd      # Windows\n# or\ncd scripts/java \u0026\u0026 ./mcp_server.sh\ncd scripts/java \u0026\u0026 mcp_server.cmd        # Windows\n```\n\nUses Maven profile: `enable-agent-mcp-server`\n\nYou can use the Embabel agent platform as an MCP server from a\nUI like Claude Desktop. The Embabel MCP server is available over SSE.\n\nConfigure Claude Desktop as follows in your `claude_desktop_config.yml`:\n\n```json\n{\n  \"mcpServers\": {\n    \"embabel-examples\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"http://localhost:8080/sse\"\n      ]\n    }\n  }\n}\n\n```\n\nSee [MCP Quickstart for Claude Desktop Users](https://modelcontextprotocol.io/quickstart/user) for how to configure\nClaude Desktop.\n\nCreate a project in Claude Desktop to work with Embabel examples. This will\nenable you to add a custom system prompt.\n\nThe Embabel server will expose each goal as an MCP tool, enabling\nClaude Desktop to invoke them like this:\n\n\u003cimg src=\"images/Claude_Desktop_StarNews.jpg\" alt=\"Claude Desktop invoking Embabel Star News Finder Agent\" width=\"600\"/\u003e\n\n\n\nThe [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a helpful tool for interacting with your\nEmbabel\nSSE server, manually invoking tools and checking the exposed prompts and resources.\n\nStart the MCP Inspector with:\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\n### **Manual Execution**\n\n```bash\n# Kotlin shell mode with MCP client (default)\ncd examples-kotlin\nmvn -P enable-shell-mcp-client spring-boot:run\n\n# Kotlin shell mode without MCP client\ncd examples-kotlin\nmvn -P enable-shell spring-boot:run\n\n# Kotlin MCP server mode\ncd examples-kotlin  \nmvn -P enable-agent-mcp-server spring-boot:run\n\n# Java equivalents use the same pattern\ncd examples-java\nmvn -P enable-shell-mcp-client spring-boot:run\n```\n\n### **Testing**\n\n```bash\n# Run all tests\n./mvnw test             # Unix/Linux/macOS\nmvnw.cmd test           # Windows\n\n# Module-specific tests\ncd examples-kotlin \u0026\u0026 ../mvnw test\ncd examples-java \u0026\u0026 ../mvnw test\n```\n\n---\n\n## 🌐 **MCP (Model Context Protocol) Support**\n\n### **What is MCP?**\n\nMCP (Model Context Protocol) is an open protocol that enables AI assistants and applications to securely connect to data\nsources and tools. Embabel supports MCP in two ways:\n\n1. **MCP Server Mode**: Your agents become tools that can be called by MCP clients\n2. **MCP Client Support**: Your agents can call external MCP servers (like Docker Desktop)\n\n### **MCP Server Mode**\n\nRun your agents as an MCP server that exposes tools over Server-Sent Events (SSE):\n\n```bash\n# Start Kotlin agents as MCP server\ncd scripts/kotlin \u0026\u0026 ./mcp_server.sh\n\n# Start Java agents as MCP server  \ncd scripts/java \u0026\u0026 ./mcp_server.sh\n```\n\nYour agents become available as tools:\n\n- **StarNewsFinder** - `find_horoscope_news`\n- **Researcher** - `research_topic`\n- **FactChecker** - `check_facts`\n\n### **MCP Client Support**\n\nDocker tools are enabled by default. To disable:\n\n```bash\n# Disable Docker MCP integration\ncd scripts/kotlin \u0026\u0026 ./shell.sh --no-docker-tools\ncd scripts/java \u0026\u0026 ./shell.sh --no-docker-tools\n```\n\nWith Docker tools enabled, your agents can:\n\n- Execute commands in Docker containers\n- Access containerized services\n- Integrate with other MCP-compatible tools\n\n### **Benefits of MCP**\n\n- **🔄 Tool Interoperability** - Agents can use and be used as tools\n- **🎯 Domain Expertise** - Specialized agents for specific tasks\n- **🛠️ Tool Composition** - Combine multiple tools in workflows\n- **🔒 Secure Access** - MCP handles authentication and sandboxing\n- **📈 Scalable Architecture** - Add new tools without changing code\n\n---\n\n## 🎯 **Creating Your Own Agent Application**\n\n### **Basic Shell Application**\n\n```kotlin\n@SpringBootApplication\nclass MyAgentApplication\n\nfun main(args: Array\u003cString\u003e) {\n    runApplication\u003cMyAgentApplication\u003e(*args)\n}\n```\n\nAdd the shell starter to your `pom.xml`:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.embabel.agent\u003c/groupId\u003e\n    \u003cartifactId\u003eembabel-agent-starter-shell\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\n### **Shell with Theme and MCP Client**\n\n```kotlin\n@SpringBootApplication\n@ConfigurationPropertiesScan(basePackages = [\"com.example\"])\nclass MyThemedAgentApplication\n\nfun main(args: Array\u003cString\u003e) {\n    runApplication\u003cMyThemedAgentApplication\u003e(*args) {\n        setAdditionalProfiles(\"docker-ce\")  // Enable MCP client via profile\n        setDefaultProperties(\n            mapOf(\"embabel.agent.logging.personality\" to LoggingThemes.STAR_WARS)\n        )\n    }\n}\n```\n\n### **MCP Server Application**\n\n```kotlin\n@SpringBootApplication\nclass MyMcpServerApplication\n\nfun main(args: Array\u003cString\u003e) {\n    runApplication\u003cMyMcpServerApplication\u003e(*args)\n}\n```\n\nAdd the MCP server starter to your `pom.xml`:\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.embabel.agent\u003c/groupId\u003e\n    \u003cartifactId\u003eembabel-agent-starter-mcpserver\u003c/artifactId\u003e\n\u003c/dependency\u003e\n```\n\n---\n\n## 🎯 Getting Started Recommendations\n\n### **New to Agents?**\n\n1. Start with **Horoscope News Agent** (Java or Kotlin)\n2. Compare the Java vs Kotlin implementations\n3. Experiment with different prompts and see how the agent plans different workflows\n4. Try different logging themes to make development more fun!\n\n### **Spring Developer?**\n\n1. Look at the configuration classes and repository integration\n2. Study the domain model design and service composition\n3. Explore the different application modes and Maven profiles\n4. See how profiles and properties configure MCP clients\n\n### **Kotlin Enthusiast?**\n\n1. Progress to **Researcher** for multi-model patterns\n2. Explore **Fact Checker** for functional DSL approaches\n\n### **AI/ML Developer?**\n\n1. Study prompt engineering techniques in any example\n2. Examine the **Researcher** for multi-model consensus patterns\n3. Look at **Fact Checker** for confidence scoring and source evaluation\n4. Explore MCP integration for tool composition\n\n---\n\n## 🚨 Common Issues \u0026 Solutions\n\n| Problem                         | Solution                                                                                        |\n|---------------------------------|-------------------------------------------------------------------------------------------------|\n| **\"No API keys found\"**         | Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`                                                     |\n| **Wrong examples load**         | Use correct script: `kotlin/shell.sh` vs `java/shell.sh`                                        |\n| **Build failures**              | Run `./mvnw clean install` (Unix/macOS) or `mvnw.cmd clean install` (Windows) from project root |\n| **Application class not found** | Check Maven profile matches application class                                                   |\n| **MCP client fails to connect** | Check port availability and Docker Desktop status. See instructions on pulling models above.    |\n\nLook at the log output in the event of failure as it may contain hints as to the solution.\n\n---\n\n## 📁 Project Structure\n\n```\nembabel-agent-examples/\n├── examples-kotlin/                 # 🏆 Kotlin implementations\n│   ├── src/main/kotlin/com/embabel/example/\n│   │   ├── KotlinAgentShellApplication.kt       # Shell + MCP client (default)\n│   │   ├── KotlinAgentSimpleShellApplication.kt # Shell without MCP\n│   │   ├── KotlinAgentMcpServerApplication.kt   # MCP server mode  \n│   │   ├── horoscope/              # 🌟 Beginner: Star news agent\n│   ├── pom.xml                     # Maven profiles for each mode\n│   └── README.md                   # 📖 Kotlin-specific documentation\n│\n├── examples-java/                   # ☕ Java implementations  \n│   ├── src/main/java/com/embabel/example/\n│   │   ├── JavaAgentShellApplication.java       # Shell with themes\n│   │   ├── JavaAgentSimpleShellApplication.java # Shell without MCP\n│   │   ├── JavaMcpServerApplication.java        # MCP server mode\n│   │   └── horoscope/              # 🌟 Beginner: Star news agent\n│   └── README.md                   # 📖 Java-specific documentation\n│\n├── examples-common/                 # 🔧 Shared services \u0026 utilities\n├── scripts/                        # 🚀 Quick-start scripts\n│   ├── kotlin/\n│   │   ├── shell.sh               # Launch shell (--no-docker-tools to disable)\n│   │   └── mcp_server.sh          # Launch MCP server\n│   ├── java/\n│   │   ├── shell.sh               # Launch shell (--no-docker-tools to disable)\n│   │   └── mcp_server.sh          # Launch MCP server\n│   ├── support/                   # Shared script utilities\n│   └── README.md                  # 📖 Scripts documentation\n└── pom.xml                         # Parent Maven configuration\n```\n\n---\n\n## 📄 License\n\nLicensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n**🎉 Happy coding with Spring Framework and agentic AI!**\n\n### 🌟 May the Force be with your agents! 🌟\n\n## Contributors\n\n[![Embabel contributors](https://contrib.rocks/image?repo=embabel/embabel-agent-examples)](https://github.com/embabel/embabel-agent-examples/graphs/contributors)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fembabel%2Fembabel-agent-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fembabel%2Fembabel-agent-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fembabel%2Fembabel-agent-examples/lists"}