Sessions
Sessions são execuções stateful de um agent. Elas preservam histórico, status, recursos montados e eventos necessários para retomada.
#O que é uma session
Uma session representa uma tarefa em andamento: uma conversa, uma análise de documento, uma automação de portal ou qualquer fluxo em que o agent precise manter contexto entre eventos.
Ao criar a session, você escolhe o agent e pode montar recursos como memory stores, vaults e metadados. Esses recursos formam o contexto autorizado da execução.
#Ciclo de vida
| Status | Significado |
|---|---|
idle | A session está pronta para receber novo input ou aguardando ação externa. |
running | O agent está processando eventos e pode emitir mensagens ou tools. |
rescheduled | A execução foi reagendada para continuar depois. |
terminated | A session chegou a um estado final. |
O status é derivado de eventos. Seu backend deve reagir aos eventos do stream, não a timers ou polling agressivo.
#Event log
O event log é append-only: cada evento recebe um seq crescente dentro da session. Esse número é o cursor natural para histórico, stream, retry e deduplicação do consumidor.
Eventos do usuário iniciam ou orientam trabalho. Eventos do agent descrevem respostas, raciocínio apresentado, tools e resultados. Eventos de status indicam transições observáveis.
#Padrões de integração
- Grave metadados de negócio na session, como
customerId,ticketIdouconversationId. - Use
idempotencyKeyao reenviar eventos a partir do seu backend. - Trate
seqcomo checkpoint de consumo. - Responda custom tools pelo evento correspondente, usando o
toolUseId. - Interrompa uma execução quando o usuário mudar a intenção do trabalho.
#Uso com SDK
const session = await client.sessions.create({
agent: { id: 'agent_...', version: 3 },
metadata: { ticketId: 'tk_123' },
resources: [{ memoryStore: 'ms_...', mode: 'read-write' }],
});
const run = await session.send('Resuma o histórico deste cliente.');
for await (const event of run.stream()) {
console.log(event.seq, event.type);
}