# How to Deploy Embabel-Agent: Spring Boot AI Deployment Guide
> Deploy embabel-agent easily with this Spring Boot AI deployment guide. Add the starter dependency, configure your API key, and run locally or via Docker.
- Repository: [Embabel/embabel-agent](https://github.com/embabel/embabel-agent)
- Tags: how-to-guide
- Published: 2026-08-14
---
**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`](https://github.com/embabel/embabel-agent/blob/main/pom.xml). The `embabel-agent-starter` artifact pulls in the agent platform, auto-configuration, and default tooling required to run the application.
```xml
com.embabel.agent
embabel-agent-starter
${embabel-agent.version}
```
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.
```text
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.
```bash
./mvnw spring-boot:run
```
For a packaged deployment, build the JAR and execute:
```bash
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.
```xml
com.embabel.agent
emabel-agent-starter-shell
```
After adding the dependency, run `./mvnw spring-boot:run` to launch directly into the shell interface. Execute commands like:
```text
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`](https://github.com/embabel/embabel-agent/blob/main/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:
```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:
```bash
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.
```xml
com.embabel.agent
embabel-agent-starter-ollama
```
This configuration is defined in the starter documentation at [`embabel-agent-starters/embel-agent-starter-ollama/README.md`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-starters/embel-agent-starter-ollama/README.md).
## Configure Platform Settings
Fine-tune the deployment through YAML configuration in [`application.yml`](https://github.com/embabel/embabel-agent/blob/main/application.yml). The `AgentPlatform` interface in [`embabel-agent-api/src/main/kotlin/com/embabel/agent/AgentPlatform.kt`](https://github.com/embabel/embabel-agent/blob/main/embabel-agent-api/src/main/kotlin/com/embabel/agent/AgentPlatform.kt) supports observability and MCP client customization.
Enable Zipkin tracing:
```yaml
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:
```xml
io.opentelemetry
opentelemetry-exporter-zipkin
```
## Testing Before Deployment
Validate your configuration before production deployment. Unit tests require no network connectivity:
```bash
mvn test
```
Run integration tests to verify provider connectivity while excluding Ollama-specific tests:
```bash
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`](https://github.com/embabel/embabel-agent/blob/main/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.