Configuration

Enabling Embabel

Annotate your Spring Boot application class to get agentic behavior.

Example:

@SpringBootApplication
public class MyAgentApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyAgentApplication.class, args);
    }
}

This is a normal Spring Boot application class. You can add other Spring Boot annotations as needed.

You also need to add the dependency and configuration for your LLM provider(s) of choice.

Configuration Properties

The following table lists all available configuration properties in Embabel Agent Platform. Properties are organized by their configuration prefix and include default values where applicable. They can be set via application.properties, application.yml, profile-specific configuration files or environment variables, as per standard Spring configuration practices.

Setting default LLM and roles

From ConfigurableModelProviderProperties - configuration for default LLMs and role-based model selection.

Role-based model selection allows you to assign specific LLMs or embedding services to different roles within your application. For example:

embabel:
  models:
    default-llm: gpt-4o-mini
    default-embedding-model: text-embedding-3-small
    llms:
      cheapest: gpt-4o-mini
      best: gpt-4o
      reasoning: o1-preview
    embedding-services:
      fast: text-embedding-3-small
      accurate: text-embedding-3-large

It’s good practice to decouple your code from specific models in this way.

Platform Configuration

From AgentPlatformProperties - unified configuration for all agent platform properties.

Logging Personality

Configuration for agent logging output style and theming.

Available Personality Values

Example Configuration

embabel:
  agent:
    logging:
      personality: hitchhiker

Agent Scanning

From AgentPlatformProperties.ScanningConfig - configures scanning of the classpath for agents.

Ranking Configuration

From AgentPlatformProperties.RankingConfig - configures ranking of agents and goals based on user input when the platform should choose the agent or goal.

LLM Operations

From AgentPlatformProperties.LlmOperationsConfig - configuration for LLM operations including prompts and data binding.

Tool Loop

From ToolLoopConfiguration - configuration for tool loop execution.

Empty-Response Handling

Weak open-weights chat models (such as gpt-oss-20b or some Qwen variants) occasionally return blank text with no further tool calls after a tool result, when the model has run out of ideas about what to do next. Without intervention the tool loop exits with empty content, which the rendering layer surfaces as EmptyLlmResponseException.

The empty-response configuration controls whether the loop gives the model a second chance. Setting max-retries: 1 activates RetryWithFeedbackPolicy: when an empty response is detected the loop appends the configured nudge message as a synthetic UserMessage and re-invokes the LLM in the same loop iteration. The retry counter is reset on any non-empty response, so retries are bounded per consecutive failure rather than cumulative across the whole loop.

Example for a deployment running a smaller chat model:

embabel:
  agent:
    platform:
      toolloop:
        max-iterations: 30        # raise to give retries headroom
        empty-response:
          max-retries: 1          # one nudge before throwing

For most deployments using strong frontier models the default (max-retries: 0) is correct — empty responses are rare, and the typed exception lets callers handle the case explicitly. This setting is provided to make small / local model deployments more robust without forcing every caller to wrap LLM invocations in their own retry logic.

For programmatic configuration (custom retry counts or messages), inject your own EmptyResponsePolicy bean — the auto-configuration honours @ConditionalOnMissingBean.

Process ID Generation

From AgentPlatformProperties.ProcessIdGenerationConfig - configuration for process ID generation.

Autonomy Configuration

From AgentPlatformProperties.AutonomyConfig - configures thresholds for agent and goal selection. Certainty below thresholds will result in failure to choose an agent or goal.

Model Provider Configuration

From AgentPlatformProperties.ModelsConfig - model provider integration configurations.

Anthropic

OpenAI

Google GenAI (Native)

Uses the native Google GenAI SDK (spring-ai-google-genai) for direct access to Gemini models with full feature support.

Google GenAI models (both LLM and embedding) are configured via the embabel-agent-starter-google-genai starter dependency.

The following embedding models are available:

The following environment variables control authentication:

To use Gemini 3 with Vertex AI, you must set GOOGLE_LOCATION=global.

To add new Google GenAI embedding models, edit the configuration file:

embabel-agent-autoconfigure/models/embabel-agent-google-genai-autoconfigure/
  src/main/resources/models/google-genai-models.yml

embedding_models:
  - name: "gemini_embedding_001"
    model_id: "gemini-embedding-001"
    display_name: "Gemini Embedding 001"
    dimensions: 3072
    pricing_model:
      usd_per1m_tokens: 0.15

HTTP Client Configuration

From NettyClientFactoryProperties - configuration for the HTTP client used by model providers (OpenAI, Anthropic, etc.) when making API calls.

Embabel uses Reactor Netty as the HTTP client for improved performance and non-blocking I/O. This is particularly important for LLM API calls which can have long response times.

Dependency Requirement

To use the Netty client, you must manually add the following autoconfiguration dependency to your project:

<dependency>
    <groupId>com.embabel.agent</groupId>
    <artifactId>embabel-agent-netty-client-autoconfigure</artifactId>
</dependency>

For Gradle:

implementation 'com.embabel.agent:embabel-agent-netty-client-autoconfigure'

Example Configuration

embabel:
  agent:
    platform:
      http-client:
        connect-timeout: 10s
        read-timeout: 10m

When to Adjust Timeouts

• Long-running LLM calls: If you experience timeout errors during complex reasoning tasks, increase read-timeout
• Slow network environments: Increase connect-timeout if connection establishment is failing
• Streaming responses: The read-timeout applies to the initial response; streaming content has its own handling

Server-Sent Events

From AgentPlatformProperties.SseConfig - server-sent events configuration.

REST Endpoints

From AgentPlatformProperties.RestConfig - toggles for the platform’s built-in REST endpoints. Each flag controls whether the corresponding endpoint is exposed. When disabled, the corresponding controller bean is not registered, so the endpoint is absent from Swagger/OpenAPI documentation and routing rejects calls (HTTP 404, or HTTP 405 if another method remains mapped at the same path).

Test Configuration

From AgentPlatformProperties.TestConfig - test configuration.

Process Repository Configuration

From ProcessRepositoryProperties - configuration for the agent process repository.

Standalone LLM Configuration

LLM Operations Prompts

From LlmOperationsPromptsProperties - properties for ChatClientLlmOperations operations.

LLM Data Binding

From LlmDataBindingProperties - data binding properties with retry configuration for LLM operations.

Additional Model Providers

AWS Bedrock

From BedrockProperties - AWS Bedrock model configuration properties.

ONNX Embeddings

From OnnxEmbeddingProperties - configuration for local ONNX embedding models.

Docker Local Models

From DockerProperties - configuration for Docker local models (OpenAI-compatible).