Copilot

client.copilot は、ワークフロー用の Nodaro のアシスタントである Copilot を操作します。スレッドは、ワークフロー上で開かれる会話で、ターンは、1 つのメッセージと、それに答えるためにアシスタントが行うことすべてです。これらのメソッドは /v1/copilot/* を呼び出します。この機能については、ワークフロー Copilot を参照してください。

Copilot が動作するのは、Nodaro アプリの中だけです。すべてのルートは、ログイン中のユーザー自身のセッションを持たない呼び出し元を、403 in_app_only で拒否します。SDK はこれを ForbiddenError としてスローし、その code は forbidden になるため、message を確認してください。API トークンと OAuth トークンでは、誰の Copilot も操作できません。ブラウザーアプリからは、supabaseAuth を使って利用します。Copilot は Nodaro Cloud で動作します。この機能をオフにしているデプロイメントでは、スレッドを開いたりターンを送信したりすると 503 feature_disabled が返されます。

メソッド

これらのメソッドは、stream() を除き、API の { data } エンベロープをそのまま返します。stream() は、フレームを yield します。

client.copilot

create(input)

スレッドを開きます。既存の workflowId か、prompt を渡します。prompt を渡した場合は、サーバーがそれをもとにワークフローを作成します。すでに有効なスレッドがあるワークフローを開いた場合、2 つ目のスレッドではなく、その既存のスレッドが返されます。

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

スレッドは、id、workflowId、runMode（実行を提案して待つ ask、または autoRunLimitCredits の範囲内で実行する auto）、modelTier、allowPublishing、userTurnCount、lastMessageAt、createdAt を持ちます。surface は、そのスレッドが属するアシスタントを示します。存在しない場合、デプロイメントがそれを示していません。

list(params)

ワークフローの有効なスレッドを読み取ります。存在しない場合は null です。

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

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

get(id, opts?)

スレッドを、そのメッセージとともに読み取ります。スレッドには、導出された status（running または idle）と 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 })

各メッセージは、id、seq、turnId、role、createdAt、parts（テキストの部分とツール呼び出しの部分）を持ちます。

archive(id)

スレッドをアーカイブします。メッセージは引き続き読み取れ、何も削除されません。実行中のターンがあるスレッドは、アーカイブできません。

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

await client.copilot.archive(threadId)

cancel(id)

スレッドの実行中のターンを停止し、停止を要求したターンを返します。そのターンのストリームは、done フレームで終わります。

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

await client.copilot.cancel(threadId)

stream(threadId, opts)

メッセージを送信し、ターンのフレームをサーバー送信イベントとして、届くたびに yield します。完全な回答を待つのではなく、テキスト、ツールの動作、提案をリアルタイムで表示できます。ここで紹介するメソッドのうち、クレジットを消費するのはこれだけです。

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 は、type で判別するユニオン型です。

フレームの data はそのまま渡されるため、この SDK がモデル化していないフィールドも受け取れます。モデル化されていない種類のフレームは、例外をスローするのではなくスキップされるため、新しいサーバーによって古いクライアントが壊れることはありません。このバージョンは、studio サーフェスのスレッドにある提案カードである action_proposed をモデル化していないため、その提案は呼び出し元に渡されません。

ターンの存続期間は、あなたが管理します。ターンは数分間実行されることがあるため、クライアントの timeoutMs は適用されません。signal を渡すか、反復処理を止めてください。どちらもリクエストを終了させます。中断すると、最初のフレームの前であれ、2 つのフレームの間であれ、NodaroError ではなく、ランタイム自身の AbortError で反復処理が拒否されます。開始リクエストのエラーステータスは、どのフレームより前に、通常の型付きエラーとして、引き続きスローされます。