Copilot

client.copilot controla o Copilot, o assistente de workflows do Nodaro. Uma thread é uma conversa aberta em um workflow, e uma rodada é uma mensagem mais tudo o que o assistente faz para respondê-la. Os métodos chamam /v1/copilot/*. Veja Workflow Copilot para conhecer o recurso.

O Copilot só funciona dentro de um app do Nodaro. Todas as rotas recusam, com 403 in_app_only, quem chama sem a sessão do próprio usuário conectado. O SDK lança esse erro como ForbiddenError, cujo code é forbidden, então verifique o message dele. Tokens de API e tokens OAuth não conseguem controlar o Copilot de ninguém. Use-o a partir de um app de navegador com supabaseAuth. Ele funciona no Nodaro Cloud. Uma implantação com o recurso desativado responde 503 feature_disabled quando você abre uma thread ou envia uma rodada.

Métodos

Estes métodos retornam o envelope { data } da API como ele chega, exceto stream(), que emite frames.

client.copilot

create(input)

Abre uma thread. Informe um workflowId existente, ou um prompt, e o servidor cria um workflow a partir dele. Abrir um workflow que já tem uma thread ativa retorna essa thread em vez de uma segunda.

create(input: { workflowId?: string; prompt?: string; name?: string }): Promise<{
  data: { thread: CopilotThread; workflow: CopilotThreadWorkflow }
}>

const { data } = await client.copilot.create({ workflowId })
const threadId = data.thread.id

Uma thread tem id, workflowId, runMode (ask, que propõe execuções e espera, ou auto, que executa dentro de autoRunLimitCredits), modelTier, allowPublishing, userTurnCount, lastMessageAt e createdAt. surface indica o assistente a que a thread pertence; quando esse campo não vem, a implantação não informou.

list(params)

Lê a thread ativa de um workflow, ou null quando não há nenhuma.

list(params: { workflowId: string }): Promise<{ data: { thread: CopilotThread | null } }>

const { data: { thread } } = await client.copilot.list({ workflowId })

get(id, opts?)

Lê uma thread com as mensagens dela. A thread também traz um status derivado (running ou idle) e activeTurnId.

get(id: string, opts?: { after?: number; limit?: number }): Promise<{
  data: { thread: CopilotThread; messages: CopilotMessage[] }
}>

const { data: { messages } } = await client.copilot.get(threadId, { after: lastSeq })

Cada mensagem tem id, seq, turnId, role, createdAt e parts: partes de texto e partes de chamada de ferramenta.

archive(id)

Arquiva uma thread. As mensagens continuam legíveis; nada é excluído. Uma thread com uma rodada em andamento não pode ser arquivada.

archive(id: string): Promise<{ data: { archived: true } }>

await client.copilot.archive(threadId)

cancel(id)

Interrompe a rodada em andamento de uma thread e responde qual rodada pediu para interromper. O stream dessa rodada termina com um frame done.

cancel(id: string): Promise<{ data: { cancelling: true; turnId: string } }>

await client.copilot.cancel(threadId)

stream(threadId, opts)

Envia uma mensagem e emite os frames da rodada à medida que chegam, como server-sent events. Renderize o texto, a atividade das ferramentas e as propostas ao vivo, em vez de esperar a resposta completa. É o único destes métodos que gasta créditos.

stream(threadId: string, opts: {
  message: string
  baseVersion?: number
  tier?: "economy" | "standard" | "premium"
  signal?: AbortSignal
}): AsyncGenerator<CopilotStreamFrame>

try {
  for await (const frame of client.copilot.stream(threadId, { message: "Tidy the graph" })) {
    if (frame.type === "token") appendText(frame.data.text)
    if (frame.type === "run_proposed") await askTheUser(frame.data)
    if (frame.type === "done") break
  }
} catch (err) {
  if ((err as Error).name !== "AbortError") throw err // a stopped turn is a normal ending
}

CopilotStreamFrame é uma união discriminada por type:

O data de um frame é repassado como está, então os campos que este SDK não modela também chegam até você. Um tipo de frame que o SDK não modela é ignorado em vez de lançar um erro, então um servidor mais novo não consegue quebrar um cliente mais antigo. Esta versão não modela action_proposed, o cartão de proposta das threads na superfície studio, então essas propostas não chegam a quem faz a chamada.

A duração da rodada fica por sua conta. O timeoutMs do cliente não se aplica a uma rodada, porque uma rodada pode durar minutos. Passe signal, ou pare de iterar, o que encerra a requisição. Abortar rejeita a iteração com o AbortError do próprio runtime, não com um NodaroError, seja antes do primeiro frame, seja entre dois frames. Um status de erro na requisição inicial ainda lança o erro tipado de sempre, antes de qualquer frame.