AgentCore:AgentCore Java SDK usage guide

Streaming output

Use stream for streaming output:

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

A regular call and a streaming call are two independent requests. The response structure depends on the model protocol, and the OpenAI and Anthropic protocols return different fields.

Responses API

If the model uses the OpenAI protocol and supports the Responses API, you can call responses(input, parameters) and responsesStream(input, parameters). When a Responses call fails, the SDK does not automatically fall back to Chat Completions.

Limits

The hosted model client does not provide embedding capabilities. The embedding(input, parameters) method of a direct OpenAI-compatible client applies only to services that support vector generation.

Use memory in frameworks

All three frameworks first construct a MemoryContext and then register it in their own way:

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

Automatic write-back is disabled by default. Enable it with the constructor that takes true. Write-back stores only the user input of the current turn and the final text answer of a turn that completed normally; it does not write history messages or tool results again. After you enable automatic write-back, do not manually write back the same turn. Registering only retriever() retrieves memory without writing back.

The following example integrates memory with LangChain4j:

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));

adapter.stream(...) returns an event stream. The Spring AI MemoryAdvisor applies to the ChatClient invocation chain, and does not apply to a separate flow that calls SpringAIEvents.stream directly.

For the complete example, see MemoryAdapters.java.

Step 1: Create a Maven project

Add agentcore-sdk-langchain4j and agentcore-sdk-server to pom.xml, both at version 0.1.0, and set the release of maven-compiler-plugin to 17. For the complete pom.xml, see the GitHub example at the end of this topic.

Step 2: Write the application entry point

The following code is simplified pseudo-code that outlines the application entry point. It does not compile as written. For the complete runnable source, see LangChainAgent.java.

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);

The example merges the MCP tools and the Skill tools and registers them with AiServices. If you do not use MCP or Skills, remove the corresponding loading and registration code.

LangChain4jEvents.from starts the TokenStream and converts text, tool calls, tool results, and message boundaries into service events. Do not call start() manually, and do not forward only the text callback, which would lose the tool execution process.

Step 3: Build and deploy

Build the application:

mvn -B -ntp package

Use the copy-dependencies goal of maven-dependency-plugin (-DincludeScope=runtime) to export the runtime dependencies, and put target/classes and target/dependency into the image. For the plugin configuration, see the complete pom.xml in LangChainAgent.java. Start the application in the managed environment (Linux):

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

The deployment settings on the platform side must match the code:

The default AG-UI path of Java SDK 0.1.0 is /agui. Do not copy the path from examples of SDKs in other languages.

The container image must be Linux amd64, must include /bin/bash and /bin/sh, and must be reachable and pullable from the image repository. Building a JAR alone does not mean that the image contains these components.

Code upload, image building, and deployment are not handled by the SDK.

Step 4: Verify the deployment

After the deployment completes, verify that the service is running before you call it. Send a GET /readyz request (the readiness probe) to the deployed endpoint and confirm that the service reports ready. Do not continue until the readiness check succeeds.

The example service starts only after resource initialization completes. GET /healthz (the liveness probe) does not check the state of downstream resources. To customize the readiness check, use the readiness callback of AgentCoreServer.

AG-UI

The AG-UI endpoint is POST /agui. The request body contains threadId, runId, messages, state, tools, context, and forwardedProps. threadId and runId must not be empty, and each run uses a new runId. The same conversation can reuse a threadId, but the example service does not automatically restore history. An empty tools field does not disable the tools registered in the code.

A successful response starts with RUN_STARTED and ends with RUN_FINISHED, and a failure returns RUN_ERROR. Tool calls and tool results are correlated by toolCallId.

OpenAI Chat Completions

The OpenAI Chat Completions endpoint is POST /openai/v1/chat/completions. The request body contains model, messages, and stream. A streaming response ends with data: [DONE], and stream=false returns regular JSON. The model field does not automatically switch the downstream model.

Choose a protocol

Both SSE endpoints send a heartbeat comment after 15 seconds of idle time. A heartbeat is not model output and does not indicate that generation is complete.

The framework service already runs tools on the server side, so the client must not run the tool call traces that it receives. To show the complete execution process, use the AG-UI protocol with the framework event converter.

Spring AI

The entry classes are io.agentcore.springai.AgentCoreSpringAI, SpringAIEvents, and MemoryAdvisor.

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));

Resources are loaded at initialization, and a Prompt is constructed per request at each call. Skill tools are registered in the same way. An existing ChatClient can register a MemoryAdvisor.

For the integration guide, see spring-ai.md. For an example, see SpringAIAgent.java.

AgentScope Java

The entry classes are io.agentcore.agentscope.AgentCoreAgentScope, AgentScopeEvents, and MemoryMiddleware.

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

Create a separate ReActAgent for each request and release it after the request completes, fails, or is canceled; Flux.using can wrap this pattern. To use memory, register the corresponding MemoryMiddleware.

For the integration guide, see agentscope.md. For an example, see AgentScopeAgent.java.

Reuse native framework providers

If a native model is already available, use the native provider of the framework directly and continue to register the AgentCore tool and memory adapters. For an example, see NativeFrameworkAgents.java.

Is AgentCoreServer required?

No. You can call the resource interfaces directly from an existing web service or executor. Use AgentCoreServer to reuse the protocol encapsulation.

Why does the model still not call tools after MCP or Skills are loaded?

Loading only completes the preparation. Register the tools with a framework and select a model that supports tool calling. For a simple question, the model may also decide that no tool call is needed.

Does the same session ID automatically restore history?

No. AgentCoreServer does not persist history, and multi-turn conversations are managed by the application or the framework. Memory does not replace the full conversation history.

Does automatic memory write-back store all history?

No. Write-back is disabled by default. After it is enabled, only the user input of the current turn and the final text answer are stored. The caller handles failures of explicit MemoryStore calls.

Do clients need to be closed manually?

Reuse Core within the application lifecycle, and call close() or use try-with-resources at exit. Do not close a shared Core after a single HTTP request. A reactive call runs only after it is subscribed.

How are logging and cross-origin browser access handled?

The SDK uses SLF4J, and the application configures a logging implementation such as Logback. Do not log keys or sensitive conversation content. Cross-origin access is configured by the application or the gateway with CORS rules for each origin.