ADK-Rust

Gerenciamento de Estado

O estado de sessão em ADK-Rust permite que os agents armazenem e recuperem data que persiste entre as turns de conversação. O estado é organizado usando key prefixes que determinam o escopo e o tempo de vida dos data.

Visão Geral

O estado é armazenado como pares key-value onde:

  • Keys são strings com prefixes opcionais
  • Values são JSON values (serde_json::Value)

O sistema de prefixos permite diferentes níveis de escopo:

  • Escopo de sessão: Padrão, vinculado a uma única session
  • Escopo de usuário: Compartilhado entre todas as sessions para um user
  • Escopo de aplicativo: Compartilhado entre todos os users de uma application
  • Temporário: Limpo após cada invocation

Trait de Estado

O trait State define a interface para acesso ao estado:

use serde_json::Value;
use std::collections::HashMap;

pub trait State: Send + Sync {
    /// Get a value by key
    fn get(&self, key: &str) -> Option<Value>;
    
    /// Set a value
    fn set(&mut self, key: String, value: Value);
    
    /// Get all state as a map
    fn all(&self) -> HashMap<String, Value>;
}

Há também um trait ReadonlyState para acesso somente leitura:

pub trait ReadonlyState: Send + Sync {
    fn get(&self, key: &str) -> Option<Value>;
    fn all(&self) -> HashMap<String, Value>;
}

Prefixes de Chave de Estado

ADK-Rust usa três key prefixes para controlar o state scoping:

PrefixoConstanteEscopo
app:KEY_PREFIX_APPCompartilhado entre todos os usuários e sessões
user:KEY_PREFIX_USERCompartilhado entre todas as sessões para um usuário
temp:KEY_PREFIX_TEMPLimpo após cada invocação
(nenhum)-Com escopo de Session (padrão)

app: - Estado da Aplicação

Estado compartilhado entre todos os usuários e sessões de uma aplicação.

use adk_session::KEY_PREFIX_APP;

// KEY_PREFIX_APP = "app:"
let key = format!("{}settings", KEY_PREFIX_APP);  // "app:settings"

Casos de uso:

  • Configuração da aplicação
  • Recursos compartilhados
  • Contadores ou estatísticas globais

user: - Estado do Usuário

Estado compartilhado entre todas as sessões para um usuário específico.

use adk_session::KEY_PREFIX_USER;

// KEY_PREFIX_USER = "user:"
let key = format!("{}preferences", KEY_PREFIX_USER);  // "user:preferences"

Casos de uso:

  • Preferências do usuário
  • Dados do perfil do usuário
  • Contexto do usuário entre sessões

temp: - Estado Temporário

Estado que é limpo após cada invocação. Não persistido.

use adk_session::KEY_PREFIX_TEMP;

// KEY_PREFIX_TEMP = "temp:"
let key = format!("{}current_step", KEY_PREFIX_TEMP);  // "temp:current_step"

Casos de uso:

  • Resultados de computação intermediários
  • Contexto da operação atual
  • Dados que não devem persistir

Sem Prefixo - Estado da Sessão

Chaves sem prefixo têm escopo de sessão (comportamento padrão).

let key = "conversation_topic";  // Session-scoped

Casos de uso:

  • Contexto da conversa
  • Dados específicos da sessão
  • Estado de turno a turno

Definindo o Estado Inicial

O estado pode ser inicializado ao criar uma sessão:

use adk_session::{InMemorySessionService, SessionService, CreateRequest, KEY_PREFIX_APP, KEY_PREFIX_USER};
use serde_json::json;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut initial_state = HashMap::new();

    // App-scoped state
    initial_state.insert(
        format!("{}version", KEY_PREFIX_APP),
        json!("1.0.0")
    );

    // User-scoped state
    initial_state.insert(
        format!("{}name", KEY_PREFIX_USER),
        json!("Alice")
    );

    // Session-scoped state
    initial_state.insert(
        "topic".to_string(),
        json!("Getting started")
    );

    let service = InMemorySessionService::new();
    let session = service.create(CreateRequest {
        app_name: "my_app".to_string(),
        user_id: "user_123".to_string(),
        session_id: None,
        state: initial_state,
    }).await?;
    
    Ok(())
}

Lendo o Estado

Acesse o estado através do método state() da sessão:

let state = session.state();

// Get a specific key
if let Some(value) = state.get("topic") {
    println!("Topic: {}", value);
}

// Get app-scoped state
if let Some(version) = state.get("app:version") {
    println!("App version: {}", version);
}

// Get all state
let all_state = state.all();
for (key, value) in all_state {
    println!("{}: {}", key, value);
}

Atualizações de Estado via Eventos

O estado é tipicamente atualizado através de ações de evento. Quando um evento é anexado a uma sessão, seu state_delta é aplicado:

use adk_session::{Event, EventActions};
use serde_json::json;
use std::collections::HashMap;

let mut state_delta = HashMap::new();
state_delta.insert("counter".to_string(), json!(42));
state_delta.insert("user:last_seen".to_string(), json!("2024-01-15"));

let mut event = Event::new("invocation_123");
event.actions = EventActions {
    state_delta,
    ..Default::default()
};

// When this event is appended, state is updated
service.append_event(session.id(), event).await?;

Comportamento de Escopo de Estado

O serviço de sessão lida com o escopo de estado automaticamente:

Na Criação da Sessão

  1. Extrair chaves prefixadas com app: → Armazenar no estado do aplicativo
  2. Extrair chaves prefixadas com user: → Armazenar no estado do usuário
  3. Chaves restantes (exceto temp:) → Armazenar no estado da sessão
  4. Mesclar todos os escopos para a sessão retornada

Na Recuperação da Sessão

  1. Carregar o estado do aplicativo para a aplicação
  2. Carregar o estado do usuário para o usuário
  3. Carregar o estado da sessão
  4. Mesclar todos os escopos (app → user → session)

No Anexo de Evento

  1. Extrair delta de estado do evento
  2. Filtrar chaves temp: (não persistidas)
  3. Aplicar deltas app: ao estado do aplicativo
  4. Aplicar deltas user: ao estado do usuário
  5. Aplicar deltas restantes ao estado da sessão

Exemplo Completo

use adk_session::{
    InMemorySessionService, SessionService, CreateRequest, GetRequest,
    KEY_PREFIX_APP, KEY_PREFIX_USER,
};
use serde_json::json;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let service = InMemorySessionService::new();
    
    // Create first session with initial state
    let mut state1 = HashMap::new();
    state1.insert(format!("{}theme", KEY_PREFIX_APP), json!("dark"));
    state1.insert(format!("{}language", KEY_PREFIX_USER), json!("en"));
    state1.insert("context".to_string(), json!("session1"));
    
    let session1 = service.create(CreateRequest {
        app_name: "my_app".to_string(),
        user_id: "alice".to_string(),
        session_id: Some("s1".to_string()),
        state: state1,
    }).await?;
    
    // Create second session for same user
    let mut state2 = HashMap::new();
    state2.insert("context".to_string(), json!("session2"));
    
    let session2 = service.create(CreateRequest {
        app_name: "my_app".to_string(),
        user_id: "alice".to_string(),
        session_id: Some("s2".to_string()),
        state: state2,
    }).await?;
    
    // Session 2 inherits app and user state
    let s2_state = session2.state();
    
    // App state is shared
    assert_eq!(s2_state.get("app:theme"), Some(json!("dark")));
    
    // User state is shared
    assert_eq!(s2_state.get("user:language"), Some(json!("en")));
    
    // Session state is separate
    assert_eq!(s2_state.get("context"), Some(json!("session2")));
    
    println!("State scoping works correctly!");
    Ok(())
}

Modelagem de Instruções com Estado

Valores de estado podem ser injetados nas instruções do agente usando a sintaxe {key}:

use adk_rust::prelude::*;
use std::sync::Arc;

let agent = LlmAgentBuilder::new("personalized_assistant")
    .instruction("You are helping {user:name} with {topic}. Their preferred language is {user:language}.")
    .model(Arc::new(model))
    .build()?;

Quando o agente é executado, {user:name}, {topic} e {user:language} são substituídos por valores do estado da sessão.

Melhores Práticas

1. Usar Escopos Apropriados

// ✅ Good: User preferences in user scope
"user:theme"
"user:timezone"

// ✅ Good: Session-specific context without prefix
"current_task"
"conversation_summary"

// ✅ Good: App-wide settings in app scope
"app:model_version"
"app:feature_flags"

// ❌ Bad: User data in session scope (lost between sessions)
"user_preferences"  // Should be "user:preferences"

2. Usar Estado Temporário para Dados Intermediários

// ✅ Good: Intermediate results in temp scope
"temp:search_results"
"temp:current_step"

// ❌ Bad: Intermediate data persisted unnecessarily
"search_results"  // Will be saved to database

3. Manter as Chaves de Estado Consistentes

// ✅ Good: Consistent naming convention
"user:preferences.theme"
"user:preferences.language"

// ❌ Bad: Inconsistent naming
"user:theme"
"userLanguage"
"user-timezone"

Relacionado

  • Sessions - Visão geral do gerenciamento de sessões
  • Eventos - Estrutura de eventos e state_delta
  • LlmAgent - Modelagem de instruções

Anterior: ← Sessions | Próximo: Callbacks →

Gerenciamento de Estado - Documentação ADK-Rust | ADK-Rust