RuntimeContext
public class RuntimeContext
io/agentscope/core/agent/RuntimeContext.java:34–486RuntimeContext 承载单次调用所需的会话/用户标识、AgentState、工具执行配置与自定义属性。它不持久化,跨调用状态应放在 AgentState 中。位于 io.agentscope.core.agent 包。核心成员包括 empty、getSessionId、getUserId、getAgentState、setAgentState、resolveAgentState。
Per-call metadata for an agent run: session-scoped fields plus a thread-safe attribute bag and
an optional ToolExecutionContext (tool-POJO / DI layer).
Attributes are not persisted. Hooks and tools may read and update the same instance for the
duration of a single call.
核心精讲Deep dive
RuntimeContext:单次调用上下文RuntimeContext: per-call context
RuntimeContext 承载单次调用所需的会话/用户标识、AgentState、工具执行配置与自定义属性。它不持久化,跨调用状态应放在 AgentState 中。
RuntimeContext carries per-call session/user identity, AgentState, tool execution configuration and custom attributes. It is not persisted; cross-call state belongs in AgentState.
- sessionId 与 userId 用于状态隔离、审计和权限判断。sessionId and userId drive state isolation, auditing and permission decisions.
- agentState 可显式传入,也可由 resolveAgentState 回退到智能体默认状态。agentState can be supplied explicitly or resolved from the agent via resolveAgentState.
- toolRequestConfig 与自定义属性允许按调用覆盖工具行为。toolRequestConfig and custom attributes override tool behavior per call.
为一次调用绑定会话Bind a session to one call
import io.agentscope.core.ReActAgent;
import io.agentscope.core.agent.RuntimeContext;
import io.agentscope.core.message.Msg;
import io.agentscope.core.message.MsgRole;
import io.agentscope.extensions.model.openai.OpenAIChatModel;
import java.util.List;
public class ContextDemo {
public static void main(String[] args) {
ReActAgent agent = ReActAgent.builder()
.name("assistant")
.sysPrompt("You are a helpful assistant.")
.model(OpenAIChatModel.builder()
.apiKey(System.getenv("OPENAI_API_KEY"))
.modelName("gpt-4.1-mini")
.build())
.build();
RuntimeContext context = RuntimeContext.builder()
.sessionId("demo-session")
.userId("alice")
.build();
Msg reply = agent.call(
List.of(Msg.builderForRole(MsgRole.USER)
.name("user")
.textContent("Summarize the attached report.")
.build()),
context
).block();
System.out.println(reply.getTextContent());
agent.close();
}
}嵌套类摘要Nested Class Summary
| 类Class | 类型Kind | 说明Description |
|---|---|---|
Builder | 类class | 构建器,用于构建并配置目标实例。 A class in io.agentscope.core.agent that drives agent reasoning, tool calls and conversation execution. |
方法摘要Method Summary
| 方法Method | 说明Description |
|---|---|
public static RuntimeContext empty()static | 返回不含任何上下文的空实例。 Shallow, mutable empty context (null session fields, empty attribute maps, no tool context). |
public String getSessionId() | 返回会话 ID。 Returns the session id. |
public String getUserId() | 返回用户 ID。 Returns the user id. |
public AgentState getAgentState() | 返回绑定的会话状态。 Returns the call-scoped `AgentState` for this run, or `null` when accessed
outside of an active `call()`. |
public void setAgentState(AgentState agentState) | 绑定会话状态。 Installs the call-scoped `AgentState`. |
public static AgentState resolveAgentState(RuntimeContext ctx, Agent fallbackAgent)static | 解析智能体状态。 Resolves the live `AgentState` for the current call, preferring the call-scoped state
carried on `ctx` (concurrency-safe) and falling back to `fallbackAgent`'s state
only when the context carries none. |
public ToolExecutionContext getToolExecutionContext() | 获取工具执行上下文。 Returns the tool execution context provided at build time, if any. |
public ToolRequestConfig getToolRequestConfig() | 返回本次调用的工具请求配置。 Returns the per-call tool request config, or `null` when none was provided (the
execution engine then uses the agent's shared toolkit as-is). |
public void setToolRequestConfig(ToolRequestConfig toolRequestConfig) | 设置本次调用的工具请求配置。 Installs the per-call tool request config. |
public T T get(String key) | 读取调用级自定义属性。 Performs the get operation. |
public void put(String key, Object value) | 写入调用级自定义属性。 Performs the put operation. |
public T T get(Class<T> type) | 读取调用级自定义属性。 Performs the get operation. |
public T void put(Class<T> type, T value) | 写入调用级自定义属性。 Performs the put operation. |
public T T get(String key, Class<T> type) | 读取调用级自定义属性。 Performs the get operation. |
public T void put(String key, Class<T> type, T value) | 写入调用级自定义属性。 Performs the put operation. |
public static Builder builder(RuntimeContext source)static | 创建 RuntimeContext 构建器。 Performs the builder operation. |
public Map<String, Object> getExtra() | 获取 `getExtra`。 View of string-keyed attributes; mutating the returned map affects this context. |
public ToolExecutionContext asToolExecutionContext() | 返回as 工具执行上下文。 Merges this context's data into a `ToolExecutionContext` for tool invocations. |
public static Builder builder()static | 创建 RuntimeContext 构建器。 Returns the builder. |
方法详情Method Detail
empty
public static RuntimeContext empty()
返回 empty 结果。
Shallow, mutable empty context (null session fields, empty attribute maps, no tool context).
RuntimeContextio/agentscope/core/agent/RuntimeContext.java:98–100getSessionId
public String getSessionId()
获取会话标识。
Returns the session id.
Stringio/agentscope/core/agent/RuntimeContext.java:102–104getUserId
public String getUserId()
获取用户标识。
Returns the user id.
Stringio/agentscope/core/agent/RuntimeContext.java:106–108getAgentState
public AgentState getAgentState()
获取智能体状态。
Returns the call-scoped AgentState for this run, or null when accessed outside of an active call().
AgentStateio/agentscope/core/agent/RuntimeContext.java:115–117setAgentState
public void setAgentState(AgentState agentState)
设置智能体状态。
Installs the call-scoped AgentState.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
agentState | AgentState | 智能体状态(类型 `AgentState`)。The agent state. |
io/agentscope/core/agent/RuntimeContext.java:123–125resolveAgentState
public static AgentState resolveAgentState(RuntimeContext ctx, Agent fallbackAgent)
解析智能体状态。
Resolves the live AgentState for the current call, preferring the call-scoped state carried on ctx (concurrency-safe) and falling back to fallbackAgent's state only when the context carries none.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
ctx | RuntimeContext | 运行时上下文(类型 `RuntimeContext`)。the per-call runtime context (may be `null`) |
fallbackAgent | Agent | 回退智能体(类型 `Agent`)。the agent to fall back to (may be `null`) |
AgentStateio/agentscope/core/agent/RuntimeContext.java:137–143getToolExecutionContext
public ToolExecutionContext getToolExecutionContext()
获取工具执行上下文。
Returns the tool execution context provided at build time, if any.
ToolExecutionContextio/agentscope/core/agent/RuntimeContext.java:150–152getToolRequestConfig
public ToolRequestConfig getToolRequestConfig()
获取工具请求配置。
Returns the per-call tool request config, or null when none was provided (the execution engine then uses the agent's shared toolkit as-is).
ToolRequestConfigio/agentscope/core/agent/RuntimeContext.java:158–160setToolRequestConfig
public void setToolRequestConfig(ToolRequestConfig toolRequestConfig)
设置工具请求配置。
Installs the per-call tool request config.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
toolRequestConfig | ToolRequestConfig | 工具请求配置(类型 `ToolRequestConfig`)。The tool request config. |
io/agentscope/core/agent/RuntimeContext.java:167–169get
public T T get(String key)
按条件读取数据。
Performs the get operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
key | String | 键(类型 `String`)。The key. |
Tio/agentscope/core/agent/RuntimeContext.java:171–177put
public void put(String key, Object value)
执行 put 方法。
Performs the put operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
key | String | 键(类型 `String`)。The key. |
value | Object | 值(类型 `Object`)。The value. |
io/agentscope/core/agent/RuntimeContext.java:179–188get
public T T get(Class<T> type)
按条件读取数据。
Performs the get operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
type | Class<T> | 类型(类型 `Class`)。The type. |
Tio/agentscope/core/agent/RuntimeContext.java:190–204put
public T void put(Class<T> type, T value)
执行 put 方法。
Performs the put operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
type | Class<T> | 类型(类型 `Class`)。The type. |
value | T | 值(类型 `T`)。The value. |
io/agentscope/core/agent/RuntimeContext.java:206–215get
public T T get(String key, Class<T> type)
按条件读取数据。
Performs the get operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
key | String | 键(类型 `String`)。The key. |
type | Class<T> | 类型(类型 `Class`)。The type. |
Tio/agentscope/core/agent/RuntimeContext.java:217–238put
public T void put(String key, Class<T> type, T value)
执行 put 方法。
Performs the put operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
key | String | 键(类型 `String`)。The key. |
type | Class<T> | 类型(类型 `Class`)。The type. |
value | T | 值(类型 `T`)。The value. |
io/agentscope/core/agent/RuntimeContext.java:240–249builder
public static Builder builder(RuntimeContext source)
返回构建器实例。
Performs the builder operation.
| 名称Name | 类型Type | 说明Description |
|---|---|---|
source | RuntimeContext | 来源(类型 `RuntimeContext`)。The source. |
Builderio/agentscope/core/agent/RuntimeContext.java:251–253getExtra
public Map<String, Object> getExtra()
获取 getExtra。
View of string-keyed attributes; mutating the returned map affects this context.
Map<String, Object>io/agentscope/core/agent/RuntimeContext.java:260–262asToolExecutionContext
public ToolExecutionContext asToolExecutionContext()
返回as 工具执行上下文。
Merges this context's data into a ToolExecutionContext for tool invocations.
ToolExecutionContextio/agentscope/core/agent/RuntimeContext.java:334–345builder
public static Builder builder()
返回构建器实例。
Returns the builder.
Builderio/agentscope/core/agent/RuntimeContext.java:347–349嵌套类详情Nested Class Detail
Builder
public static class Builder构建器,用于构建并配置目标实例。位于 io.agentscope.core.agent 包。核心成员包括 sessionId、userId、agentState、put、putAll、from。
A class in io.agentscope.core.agent that drives agent reasoning, tool calls and conversation execution. Declared in io.agentscope.core.agent.