AS AgentScopeAPI 手册 / API Reference

RuntimeContext

public class RuntimeContext
源码Source io/agentscope/core/agent/RuntimeContext.java:34–486

RuntimeContext 承载单次调用所需的会话/用户标识、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()
static

返回 empty 结果。

Shallow, mutable empty context (null session fields, empty attribute maps, no tool context).

返回Returns RuntimeContext
返回RuntimeContext。Returns runtime context.
源码Source io/agentscope/core/agent/RuntimeContext.java:98–100

getSessionId

public String getSessionId()

获取会话标识。

Returns the session id.

返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/core/agent/RuntimeContext.java:102–104

getUserId

public String getUserId()

获取用户标识。

Returns the user id.

返回Returns String
返回字符串结果。Returns a string.
源码Source io/agentscope/core/agent/RuntimeContext.java:106–108

getAgentState

public AgentState getAgentState()

获取智能体状态。

Returns the call-scoped AgentState for this run, or null when accessed outside of an active call().

返回Returns AgentState
返回AgentState。Returns agent state.
源码Source io/agentscope/core/agent/RuntimeContext.java:115–117

setAgentState

public void setAgentState(AgentState agentState)

设置智能体状态。

Installs the call-scoped AgentState.

参数Parameters
名称Name类型Type说明Description
agentStateAgentState智能体状态(类型 `AgentState`)。The agent state.
源码Source io/agentscope/core/agent/RuntimeContext.java:123–125

resolveAgentState

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.

参数Parameters
名称Name类型Type说明Description
ctxRuntimeContext运行时上下文(类型 `RuntimeContext`)。the per-call runtime context (may be `null`)
fallbackAgentAgent回退智能体(类型 `Agent`)。the agent to fall back to (may be `null`)
返回Returns AgentState
返回AgentState。the resolved `AgentState`, or `null` if neither source provides one
源码Source io/agentscope/core/agent/RuntimeContext.java:137–143

getToolExecutionContext

public ToolExecutionContext getToolExecutionContext()

获取工具执行上下文。

Returns the tool execution context provided at build time, if any.

返回Returns ToolExecutionContext
返回ToolExecutionContext。Returns tool execution context.
源码Source io/agentscope/core/agent/RuntimeContext.java:150–152

getToolRequestConfig

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

返回Returns ToolRequestConfig
返回ToolRequestConfig。Returns tool request config.
源码Source io/agentscope/core/agent/RuntimeContext.java:158–160

setToolRequestConfig

public void setToolRequestConfig(ToolRequestConfig toolRequestConfig)

设置工具请求配置。

Installs the per-call tool request config.

参数Parameters
名称Name类型Type说明Description
toolRequestConfigToolRequestConfig工具请求配置(类型 `ToolRequestConfig`)。The tool request config.
源码Source io/agentscope/core/agent/RuntimeContext.java:167–169

get

public T T get(String key)

按条件读取数据。

Performs the get operation.

参数Parameters
名称Name类型Type说明Description
keyString键(类型 `String`)。The key.
返回Returns T
返回T。Returns t.
源码Source io/agentscope/core/agent/RuntimeContext.java:171–177

put

public void put(String key, Object value)

执行 put 方法。

Performs the put operation.

参数Parameters
名称Name类型Type说明Description
keyString键(类型 `String`)。The key.
valueObject值(类型 `Object`)。The value.
源码Source io/agentscope/core/agent/RuntimeContext.java:179–188

get

public T T get(Class<T> type)

按条件读取数据。

Performs the get operation.

参数Parameters
名称Name类型Type说明Description
typeClass<T>类型(类型 `Class`)。The type.
返回Returns T
返回T。Returns t.
源码Source io/agentscope/core/agent/RuntimeContext.java:190–204

put

public T void put(Class<T> type, T value)

执行 put 方法。

Performs the put operation.

参数Parameters
名称Name类型Type说明Description
typeClass<T>类型(类型 `Class`)。The type.
valueT值(类型 `T`)。The value.
源码Source io/agentscope/core/agent/RuntimeContext.java:206–215

get

public T T get(String key, Class<T> type)

按条件读取数据。

Performs the get operation.

参数Parameters
名称Name类型Type说明Description
keyString键(类型 `String`)。The key.
typeClass<T>类型(类型 `Class`)。The type.
返回Returns T
返回T。Returns t.
源码Source io/agentscope/core/agent/RuntimeContext.java:217–238

put

public T void put(String key, Class<T> type, T value)

执行 put 方法。

Performs the put operation.

参数Parameters
名称Name类型Type说明Description
keyString键(类型 `String`)。The key.
typeClass<T>类型(类型 `Class`)。The type.
valueT值(类型 `T`)。The value.
源码Source io/agentscope/core/agent/RuntimeContext.java:240–249

builder

public static Builder builder(RuntimeContext source)
static

返回构建器实例。

Performs the builder operation.

参数Parameters
名称Name类型Type说明Description
sourceRuntimeContext来源(类型 `RuntimeContext`)。The source.
返回Returns Builder
返回当前实例,以支持链式调用。Returns the current instance for chaining.
源码Source io/agentscope/core/agent/RuntimeContext.java:251–253

getExtra

public Map<String, Object> getExtra()

获取 getExtra。

View of string-keyed attributes; mutating the returned map affects this context.

返回Returns Map<String, Object>
返回映射。Returns map.
源码Source io/agentscope/core/agent/RuntimeContext.java:260–262

asToolExecutionContext

public ToolExecutionContext asToolExecutionContext()

返回as 工具执行上下文。

Merges this context's data into a ToolExecutionContext for tool invocations.

返回Returns ToolExecutionContext
返回ToolExecutionContext。Returns tool execution context.
源码Source io/agentscope/core/agent/RuntimeContext.java:334–345

builder

public static Builder builder()
static

返回构建器实例。

Returns the builder.

返回Returns Builder
返回当前实例,以支持链式调用。Returns the current instance for chaining.
源码Source io/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.

基于官方固定版本源码静态生成Generated from pinned official sources · Python 2.0.11 · Java 2.0.4
签名与文档为静态抽取;如有疑问请以源码为准。Signatures and docs are extracted statically; verify against the source when in doubt.