イネーブリングチームの東です。
直近はAIエージェント開発を支えるAgentSDKチームとして動いており、いくつかの社内ライブラリを作りました。
社内ではMastraを中心にAIエージェント開発が進んでいたため、Mastraで提供されていない機能を中心に作っていきました。
要望を受けつついろいろ作っていったのですが...実際の使われ方は想定とは違うものでした。
この記事では、社内ライブラリを作ってみて起きたこと・学んだことをまとめます。
同じく社内ライブラリ開発に関わる方々の参考になればと思います。
背景と経緯
TOKIUMがAIエージェント開発に舵を切ることになったとき、「AIエージェントのどこでも必要になるようなものを作ってほしい」と依頼を受けました。
そこで、まず現場のチームに参加し、全体ミーティングにも出席しながら、意見や要望を収集していくことにしました。
各チームと一緒に動いてみると、すぐに気づいたことがありました。急速に開発を進めていく中で機能面が重要視され、リリース後の運用やセキュリティ面はまだ話題に上がっていません。
そこで、個人情報検出などのガードレール機能、テレメトリーの整備などに取り組むことにしました。
また、開発が進むにつれて、各エージェントで同様の機能要求が見えてきました。管理画面に対するOAuth認証、チャット・会話機能など、どのエージェントでも必要になるものです。
これらを毎回ゼロから実装するのは非効率的であり、現場からも整備に苦労している声があったので、共通化できる部分を支援する仕組みが必要だと考えました。
このような経緯で、agent-sdkというライブラリ群を作っていくことになりました。
作ったもの
今回はagent-sdkというプライベートなnpmパッケージ群を作りました。
agent-sdkは3つのパッケージで構成されています。
全体構成
agent-sdk (monorepo)
├── packages/mastra-sdk - Mastra向けユーティリティ
├── packages/react-sdk - React向けユーティリティ
└── packages/bootstrap-mcp - プロンプトベースのセットアップ自動化
packages/mastra-sdk
src/
├── oauth/ - TOKIUM OAuth認証ミドルウェア
├── processors/ - セキュリティガードレール（個人情報検出、リンク制限、独占業務防止）
├── telemetries/ - OpenTelemetryベースのテレメトリー計装
├── chats/ - チャット機能とスレッド・メッセージ管理
└── evals/ - AIモデル出力品質の評価メトリクス
- oauth: ミドルウェアとして提供、トークン管理を隠蔽
- processors: AIモデルの入出力を安全に制御するプロセッサ群
- telemetries: Mastra EvalsをOpenTelemetryで計装、Datadogへ送信
- chats: スレッドベースのチャット機能、REST API提供
- evals: Hallucination検出などの評価メトリクス
packages/react-sdk
src/
└── oauth/ - TOKIUM OAuth認証コンポーネント
- oauth: Reactコンポーネントとhooksで提供、OAuthフローを簡素化
packages/bootstrap-mcp
src/
├── mastra/ - Mastra向けセットアップ自動化
└── react/ - React向けセットアップ自動化
- mastra: OAuth、テレメトリー、ガードレール、テンプレートのセットアップ
- react: React OAuth、テンプレートのセットアップ
- MCPサーバーとして動作し、Claude Codeなどから利用可能
何が起きたか
結論から言うと、認証や会話機能は使われたものの、その他の機能はあまり定着しませんでした。
使われなかった理由をいくつか述べてみます。
フレームワークの進化に追いつかれてしまった
作った当初はMastraに備わっていなかった機能を実装しても、フレームワークの開発が追いついてしまって陳腐化するという問題がありました。
例えば、個人情報検出などのガードレール機能を作りましたが、作ったタイミングでGuardrailが入ってしまいました。
本家にないものだけ残しましたが、重複するものはメンテナンスコストだけかかって意味がありません。
開発者の慣れたやり方からずれてしまった
MastraはOpenTelemetryに対応していたため、DatadogへのトレーシングもOpenTelemetryで実現しましたが、dd-traceなどこれまでのやり方と異なるため、敬遠される形になってしまいました。
ただでさえAIエージェントやMastraなどキャッチアップが必要なことが多い中で、新しいやり方を強いるのは負担になります。
フレームワークの破壊的変更が多くサポートしづらかった
採用段階でMastraはまだ安定版ではなく、頻繁に破壊的変更が入っていました。
例えばEvals機能に対してOpenTelemetryで計装する仕組みを作りましたが、途中でScorerに変更されてしまい、それまでのやり方が使えなくなってしまいました。
また、Mastraを使う各サービス側でもMastraのバージョンが異なることが多く、全てをサポートすることは無理でした。
認証と会話履歴機能は使われた
一方で、認証と会話履歴機能は比較的使われました。両者ともにフレームワークで提供される機能というよりは、各エージェントで必須になる機能だったためです。
実装が複雑だったり共通のインターフェースを維持することが困難な問題に対して、各サービスは具体的な実装を考えなくて良くなりました。
一番印象的だったのは、全体のミーティングで話題に上がることが減ったことです。いちいちOAuthの話が問題にならなくなり、認知負荷が下がったことを実感しました。
学び
社内向けのツールを簡単に作って運用することはありましたが、共通で使われるライブラリを作るのは初めての経験でした。
その中で学んだことをまとめます。
1. 現場にとにかく足を運ぶこと
外から見ているだけだと、ニーズもふんわりとしたままの理解になります。
いざ作ったとしてもプロモーションできず、何も使われないままになってしまいます。
現場に入り込んで一緒に開発を続けることでニーズを理解できますし、信頼を得ることで導入もスムーズになります。
2. フレームワークの動向を注視・予測すること
自分たちが必要としている一般的な機能は、他の人たちも必要としていることが多く、フレームワークに取り込まれる可能性があります。
公式に立っているissueをウォッチしたり、ロードマップを確認したりして、フレームワークの動向を注視することが重要です。
とはいえ放置されるissueもあるので、無駄なくというのはなかなか難しいのですが。
3. 認知負荷に注目すること
新しいライブラリを導入するとき、開発者は新しい概念や使い方を覚える必要があります。
サンプルやドキュメントを用意しても、認知負荷が高いと敬遠されがちです。
ライブラリを必要とする領域も、認知負荷が高い面倒な問題が含まれているのかもしれません。
総括
社内ライブラリは作ること自体に熱中してしまいがちかもしれませんが、実際にチームに組み込んで使ってもらわないと意味がありません。
現場と一緒に苦労を重ねて信頼を得て、見つかった課題から本当に必要なものを蒸留し、滑らかに導入して、安心して使ってもらうことが重要です。
Discussion