# 開発

`agenticstar-platform` SDK は、AGENTIC STAR プラットフォーム上で動作するカスタム AI エージェントを Python で開発するためのインフラ SDK です。エージェントロジックは開発者が自由に設計し、SDK はデータベース・イベント配信・メモリ・ストレージ・RAG・セキュリティなどのプラットフォーム基盤を提供します。

## エージェントSDK とは

| 項目        | 値                             |
| --------- | ----------------------------- |
| **パッケージ** | `agenticstar-platform`        |
| **バージョン** | v3.3.0                        |
| **言語**    | Python 3.12+                  |
| **配布**    | PyPI                          |
| **設計思想**  | SDK はインフラのみ。エージェントロジックはユーザー自由 |

> **版番号について**
>
> v3.0.0 から、SDK の版番号は AGENTIC STAR 本体のバージョンに合わせています（以後 3.0.1, 3.0.2, …）。PyPI 上の前の系列は 0.5.x → 1.0.x で、番号が飛んでいるのは製品と系列を揃えたためです。番号の変更は互換性を一律に保証するものではありません。0.5.40 から上げるときは次を確認してください: (1) `ActionAudit` で人 / system の決定イベント（`gate.resolved` / `policy.changed` など）を記録するときは `actor_ref` が必須（1.0.0 以降。欠落は `ValueError`）、(2) `PostgreSQLManager.execute_query()` は `WITH … SELECT` / `VALUES` / `TABLE` の結果を行リストで返すよう修正済み（0.5.41。以前の返却形式に依存したコードは要確認）、(3) metering の台帳に 2 列が増える（下のリファレンス参照。書き込みを始める前に列の実在を確認）、(4) `ActionAudit` の `metadata` に入れた小数と絶対値 2^53 以上の整数は文字列として保存される（1.0.0 以降。言語をまたいで `row_hash` を一致させるため。台帳の `metadata` を数値として読んでいるコードは要確認）。1.0.x を使っている場合は、3.0.0 に含まれる workflow / audit の語彙の除去（`items_advanced` / `no_items` / `claim.stale`）と、3.0.1 での `KNOWN_EVENT_TYPES` からの `verification.completed` の除去も確認してください（`event_type` は自由な文字列のままで、影響するのは辞書を直接参照・列挙しているコードだけです）。workflow runner を使っている場合は、3.0.1 で実行結果の形式が version 2 になり（outcome の語彙と `counts` のキー名が変わった）、プラットフォームは新しい形式だけを受け付けます（[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md)）。

## モジュール構成

SDK は 13 のモジュールで構成されています。必要なモジュールだけを `extras` で選択インストールできます。

| モジュール        | 説明                                                                                                      | 主要クラス                                                                                   |
| ------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **events**   | 非同期イベント配信（SSE / Webhook / DB）                                                                           | `EventEmitter`, `StreamingEvent`                                                        |
| **db**       | PostgreSQL 接続 + Azure AD 認証                                                                             | `PostgreSQLManager`, `DataAccess`                                                       |
| **rag**      | Qdrant ベクトル検索 + Azure OpenAI Embedding                                                                  | `QdrantManager`, `EmbeddingGenerator`                                                   |
| **storage**  | マルチクラウドストレージ（Azure / S3 / GCS）                                                                          | `AzureBlobStorageClient`, `S3StorageClient`                                             |
| **auth**     | AGENTIC STAR 認証 API クライアント                                                                              | `AgenticStarAuthClient`                                                                 |
| **memory**   | セマンティックメモリ（Mem0 + Qdrant）                                                                               | `SemanticMemoryClient`                                                                  |
| **security** | コンテンツモデレーション + PII 検出                                                                                   | `AzureSecurityClient`, `ContentSafetyValidator`                                         |
| **common**   | 共通ユーティリティ（バリデーション・シークレットマスク）                                                                            | `SecretMasker`, `validate_identifier`                                                   |
| **metering** | LLM 利用量・コスト計測（台帳記録 + 日次集計, v0.5.15+）                                                                    | `UsageMeter`                                                                            |
| **runner**   | Marketplace 互換の実行ライフサイクル（identity 検証 → 入力取得 → 実行 → 結果保存/Webhook → terminal 正確に 1 回 → cleanup, v0.5.30+） | `run_marketplace_agent`                                                                 |
| **audit**    | 行為監査台帳（承認・ツール認可・ポリシー違反等の append-only 記録。本文は digest 化して渡す設計, v0.5.31+。alerts writer は v0.5.32+）          | `ActionAudit`, `GatewayActionAudit`, `GuardrailAlertWriter`, `GuardrailAlertAggregates` |
| **workflow** | プロジェクトのワークフローの工程で動くエージェントの runner（`mp-workflow/1`。マーケットプレイス版 3.2.0 以降, v1.0.1+）                         | `run`, `WorkflowContext`, `AuditApi`                                                    |
| **policy**   | tool 呼び出しの統制ポリシー（テナントとプロジェクトの 2 層を合成して allow / forbid を判定する純計算, v1.0.0+）                                | `tighten_merge`, `evaluate`                                                             |

このほか、credential 不要で DB / RAG / storage の統合 journey を 1 コマンド体験できる **Local Integration Lab**（`python -m agenticstar_platform.lab`, v0.5.35+）を同梱しています。 詳細は [クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/quickstart/quickstart-sdk.md) の Lab 節を参照してください。

## クイックスタート

```bash
pip install agenticstar-platform[all]==3.3.0
```

```python
from agenticstar_platform.events import EventEmitter, EventType
from agenticstar_platform.db import PostgreSQLManager, PostgreSQLConfig, DataAccess

# データベース接続
db_manager = PostgreSQLManager(PostgreSQLConfig.from_toml("config.toml"))
da = DataAccess(db_manager)
await da.initialize()

# イベント配信
emitter = EventEmitter(execution_id="exec-001")
await emitter.emit_event(EventType.PHASE_START, message="処理を開始します")
```

## 始め方

| 対象                     | 手順                                                                                                                                         |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **新規開発**               | [クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/quickstart/quickstart-sdk.md) で最小構成のエージェントを構築         |
| **ワークフローの工程で動くエージェント** | [ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md) で契約と `run(context)` の書き方を確認 |
| **既存エージェントの移行**        | [アーキテクチャガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/architecture.md) でモジュール構成を理解してから段階的に導入        |

## ガイド

- [アーキテクチャガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/architecture.md) — SDK のモジュール構成と設計思想
- [デプロイガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/deploy.md) — Docker ビルドとプラットフォームへの登録
- [イベント / ストリーミングガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/events-guide.md) — SSE イベント配信の実装
- [メモリガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/memory-guide.md) — セマンティックメモリ（Mem0）の活用
- [ストレージガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/storage-guide.md) — マルチクラウドオブジェクトストレージ
- [セキュリティガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/security-guide.md) — コンテンツモデレーションと PII 検出
- [ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md) — プロジェクトのワークフローの工程で動くエージェント

## リファレンス

- [SDK API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/reference/sdk-ref.md) — 全モジュール・クラス・メソッドの完全仕様
