add-announcement

お知らせカードの追加

このスキルでは、Agenta サイドバーのバナーシステムにお知らせカードを追加できます。お知らせカードはサイドバーの下部に表示され、ユーザーが閉じることができます。

システムの概要

サイドバーのバナーシステムは web/oss/src/components/SidebarBanners/ にあり、次の機能を使用します。

• 優先度ベースのキュー：一度に表示されるバナーは 1 つだけです
• 自動切り替え：バナーが閉じられると、次に優先度の高いバナーが表示されます
• 閉じた状態の永続化：閉じたバナーを記憶するために localStorage を使用します
• Jotai atoms：リアクティブな状態管理に使用します

お知らせの 2 つの種類

1. シンプルな変更履歴のお知らせ（最も一般的）

標準的な製品の更新、機能、変更については、changelog.json に追加するだけです。

ファイル：web/oss/src/components/SidebarBanners/data/changelog.json

形式：

{
    "id": "changelog-YYYY-MM-DD-feature-name",
    "title": "Feature Title (Short)",
    "description": "Brief description of the feature or change.",
    "link": "https://agenta.ai/docs/changelog/feature-name"
}

ID の規則：changelog- + 日付（YYYY-MM-DD）+ 機能のスラッグ

• 例：changelog-2026-01-09-chat-sessions
• 競合を防ぐため、一意である必要があります

タイトルのガイドライン：

• 40 文字以内にします
• 明確で、ユーザーが次に取る行動がわかる内容にします
• ユーザーにとってのメリットを中心にします
• 例：「Observability のチャットセッション」、「Playground の PDF サポート」

説明のガイドライン：

• 100 文字以内の 1 文にします
• 技術的な詳細ではなく、ユーザーにできることを説明します
• 例：「セッションごとのグループ化とコスト分析で、複数ターンの会話を追跡できます。」

リンクの規則：

• 常に https://agenta.ai/docs/changelog/[feature-slug] を指定します
• 対応する変更履歴のドキュメントページを作成する必要があります

2. カスタムバナー（上級）

カスタム UI、操作、ロジックを伴う複雑なバナー（トライアルの警告、アップグレードの案内など）には、次の作業が必要です。

1. types.ts にバナーの種類を追加します
2. state/atoms.ts に優先度を追加します
3. activeBannersAtom（OSS）または eeBannersAtom（EE）にバナーを作成します

カスタムバナーを使用する場合：

• 閉じられないバナー（例：トライアルの期限切れ）
• カスタム操作（onClick ハンドラー付きのボタン）
• 動的なコンテンツ（ユーザーの状態に応じて変化）
• 条件付き表示（特定の条件下でのみ表示）

手順：シンプルな変更履歴のお知らせを追加する

ステップ 1：現在の changelog.json を読み込む

# View current entries to understand the structure
cat web/oss/src/components/SidebarBanners/data/changelog.json

ステップ 2：エントリーを追加する

web/oss/src/components/SidebarBanners/data/changelog.json を編集し、新しいエントリーを配列に追加します。

[
    {
        "id": "changelog-2024-12-16-pdf-support",
        "title": "PDF Support in Playground",
        "description": "You can now upload and test PDFs directly in the playground.",
        "link": "https://agenta.ai/docs/changelog/pdf-support-in-playground"
    },
    {
        "id": "changelog-2026-01-09-your-feature",
        "title": "Your Feature Title",
        "description": "Brief description of what users can do.",
        "link": "https://agenta.ai/docs/changelog/your-feature-slug"
    }
]

ステップ 3：形式を確認する

• 有効な JSON であること（末尾に余分なカンマがなく、引用符が正しいこと）を確認します
• ID が一意であることを確認します
• リンク URL が作成するドキュメントページと一致することを確認します

ステップ 4：ローカルでテストする

バナーは次回のページ読み込み時にサイドバーに自動的に表示されます。表示するには、次の操作を行います。

1. localStorage をクリアします：localStorage.removeItem('agenta:dismissed-banners')
2. ページを更新します
3. バナーがサイドバーの下部に表示されます

バナーの優先度システム

バナーは優先度の順に表示されます（数値が小さいほど先に表示されます）。

Priority 0: star-repo (GitHub star prompt for new users)
Priority 1: changelog (product updates) ← Most changelog entries
Priority 2: upgrade (upgrade prompts)
Priority 3: trial (trial/billing warnings)

変更履歴のエントリーには、自動的に優先度 1 が割り当てられます。

よくあるパターンと例

例 1：機能のお知らせ

{
    "id": "changelog-2026-01-15-batch-evaluation",
    "title": "Batch Evaluation Available",
    "description": "Evaluate multiple test sets simultaneously with batch processing.",
    "link": "https://agenta.ai/docs/changelog/batch-evaluation"
}

例 2：統合のお知らせ

{
    "id": "changelog-2026-01-20-langchain-support",
    "title": "LangChain v0.3 Support",
    "description": "Full support for LangChain v0.3 with auto-instrumentation.",
    "link": "https://agenta.ai/docs/changelog/langchain-v03"
}

例 3：改善のお知らせ

{
    "id": "changelog-2026-01-25-faster-traces",
    "title": "10x Faster Trace Loading",
    "description": "Observability page now loads traces up to 10x faster.",
    "link": "https://agenta.ai/docs/changelog/faster-trace-loading"
}

関連ファイル

コアシステムのファイル

• web/oss/src/components/SidebarBanners/index.tsx - メインコンテナー
• web/oss/src/components/SidebarBanners/SidebarBanner.tsx - 表示コンポーネント
• web/oss/src/components/SidebarBanners/types.ts - 型定義
• web/oss/src/components/SidebarBanners/state/atoms.ts - 状態管理
• web/oss/src/components/SidebarBanners/data/changelog.json - 変更履歴データ

統合ポイント

• web/oss/src/components/Sidebar/Sidebar.tsx - バナーが描画される場所

EE によるオーバーライド（Enterprise Edition）

• web/ee/src/components/SidebarBanners/index.tsx - EE ラッパー
• web/ee/src/components/SidebarBanners/state/atoms.ts - EE バナー（トライアル、アップグレード）

ベストプラクティス

1. タイミング：機能のデプロイとドキュメントの作成が完了したら、お知らせを追加します
2. ユーザー視点：「今回から〜できるようになりました」のように、技術的な視点ではなくユーザーの視点で記述します
3. 簡潔さ：バナーは流し読みされるため、タイトルと説明は短くします
4. リンク：ブログ記事だけでなく、包括的なドキュメントに必ずリンクします
5. テスト：localStorageをクリアし、バナーが正しく表示されることを確認します
6. 一意性：過去または今後のお知らせとの競合を防ぐため、日付ベースのIDを使用します

トラブルシューティング

バナーが表示されませんか？

• JSONの構文を確認します（JSONバリデーターを使用してください）
• localStorageをクリアします：localStorage.removeItem('agenta:dismissed-banners')
• 正しい環境（OSSとEEのどちらか）を確認します
• ブラウザーのコンソールでエラーを確認します

バナーが何度も表示されますか？

• IDが一意であること（非表示リストにすでに存在しないこと）を確認します
• changelog.jsonに重複したエントリーがないか確認します

バナーのスタイルが正しくありませんか？

• SidebarBannerコンポーネントがすべてのスタイルを自動で処理します
• 説明にカスタムHTMLやスタイルを追加しないでください。プレーンテキストとして表示されます

お知らせを追加した後の次の手順

changelog.jsonにお知らせを追加した後、次の作業を行います。

1. 変更履歴のドキュメントページを作成します：docs/docs/changelog/[feature-slug].mdx
2. スクリーンショットまたはデモ動画を追加します
3. 変更履歴ページから関連する機能ドキュメントにリンクします
4. OSS環境とEE環境の両方でバナーをテストします
5. 説明的なコミットメッセージを付けて変更をコミットします

ワークフローの例

# 1. Edit changelog.json
code web/oss/src/components/SidebarBanners/data/changelog.json

# 2. Create documentation page
code docs/docs/changelog/your-feature.mdx

# 3. Test locally (if running dev server)
# Clear localStorage in browser console:
# localStorage.removeItem('agenta:dismissed-banners')

# 4. Commit
git add web/oss/src/components/SidebarBanners/data/changelog.json
git add docs/docs/changelog/your-feature.mdx
git commit -m "docs: add changelog announcement for [feature name]"

---

注：このスキルでは、シンプルな変更履歴のお知らせを扱います。複雑なロジックを含むカスタムバナーについては、SidebarBannersのREADMEを参照するか、カスタムバナーコンポーネントの作成方法について問い合わせてください。