State 读写：Agent 内部状态管理

Session 管理对话历史，State 管理 Agent 的内部状态。两者结合，让 Agent 在多轮对话中既记得聊了什么，也记得自己当前的状态。

State vs Session

概念内容生命周期
Session对话历史消息整个会话期间
State自定义键值数据按需定义，可跨 Session

Session 是框架管理的，State 是开发者自定义的。

State 的基本操作

写入 State

session.State(ctx).Set("user_name", "张三")
session.State(ctx).Set("preference", map[string]interface{}{
    "language": "中文",
    "notifications": true,
})

读取 State

name := session.State(ctx).Get("user_name")  // "张三"
pref := session.State(ctx).Get("preference") // map[string]interface{}{...}

删除 State

session.State(ctx).Delete("user_name")

使用场景

场景 1：记住用户信息

// 第一轮：用户说"我叫张三"
session.State(ctx).Set("user_name", "张三")

// 后续轮次：Agent 知道用户名字
func agentInstruction() string {
    name := session.State(ctx).Get("user_name")
    if name != nil {
        return fmt.Sprintf("用户名叫 %s，用名字称呼用户", name)
    }
    return "友好地询问用户名字"
}

场景 2：多步流程状态

// 用户在订票流程中
session.State(ctx).Set("booking_step", 1)  // 选目的地
session.State(ctx).Set("destination", "上海")

// 用户完成第一步，进入第二步
session.State(ctx).Set("booking_step", 2)  // 选日期
session.State(ctx).Set("travel_date", "2026-06-01")

场景 3：Tool 间共享数据

两个 Tool 需要共享数据时，通过 State 中转：

// Tool A: 查询天气，缓存结果
session.State(ctx).Set("cached_weather", weatherResult)

// Tool B: 直接读缓存，不重复查
weather := session.State(ctx).Get("cached_weather")

State 的持久化

State 默认存在内存，Session 结束时清空。如果需要持久化，配合 Session 持久化一起用：

store := sessions.NewRedisStore(redisClient, "sessions:", time.Hour*24)

session, err := sessions.NewSession(ctx,
    sessions.WithUserID("user-123"),
    sessions.WithAgentID("my-agent"),
    sessions.WithStore(store),
)

// State 自动跟随 Session 持久化
session.State(ctx).Set("persistent_data", "value")

常见问题

Q：State 是线程安全的吗 A：是的，Session.State() 返回的对象是线程安全的，多个 Tool 并发读写没问题。

Q：State 数据太大会怎样 A：State 数据会跟随 Session 一起传输和存储，数据太大会影响性能。建议 State 数据控制在 KB 级别，不要存大量原始数据。

Q：Session 过期了，State 还在吗 A：State 跟随 Session 一起，Session 过期时 State 也会被清理。如果需要长期保存，把数据存到外部数据库。

下一步

State 管理了内部状态，接下来看 Event 系统——理解 Agent 运行过程中的事件流，如何监听和处理。

← Session Management | Event System →

想跟着学更多 Go ADK 实战？关注「全栈之巅-梦兽编程」公众号，每周更新 Go / AI 编程实战干货。