spring-agent-scope

About Yoke

Yoke · AgentHarness: a monolithic agent service built on Spring Boot and AgentScope Java (V2).

A Spring-based agent harness.

A yoke is the wooden frame that makes oxen and horses pull in the direction you want. Yoke does the same for models: it is the runtime layer wrapped around a model so it can do real work reliably. It turns AgentScope's agent capabilities into a ready-to-use HTTP service, so you can focus on your business logic instead of glue code:

• One endpoint for multi-turn conversations: POST /api/chat, plus POST /api/chat/stream that streams the reasoning process over SSE using the AG-UI protocol.
• A built-in get_weather tool queries current weather through the open-source Open-Meteo API (no key needed; its free tier is for non-commercial use only).
• A temporary agent is built for every request and closed afterwards; conversation history lives in a shared state store and is isolated per session.
• Models are plugged in through the official AgentScope starters: OpenAI-compatible APIs (works with DashScope, DeepSeek and others), Anthropic, Gemini and Ollama. Switching is a dependency and configuration change.
• local / test / prod profiles. In production, a missing API key fails the startup instead of shipping with an empty key.
• Virtual threads are enabled by default, for both Tomcat and Spring's default thread pool.
• Request validation: a missing message returns 400.

Getting Started

Requires JDK 25.

sdk env                         # switch to JDK 25 (if you use sdkman)
export ARK_API_KEY=...          # the local profile talks to Volcengine Ark (OpenAI-compatible)
./gradlew bootRun               # the local profile is active by default

curl -X POST localhost:8080/api/chat \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello"}'
# {"sessionId":"…","reply":"…"}

Send the returned sessionId with later requests to continue the same conversation; conversations with different sessionIds are isolated from each other. A sessionId you send yourself must follow the same rule as threadId below (letters, digits and _.-, 1 to 64 characters, not all dots), otherwise the request returns 400; a blank one is treated as missing. Run the tests with ./gradlew build.

Streaming (AG-UI)

POST /api/chat/stream speaks the AG-UI protocol: the request body is a standard RunAgentInput, and the response is a text/event-stream of AG-UI events pushed while the agent is reasoning. Use curl -N to turn off buffering:

curl -N -X POST localhost:8080/api/chat/stream \
  -H 'Content-Type: application/json' \
  -d '{"threadId": "demo", "runId": "run-1", "messages": [{"id": "msg-1", "role": "user", "content": "What is the weather in Beijing?"}]}'

Request rules (any violation returns 400 before the stream starts):

• Content-Type must be application/json, otherwise 415. This also stops a cross-site page from starting a run with a text/plain request that skips the CORS preflight
• threadId is the session ID and is required: letters, digits and _.-, 1 to 64 characters, not all dots. It shares the same history as sessionId of POST /api/chat
• runId is required and must not be blank (RunAgentInput requires it)
• messages must not be empty, every message needs an id and a role, and the last one must be a user message with non-blank plain text (multimodal content blocks are not supported)
• The server keeps the history itself and only uses the last user message. Earlier messages, tools, context, state, forwardedProps and resume are ignored, so a client cannot add tools to the agent or rewrite the history. Only the text of that message is kept: its id, toolCalls and toolCallId never reach the history, and the message ID is generated on the server. The adapter is also configured with ToolMergeMode.AGENT_ONLY, so only server-registered tools are ever used

Illustrative output (values are made up, field names come from real runs against a stub model, long fields are elided). Only data: lines are sent; the event type is the type field in the JSON, there is no SSE event: name:

data:{"type":"RUN_STARTED","threadId":"demo","runId":"…","input":{…}}

data:{"type":"TOOL_CALL_START","threadId":"demo","runId":"…","toolCallId":"call_1","toolCallName":"get_weather"}

data:{"type":"TOOL_CALL_ARGS","threadId":"demo","runId":"…","toolCallId":"call_1","delta":"{\"city\":\"Beijing\"}"}

data:{"type":"TOOL_CALL_END","threadId":"demo","runId":"…","toolCallId":"call_1"}

data:{"type":"TOOL_CALL_RESULT","threadId":"demo","runId":"…","toolCallId":"call_1","content":"\"Sunny, 25 C\"","role":"tool","messageId":"…"}

data:{"type":"TEXT_MESSAGE_START","threadId":"demo","runId":"…","messageId":"…","role":"assistant"}

data:{"type":"TEXT_MESSAGE_CONTENT","threadId":"demo","runId":"…","messageId":"…","delta":"It is sunny, 25 C."}

data:{"type":"TEXT_MESSAGE_END","threadId":"demo","runId":"…","messageId":"…"}

data:{"type":"CUSTOM","threadId":"demo","runId":"…","name":"token_usage","value":{"delta":{…},"cumulative":{"inputTokens":83,"outputTokens":27,…},"modelCall":{…}}}

data:{"type":"RUN_FINISHED","threadId":"demo","runId":"…"}

Every stream starts with RUN_STARTED, even when the agent cannot be created, and ends with either RUN_FINISHED or RUN_ERROR, never both. When the agent fails while running, the AG-UI adapter maps the exception to code (TIMEOUT_ERROR, INTERRUPTED_ERROR, INVALID_INPUT_ERROR or INTERNAL_ERROR); failures outside the adapter, such as the agent not being created, are always INTERNAL_ERROR. There is no done event and the final text is not repeated: the client concatenates TEXT_MESSAGE_CONTENT. The temporary agent is closed when the stream completes, fails or the client disconnects. The adapter's runTimeout setting is not read by AgentScope 2.0.4, so it does not limit the run time.

Breaking change The earlier private events (textDelta, toolCall, toolResult, hint, done, error) and the {"sessionId", "message"} request body of the streaming endpoint are gone. The streaming endpoint now only accepts Content-Type: application/json; requests without a Content-Type, or with text/plain or application/*+json, get 415. POST /api/chat now validates sessionId with the same rule as threadId (non-blank values like user:42 used to be accepted and now return 400); a blank sessionId still starts a new session.

Note The default in-memory state store only suits a single process, and history is lost when the service restarts. For multi-instance deployments, switch to a Redis or JDBC implementation. Concurrent requests for the same session are not serialized, so avoid sending them at the same time.

Configuration

Configuration is split by profile. The local profile is active when none is specified; switch with the SPRING_PROFILES_ACTIVE=prod environment variable or the --spring.profiles.active=prod command-line argument.

• application.yml: Shared by all profiles: model, agent, virtual threads, log format
• application-local.yml: Local development: Volcengine Ark base-url and model name live in the file, the API key comes from ARK_API_KEY (may be empty), com.yoke logs at debug
• application-test.yml: Automated tests: a fake API key, the model is never really called
• application-prod.yml: Production: the API key must come from the environment, startup fails without it; graceful shutdown

The model is created by the official AgentScope starter from agentscope.*, and the agent is built per request by a shared builder (the official singleton agent is turned off):