--- title: "Flue 1.0 BetaでGitHub Issueトリアージエージェントを動かしてみた" description: "Flue 1.0 BetaのAgent・Skill・Workflowを使い、GitHub Issueのseverity、再現可否、ラベル候補を構造化して返すトリアージエージェントを作った検証ログ。" lang: "ja" canonical: "https://llm-lab.dev/posts/flue-1-0-beta-issue-triage-agent/" source: "https://llm-lab.dev/posts/flue-1-0-beta-issue-triage-agent.md" publishedAt: "2026-06-19" updatedAt: "2026-06-19" category: "Flue" tags: - "agent" - "typescript" - "workflow" - "structured-output" --- # Flue 1.0 BetaでGitHub Issueトリアージエージェントを動かしてみた import LinkCard from "../../components/LinkCard.astro"; > [!NOTE] > この記事で確認したこと: Flue 1.0 Betaでは、WorkflowからAgentを初期化し、トリアージ基準をSkillとして読み込み、Valibotで検証した構造化結果を返せました。直接payloadだけでなくGitHub CLIで取得した実Issueでも動きましたが、API接続が通るだけでは不十分で、モデルがFlueのtool callingプロトコルに従って`finish`を返せるかが成否を分けました。 Flueの全体像は、先に以下の記事で整理しています。 前回、以下に記事を書きました。 前回はQuickstartを追い、サンプルをビルドして、APIキーがない状態でエラーが出るところまで確認しました。今回はもう少し踏み込み、実際にモデル呼び出しまで通る小さなAgentを作りました。 作ったのは、GitHub Issueのタイトルと本文を受け取り、severity、再現可否、ラベル候補、要約を返すトリアージ用Agentです。GitHub webhookやコメント投稿までつなぐと記事の論点が広がりすぎるため、今回はFlueのAgent、Skill、Workflow、structured outputがどう動くかに絞っています。 ただし、完全に手入力だけだとGitHub Issueトリアージと呼ぶには少し遠いので、最後にGitHub CLIで実Issueを1件取得し、同じWorkflowへ渡す薄いスクリプトも用意しました。webhook常駐サーバーではなく、`gh issue view`でtitle/bodyを取り出して`flue run`へ渡すだけの構成です。 ## 何を作ったか プロジェクトは、Flueの規約に合わせて`src/agents`、`src/skills`、`src/workflows`を分ける最小構成にしました。最終的なファイル構成は次の通りです。 ```txt scripts/ └─ triage-github-issue.mjs # GitHub CLIからIssueを1件取得する補助スクリプト src/ ├─ agents/ │ └─ issue-triage.ts # トリアージを行うAgent本体 ├─ skills/ │ └─ triage/ │ └─ SKILL.md # トリアージの判定基準 ├─ workflows/ │ └─ triage-issue.ts # 1件のIssueを分類するWorkflow ├─ providers.ts # OpenAI互換APIを使うためのprovider設定 └─ app.ts # dev server用のHono app ``` 今回の検証では、継続的に会話するAgentだけではなく、1件のIssueを受け取って結果を返す有限の処理を試したかったため、Agentに加えてWorkflowを作りました。Flueの整理で言えば、Agentは振る舞いやSkillを持つ主体で、Workflowはそれを使って一回の処理を完了させる入口です。 ## Skillを書く まず、トリアージの判断基準をSkillとして切り出しました。FlueのSkillはMarkdownで書けるため、コードに埋め込むよりも判断基準を見直しやすくなります。 ```markdown --- name: triage description: Triages a GitHub issue by severity and reproducibility, and proposes labels. --- # Issue Triage Read the issue title and body provided in the prompt. Decide: 1. `severity`: one of `low`, `medium`, `high`, `critical`. 2. `reproducible`: whether the report includes enough information to reproduce the problem. 3. `labels`: an array of suggested GitHub labels. 4. `summary`: a one-paragraph summary in Japanese. Be conservative. Do not guess at reproduction steps, affected users, system state, or business impact that are not present in the issue body. ``` ここで意識したのは、Issue本文に書かれていない影響範囲や再現条件を推測させないことです。トリアージは分類タスクに見えますが、実際には入力にない情報を補いたくなる場面が多いので、「保守的に判断する」という制約を明示しました。 ## Agentを書く Agent本体は`src/agents/issue-triage.ts`に置きました。 ```ts import '../providers'; import { createAgent } from '@flue/runtime'; import triage from '../skills/triage/SKILL.md' with { type: 'skill' }; export const description = 'Triages a GitHub issue by severity, reproducibility, and labels.'; export default createAgent(() => ({ model: process.env.FLUE_MODEL ?? 'openai/preview/Kimi-K2.6', skills: [triage], instructions: 'You triage incoming GitHub issues. Use the triage skill to classify severity, reproducibility, and suggested labels. Be conservative: never assume reproduction steps or impact that are not written in the issue body.', })); ``` 前回のQuickstartでは`anthropic/claude-sonnet-4-6`のようにモデルを固定していましたが、今回は手元で利用できるOpenAI互換APIを使いました。記事の主題はFlueの検証なので、特定providerの話は前面に出しません。重要なのは、Flue側では`provider-id/model-id`形式のmodel specifierを使い、必要に応じてprovider設定を差し替えられるという点です。 OpenAI互換APIを使う場合は、`registerProvider()`で組み込み`openai` providerの向き先を変えています。 ```ts import { registerProvider } from '@flue/runtime'; const openAiCompatibleApiKey = process.env.OPENAI_COMPAT_API_KEY; const openAiCompatibleBaseUrl = process.env.OPENAI_COMPAT_BASE_URL; if (openAiCompatibleApiKey && openAiCompatibleBaseUrl) { registerProvider('openai', { baseUrl: openAiCompatibleBaseUrl, apiKey: openAiCompatibleApiKey, models: { 'gpt-oss-120b': { contextWindow: 131_072, maxTokens: 16_384, }, 'preview/Kimi-K2.6': { contextWindow: 131_072, maxTokens: 16_384, }, }, }); } ``` このあたりで一度失敗したのは、独自のprovider IDを作ろうとしたことです。`sakura/example-model`のような独自prefixを登録すればよいと考えましたが、`flue run`ではモデル解決のタイミングにうまく乗らず、`Unknown model specifier`で止まりました。最終的には、OpenAI互換APIとして扱うなら、組み込みの`openai` providerをbase URL差し替えで使う方が素直でした。 ## Workflowを書く 1件のIssueを入力として受け取り、Agentを初期化して結果を返すWorkflowを作りました。 ```ts import '../providers'; import { type FlueContext, type WorkflowRouteHandler } from '@flue/runtime'; import * as v from 'valibot'; import issueTriage from '../agents/issue-triage'; type IssuePayload = { title: string; body: string; }; const TriageResult = v.object({ severity: v.picklist(['low', 'medium', 'high', 'critical']), reproducible: v.boolean(), labels: v.array(v.string()), summary: v.string(), }); export const route: WorkflowRouteHandler = async (_c, next) => next(); export async function run({ init, payload }: FlueContext) { const harness = await init(issueTriage); const session = await harness.session(); const { data } = await session.prompt(`Use the triage skill to classify this GitHub issue. Title: ${payload.title} Body: ${payload.body} Return only the structured triage result.`, { result: TriageResult, }); return data; } ``` ここではValibotで結果スキーマを定義しています。Issueトリアージのような後続処理につなげるタスクでは、自然文のまま返すより、`severity`や`labels`を型付きで受け取れる方が扱いやすくなります。 ## まずpayloadを直接渡して動かす `.env`は次のように、OpenAI互換APIとして抽象化した名前にしています。 ```text OPENAI_COMPAT_API_KEY="your-api-key" OPENAI_COMPAT_BASE_URL="https://your-openai-compatible-endpoint/v1" FLUE_MODEL="openai/preview/Kimi-K2.6" ``` `FLUE_MODEL`は必ず`provider-id/model-id`形式で書きます。OpenAI互換APIの向き先を差し替えている場合でも、Flue上のprovider IDは`openai`なので、`preview/Kimi-K2.6`ではなく`openai/preview/Kimi-K2.6`になります。 最初はGitHubには接続せず、Issueの`title`と`body`を直接payloadとして渡してWorkflowを確認します。ここで見たいのは、GitHub連携ではなく、Agent、Skill、Workflow、structured outputの中核処理が最後まで通るかです。 ```sh npm run triage -- '{"title":"Dashboard is blank after login","body":"Steps: log in, open /dashboard. Expected widgets. Actual blank white screen in Chrome 126."}' ``` 最終的に、次のような結果が返りました。 ```txt ▗ flue run ▚ workflow triage-issue ▘ starting... run run_... thinking The user wants me to triage a GitHub issue using the triage skill... tool activate_skill tool done activate_skill (547 chars) tool finish tool done finish { "severity": "high", "reproducible": true, "labels": [ "bug", "frontend", "dashboard" ], "summary": "ログイン後に /dashboard を開くと、ウィジェットが表示されるべきところが空白の白い画面が表示される。Chrome 126 で発生したバグ。" } done workflow completed ``` `tool activate_skill`でSkillが読み込まれ、最後に`tool finish`でValibotのスキーマに合う結果が返っています。このログを見ると、Flueが単にプロンプトを投げているだけではなく、Agentの実行をツール呼び出しと完了条件を持つプロトコルとして扱っていることが分かります。 ## 次にGitHub Issueを1件だけ読む 中核処理が動くことを確認した後で、GitHub CLIで実Issueを1件だけ取得する入口を足しました。ここでもGitHub webhookまでは作らず、`gh issue view`で取得した`title`と`body`を、先ほどと同じWorkflowへ渡します。 ```js import { execFileSync, spawnSync } from 'node:child_process'; const [, , repo, issueNumber] = process.argv; if (!repo || !issueNumber) { console.error('Usage: npm run triage:github -- owner/repo issue-number'); process.exit(1); } const issueJson = execFileSync( 'gh', ['issue', 'view', issueNumber, '--repo', repo, '--json', 'title,body,url,number'], { encoding: 'utf8' }, ); const issue = JSON.parse(issueJson); const payload = JSON.stringify({ title: issue.title, body: issue.body ?? '', source: { repo, number: issue.number, url: issue.url, }, }); const result = spawnSync( 'npx', ['flue', 'run', 'triage-issue', '--target', 'node', '--payload', payload], { stdio: 'inherit' }, ); process.exit(result.status ?? 1); ``` 使い方は次の通りです。 ```sh gh auth login npm run triage:github -- owner/repo 123 ``` `owner/repo`は対象リポジトリのフルネーム、`123`はIssue番号です。たとえば`withastro/astro`のIssue 1を読む場合は、次のように指定します。 ```sh npm run triage:github -- withastro/astro 1 ``` この方法なら、GitHub webhookの署名検証、常駐サーバー、コメント投稿権限、ラベル更新権限をいったん考えずに、実Issueの本文をFlueのWorkflowへ流せます。今回確認したかった中核は「Issueを読んだ後の分類処理」なので、最初のGitHub連携としてはこのくらいの薄さで十分でした。 実際に`withastro/astro`のIssueを1件読ませると、次のようにWorkflowが完了しました。 ```txt $ npm run triage:github -- withastro/astro 1 ▗ flue run ▚ workflow triage-issue ▘ starting... run run_... tool activate_skill tool done activate_skill (547 chars) tool finish tool done finish { "severity": "low", "reproducible": false, "labels": [ "enhancement" ], "summary": "本Issueは、開発時にファイル変更を自動的に検知してコンパイルする`npm run dev`モード（ウォッチモード）を追加する機能要請である。記載内容は要望の主旨のみに留まっており、具体的な実装方法、対象とするビルドツール、既存ワークフローへの影響などの詳細情報は含まれていない。" } done workflow completed ``` ここまで来ると、少なくとも「GitHub上の実Issueを読み、FlueのWorkflowで分類し、構造化結果として返す」ところまでは確認できたと言えます。まだGitHubへコメントを書き戻してはいませんが、Issueを読む部分とトリアージ中核処理はつながりました。 ## 詰まったところ 今回一番時間を使ったのは、API接続そのものよりも、モデルがFlueの実行プロトコルにどれだけ従えるかでした。 最初に試したモデルでは、API接続とモデル呼び出し自体は通っていました。しかし、Workflowの最後で必要な`finish` tool callを返せず、次のエラーで止まりました。 ```txt Error: Workflow failed: [internal_error] The agent gave up: Agent did not call `finish` or `give_up` after 33 attempts. ``` ログを見ると、モデルは「`finish`を呼ぶ必要がある」と文章では理解しているものの、実際のtool callとして返せていませんでした。これはFlueの問題というより、モデル側のtool calling適性やOpenAI互換API側の実装差が表に出たものだと見ています。 同じWorkflowでも、別のモデルに切り替えると`activate_skill`から`finish`まで進み、Workflowは完了しました。ここから分かるのは、Agentフレームワークの検証では「APIが呼べるか」だけでなく、「モデルがフレームワークの期待するtool callingやstructured outputのプロトコルを守れるか」を確認する必要があるということです。 ## まだやっていないこと 今回の記事では、GitHub webhookを受け取るChannel、GitHubへのコメント投稿、OpenTelemetryへのexportまでは実装していません。最初はそこまで一気に試すつもりでしたが、実際にはAgent、Skill、Workflow、model provider、structured outputだけでも十分に確認することがありました。 特に、未信頼のGitHub Issue本文を扱う場合、`local()`サンドボックスを安易に使うべきではありません。リポジトリのファイルを読ませたい、CLIを叩かせたい、GitHub tokenを使わせたい、といった欲求は自然に出ますが、その時点で「どの入力を信頼しているのか」「どの環境変数をAgentに見せるのか」という境界設計が必要になります。 残る検証範囲は、GitHub Actions上で`flue run`を呼び、Issue本文をpayloadとして渡す構成です。常駐サーバーで外部webhookを受けるよりも、まずはCIの使い捨て環境で動かす方が、検証としては扱いやすそうです。 その後の派生として、CIで呼ぶ方向と、実行ログを観測基盤へ送る方向を分けて検証しました。 ## まとめ 今回の検証で確認できたのは、FlueではAgentの振る舞いをSkillとして分け、WorkflowからAgentを初期化し、Valibotで構造化結果を受け取れるという点です。Issueトリアージのような「入力を分類し、後続処理に渡す」タスクとは相性がよいと感じました。 一方で、Agentフレームワークはモデルを差し替えれば同じように動く、というほど単純ではありません。特にtool callingやstructured outputを前提にする場合、モデルがプロトコルに従えるかどうかが実行成否に直結します。今回のように、あるモデルでは`finish`を返せず失敗し、別モデルでは同じWorkflowが完了する、という差は普通に起きます。 その意味で、Flueの検証では、コードがビルドできるか、APIキーが通るか、モデルが返答するか、Workflowが完了条件まで到達するかを分けて見る必要があります。ここを分けてログに残しておくと、単なる「動いた・動かなかった」ではなく、Agent実装時にどの層で問題が起きたのかを説明しやすくなります。