Building AI Agents with TypeScript #TSKaigiHokuriku

TSKaigi Hokuriku 2025 の登壇資料
https://hokuriku.tskaigi.org/talks/32

サンプルリポジトリ
https://github.com/izumin5210-sandbox/open-deep-research-with-ai-sdk

Transcript

1. Building AI Agents with TypeScript 2025-11-23 TSKaigi Hokuriku 2025 @izumin5210
2. @izumin5210 © LayerX Inc. whoami LayerX バクラク事業部 (2022-09 -) Platform Engineering 部 Enabling チーム Staff Software Engineer バックエンドや Web フロントエンドが専門です AI は初心者 ISUCON14 4位 好きな Drizzle ORM の API は .$type<TType>()
3. 今日話すこと © LayerX Inc. AI の活用 - Coding Agent のいい感じの使い方とか AI の開発 - AI を使った機能の開発 3
4. LLM の登場で AI 機能開発は TypeScript にも開かれた © LayerX Inc. 4
5. © LayerX Inc. 5
6. © LayerX Inc. 6
7. © LayerX Inc. 7
8. LLM により、モデルが汎用的な REST API になった © LayerX Inc. モデルが巨大になったことで、自前で学習・ホストせず プロバイダがホストするモデルを REST API 経由で使うことが主流に 学習ではなく入力（コンテキスト） でできる挙動の制御・最適化の範囲が広がった 1つの REST API で様々なタスクに対応できる 機械学習周りのエコシステムへの依存度が下がり、言語選択の自由度が高まる TypeScript も有力な選択肢に！ UI とも近く、かつ型安全性の高い TypeScript は Python に次ぐ選択肢となりえる 8
9. TypeScript で作られた AI Agent を見てみよう！ 2つのサンプルアプリケーションを例にしつつ、 TypeScript でどのように AI Agent を作るかを簡単に紹介します © LayerX Inc. 9
10. 利用するライブラリ: vercel/ai © LayerX Inc. 何をするライブラリ？ Model Provider の抽象化 Agent Loop の簡易なラッパー（Tool 実行のハンドリングなど） Web Frontend との接続をいい感じにしてくれる 薄い！ 知識がなくても(比較的)処理が追いやすい 内部で何が起きているかがわかりやすい 10
11. 例1. チャット
12. © LayerX Inc. 12
13. Backend API の実装。 streamText を呼ぶだけ。 © LayerX Inc. 13
14. Web Frontend の実装。 useChat で状態管理とAPI通信を行う。 © LayerX Inc. 14
15. 動いた！ …が、文字文字しくて見づらい © LayerX Inc. 15
16. おもむろに console.log(JSON.stringify(messages, null, 2)); 構造化された Tool 実行結果が含まれていることがわかる © LayerX Inc. 16
17. Tool Call の結果を型安全に、いい感じの UI で表示 Tool の結果を型安全に扱うための型定義 © LayerX Inc. 17
18. © LayerX Inc. 18
19. © LayerX Inc. 19
20. Tool Call の結果を型安全に、いい感じの UI で表示 © LayerX Inc. tools の定義からフロントエンドに渡るメッセージ（ UIMessage ）の型を生成可能 type MyUIMessage = UIMessage<..., InferUITools<typeof tools>> useChat<MyUIMessage> のように型パラメータで指定できる メッセージ ( UIMessage ) には構造化されたツール実行結果が含まれる messages.parts からツール実行結果を型安全に参照でき、専用 UI を表示可能 自前 Web UI 上で自前ツールを扱うだけなら、 MCP UI や AG-UI といった専用の仕組みは不要 20
21. チャット内容の永続化・復元 Drizzle ORM を利用して PostgreSQL に保存するスキーマ例 © LayerX Inc. UIMessage をお好みのデータベースに保存すれば OK 21
22. API ハンドラ上でユーザメッセージと AI が生成したメッセージを保存 © LayerX Inc. 22
23. vercel/ai を使った簡易チャットアプリ © LayerX Inc. Backend tool() でツールを定義・実装し、 streamText() に渡す チャット履歴の永続化は UIMessage[] を保存すればひとまず OK Web Frontend useChat でつなぎ込む UIMessage を拡張することで、専用UIも型安全に実装可能 23
24. 例2. Deep Research
25. Deep Research？ © LayerX Inc. ユーザーの質問に対して、複数の Agent が協調してリサーチを行う Web 検索を行いながら、徐々に情報を収集 最終的にまとまったレポートを生成 25
26. langchain-ai/open_deep_research © LayerX Inc. LangChain が公開している Open Deep Research を参考に、 AI SDK で実装し直してみた https://blog.langchain.com/open-deep-research/ https://github.com/langchain-ai/open_deep_research https://academy.langchain.com/courses/deep-research-with-langgraph 複数の Agent が連携し、動作するシステム Agent の構成がよく練られており、教材としてちょうど良さそう（？） 26
27. 複数の Agent が連携する Workflow Workflows are systems where LLMs and tools are orchestrated through predefined code paths. Agents, on the other hand, are systems where LLMs dynamically direct their own processes and tool usage, maintaining control over how they accomplish tasks. - Building effective agents * © LayerX Inc. * Anthropic, 2024, https://www.anthropic.com/engineering/building-effective-agents 27
28. 複数の Agent が連携する Workflow ワークフロー とは、LLMとツールが事前に定義されたコードパスに沿って制御されるシステムを指しま す。 一方、 エージェント とは、LLMが自らのプロセスとツールの使用を動的に制御しながら、タスクの実行方 法を自律的に決定するシステムを指します。 - Building effective agents *（日本語に訳したもの） © LayerX Inc. * Anthropic, 2024, https://www.anthropic.com/engineering/building-effective-agents 28
29. © LayerX Inc. https://github.com/langchain-ai/open_deep_research 29
30. langchain-ai/open_deep_research の Agent 構成 © LayerX Inc. User Clarification, Brief Generationn ユーザーとの対話で要件を明確化し、調査指示書を生成 Research Supervisor Agent リサーチ全体を監督し、サブエージェントに委譲 Research Sub-agents 実際に並列で検索を行い、得た情報のサマリを Supervisor に返す One-Shot Report Generation 最終レポートを生成 30
31. User Clarification © LayerX Inc. https://blog.langchain.com/open-deep-research/ 31
32. User Clarification © LayerX Inc. 32
33. User Clarification: generateObject による構造化出力 © LayerX Inc. 33
34. Brief Generation © LayerX Inc. https://blog.langchain.com/open-deep-research/ 34
35. Brief Generation © LayerX Inc. 35
36. Brief Generation: Agent 連携 © LayerX Inc. User Clarification の結果をもとに、Brief Generation を呼び出す必要がある プロンプトどころか、場合によっては利用モデルが違う可能性もある どうやって連携する？ 36
37. Workflow: Prompt Chaining © LayerX Inc. https://www.anthropic.com/engineering/building-effective-agents 37
38. Brief Generation: Agent 連携 © LayerX Inc. 38
39. Research © LayerX Inc. https://github.com/langchain-ai/open_deep_research 39
40. Research Supervisor © LayerX Inc. researchBrief を受け取る brief を元に調査項目を決定し、sub-agent に移譲 sub-agent からの結果を確認し、不十分であれば次の調査を指示 結果が十分であれば調査完了を宣言 40
41. Research Supervisor © LayerX Inc. sub-agent の呼び出しはどのようにするか？ 41
42. Research Supervisor: sub-agent 呼び出し シンプルに Tool として Research Agent を実行するだけ © LayerX Inc. 42
43. 単純な Agent 連携は実装が容易 © LayerX Inc. メッセージ履歴・コンテキストの共有や Agent 同士の interaction などが不要なら、 特別な仕組みなしに Agent 連携は実装できる e.g. clarification → brief generation は通常の関数呼び出しのようにパラメタを渡すだけ research supervisor → sub-agent は Tool として呼ぶだけ OpenAI Agents SDK や Strands Agent では agent as tool の仕組みが API として提供されている 43
44. © LayerX Inc. 44
45. Research sub-agent © LayerX Inc. researchTopic を元に、複数の検索クエリを生成 検索を並列で実行 結果を要約・結合して supervisor に返す 並行プログラミングにおける Fan-in / Fan-out パターンが近いイメージか？ 45
46. Workflow: Parallelization © LayerX Inc. https://www.anthropic.com/engineering/building-effective-agents 46
47. Research Supervisor: 調査の終了 / loop control © LayerX Inc. ループ制御の仕組みが必要 調査結果に満足したらループを抜けなければならないが、満足できない場合は無限に調査し続ける可能性もある 47
48. Langfuse などの LLM Observability ツールで Agent 連携や Tool 呼び出しの Trace を確認する © LayerX Inc. 48
49. Agent Loop と AI SDK の Loop Control © LayerX Inc. AI SDK の generateText や streamText は内部で Agent Loop を回している 終了条件 にあたるのが stopWhen: [hasToolCall("..."), stepCountIs(n)] 49
50. あとはいい感じにがんばる コードは https://github.com/izumin5210-sandbox/open-deep-research-with-ai-sdk にあります © LayerX Inc. 50
51. Deep Research は複数の Agent を Workflow として制御して実現する © LayerX Inc. 完全に自律的に動作する1つの Agent で実装できなくはないかもしれないが… 扱うコンテキストが大きくなりすぎてしまう 特に調査 Agent は巨大な検索結果や Web ページなどを扱うのでコンテキストが膨らみがち 決定論的に処理できるものを確率的に処理させる必要性は低い 「検索結果を取得したら必ず要約する」を AI に判断させるか？ 忘れたら大変なことに… どこを決定論的に、どこを LLM で柔軟・自律的に処理させるかのタスク設計が重要そう 今回は langchain-ai/open_deep_research がいい感じに設計してくれているが、 本来は解くべき問題に応じて設計が必要 そして設計・実装がうまくいったかを評価する同じく重要 今日は省略… LangChain Academy の Depp Research のコース*では軽く触れられています * https://academy.langchain.com/courses/deep-research-with-langgraph 51
52. あんまり難しく考えすぎない © LayerX Inc. 1つの Agent に対するメッセージのループにとらわれすぎず、 素直に処理を分ける・Agent を分ける 自分はAI Agent の開発を始めた直後、ここでかなりハマった ちゃんとタスクを分解する・タスクごとに Agent (関数) を分ける ワークフローのパターンをまとめたドキュメントやブログがあるので、適宜参考に 外側だけ見ると普通の制御構造とそんな変わらない https://www.anthropic.com/engineering/building-effective-agents https://ai-sdk.dev/docs/agents/workflows 「Agent 連携」も、単純な結果の引数渡しや Tool cal で済むケースも多い 52
53. 余談: Context Engieering など、精度を上げるための取り組み © LayerX Inc. 今回はほぼ触れなかったが、Open Deep Agent には精度を上げるために 様々な Context Engineering のプラクティスが適用されている e.g. researcher sub-agent は余計な情報を削ぎ落としてから supervisor に戻す 慣れてきたらそういう目線で Open Deep Research を読むと楽しい 53
54. 例2'. Durable Deep Research
55. Deep Research はこのままだと本番に出しづらい © LayerX Inc. 処理時間が長い 数分〜10分程度かかることもある それ自体は仕方ないが、そのあいだ通信が切れたりすると結果が失われる 状態遷移も複雑 clarify -> generate brief -> research と API が3つに分かれたとして、その管理はフロントがやるのか…？ 55
56. Durable な実行基盤に乗せる © LayerX Inc. Durable - 耐久性のある 長時間実行でも・途中で通信が切れても・サーバ落ちても… ちゃんと最後までタスクを実行できるような基盤 そのために Resumable, Observable も同時に達成される かつ、Resumable であることで状態遷移の管理も楽になる（後述） Temporal*, Trigger.dev**, vercel/workflow (Workflwo Development Kit)*** など * https://docs.temporal.io/workflows ** https://trigger.dev/ *** https://useworkflow.dev/ 56
57. Deep Reserach を vercel/workflow で © LayerX Inc. 57
58. Deep Research のワークフロー中の各ノード（Agent）を Step として定義し… © LayerX Inc. 58
59. Deep Research のワークフロー中の各ノード（Agent）を Step として定義し… © LayerX Inc. 59
60. 定義した Step を呼び出す Workflow を記述する © LayerX Inc. 60
61. 処理の流れ・input/output などを可視化できる Web UI が付属 © LayerX Inc. 61
62. Durable な実行基盤に乗せる © LayerX Inc. 長時間実行でも・途中で通信が切れても・サーバ落ちても… ちゃんと最後までタスクを実行できるような基盤 一連の処理の流れ（workflow）を1つの関数で記述することになり、見通しも良い ワークフロー外部（例えば Web Frontend が叩く API）から稼働中のワークフローに message を送ることもできる Human-in-the-Loop を含むようなワークフローも扱える 62
63. 余談: vercel/workflow 所感 (1/2) © LayerX Inc. AI 関係なく、バックグラウンドジョブを簡潔に記述でき、 信頼性高く実行できる基盤としてアツい 最初期の技術選定では見落としがちかもしれないが、 プロダクト開発ではほぼ必須の要素 これをデファクトを備えているフレームワークは意外と少なく、 これが Next.js にインテグレーションしやすい形で出てきたのは大きい 63
64. 余談: vercel/workflow 所感 (2/2) © LayerX Inc. この AI 時代に Vercel が出してきただけあって、 AI を Workflow に乗せやすくするための高度な機能が備わる Workflow から外部（例えば Web Frontend が叩く API）に stream でデータを流せる謎の仕組み AI SDK v6 の Agent abstraction を利用した DurableAgent なる仕組みも開発中 このクラスを使って定義・実装された Agent は Durable に実行され、その結果を stream で外に流せる Open Deep Research もこの仕組みを使えばかなりシンプルに実装できる！ かも？ まだまだ開発中のものも多いが、かなりワクワクする感じになってる 64
65. まとめ
66. TypeScript で AI Agent を作る © LayerX Inc. LLM により、AI 機能開発は TypeScript にも開かれた モデルが汎用的な REST API になった 言語選択の自由度が高まった TypeScript で AI Agent を作る利点 Web Frontend と同じ言語・エコシステム 型安全性が高い 既存の Web アプリケーション開発の知識が活かせる 66
67. TypeScript で AI Agent を作る © LayerX Inc. vercel/ai のような薄いライブラリでもそれなりに実装できる streamText で Tool Calling を含む Agent Loop を簡単に実装 useChat などの React Hooks で Frontend との連携が簡単 複数の Agent を組み合わせることで、複雑なタスクも実現可能 Agent を Tool として呼び出す（ ToolLoopAgent を使用） 並列実行やステップ数の制限など、実行を制御する機能 Temporal や vercel/workflow といった Durable Execution の仕組みも整いつつある 67
68. AI 初心者が AI Agent を作る © LayerX Inc. あんまり考えすぎず・いろいろ同時に学びすぎず、 とりあえず手を動かしてみたほうが解像度上がるかも RAG, MCP, MCP-UI, AG-UI, ... 楽しそうな概念はたくさんあるが、これらなしで戦える範囲は意外と広い TypeScript にこだわらなければ、 Deep Research をはじめとして様々な実装が OSS で存在する それを写経・移植するだけでもかなり学びが多い 68
69. 宣伝 © LayerX Inc. 69
70. 技術書典に出しました！ 僕は落としました。 370ページ超の超大作！ © LayerX Inc. 70
71. LayerX は TSKaigi Hokuriku 2025 にブースを出してます 今日はバクラクではなく Ai Workforce 事業部が来ています 今日の話を詳しく聞きたい / AI プロダクトの話を聞きたい / 普通にフロントエンドの話を聞きたい方もぜひ！ © LayerX Inc. 71