Docs
Console
Guia

Sessions e eventos

Implemente um fluxo completo: criar session, enviar eventos, consumir stream, retomar leitura e responder custom tools.

Este guia é para o backend do seu produto. Ele usa o SDK quando possível e mostra HTTP onde o contrato do event log é importante.

#Criar a session

Crie a session com a versão de agent que deve executar o trabalho. Adicione metadados para correlacionar a execução com seus objetos internos.

ts
const session = await client.sessions.create({
agent: { id: 'agent_...', version: 4 },
title: 'Análise de sinistro',
metadata: {
  claimId: 'clm_123',
  customerId: 'cus_456',
},
resources: [{ memoryStore: 'ms_...', mode: 'read-only' }],
vaultIds: ['vault_...'],
});

#Enviar mensagem

Uma mensagem do usuário entra como evento. O SDK gera idempotencyKey quando você não informa uma.

ts
const run = await session.send({
  content: 'Leia os documentos do sinistro e liste pendências.',
  idempotencyKey: 'claim-clm_123-turn-1',
});

Em HTTP, envie um batch de eventos:

bash
curl -sS -X POST "$NOORDEN_API_URL/v1/projects/$PROJECT_ID/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $NOORDEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{ "type": "text", "text": "Leia os documentos do sinistro." }],
      "idempotencyKey": "claim-clm_123-turn-1"
    }]
  }'

#Consumir o stream

O stream entrega eventos em ordem. Persista o maior seq processado para retomar depois.

ts
let checkpoint = 0;

for await (const event of run.stream({ afterSeq: checkpoint })) {
  checkpoint = event.seq;

  switch (event.type) {
    case 'agent.message':
      await appendAssistantText(event.text);
      break;
    case 'agent.custom_tool_use':
      await enqueueToolExecution(event.toolUseId, event.name, event.input);
      break;
    case 'session.status_idle':
      await markReadyForNextUserTurn();
      break;
  }
}

#Retomar histórico

Se o consumidor cair, leia o histórico a partir do checkpoint e depois reabra o stream.

ts
for await (const event of session.eventsIterator({ afterSeq: checkpoint, limit: 100 })) {
  checkpoint = event.seq;
  await processEvent(event);
}

for await (const event of session.stream({ afterSeq: checkpoint })) {
  checkpoint = event.seq;
  await processEvent(event);
}

#Responder custom tools

Quando o stream emitir agent.custom_tool_use, execute a tool no seu backend e responda com o mesmo toolUseId.

ts
if (event.type === 'agent.custom_tool_use') {
  const result = await executeBusinessTool(event.name, event.input);

  await run.respondTool(event.toolUseId, {
    content: JSON.stringify(result),
    idempotencyKey: `tool-${event.toolUseId}`,
  });
}

#Interromper

Interrompa quando o usuário mudar a intenção ou quando seu produto precisar parar trabalho em andamento.

ts
await run.interrupt({
  waitForIdle: true,
  timeoutMs: 10_000,
  idempotencyKey: 'claim-clm_123-interrupt-1',
});

#Referência relacionada