State Management

Visão Geral

O StateManager é responsável pelo gerenciamento de estado sistêmico das actions. Diferente da memória, o estado é usado exclusivamente para regras de negócio e controle interno, não sendo enviado para o contexto do LLM.

State vs Memory

Aspecto	State	Memory
Propósito	Informações sistêmicas e regras de negócio	Contexto para o LLM
Visibilidade	Apenas dentro das actions	Enviado para o LLM como contexto
Conversão	Nenhuma	Automaticamente convertido para markdown
Uso típico	Flags, configurações, dados temporários e informações que alimentam regras de negócio	Informações do usuário e fatos da conversa que agregam valor contextual

---

📖 Métodos Principais

get(path, model_class=None)

Recupera valores do estado com suporte a caminhos aninhados.

Parâmetros:

• path (str | list): Caminho para o valor ("user" ou "session.user.name")
• model_class (Type[BaseModel]): Classe Pydantic para conversão (opcional)

Quando utilizar:

• Verificar status de workflows
• Obter configurações temporárias
• Recuperar dados de controle interno
• Acessar flags de validação

Resultado esperado:

• Valor encontrado ou None se não existir
• Instância do modelo Pydantic se model_class especificado

Exemplos:

# Valor simples
workflow_step = state_manager.get("workflow_step")
# Retorna: "validacao_documento"

# Estrutura aninhada
attempts = state_manager.get("validation.cpf.attempts")
# Retorna: 2

# Com validação Pydantic
class ValidationConfig(BaseModel):
    max_attempts: int = 3
    timeout: int = 30

config = state_manager.get("validation.config", ValidationConfig)
# Retorna instância de ValidationConfig (criada vazia se não existir)

# Caminhos como lista
user_id = state_manager.get(["session", "user", "id"])

update(path, value, model_class=None)

Atualiza ou cria valores no estado com criação automática de caminhos.

Parâmetros:

• path (str | list): Caminho para o valor
• value (Any | BaseModel): Valor a ser armazenado
• model_class (Type[BaseModel]): Classe para validação (opcional)

Quando utilizar:

• Atualizar status de workflows
• Definir flags de controle
• Armazenar resultados temporários
• Configurar parâmetros dinâmicos

Resultado esperado:

• True se operação foi bem-sucedida
• Estrutura aninhada criada automaticamente se necessário
• Validação Pydantic aplicada se especificada

Exemplos:

# Valor simples
state_manager.update("workflow_step", "documento_validado")

# Estrutura aninhada (criada automaticamente)
state_manager.update("validation.cpf.attempts", 1)
state_manager.update("validation.cpf.last_attempt", "2024-01-15T10:30:00")

# Com validação Pydantic
config_data = {"max_attempts": 5, "timeout": 60}
state_manager.update("validation.config", config_data, ValidationConfig)

# Objeto Pydantic direto
config = ValidationConfig(max_attempts=3, timeout=30)
state_manager.update("validation.config", config)

# Flag de controle
state_manager.update("document.uploaded", True)
state_manager.update("external_api.last_call", datetime.now().isoformat())

merge(path, data)

Combina dados com estrutura existente no estado.

Parâmetros:

• path (str | list): Caminho onde fazer o merge
• data (Dict | BaseModel): Dados para combinar

Quando utilizar:

• Atualizar múltiplos campos de uma vez
• Adicionar propriedades a objeto existente
• Combinar configurações parciais
• Expandir dados de controle

Resultado esperado:

• True se operação foi bem-sucedida
• Dados existentes preservados, novos dados adicionados
• Estrutura criada automaticamente se não existir

Exemplos:

# Estado atual: {"user": {"id": "123", "name": "João"}}

# Merge de dados adicionais
state_manager.merge("user", {"email": "joao@email.com", "verified": True})
# Resultado: {"user": {"id": "123", "name": "João", "email": "joao@email.com", "verified": True}}

# Merge em estrutura aninhada
state_manager.merge("validation.attempts", {
    "cpf": 1,
    "email": 0,
    "phone": 2
})

# Merge com modelo Pydantic
class UserPreferences(BaseModel):
    notifications: bool = True
    language: str = "pt-BR"

prefs = UserPreferences(notifications=False)
state_manager.merge("user.preferences", prefs)

delete(path)

Remove valores do estado com suporte a caminhos aninhados.

Parâmetros:

• path (str | list): Caminho para o valor a ser removido

Quando utilizar:

• Limpar dados temporários
• Remover flags desnecessárias
• Reset de configurações específicas
• Cleanup de dados de workflow

Resultado esperado:

• Valor removido ou None se não existir
• Estrutura pai preservada

Exemplos:

# Remover valor simples
removed_step = state_manager.delete("workflow_step")
# Retorna: "documento_validado"

# Remover estrutura aninhada
state_manager.delete("validation.cpf")
# Remove toda seção "cpf" dentro de "validation"

# Cleanup de dados temporários
state_manager.delete("temp_upload.file_path")
state_manager.delete("cache.last_api_response")

# Verificar se foi removido
if state_manager.delete("non_existent_key") is None:
    print("Chave não existia")

---

🔧 Suporte a Pydantic

Validação e Estruturação

O StateManager oferece suporte completo ao Pydantic para validação e estruturação de dados:

from pydantic import BaseModel, Field
from typing import Optional

class WorkflowState(BaseModel):
    current_step: str
    completed_steps: list[str] = Field(default_factory=list)
    started_at: str
    data: dict = Field(default_factory=dict)

class ValidationAttempts(BaseModel):
    cpf: int = 0
    email: int = 0
    phone: int = 0
    max_attempts: int = 3

# Armazenar com validação
workflow = WorkflowState(
    current_step="document_upload",
    started_at="2024-01-15T10:00:00"
)
state_manager.update("workflow", workflow)

# Recuperar como objeto
workflow_obj = state_manager.get("workflow", WorkflowState)
print(workflow_obj.current_step)  # "document_upload"

# Validação automática em updates
attempts_data = {"cpf": 2, "email": 1}
state_manager.update("attempts", attempts_data, ValidationAttempts)

Vantagens do Pydantic

• Validação automática de tipos e constraints
• Valores padrão para campos opcionais
• Serialização consistente para dicionários
• Type hints para melhor desenvolvimento
• Documentação automática dos modelos

---

💡 Casos de Uso Comuns

✅ Bom para State

• Flags de controle: {"document_uploaded": True}
• Contadores: {"validation_attempts": 2}
• Status de workflow: {"current_step": "validacao"}
• Configurações temporárias: {"api_timeout": 60}
• Dados de sessão: {"user_authenticated": True}

❌ Evitar no State (usar Memory)

• Fatos da conversa: Preferências, histórico
• Contexto para decisões: Dados que o LLM precisa saber

Diferença Fundamental

O State é usado para controle interno das Actions e nunca é enviado para o LLM. Para dados que o LLM precisa conhecer para tomar decisões, use o Memory Management.

Quando usar cada um

• State: Flags, contadores, configurações, dados temporários de controle
• Memory: Informações do usuário, fatos da conversa, contexto para decisões do LLM