AgentCore Java SDK 使用指南

前提条件

开始之前，确认以下条件已满足：

1. 已开通 AgentCore，并在 AgentCore 控制台 创建 Workspace，操作方法参见管理 Workspace。

2. 已按下表准备示例使用的资源，并确认 Agent 具有相应的访问权限。

3. 构建环境为 JDK 17 及以上、Maven 3.9 及以上。

本文示例的资源名称统一使用上表中的占位值，实际使用时替换为对应的资源名称。示例中以尖括号书写的部分（如 <工具名>、<参数名>）表示按实际调用填写的参数，以裸标识符书写的部分（如 name、baseUrl）取自所在章节的配置表。仅调用模型时，不需要准备 MCP 服务、Skill、MemoryStore 和额外凭证。

安装 SDK

SDK 发布在 Maven Central，不需要配置额外仓库。向 pom.xml 添加基础 SDK 依赖：

<dependency>
  <groupId>io.github.ai-agentcore</groupId>
  <artifactId>agentcore-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

按需添加同一 groupId 与版本的其余模块。模块分三类：基础 SDK 提供资源接口，server 模块提供协议服务，框架适配模块把资源接入具体的 Agent 框架。

框架模块会引入基础 SDK 和对应框架依赖，不需要重复声明；完整的构件坐标见 Maven Central。代码包名以 io.agentcore 开头，与 Maven groupId io.github.ai-agentcore 不同。

初始化客户端

云端资源的调用都从一个客户端实例发起。AgentCore.auto() 从 AgentCore 运行环境获取访问配置并创建该实例，业务代码中不需要填写平台访问密钥，因此云端资源示例运行在 AgentCore 托管环境内。自有模型、自有 MCP 服务和本地 Skill 不注册为平台资源，由应用提供连接配置，接入方式见接入自定义资源。

在应用生命周期内复用同一个实例，退出时调用 close() 或使用 try-with-resources；不要在单次 HTTP 请求结束后关闭共享的实例。本文后续示例统一以变量 core 指代该实例，模型、MCP、Skill、记忆与凭证的调用都在 core 的生命周期内完成，首个示例见调用云端模型。

基础 API 返回 Reactor 的 Mono 与 Flux，响应式调用必须被订阅才会执行，示例中的 block() 用于把响应式返回值取出到普通主线程。

代码示例聚焦调用结构本身，text、query、input 等变量与省略号 ... 均为占位，编写实际代码时需按上下文补全；各节末尾给出的完整示例可直接运行。

调用云端模型

调用云端模型时分别指定模型连接名和模型名，不需要手动拼接服务地址。

try (var core = AgentCore.auto()) {
    var model = core.model("my-model-connection", "my-model").block();
    var response = model.completion(
            List.of(Map.of("role", "user", "content", "用一句话介绍杭州。")),
            Map.of("temperature", 0.2)).block();
}

流式输出使用 stream：

model.stream(messages).doOnNext(System.out::println).blockLast();

普通调用与流式调用是两次独立请求，响应结构由模型协议决定，OpenAI 与 Anthropic 协议返回的字段不同。使用 OpenAI 协议时还可以调用 responses(input, parameters) 与 responsesStream(input, parameters)，前提是模型支持 Responses API。

托管模型客户端不提供 Embedding 能力。直连 OpenAI 兼容客户端的 embedding(input, parameters) 仅适用于支持向量生成的服务。

使用 MCP 工具

MCP 客户端在 core 的生命周期内使用：

var mcp = core.mcp("my-mcp").block();
mcp.listTools().block();
mcp.callTool("<工具名>", Map.of("<参数名>", "<参数值>")).block();

listTools() 只发现工具，不执行工具；callTool() 按工具名和参数发起调用。

需要模型自行选择并执行工具时，把工具注册到 Agent 框架，具体见使用 LangChain4j 构建 Agent 服务和集成其他框架。单独调用模型不会自动执行 MCP 工具。

使用 Skill

加载平台 Skill 并取出其工具：

var skill = core.skills().load("my-skill", "1.0.0").block();
skill.tools();

版本号 1.0.0 必须是已发布版本；省略版本号时解析为最新版本。同一个 core 实例会固定首次成功加载的版本，建议显式指定版本号。

本地 Skill 从目录加载：

core.skills().local(Path.of("./skills")).block();

每个 Skill 包含 SKILL.md 及其引用文件。加载多个 Skill 时，使用 io.agentcore.skill.Skill.tools(skills, workingDirectory) 统一生成工具。

使用记忆

本文用“记忆”指代长期记忆的保存与检索能力，承载该能力的资源实例统一称 MemoryStore。MemoryStore 不替代 Agent 框架的对话历史，检索结果由业务代码或框架适配器提供给模型。

写入与检索记忆：

var store = core.memory("my-memory");

var writeScope = new MemoryScope("example-user", "example-agent", "example-session");
store.addMemories(text, writeScope).block();

var readScope = new MemoryScope("example-user", "example-agent", null);
store.searchMemories(query, readScope, 5).block();

检索时把 sessionId 传为 null，表示跨会话检索。

Workspace 来自 core 的资源上下文，不需要重复传入。多用户场景必须显式设置范围，范围字段的可信来源要求见安全约束。

除写入与检索外，MemoryStore 还支持 listMemories、getMemory、updateMemory、deleteMemory、listMemorySessions 和 listMemorySessionMessages。查询会话消息需要提供会话 ID，并至少提供 userId 或 agentId。

new MemoryContext(core.memory("my-memory"), readScope, writeScope, 5);

var adapter = new MemoryAdapter(memory, true);
var assistant = AiServices.builder(Assistant.class)
        .streamingChatModel(AgentCoreLangChain4j.streamingModel(model))
        .contentRetriever(adapter.retriever())
        .build();
adapter.stream(input, () -> assistant.chat(input));

使用凭证和 MCP Header

获取托管凭证：

core.credentials().get("my-api-key").block().value();
core.credentials().get("my-mcp-header").block().asHeaders();

value() 用于获取 API Key，asHeaders() 用于获取 MCP Header。凭证值的保存与输出约束见安全约束。

为 MCP 服务绑定凭证：

core.mcp("my-mcp", "my-mcp-header", Map.of("X-Business-Id", "my-app")).block();

绑定的 Header 凭证必须允许应用到该 MCP 服务。不需要凭证时使用 core.mcp("my-mcp")；只固定 Header、不绑定凭证时，第二个参数传 null。

Header 是客户端级别的固定配置，作用于握手、工具发现和工具调用，不是每个请求的用户身份。使用时注意以下限制：

• Header 名称大小写不敏感；出现冲突时报错，不会静默覆盖。

• 不能覆盖 Authorization、平台 Header 和 MCP 保留字段。

• SDK 不会自动复制入站请求的 Header，不要修改共享客户端以切换用户身份。

接入自定义资源

自有模型、自有 MCP 服务和本地 Skill 不需要注册为平台资源，由应用提供连接配置。

core.directModel(name, URI.create(baseUrl), ModelClient.Protocol.OPENAI, headerProvider);
core.directMcp(URI.create(url), MCPClient.Transport.STREAMABLE_HTTP, headerProvider);

示例使用以下环境变量提供连接配置，上例中的 name、baseUrl 与 url 即取自该表：

直连模型同样支持 Protocol.ANTHROPIC：Base URL 不含末尾的 /v1，请求需要指定 max_tokens，认证方式按服务要求配置。直连 MCP 还支持 SSE 与 stdio 传输，其中 stdio 不承载 HTTP Header。

需要同时接入多个供应商时，可以继续使用三个框架的原生 Provider，并复用 AgentCore 的工具与记忆适配。

选择 Agent 框架

三个框架的适配模块能力范围一致，都覆盖模型、工具、执行事件与记忆适配，因此框架选择取决于应用已有的技术栈与 Agent 编排方式，而不是 SDK 侧的功能差异。已有 ChatClient 的项目可以直接注册 MemoryAdvisor 与工具回调；已有原生模型时也可以继续使用框架原生 Provider，并复用 AgentCore 的工具与记忆适配。本文的端到端流程以 LangChain4j 为例展开，其他框架的差异集中在事件转换器与记忆注册方式上。

各适配模块对应的框架版本见安装 SDK。完整的端到端步骤见使用 LangChain4j 构建 Agent 服务，Spring AI 与 AgentScope Java 的入口类与差异点见集成其他框架。

使用 LangChain4j 构建 Agent 服务

本节把云端模型、MCP 和 Skill 接入 LangChain4j，并使用 AgentCoreServer 对外提供 AG-UI 与 OpenAI Chat Completions 服务。示例服务每次只处理最新一条用户文本。AgentCoreServer 自身不持久化对话历史，本文示例也未配置 ChatMemory，因此不保存跨请求历史，多轮对话由应用或框架管理。示例未接入记忆，需要长期记忆时按使用记忆显式接入。

var model = AgentCoreLangChain4j.streamingModel(core.model(...).block());
var tools = core.mcp(...).listTools() + core.skills().load(...).tools();
var assistant = AiServices.builder(Assistant.class)
        .streamingChatModel(model)
        .tools(AgentCoreLangChain4j.tools(tools))
        .build();
new AgentCoreServer(request -> ... LangChain4jEvents.from(() -> assistant.chat(input))).start(9000);

mvn -B -ntp package

java -cp 'target/classes:target/dependency/*' App

集成其他框架

本章给出 Spring AI 与 AgentScope Java 适配的入口类与差异点，不作为端到端流程，完整步骤见各框架的集成指南。构建产物和平台侧部署配置与框架无关，见部署 Agent 服务。

var model = AgentCoreSpringAI.model(core.model(...).block());
var callbacks = mcp.listTools().stream().map(AgentCoreSpringAI::tool).toArray(ToolCallback[]::new);
var options = ToolCallingChatOptions.mutate().toolCallbacks(callbacks);
var events = SpringAIEvents.stream(model, new Prompt(prompt, options));

var model = AgentCoreAgentScope.model(...);
toolkit.registerAgentTool(AgentCoreAgentScope.tool(tool));

部署 Agent 服务

以下配置与框架无关，使用 Spring AI、LangChain4j 或 AgentScope Java 部署时同样适用。平台侧的部署配置需要与代码保持一致：

需要自定义就绪判断时使用 AgentCoreServer 的 readiness 回调。代码上传、镜像构建和部署不由 SDK 负责，需要在平台侧完成。

调用 Agent 服务

把 https://<agent-endpoint> 替换为应用的实际地址，并按需补充认证信息。该地址是 Agent 应用的地址，不是模型供应商的地址。

安全约束

以下约束适用于本文全部示例，应用上线前逐条确认：

• 凭证保护：凭证值不写入源码、日志或对外响应；自有模型的 API Key 由运行环境或密钥管理服务提供，不硬编码。

• Skill 脚本执行：Skill 中的脚本以应用进程权限执行，仅加载可信来源的 Skill；不需要命令执行能力时，设置 ALLOW_EXECUTE_COMMAND=false。

• 记忆范围字段：范围字段由可信的业务上下文提供，不应由模型任意指定，也不替代访问控制。

• 日志内容：不记录密钥和敏感对话内容。

常见问题

相关文档

• 《SDK 概述》：同系列文档。

• Java SDK 源码：SDK 实现与版本信息。

• Java SDK 示例说明：完整可运行示例说明。

• Maven Central：构件版本与依赖坐标。