09 · 配置（Configuration）

启用 Embabel（Enabling Embabel）

给你的 Spring Boot 应用类加上注解，就能获得智能体行为。

示例：

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

这就是一个普通的 Spring Boot 应用类，你可以按需再加其它 Spring Boot 注解。

另外，你还需要为你选用的 LLM 提供方添加相应依赖与配置。

配置属性（Configuration Properties）

下表列出 Embabel Agent Platform 的全部可用配置属性。属性按其配置前缀组织，并给出适用时的默认值。 它们可以按标准 Spring 配置实践，通过 application.properties、application.yml、profile 专属配置文件或环境变量来设置。

默认 LLM 与角色（Setting default LLM and roles）

来自 ConfigurableModelProviderProperties —— 默认 LLM 与基于角色的模型选择配置。

属性	类型	默认值	说明
embabel.models.default-llm	String	gpt-4.1-mini	默认 LLM 名称。建议在配置里覆盖它。
embabel.models.default-embedding-model	String	null	默认 embedding 模型名。可以不设置，此时为 null。
embabel.models.llms	Map	{}	"角色 → LLM 名称"的映射。每一项都要求已注册同名 LLM。可以不包含默认 LLM。
embabel.models.embedding-services	Map	{}	"角色 → embedding 服务名"的映射。不必包含默认 embedding 服务。角色数量随你定义。

基于角色的模型选择，让你可以把特定的 LLM 或 embedding 服务分配给应用中的不同角色。例如：

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

用这种方式把代码与具体模型解耦，是推荐做法。

平台配置（Platform Configuration）

来自 AgentPlatformProperties —— 所有 Agent 平台属性的统一配置。

属性	类型	默认值	说明
embabel.agent.platform.name	String	embabel-default	平台核心标识名
embabel.agent.platform.description	String	Embabel Default Agent Platform	平台描述

日志人格（Logging Personality）

用于配置 Agent 日志输出的风格与主题。

属性	类型	默认值	说明
embabel.agent.logging.personality	String	（无）	主题化的日志文案，为 Agent 输出增添人格

可用的人格取值：

取值	说明
starwars	星球大战主题的日志文案
severance	《人生切割术》主题 —— Praise Kier
colossus	《巨人：福宾计划》主题文案
hitchhiker	《银河系漫游指南》主题文案
montypython	蒙提·派森主题日志文案

配置示例：

embabel:
  agent:
    logging:
      personality: hitchhiker

Agent 扫描（Agent Scanning）

来自 AgentPlatformProperties.ScanningConfig —— 配置对 classpath 中 Agent 的扫描。

属性	类型	默认值	说明
embabel.agent.platform.scanning.annotation	Boolean	true	是否自动注册带 @Agent 与 @Agentic 注解的 bean
embabel.agent.platform.scanning.bean	Boolean	false	是否把类型为 Agent 的 Spring bean 自动注册为 Agent

规划器配置（Planner Configuration）

控制 GOAP 规划器在启动期间如何处理带注解的 Agent。

属性	类型	默认值	说明
embabel.agent.platform.planner.restricted-goals	Boolean	false	为 false（默认）时，允许 @Agent 声明多个返回不同类型的 @AchievesGoal 动作，从而让规划器用互斥的 @Condition 来门控这些动作。为 true 时，所有 @AchievesGoal 动作必须收敛到同一个唯一返回类型；违反此约束的 @Agent 会在启动时被拒绝。

示例 —— 显式开启严格单目标限制：

embabel:
  agent:
    platform:
      planner:
        restricted-goals: true

排序配置（Ranking Configuration）

来自 AgentPlatformProperties.RankingConfig —— 当平台需要选择 Agent 或目标时，基于用户输入对 Agent 与目标进行排序的配置。

属性	类型	默认值	说明
embabel.agent.platform.ranking.llm	String	null	用于排序的 LLM 名称；为 null 时使用自动选择
embabel.agent.platform.ranking.max-attempts	Int	5	排序重试的最大尝试次数
embabel.agent.platform.ranking.backoff-millis	Long	100	初始退避时间（毫秒）
embabel.agent.platform.ranking.backoff-multiplier	Double	5.0	退避时间倍数
embabel.agent.platform.ranking.backoff-max-interval	Long	180000	最大退避时间（毫秒）

LLM 操作（LLM Operations）

来自 AgentPlatformProperties.LlmOperationsConfig —— 包括提示词与数据绑定的 LLM 操作配置。

属性	类型	默认值	说明
embabel.agent.platform.llm-operations.prompts.maybe-prompt-template	String	maybe_prompt_contribution	"maybe" 提示词所用模板，使 LLM 信息不足时可以返回失败结果
embabel.agent.platform.llm-operations.prompts.generate-examples-by-default	Boolean	true	是否默认生成示例
embabel.agent.platform.llm-operations.data-binding.max-attempts	Int	10	数据绑定的最大重试次数
embabel.agent.platform.llm-operations.data-binding.fixed-backoff-millis	Long	30	重试之间的固定退避时间（毫秒）

工具循环（Tool Loop）

来自 ToolLoopConfiguration —— 工具循环执行的配置。

属性	类型	默认值	说明
embabel.agent.platform.toolloop.type	String	default	工具循环类型：default（顺序）或 parallel（实验性）
embabel.agent.platform.toolloop.max-iterations	Int	20	工具循环的最大迭代次数
embabel.agent.platform.toolloop.parallel.per-tool-timeout	Duration	30s	并行模式下单个工具执行的超时
embabel.agent.platform.toolloop.parallel.batch-timeout	Duration	60s	整批并行工具的超时
embabel.agent.platform.toolloop.empty-response.max-retries	Int	0	抛出 EmptyLlmResponseException 之前，允许的连续空响应重试次数。0（默认）保持既有行为 —— 循环以空白内容退出。任何大于 0 的值都会启用 RetryWithFeedbackPolicy。
embabel.agent.platform.toolloop.empty-response.nudge-message	String	（见下）	当 LLM 沉默时，作为合成 UserMessage 追加到对话中的消息。仅在 max-retries > 0 时使用。默认值会推动模型采取一个具体行动。

空响应处理（Empty-Response Handling）

较弱的开放权重对话模型（例如 gpt-oss-20b 或部分 Qwen 变体），在拿到工具结果之后、 当模型对下一步该做什么"没想法"时，偶尔会返回空白文本且不再发起工具调用。

如果不加干预，工具循环会以空内容退出，渲染层最终把它暴露为 EmptyLlmResponseException。

空响应配置控制是否给模型第二次机会。 设置 max-retries: 1 会启用 RetryWithFeedbackPolicy：检测到空响应时，循环会把配置的"提醒消息"作为合成 UserMessage 追加进去， 并在同一个循环迭代中重新调用 LLM。重试计数在任何非空响应时都会重置， 因此重试是针对连续失败有界的，而不是在整个循环里累计。

下面是运行较小对话模型时的部署示例：

embabel:
  agent:
    platform:
      toolloop:
        max-iterations: 30       # 调大一些，给重试留出余量
        empty-response:
          max-retries: 1         # 抛异常前先提醒一次

对大多数使用强前沿模型的部署来说，默认值（max-retries: 0）就是对的 —— 空响应很罕见，而类型化异常让调用方可以显式处理这种情况。 提供这个设置，是为了让小模型 / 本地模型的部署更健壮，而不必强迫每个调用方都把自己的 LLM 调用包在重试逻辑里。

若要以编程方式配置（自定义重试次数或文案），请注入你自己的 EmptyResponsePolicy bean —— 自动配置遵循 @ConditionalOnMissingBean。

进程 ID 生成（Process ID Generation）

来自 AgentPlatformProperties.ProcessIdGenerationConfig —— 进程 ID 生成的配置。

属性	类型	默认值	说明
embabel.agent.platform.process-id-generation.include-version	Boolean	false	进程 ID 中是否包含版本
embabel.agent.platform.process-id-generation.include-agent-name	Boolean	false	进程 ID 中是否包含 Agent 名称

自主性配置（Autonomy Configuration）

来自 AgentPlatformProperties.AutonomyConfig —— 配置 Agent 与目标选择的阈值。 低于阈值的确定性（certainty）会导致选择 Agent 或目标失败。

属性	类型	默认值	说明
embabel.agent.platform.autonomy.agent-confidence-cut-off	Double	0.6	Agent 操作的置信度阈值
embabel.agent.platform.autonomy.goal-confidence-cut-off	Double	0.6	目标达成的置信度阈值

模型提供方配置（Model Provider Configuration）

来自 AgentPlatformProperties.ModelsConfig —— 各模型提供方的集成配置。

Anthropic

属性	类型	默认值	说明
embabel.agent.platform.models.anthropic.max-attempts	Int	10	最大重试次数
embabel.agent.platform.models.anthropic.backoff-millis	Long	5000	初始退避时间（毫秒）
embabel.agent.platform.models.anthropic.backoff-multiplier	Double	5.0	退避倍数
embabel.agent.platform.models.anthropic.backoff-max-interval	Long	180000	最大退避间隔（毫秒）

OpenAI

属性	类型	默认值	说明
embabel.agent.platform.models.openai.max-attempts	Int	10	最大重试次数
embabel.agent.platform.models.openai.backoff-millis	Long	5000	初始退避时间（毫秒）
embabel.agent.platform.models.openai.backoff-multiplier	Double	5.0	退避倍数
embabel.agent.platform.models.openai.backoff-max-interval	Long	180000	最大退避间隔（毫秒）

Google GenAI（原生）

使用原生 Google GenAI SDK（spring-ai-google-genai）直接访问 Gemini 模型并支持全部特性。

属性	类型	默认值	说明
embabel.agent.platform.models.googlegenai.max-attempts	Int	10	最大重试次数
embabel.agent.platform.models.googlegenai.backoff-millis	Long	5000	初始退避时间（毫秒）
embabel.agent.platform.models.googlegenai.backoff-multiplier	Double	5.0	退避倍数
embabel.agent.platform.models.googlegenai.backoff-max-interval	Long	180000	最大退避间隔（毫秒）

Google GenAI 的模型（LLM 与 embedding）通过 embabel-agent-starter-google-genai 依赖来配置。

可用的 embedding 模型如下：

模型名	模型 ID	维度	价格（每 100 万 token）
gemini_embedding_001	gemini-embedding-001	3072	$0.15

以下环境变量控制认证：

环境变量	说明
GOOGLE_API_KEY	Google AI Studio 认证所用的 API key
GOOGLE_PROJECT_ID	Google Cloud 项目 ID（用于 Vertex AI 认证）
GOOGLE_LOCATION	Google Cloud 区域，例如 us-central1（用于 Vertex AI 认证）

必须设置 GOOGLE_API_KEY，或者同时设置 GOOGLE_PROJECT_ID 与 GOOGLE_LOCATION。

Gemini 3 模型在 Vertex AI 上仅在全球（global）区域可用。 要用 Vertex AI 跑 Gemini 3，必须设置 GOOGLE_LOCATION=global。

要新增 Google GenAI embedding 模型，请编辑配置文件：

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

OCI Generative AI

OCI Generative AI 的模型通过 embabel-agent-starter-oci-genai 依赖配置。 该 starter 会从内置元数据注册 OCI 的 chat 与 embedding 模型，并使用 OCI Java SDK 的认证提供方。

当 classpath 上没有标准 OpenAI 提供方时，OCI starter 会为 Embabel 的默认 LLM 与 embedding 模型提供 OCI 默认值：

embabel.models.default-llm=cohere.command-a-03-2025
embabel.models.default-embedding-model=cohere.embed-v4.0

想换用其它 OCI 模型，就在应用配置里覆盖这些值。Embabel 的模型选择使用 OCI 的 model id。 该 starter 的 Spring bean 名是 Java 友好的别名，例如 cohere_command_a 对应 cohere.command-a-03-2025， llama_33_70b 对应 meta.llama-3.3-70b-instruct。

属性	类型	默认值	说明
embabel.agent.platform.models.ocigenai.authentication-type	Enum	FILE	使用的认证提供方。支持 FILE、INSTANCE_PRINCIPAL、RESOURCE_PRINCIPAL、WORKLOAD_IDENTITY、SESSION_TOKEN、SIMPLE。
embabel.agent.platform.models.ocigenai.config-file	String	~/.oci/config	FILE 认证的 OCI 配置文件路径；SESSION_TOKEN 认证时也可选填。
embabel.agent.platform.models.ocigenai.profile	String	DEFAULT	OCI 配置 profile 名。
embabel.agent.platform.models.ocigenai.region	String	（无）	OCI region id，例如 us-chicago-1。未显式设置 endpoint 时使用。
embabel.agent.platform.models.ocigenai.endpoint	String	（无）	显式的 OCI Generative AI 推理 endpoint URL。会覆盖基于 region 的 endpoint 选择。
embabel.agent.platform.models.ocigenai.compartment-id	String	（无）	chat 与 embedding 请求所用的 OCI compartment OCID。必填。
embabel.agent.platform.models.ocigenai.serving-mode	Enum	ON_DEMAND	OCI 服务模式。支持 ON_DEMAND 与 DEDICATED。
embabel.agent.platform.models.ocigenai.endpoint-id	String	（无）	专用服务 endpoint 的 OCID。serving-mode 为 DEDICATED 时必填。
embabel.agent.platform.models.ocigenai.tenant-id	String	（无）	SIMPLE、SESSION_TOKEN 或 workload identity 配置所需的 tenancy OCID。
embabel.agent.platform.models.ocigenai.user-id	String	（无）	SIMPLE 或基于 builder 的 SESSION_TOKEN 认证所需 user OCID。
embabel.agent.platform.models.ocigenai.fingerprint	String	（无）	SIMPLE 或基于 builder 的 SESSION_TOKEN 认证所用 API key 指纹。
embabel.agent.platform.models.ocigenai.private-key	String	（无）	SIMPLE 认证所用的 PEM 私钥内容。尽可能优先用 private-key-file。
embabel.agent.platform.models.ocigenai.private-key-file	String	（无）	SIMPLE 或基于 builder 的 SESSION_TOKEN 认证所用 PEM 私钥文件路径。
embabel.agent.platform.models.ocigenai.pass-phrase	String	（无）	若配置的私钥已加密，这里是私钥口令。
embabel.agent.platform.models.ocigenai.session-token	String	（无）	基于 builder 的 SESSION_TOKEN 认证所用 session token 值。
embabel.agent.platform.models.ocigenai.session-token-file	String	（无）	基于 builder 的 SESSION_TOKEN 认证所用 session token 文件路径。
embabel.agent.platform.models.ocigenai.workload-identity-token-path	String	（无）	WORKLOAD_IDENTITY 认证的 workload identity token 路径。
embabel.agent.platform.models.ocigenai.federation-endpoint	String	（无）	基于 principal 的认证可选 federation endpoint。
embabel.agent.platform.models.ocigenai.max-attempts	Int	10	OCI GenAI 请求的最大重试次数。
embabel.agent.platform.models.ocigenai.backoff-millis	Long	5000	初始重试退避（毫秒）。
embabel.agent.platform.models.ocigenai.backoff-multiplier	Double	5.0	重试退避倍数。
embabel.agent.platform.models.ocigenai.backoff-max-interval	Long	180000	最大重试退避间隔（毫秒）。

⚠️ 如果你的应用暴露了 Spring Boot Actuator 的 env 或 configprops，请保护这些端点， 并对 pass-phrase、session-token、private-key 这类 OCI 凭据属性名做脱敏。

HTTP 客户端配置（HTTP Client Configuration）

来自 NettyClientFactoryProperties —— 模型提供方（OpenAI、Anthropic 等）发起 API 调用时所用 HTTP 客户端的配置。

Embabel 使用 Reactor Netty 作为 HTTP 客户端，以获得更好的性能与非阻塞 I/O。 这对响应时间可能很长的 LLM API 调用尤为重要。

依赖要求：要使用 Netty 客户端，你必须手动把下面的自动配置依赖加入项目：

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

Gradle 写法：

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

属性	类型	默认值	说明
embabel.agent.platform.http-client.connect-timeout	Duration	25s	与模型提供方建立 HTTP 连接的超时
embabel.agent.platform.http-client.read-timeout	Duration	1m	接收模型提供方响应的读超时（响应超时）。对生成长回复的模型、或使用扩展思考（extended thinking）特性时，请调大该值。

配置示例：

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

对启用了扩展思考的模型（例如开启 thinking 模式的 Claude），建议把 read-timeout 调到 10m 或更高，以容纳更长的处理时间。

何时需要调整超时：

• 长耗时的 LLM 调用：复杂推理任务中出现超时错误时，调大 read-timeout；
• 慢网络环境：连接建立失败时，调大 connect-timeout；
• 流式响应：read-timeout 作用于初始响应；流式内容有自己的处理逻辑。

该 HTTP 客户端配置适用于所有使用 Spring RestClient 与 WebClient 的模型提供方， 包括 OpenAI、Anthropic 以及 OpenAI 兼容端点。

Server-Sent Events

来自 AgentPlatformProperties.SseConfig —— 服务端推送事件配置。

属性	类型	默认值	说明
embabel.agent.platform.sse.max-buffer-size	Int	100	SSE 的最大缓冲区大小
embabel.agent.platform.sse.max-process-buffers	Int	1000	进程缓冲区的最大数量

REST 端点（REST Endpoints）

来自 AgentPlatformProperties.RestConfig —— 平台内置 REST 端点的开关。 每个标志控制对应端点是否暴露。关闭时，对应的 controller bean 不会被注册， 因此该端点不会出现在 Swagger/OpenAPI 文档中，路由也会拒绝调用 （HTTP 404；若同一路径上还有其它方法被映射，则为 HTTP 405）。

属性	类型	默认值	说明
embabel.agent.platform.rest.process-status-enabled	Boolean	true	是否暴露 GET /api/v1/process/{id}（进程状态）
embabel.agent.platform.rest.process-kill-enabled	Boolean	true	是否暴露 DELETE /api/v1/process/{id}（终止进程）
embabel.agent.platform.rest.process-events-enabled	Boolean	true	是否暴露 GET /events/process/{id}（SSE 事件流）。关闭时不注册该 SSE controller。

测试配置（Test Configuration）

来自 AgentPlatformProperties.TestConfig —— 测试配置。

属性	类型	默认值	说明
embabel.agent.platform.test.mock-mode	Boolean	true	是否启用测试用的 mock 模式

进程仓库配置（Process Repository Configuration）

来自 ProcessRepositoryProperties —— Agent 进程仓库的配置。

属性	类型	默认值	说明
embabel.agent.platform.process-repository.window-size	Int	1000	使用默认 InMemoryAgentProcessRepository 时，内存中保留的 Agent 进程最大数量。超出时会淘汰最旧的进程。

独立 LLM 配置（Standalone LLM Configuration）

LLM 操作提示词 —— 来自 LlmOperationsPromptsProperties，用于 ChatClientLlmOperations 操作的属性。

属性	类型	默认值	说明
embabel.llm-operations.prompts.maybe-prompt-template	String	maybe_prompt_contribution	"maybe" 提示词所用模板；当 LLM 信息不足以产出目标结构时，可据此返回失败结果
embabel.llm-operations.prompts.generate-examples-by-default	Boolean	true	是否默认生成示例
embabel.llm-operations.prompts.default-timeout	Duration	60s	操作的默认超时

LLM 数据绑定 —— 来自 LlmDataBindingProperties，带重试配置的 LLM 数据绑定属性。

属性	类型	默认值	说明
embabel.llm-operations.data-binding.max-attempts	Int	10	数据绑定的最大重试次数
embabel.llm-operations.data-binding.fixed-backoff-millis	Long	30	重试之间的固定退避时间（毫秒）

其它模型提供方（Additional Model Providers）

AWS Bedrock —— 来自 BedrockProperties。

属性	类型	默认值	说明
embabel.models.bedrock.models	List	[]	要配置的 Bedrock 模型列表
embabel.models.bedrock.models[].name	String	""	模型名称
embabel.models.bedrock.models[].knowledge-cutoff	String	""	知识截止日期
embabel.models.bedrock.models[].input-price	Double	0.0	输入 token 价格
embabel.models.bedrock.models[].output-price	Double	0.0	输出 token 价格

ONNX Embeddings —— 来自 OnnxEmbeddingProperties，本地 ONNX embedding 模型的配置。

属性	类型	默认值	说明
embabel.agent.platform.models.onnx.embeddings.enabled	Boolean	true	是否启用 ONNX embedding 服务
embabel.agent.platform.models.onnx.embeddings.model-uri	String	（HuggingFace all-MiniLM-L6-v2）	ONNX 模型文件的 URI（HuggingFace URL 或 file:// 路径）
embabel.agent.platform.models.onnx.embeddings.tokenizer-uri	String	（HuggingFace all-MiniLM-L6-v2）	tokenizer JSON 文件的 URI
embabel.agent.platform.models.onnx.embeddings.dimensions	Int	384	embedding 维度
embabel.agent.platform.models.onnx.embeddings.model-name	String	all-MiniLM-L6-v2	embedding 模型的名称
embabel.agent.platform.models.onnx.embeddings.cache-dir	String	~/.embabel/models	下载的模型文件的本地缓存目录

Docker 本地模型 —— 来自 DockerProperties，Docker 本地模型（OpenAI 兼容）的配置。

属性	类型	默认值	说明
embabel.docker.models.base-url	String	http://localhost:12434/engines	Docker 模型端点的 base URL
embabel.docker.models.max-attempts	Int	10	最大重试次数
embabel.docker.models.backoff-millis	Long	2000	初始退避时间（毫秒）
embabel.docker.models.backoff-multiplier	Double	5.0	退避倍数
embabel.docker.models.backoff-max-interval	Long	180000	最大退避间隔（毫秒）