Engineer Blog

Anri Nakamura

Kakemu Fujii

Kento Kaseda

Reo Hakuta

Erika Sakurai

erikasakurai

Takaharu Nakamura

Daichi Hachisuka

Louis Avondet

Sota Sato

Taira Ouchi

Yuta Azumi

Takahiro Hayashi

Kairi Ueno

Hiroki Tamiya

Yugo Tsuchiya

TomokiIchikawa

Yoshito Ikeda

Haruki Tazoe

Hajime Shiozawa

Kazuki Katsurada

masashi kobayashi

lapla

Takehiko Okayama

Kotaro Ito

Yuhei Yasuda

naoyashiga

Takumi Ishii

Sojiro Nishimura

Katsumi Kobayashi

Kota Momoki

Calloc

Shohei Shiraki

Takaaki Kanetsuki

Yui Taniyama

Kota Yatagai

Shuhei Kondo

kenshin tanaka

KARTE Team

Security Team

Tomoya Koike

Haruki Tosa

Daiki Sakuma

Takuma Shibuya

plaidinc

Takami Yamada

Blocks Team

Takanori Koga

Takumi Katayama

Yu Nishimura

Takuya Ogawa

akira.kasuga

Kosuke Oya

Yoshiyuki Komazaki

mizchi

Ryosuke Suzuki

koichi tanaka

Arnaud Avondet

kazupon

daigo.isamatsu

Jun Kusahana

Shinnosuke Ozawa

Rei Ishikawa

Hiroto Harada

Kei Tamiya

Nobuhiro Ito

kazushi oohira

Yohei Meguro

Kazuto Kojima

Tomoki Koga

Kenichi Suzuki

Takaaki Nakama

Takahiro Tokunaga

Kohei Kadowaki

kantetsu

Makoto Kataigi

Tatsuya Monoi

Jumpei Ikegami

Masahiro Yamauchi

Shinji Eto

Yuta Nishimura

Hideyuki Okada

Wataru Ikarashi

Naoto Kato

Yuki Makino

Atsushi Fujikawa

Naohiko Takemura

Daikichi Sasamori

Atsushi Kobayashi

Naoki Shibayama

Daiki Matsui

Yohei Noda

<h1>はじめに</h1>
<p>この記事は <a href="https://qiita.com/advent-calendar/2025/datadog">Datadog Advent Calendar 2025</a> の3日目の記事です。</p>
<p>こんにちは、プレイドの Developer Experience &amp; Performance チームでエンジニアをしている大矢です。Datadog の好きな機能は <a href="https://docs.datadoghq.com/continuous_integration/">CI Visibility</a> と <a href="https://docs.datadoghq.com/dashboards/widgets/split_graph/">Split Graph</a> です。</p>
<p>Datadog の <a href="https://docs.datadoghq.com/ja/actions/workflows/">Workflow Automation</a> は Datadog の <a href="https://docs.datadoghq.com/ja/actions/actions_catalog/">Action</a> を組み合わせたワークフローを組むことができる機能です。Datadog の API で提供されているような機能を中心として様々なクラウドプロバイダーや SaaS ツールとも連携できます。</p>
<h1>背景：なぜ Pod を削除するのか</h1>
<p>私たちが運用しているサービス KARTE は GKE 上に構築されています。普通、Pod にはヘルスチェックが設定されており、サービスが応答できない状態になったらコンテナを再起動するようになっています。しかし、うまくコンテナを再起動するようにコントロールできないケースや、Pod を消して作り直した方が早いケースがこれまでに何度かありました。</p>
<p>例えば、GKE の既知の問題として Image Streaming を有効にしている際に、Image Pull のタイミングによってはファイルが存在せずに実行できないということがありました（<a href="">https://docs.cloud.google.com/kubernetes-engine/docs/troubleshooting/known-issues?hl=ja#image-screaming-missing-files</a>）。Image Streaming を有効にしているノードの中で、特定のイメージのファイルが欠落することがあるという状態でした。このケースでは、コンテナは再起動されますが同じノードで再起動しようとするため、何度再起動しても正常に起動することはありません。しかし、Pod を削除してしまえば別のノードに配置されるため、起動できる可能性があります。</p>
<p>このように 「Pod を消せば解決する」パターンはいくつかあり、社内では Pod を削除するマニュアルを作って、既知の問題には Pod を削除して解決することがしばしばありました。しかし、Datadog の画面上から問題の Pod 名を抽出した後に、GCP の管理画面もしくは CLI 上から Pod 削除を実行するというもので、地味に面倒くさいというのと決まりきった作業なのに自動化できていないという問題点がありました。</p>
<h1>Private Action Runner のセットアップ</h1>
<p>今回作成する Workflow では Pod を削除する Action を使用します。Kubernetes Core というカテゴリにあるアクションを使用する場合には Private Action Runner をインストールする必要があります。</p>
<p>App Builder モードと Workflow Automation モードがありますが、今回は Workflow Automation でしか使用しないため Workflow Automation モードを使用します。</p>
<p>https://docs.datadoghq.com/ja/actions/private_actions/#workflow-automation-mode</p>
<p><img src="https://ik.imagekit.io/plaid/5a2399e0-f356-4f82-b242-96f97ded17c9/private_action_runner_-_diagram_workflow.9034fc43fe904c71755911b987a8475e.avif" alt="private_action_runner_-_diagram_workflow.9034fc43fe904c71755911b987a8475e.avif"></p>
<p>Datadog の管理画面上から手順を進めていくと、次のようなコマンドを実行するように指示されます。</p>
<pre><code class="language-bash">docker run \
  -e DD_BASE_URL=https://us5.datadoghq.com \
  -e RUNNER_ENROLLMENT_TOKEN=xxx \
  -e STATSD_ENABLED=true \
    gcr.io/datadoghq/private-action-runner:v1.14.0 \
  --enroll-and-print-config

</code></pre>
<p>これを実行すると Helm charts に設定するべき config が生成されます。Pod を削除するアクションのみを許可した場合の config は次のようになりました。</p>
<pre><code class="language-yaml">actionsAllowlist:
    - com.datadoghq.kubernetes.core.deletePod
allowlist:
    - '*'
allowIMDSEndpoint: false
ddBaseURL: https://us5.datadoghq.com
modes:
    - pull
port: 9016
privateKey: xxx
urn: xxx
reportMetrics: true
</code></pre>
<p>注意点としては3つあります。</p>
<p>まず1つ目は secret の扱いです。Kubernetes を運用する場合 GitOps のように GitHub に Manifest をコミットして管理することが多いと思います。その場合には secret をそのままコミットするわけにはいきません。<a href="https://github.com/DataDog/helm-charts/tree/main/charts/private-action-runner#using-kubernetes-secrets-for-runner-identity">runnerIdentitySecret</a> を使用して Secret リソースを参照するようにし、Secret リソース自体は External Secrets Operator などのツールを使って管理します。</p>
<p>2つ目にスキーマが違う問題がありました。 下記の設定はエラーになります。</p>
<pre><code class="language-yaml"># kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
helmCharts:
- name: private-action-runner
  includeCRDs: true
  valuesFile: values.yaml
  releaseName: private-action-runner
  version: v1.18.0
  repo: https://helm.datadoghq.com

# values.yaml
$schema: https://raw.githubusercontent.com/DataDog/helm-charts/private-action-runner-1.18.0/charts/private-action-runner/values.schema.json
runner:
  runnerIdentitySecret: &quot;datadog-runner-identity&quot;
  # Replace this section with the output of the private action runner enrollment process with the `--enroll-and-print-config` flag
  config:
    allowIMDSEndpoint: false
    ddBaseURL: https://us5.datadoghq.com
    modes:
      - pull
    port: 9016
    reportMetrics: true
    actionsAllowlist:
        - com.datadoghq.kubernetes.core.deletePod
    allowlist:
        - '*'
</code></pre>
<pre><code class="language-bash">$ kustomize build .
Error: Error: values don't meet the specifications of the schema(s) in the following chart(s):
private-action-runner:
- runner.config: Additional property reportMetrics is not allowed
- runner.config: Additional property allowlist is not allowed
</code></pre>
<p>allowlist と reportMetrics のパラメータはドキュメントを見る限りすでに許可されていませんでした。そのためこれらのパラメータは消しました。</p>
<p>3つ目に actionsAllowlist についてですが、これを設定するだけでは private action runner が Pod を削除することはできませんでした。理由としては、この Helm charts で作成された Role リソース（private-action-runner に Bind されています）に Pod delete が割り当てられていないからです。</p>
<pre><code class="language-yaml">apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: private-action-runner
rules:
  - apiGroups:
      - &quot;&quot;
    resources:
      - pods
    verbs:
      - get
      - list
</code></pre>
<p>結局、ドキュメントを見ていると kubernetesActions というパラメータがあったのでこれを設定することで Pod を削除する権限を与えることができました。</p>
<pre><code class="language-yaml"># values.yaml
$schema: https://raw.githubusercontent.com/DataDog/helm-charts/private-action-runner-1.18.0/charts/private-action-runner/values.schema.json
runner:
  runnerIdentitySecret: &quot;datadog-runner-identity&quot;
  # Replace this section with the output of the private action runner enrollment process with the `--enroll-and-print-config` flag
  config:
    allowIMDSEndpoint: false
    ddBaseURL: https://us5.datadoghq.com
    modes:
      - pull
    port: 9016
  kubernetesActions:
    pods: [&quot;get&quot;,&quot;list&quot;, &quot;delete&quot;]
</code></pre>
<p>あとは、Private Action Runner 作成の手順に従って、Connection を作成します。Credentials は Service account authentication を選ぶのがスムーズです。</p>
<p><img src="https://ik.imagekit.io/plaid/2fcfbbf1-3bce-4a2f-b353-8c863c557419/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882025-12-0122.38.21.png" alt="スクリーンショット2025-12-0122.38.21.png"></p>
<p>Private Action Runner をインストールした際には、シンプルに Pod 削除をするだけの Workflow を作って検証するのが良いと思います。まずは pod 名を指定して削除するだけの Workflow を作り、テスト実行しました。</p>
<p><img src="https://ik.imagekit.io/plaid/b64ff087-5d6f-4eb0-803b-7be10de19e04/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882025-12-0122.40.34.png" alt="スクリーンショット2025-12-0122.40.34.png"></p>
<h1>作った Workflow</h1>
<p>最終的には次のようなワークフローを作りました。説明しやすさのために4つのセクションに色分けをしています。</p>
<p><img src="https://ik.imagekit.io/plaid/c318286c-819b-4a47-9045-63103ea9d367/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882025-12-0122.55.47.png" alt="スクリーンショット2025-12-0122.55.47.png"></p>
<ol>
<li>トリガーとパラメータの準備</li>
<li>10分以内に同じ Deployment の Pod 削除が実行されていないかのチェック</li>
<li>Ready Pod が Desired Pod よりも少なくないことのチェック</li>
<li>通知と Pod 削除の実行</li>
</ol>
<p>となっています。それぞれ解説していきます。</p>
<h2>1. トリガーとパラメータの準備</h2>
<p>Workflow Automation ではトリガーを設定します。いくつかやり方がありますが、今回のように異常を検知してその異常に対して何かアクションをするようなケースでは Monitor が適しています。Monitor の Mention として Workflow を設定できます。</p>
<p><code>@workflow-pod-delete(pod_name=&quot;{{pod_name.name}}&quot;,slack_channel=&quot;#hogehoge&quot;)</code></p>
<p>Mention にはパラメータを渡すことができます。どの Pod を削除するかというのはどの Pod で問題が起きているかによるので、パラメータとして渡す必要があります。ログやメトリクスのモニターを作る場合には pod_name で Group By して Multi Alert を設定することで、<code>{{ pod_name.name }}</code> を変数展開して渡すことが可能です。他にも、パラメータをうまく活用することで Workflow を汎用化することができます。例えば slack_channel というパラメータを用意していますが、これをすることで様々なチームでこの Workflow を利用することができます。モニターのメンションとして slack チャンネルを指定することもできますが、Workflow のパラメータとして slack_channel を用意している理由については後述します。</p>
<p>トリガーの次に deployment name というステップで Deployment 名を抽出しています。Data Transformation というアクションを使用し、次のような式を書いています。</p>
<p><code>$.Trigger.pod_name.split('-').slice(0, -2).join('-')</code></p>
<p>これだけで、Pod 名から Deployment 名を取得することが可能です。Deployment 名をパラメータとして渡すこともできます（モニターを pod_name と deployment_name の Multi Alert にすれば良い）が、使う側でパラメータが増えるというのと無駄な Group By が増えるのでこのようにちょっとしたパラメータの準備をしています。</p>
<h2>2. 10分以内に同じ Deployment の Pod 削除が実行されていないかのチェック</h2>
<p>Pod を削除する処理が短い時間で何度も行われているということは、何か想定していない事象が起きている可能性が高いです。Workflow や Monitor の設定方法が間違っていた場合、正常に動いているのに Pod を削除し続けてしまい障害になるということもあり得ます。そのような事故を防ぐための予防策として、10分間のクールタイムを設定したいと考えました。</p>
<p>これには <a href="https://docs.datadoghq.com/ja/actions/datastores/">Datastore</a> という機能を利用しています。「Get Timestamp」ステップでは Deployment 名をキーとして、その Deployment に対して Pod 削除が実行された最新のタイムスタンプを取得しています。次の「has 10 min passed」では、そのタイムスタンプから10分以上経過しているかを JavaScript でチェックしています。もし10分以内に Pod 削除を実行していなければ、「Put item」で Deployment 名をキーとして現在のタイムスタンプを保存します。</p>
<h2>3. Ready Pod が Desired Pod よりも少なくないことのチェック</h2>
<p>Desired Pod に対して Running Pod が足りてない場合、Pod 削除を実行することにより Pod が不足し、リクエストを捌ききれなくなる可能性があります。このような場合には Pod 削除を自動で実行することは避けておいた方が無難です。</p>
<p>Desired Pod は Datadog Action の Query scalar data で取得し、Ready Pod は Kubernetes Action の List pod で取得しています。Query scalar data は Datadog の Metrics に対する集計値を取得することができます。Query window の最小値が1分なためどうしてもラグがありますが、 <code>kubernetes_state.deployment.replicas_desired</code> のメトリクスの最大値としています。</p>
<p><img src="https://ik.imagekit.io/plaid/85fbc3df-77d4-465d-9de4-5319d919824a/%E3%82%B9%E3%82%AF%E3%83%AA%E3%83%BC%E3%83%B3%E3%82%B7%E3%83%A7%E3%83%83%E3%83%882025-12-0123.50.02.png" alt="スクリーンショット2025-12-0123.50.02.png"></p>
<p>Kubernetes Action で Deployment の replicas を直接取得する方法もありそうでしたが、Private Action Runner に Deployment の get の権限をつける必要がありそうで、面倒だったのでこのやり方にしています。</p>
<p>Ready Pod の取得では List pod を叩いた後に、status を確認して Ready なものの数を確認します。List pod では pod の状態が取得できるため、次のようなクエリを書いて Ready なものを抽出します。</p>
<p><code>$.Steps.List_pod.items.filter(value =&gt; value.status.containerStatuses.every(s =&gt; s.ready)).length</code></p>
<p>Desired Pod 数の取得と Ready Pod 数の取得を並列で行い、それらを比較することで自動で Pod を削除できるかの判断をします。</p>
<h2>4. 通知と Pod 削除の実行</h2>
<p>2, 3 のそれぞれの条件が True であれば自動的に Pod の削除を実行します。「Send pre delete」のステップでは Pod 削除を実行する前のログとしての通知を slack に送信します。次に「Delete pod」で削除を実行します。Pod がすでに存在しない場合など、「Delete pod」が失敗することもあるので、失敗時にも通知されるようにしています。</p>
<p>また、2, 3 の条件のいずれかが False であれば、Pod を削除することのリスクが高い可能性があります。しかし場合によっては Pod を削除した方が良い可能性もあるので、「Make a decision」というアクションを使って Approve されたら「Delete pod」を実行するというようにしています（単純に「Make a decision」を使ってみたかったというのもあります）。</p>
<h1>まとめ</h1>
<p>この記事では、Datadog の Workflow Automation を使って、安全に Pod を削除する方法を紹介しました。今回作成した Workflow によって問題が起きた Pod を削除するという手間を省くことができるようになりました。</p>
<p>Workflow Automation で使える Action はとても豊富で、他にも色々な活用方法がありそうです。Preview ですが <a href="https://www.datadoghq.com/blog/datadog-agent-builder/">Agent Builder</a> という機能を使うことで AI Agent によるアクションを Workflow に埋め込むこともできそうなので、試してみたいと思います。</p>


DatadogのWorkflow Automationで、再起不能なGKEのPodを安全に自動削除する具体的手順と設計ポイントを紹介します。クールタイム管理、Desired/Readyの健全性チェック、Slack通知と承認で誤作動を防ぎつつ、運用の手間を減らします。Helm設定の注意点や権限付与、メトリクス活用まで実例でまとめました。

Datadog の Workflow Automation を使って再起不能になった Pod を安全に削除する

KARTEの分析システムのレガシーな開発環境を高速にする。pnpm, Rspackの導入で改善できたこと。

<h1><strong>Introduction</strong></h1>
<p>I’m Oya from the Developer Experience &amp; Performance team. On <strong>October 30, 2025</strong>, <a href="https://plaid.co.jp/en/">PLAID, Inc.</a>  announced the direction for AI‑native transformation of <a href="https://karte.io/">the KARTE product series</a>, called <strong>“KARTE AI”(<strong>https://plaid.co.jp/news/20251030/</strong>)</strong>, and released several features in beta. In April 2025, we launched the KARTE AI Project to drive development of these features. I have mainly focused on platform-level work. This article explains how we ran the project, why we chose a “centralized” architecture, and the advantages of using <a href="https://mastra.ai/">Mastra ↗</a>.</p>
<h1><strong>About the KARTE AI Project</strong></h1>
<p>Before the project began, AI integration into KARTE products had barely progressed. Some products did ship AI features, but frameworks varied and we lacked a unified push to share knowledge and improve efficiency across teams. These challenges led us to launch the KARTE AI Project.</p>
<h2><strong>Project Goals</strong></h2>
<p>Based on the issues above, we set two goals:</p>
<ul>
<li>Develop talent who can lead AI development.</li>
<li>Design how to build AI features in a microservices architecture.</li>
</ul>
<p>Releasing AI‑powered features matters, but within this project, releases are a means to the end.</p>
<h2><strong>Project Structure Aligned to the Goals</strong></h2>
<p>Creating a dedicated AI team to build features would not produce the state where “each team has engineers skilled in AI Agent development.” So we adopted a dual‑assignment model. Centered on a Project Owner, Product Engineers embed AI into their respective products, Platform Engineers develop from a platform perspective, and Customer Engineers build an internal bot that answers KARTE questions. The project collaborates closely, with Platform Engineers owning AI service operations.</p>
<p><img src="https://ik.imagekit.io/plaid/0a9e8737-2bbe-4d32-8e0a-58a663f94609/team2.png" alt="team2.png"></p>
<p>Platform Engineers mainly:</p>
<ul>
<li>Keep application implementations simple by shaping the environment.</li>
<li>Aggregate learnings and review effectively.</li>
<li>Fix framework bugs or suboptimal implementations upstream.</li>
<li>Proactively design workarounds for likely pitfalls.</li>
<li>Regularly bump framework versions.</li>
<li>Explore and stay current on libraries/frameworks.</li>
<li>Evaluate what new versions enable.</li>
<li>Prepare systems for operations: observability, tests, evals.</li>
</ul>
<p>While PLAID sometimes prioritizes speed by skipping early reviews and batch‑reviewing around beta releases, for AI features we required reviews for all changes, even small ones. Since training leaders in AI development is a primary goal, code review is a highly effective lever.</p>
<p>Also, Platform Engineers need hands‑on experience to know where Product Engineers struggle. In parallel, we implemented multiple AI features—including chat‑UI agents—to gain practical insight.</p>
<h1><strong>KARTE Microservices</strong></h1>
<p>Before the AI system architecture, here’s KARTE’s microservices setup.</p>
<p>KARTE microservices are split into Web API, Internal API, and Frontend.</p>
<ul>
<li>
<p>Frontend</p>
<p>We build SPA JavaScript files using React.js or Vue.js and distribute them from Web API.</p>
</li>
<li>
<p>Web API</p>
<p>Serves HTML, CSS, JavaScript assets for Frontend and exposes APIs called by the SPA.</p>
</li>
<li>
<p>Internal API</p>
<p>APIs called from other services’ Web or Internal APIs. They assume authentication/authorization has already been handled by the calling Web API and do not implement auth themselves.</p>
</li>
</ul>
<p><img src="https://ik.imagekit.io/plaid/bc1f1682-5905-413e-a2d3-6312bd0e39ca/microservice2.png" alt="microservice2.png"></p>
<p>Each service’s owning team develops, operates, and maintains it, keeping independence under these principles:</p>
<ul>
<li>Independent deploys: build and deploy per service.</li>
<li>Independent DBs: dedicated DB per service.</li>
<li>API‑based communication: use Internal APIs between services.</li>
</ul>
<p>Tech choices are largely up to each team. APIs are often TypeScript with MongoDB. Web API, Internal API, and Frontend live in a monorepo (e.g., pnpm workspaces), allowing free codebase dependencies—such as sharing Web API types with Frontend.</p>
<h1><strong>Elements of AI Features and SDKs</strong></h1>
<p>AI features range from simple to advanced. We mostly build AI Agents, so this article focuses on them.</p>
<p>AI Agents execute tasks using Tools and Memory and, as needed, perform multi‑step LLM calls.</p>
<p><a href="https://mastra.ai/ja/docs/agents/overview">https://mastra.ai/ja/docs/agents/overview ↗</a></p>
<p><img src="https://ik.imagekit.io/plaid/44466c30-1040-42ef-9285-dc7945ed1f80/agents-overview.webp" alt="agents-overview.webp"></p>
<p>Tools are common across many LLM SDKs, but Memory in TypeScript is supported by frameworks like LangChain.js, Mastra, and VoltAgent.</p>
<p>These frameworks also include RAG, Workflows, Evals, Observability, and Web APIs. From the start, we planned to use a framework. While frameworks trade off flexibility, when you don’t yet know how to implement AI Agents or what’s possible, not adopting one carries bigger downsides. We chose Mastra, and Memory in particular is far easier than rolling our own.</p>
<h1><strong>Mastra</strong></h1>
<p>Mastra is a framework layered atop Vercel’s AI SDK. The AI SDK provides basics like model routing and tools, while Mastra adds more advanced features such as Memory and Evals.</p>
<p><a href="https://mastra.ai/ja/docs/frameworks/ai-sdk">https://mastra.ai/ja/docs/frameworks/ai-sdk ↗</a></p>
<p><img src="https://ik.imagekit.io/plaid/e3606cb6-e475-4f33-8797-65a85cd5b812/mastra-ai-sdk.webp" alt="mastra-ai-sdk.webp"></p>
<p>There’s Mastra Cloud, a managed environment to deploy Mastra apps more easily, but KARTE embeds into existing apps, so we don’t use it. In this article, “Mastra server” means a KARTE‑side server with Mastra installed, not Mastra Cloud.</p>
<h1><strong>KARTE AI System Architecture</strong></h1>
<p>In our microservices architecture, we created a single KARTE AI microservice using Mastra and have other services call it, i.e., a centralized model. Alternatively, each microservice could install Mastra (decentralized). We saw these trade‑offs:</p>
<h2>Decentralized</h2>
<ul>
<li>Faster if each team has engineers skilled in AI Agent development.</li>
<li>Fewer inter‑service dependencies.
<ul>
<li>Increased system stability.</li>
<li>Easier to roll out version/config changes in stages.</li>
</ul>
</li>
</ul>
<h2>Centralized</h2>
<ul>
<li>Agents inside the AI system can easily interoperate (cross‑product multi‑agent).</li>
<li>Knowledge can be centralized.</li>
</ul>
<p>AI Agent development patterns are still evolving, and not all teams have AI Agent skills. Strategically, KARTE is strengthening multi‑product elements, so we need an architecture amenable to future multi‑agent designs. We judged centralized has bigger near‑term benefits, so we consolidated AI code into one microservice.</p>
<p>Two key architectural questions are where Tools execute and how Storage is designed; we explain those first, then two architectures we’ve actually run.</p>
<h2><strong>Tools</strong></h2>
<p>Tools enable agents to access non‑training data or execute actions (e.g., Claude Code editing or shell execution). With Mastra, execution location leads to three types:</p>
<ul>
<li>
<p>server tool</p>
<p>Runs on the Mastra server. You can debug with Mastra Playground. Define server tools inside Mastra and it executes them.</p>
</li>
<li>
<p>client tool</p>
<p>Runs on the client relative to the Mastra server. You implement the client‑side execution.</p>
<p>With <code>@mastra/client-js</code>, pass a function to clientTools.execute for auto‑execution. With <code>@ai-sdk/react</code> <code>useChat</code>, run your logic via onToolCall.</p>
</li>
<li>
<p>provider tool</p>
<p>Runs in the provider’s environment. For example, Vertex AI provides Google Search or Code Execution.</p>
</li>
</ul>
<p>Choosing server vs client for custom tools depends on the app. Our custom tools typically access KARTE DB data, create KARTE configuration values (e.g., Action config), or call a separate LLM from the main agent. Provider tools fit general tasks like Python numerics or Google search.</p>
<h2><strong>Storage</strong></h2>
<p>We mainly use Memory for chat history and Evals for performance evaluation. With centralized Mastra, Storage is also usually single. Currently, aside from PostgreSQL, indexes aren’t created by default, so without indexes, performance may degrade as agents grow. Another issue is separating data when classification differs (e.g., sensitive data). Memory can switch Storage instances per Memory instance (allowing separate clusters/DBs), but Evals is configured once per Mastra instance and likely cannot be switched. If Evals can’t separate while Memory can, separation has limited value because Evals may include Memory‑like data for evaluation. So we didn’t split. If we build agents that handle highly confidential data in the future, we may reconsider separation.</p>
<h2><strong>Initial Architecture</strong></h2>
<p>We initially implemented KARTE AI as an Internal API. The Frontend could not call it directly; instead, each service’s Web API called the Mastra server.</p>
<p><img src="https://ik.imagekit.io/plaid/b8a5019e-fa86-4627-865e-5024d5a901b2/karte-ai.png" alt="karte-ai.png"></p>
<p>For tool calls that read or update data, we must confirm the user’s access permissions. Authorization lives in Web APIs (requests from Frontend). Internal APIs assume auth is already done and carry that information; they do not implement auth themselves. Since tool call parameters are largely chosen by the LLM, an implementation might attempt to access data the user shouldn’t. Therefore, we planned to run such tools as client tools in the Frontend.</p>
<p>This architecture had several issues:</p>
<ul>
<li>Dependency on the client library: using ‎<code>@mastra/client-js</code> server‑side isn’t well assumed, and upgrades sometimes broke streams or tool execution. It also depends on ‎<code>@mastra/server</code>, so bumping ‎<code>@mastra/server</code> past certain versions can break older <code>‎@mastra/client-js</code>. With Mastra still at major 0, compatibility windows felt short. Practically, tracking Mastra latest sometimes required bumping ‎<code>@mastra/client-js</code> in client services and deploying together.</li>
<li>Frontend coupling: the Frontend ultimately depends on <code>‎@ai-sdk/react</code> ‎<code>useChat</code>, so teams juggle three components: ‎<code>@mastra/server</code>, <code>‎@mastra/client-js</code>, and ‎<code>@ai-sdk/react.</code></li>
<li>Redundant Web APIs: many Web APIs wrapping Mastra server calls looked similar across services.</li>
</ul>
<p>To address this, we adopted the following approach.</p>
<h2><strong>Frontend Direct Requests to the Mastra Server</strong></h2>
<p><img src="https://ik.imagekit.io/plaid/9f135a66-5b99-47d0-8fe5-d367012531a7/front-mastra.png" alt="front-mastra.png"></p>
<p>In this approach, the Frontend calls the Mastra server directly and drops dependence on ‎<code>@mastra/client-js</code>, reducing minor bugs and debugging costs. After major changes in the Vercel AI SDK, this architecture let us focus on migrating Frontend ‎<code>useChat</code>. It also eliminates the need to build redundant Web APIs.</p>
<p>Previously, Frontend could only call its own service’s Web API. We removed that rule here. While it may introduce some confusion, the benefits outweighed the downsides. That rule exists to avoid other services depending on a Web API built for one service’s Frontend, which harms independence. KARTE AI is designed to be called by other services, so independence concerns don’t apply.</p>
<h1><strong>Advantages of Mastra and Usage Examples</strong></h1>
<p>We won’t do a detailed comparison, but initial reasons were: TypeScript‑native framework, released earlier than VoltAgent, and stronger docs and momentum than LangChain.js. In practice, updates are fast with frequent new features, and questions on Discord and PRs get quick reactions—great speed and flexibility, crucial in fast‑moving AI. The codebase is clear and easy to develop against; I’ve had <strong>24 PRs</strong> merged. If rapid updates worry you, <strong>Mastra v1 beta</strong> was just announced, so stability should improve.</p>
<p>Earlier this year in May, Mastra’s CTO visited Japan and our office; we discussed PLAID’s AI, Mastra’s roadmap, and shared our requests.</p>
<p><img src="https://ik.imagekit.io/plaid/495a9b00-b9e9-435b-abd7-4bb394518da2/mastra-plaid.png" alt="mastra-plaid.png"></p>
<p>Mastra is a strong choice for most TypeScript AI Agent development. I’ll focus on two especially valuable features: Memory and Stream.</p>
<h2><strong>Memory</strong></h2>
<p>Building Mastra‑like Memory from scratch would have been unrealistic. Memory is essentially chat history, but with options essential to AI Agents. All AI Agents available in the KARTE admin UI include Memory.</p>
<h3>Resources and Threads</h3>
<p>A thread contains multiple messages; passing past thread messages to the LLM as context reduces prompt writing and prevents repeated mistakes. A resource groups multiple threads. In KARTE, we restrict chat messages viewable per admin user. Even within the same tenant, users cannot access others’ instructions to KARTE AI. We include the authenticated user’s ID as a prefix in resource IDs to prevent viewing others’ histories.</p>
<h3>Processor</h3>
<p>Memory processors modify the message list before adding it to the agent’s context window and sending to the LLM. This helps manage context size, filter content, and optimize performance. KARTE agents use a</p>
<h3>TokenLimiter</h3>
<p>Processor that limits how far back to include past messages so total tokens stay within the LLM’s limit.</p>
<h3>Semantic Recall</h3>
<p>This retrieves semantically similar past history to include as context for a user’s question or instruction. It supports cross‑thread recall, searching across accessible threads. Technically it uses RAG. We tried it once, but a MongoDB bug at the time (quickly fixed) kept us from using it. Having such features available and ready in Mastra is a big plus for future needs.</p>
<h3>Message Conversion</h3>
<p>Vercel AI SDK moved from v4 to v5 with significant message format changes. We needed v4‑saved chat messages to work under v5. Mastra handles this compatibility internally, making the migration smooth.</p>
<h2><strong>Stream</strong></h2>
<p><a href="https://mastra.ai/blog/mastra-streaming">The next evolution of Mastra streaming ↗</a></p>
<p>Mastra implements its own streaming (“Mastra streaming”). With complex setups like multi‑agent or workflows, Frontend needs good visualization. Previously, an agent’s Stream method returned streams defined by the AI SDK stream protocol, which couldn’t stream outputs from LLM calls inside workflows or inside tools. Mastra streaming can handle nested LLM outputs as streams. In KARTE’s admin UI, our multi‑agent setup calls agents from tools, and we stream tool outputs.</p>
<p>Mastra converts Mastra streaming into types compatible with Vercel AI SDK v5’s stream protocol. While the protocol lacks parts for streaming tool outputs, Mastra achieves compatibility using Custom Data.<a href="https://ai-sdk.dev/docs/ai-sdk-ui/streaming-data">Streaming Custom Data ↗</a><br>
Developers can define custom data types, which improves DX.</p>
<p>Mastra will likely support AG‑UI and is developing <code>@mastra/react</code>, making UIs that leverage Mastra’s features easier to build.</p>
<h1><strong>Conclusion</strong></h1>
<p>To continuously develop AI features in KARTE’s microservices environment, we designed and operated an AI foundation using Mastra in a <strong>centralized</strong> model first. Centering the foundation on Mastra brings major advantages: rapid, continuous feature additions and usability improvements without building everything ourselves.</p>
<p>The balance between centralized and decentralized will evolve. As AI development skills spread across the Product org and we learn to build multi‑agent networks quickly and securely across services, we’ll gradually <strong>decentralize</strong>. KARTE’s microservices should also evolve to ease AI development—for example, implementing auth in Internal APIs or offering internal MCP.</p>


Learn how PLAID designed a centralized AI foundation with Mastra in a microservices architecture—covering tools, memory, storage, streaming, and frontend integration.

Designing an AI Foundation with Mastra in a Microservices Architecture

KARTEのマイクロサービス環境でのAI基盤設計を解説。Mastraを核に「まず集中」を採用し、Tool/Storage設計、Memory/Streamingの実践と運用知見を紹介。

マイクロサービスアーキテクチャにおける Mastra を活用した AI 基盤設計

3ヶ月の開発インターンで取り組んだタスクや、そこから得た学びについて紹介します。

プレイドインターン体験記：管理画面から配信基盤までを横断した機能開発

<p>株式会社プレイドのCTOシバヤマです。</p>
<p>この度、エンジニアブログを開設することにしました。<br>
背景には、<code>社外の人にプレイドの中のエンジニアのユニークなパーソナリティを知ってもらいたい</code>、というのがあります。</p>
<p>弊社のエンジニアには多様なメンバーがいて、言語解析や動画解析をやっていたメンバー、制御・ロボティクスをやっていたメンバー、並列言語コンパイラをやっていたメンバー、大手ゲーム会社出身、検索エンジンの会社出身、長くDSP畑のメンバーなどなど、ここでは書ききれないほど経験値が多種多様です。</p>
<p>年齢も23歳~38歳（平均31歳？）というレンジで、研究畑の人もいれば、文系の人もいるし、大手からベンチャーを渡ってきた人も、新卒もいます。</p>
<p>社内でミーティングをしていると、他のメンバーの意見に気づかされることが多いので（若干の悔しさは覚えますが）、このユニークなメンバーの知識や経験を社外にも還元していけるといいなぁと思っています。</p>
<p>出来る限り、<code>他では得られないユニークな経験もしくは深い洞察・知識</code>が書いている場所になるといいなぁと思っています。<br>
が、若干ハードルを上げすぎないでくれぃとメンバーには言われそうなので、このくらいにしておきますw</p>
<p>他にも開発合宿の様子とか新メンバーの紹介とか、ライトなコンテンツも用意していくかもしれません。</p>
<p>それではよろしくお願いいたします。</p>


プレイドのエンジニアブログを開設することになりました。CTOのシバヤマから、エンジニアブログを始めるにあたってのメッセージです。

プレイドのエンジニアブログを始めました！

Engineer Blog

Recent Article

プレイドのエンジニアブログを始めました！

Popular Articles

Popular Tags

Archives

Writers