How to Deploy Embabel-Agent: Spring Boot AI Deployment Guide

Deploy embabel-agent by adding the embabel-agent-starter dependency to your Spring Boot project, configuring the mandatory OPENAI_API_KEY environment variable, and executing ./mvnw spring-boot:run for local development or building a Docker image for containerized environments.

Embabel-agent is an open-source Spring Boot framework designed for building AI agents with large language models. To deploy embabel-agent successfully across development and production environments, you configure specific starter dependencies, provide API credentials, and select the appropriate runtime mode for your infrastructure.

Add the Core Dependency

Start by including the core starter in your Maven pom.xml. The embabel-agent-starter artifact pulls in the agent platform, auto-configuration, and default tooling required to run the application.

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter</artifactId>
    <version>${embabel-agent.version}</version>
</dependency>

This dependency is documented in the root README of the embabel/embabel-agent repository and serves as the foundation for all deployment scenarios.

Configure Environment Variables

Before starting the application, provide the necessary API keys as environment variables. While OPENAI_API_KEY is mandatory for cloud-based LLM interactions, additional optional keys enable alternative providers.

OPENAI_API_KEY      # mandatory for OpenAI models

ANTHROPIC_API_KEY   # optional, required for Anthropic tools

MINIMAX_API_KEY     # optional, for MiniMax models

ZAI_API_KEY         # optional, for Z‑AI models

Set these variables in your shell, Docker container, or secret management system depending on your target environment.

Choose Your Deployment Mode

The framework supports multiple runtime configurations through specialized starters. Select the mode that matches your infrastructure requirements.

Standard Spring Boot Deployment

Run embabel-agent as a conventional Spring Boot application on the default HTTP port 8080. This mode is suitable for microservices and REST API deployments.

./mvnw spring-boot:run

For a packaged deployment, build the JAR and execute:

mvn clean package
java -jar target/embabel-agent.jar

Interactive Shell Mode

Add the embel-agent-starter-shell dependency to enable an interactive CLI powered by Spring Shell. This mode is ideal for local development and debugging.

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>emabel-agent-starter-shell</artifactId>
</dependency>

After adding the dependency, run ./mvnw spring-boot:run to launch directly into the shell interface. Execute commands like:

shell:> execute "Lynda is a Scorpio, find news for her" -p -r

The -p and -r flags display prompts and raw LLM responses respectively, as documented in embabel-agent-starters/embel-agent-starter-shell/README.md.

Docker Deployment with Local LLMs

For containerized deployments using Docker-hosted models (Ollama or MCP servers), include the embabel-agent-starter-dockermodels starter. Create a Dockerfile:

FROM eclipse-temurin:21-jre
COPY target/embabel-agent.jar /app/embabel-agent.jar
ENV OPENAI_API_KEY=${OPENAI_API_KEY}
EXPOSE 8080
ENTRYPOINT ["java","-jar","/app/embabel-agent.jar"]

Build and run:

docker build -t my-embabel-agent .
docker run -p 8080:8080 -e OPENAI_API_KEY=$OPENAI_API_KEY my-embabel-agent

Ollama Local Model Mode

Deploy with local LLMs using the embabel-agent-starter-ollama starter. When present, the platform automatically detects a local Ollama endpoint at http://localhost:11434 and routes all LLM traffic there, eliminating the need for external API keys.

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-starter-ollama</artifactId>
</dependency>

This configuration is defined in the starter documentation at embabel-agent-starters/embel-agent-starter-ollama/README.md.

Configure Platform Settings

Fine-tune the deployment through YAML configuration in application.yml. The AgentPlatform interface in embabel-agent-api/src/main/kotlin/com/embabel/agent/AgentPlatform.kt supports observability and MCP client customization.

Enable Zipkin tracing:

embabel:
  agent:
    platform:
      observability:
        enabled: true
        service-name: my-agent-app
management:
  tracing:
    export:
      enabled: true
    sampling:
      probability: 1.0
zipkin:
  tracing:
    endpoint: http://localhost:9411/api/v2/spans

Add the OpenTelemetry Zipkin exporter dependency:

<dependency>
    <groupId>io.opentelemetry</groupId>
    <artifactId>opentelemetry-exporter-zipkin</artifactId>
</dependency>

Testing Before Deployment

Validate your configuration before production deployment. Unit tests require no network connectivity:

mvn test

Run integration tests to verify provider connectivity while excluding Ollama-specific tests:

mvn -Dtest='*IT,!LLMOllama*IT' test

Cloud Deployment Considerations

Because embabel-agent generates a standard Spring Boot JAR, you can deploy embabel-agent to any Java-compatible platform including Kubernetes, Google Cloud Run, or AWS Elastic Beanstalk. Ensure you:

• Set the required environment variables (OPENAI_API_KEY or alternatives) as secrets
• Expose port 8080 or configure a custom server.port
• Include the appropriate starter for your LLM provider (cloud or local)

Summary

• Core Requirement: Add embabel-agent-starter to your Maven dependencies to enable the agent platform.
• Authentication: Provide OPENAI_API_KEY as a minimum; add provider-specific keys for Anthropic, MiniMax, or Z‑AI.
• Runtime Flexibility: Choose between standard Spring Boot execution, interactive shell mode, Docker containers, or local Ollama integration.
• Observability: Configure Zipkin or Langfuse tracing through YAML properties and additional exporter dependencies.
• Testing: Execute mvn test for local validation and integration tests before cloud deployment.

Frequently Asked Questions

What is the minimum configuration required to deploy embabel-agent?

You need the embabel-agent-starter Maven dependency and the OPENAI_API_KEY environment variable set. With these two elements, you can run ./mvnw spring-boot:run to start the application on port 8080. No additional configuration is required for basic functionality.

Can I deploy embabel-agent without using OpenAI?

Yes. Add the embabel-agent-starter-ollama dependency to route all LLM calls to a local Ollama instance running at http://localhost:11434. Alternatively, include embabel-agent-starter-dockermodels to connect to Docker-hosted MCP servers or local models, eliminating the need for OpenAI API keys.

How do I enable observability in a production deployment?

Add the opentelemetry-exporter-zipkin dependency and configure embabel.agent.platform.observability.enabled: true in your application.yml. Deploy a Zipkin collector (e.g., docker run -p 9411:9411 openzipkin/zipkin) and set the endpoint URL. The platform will emit spans tracing agent execution through the AgentPlatform interface.

Which port does embabel-agent use by default?

The application starts on port 8080 by default as a standard Spring Boot application. You can override this by setting the server.port property in your configuration or through the PORT environment variable in containerized environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}