# 開発

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

## エージェントSDK とは

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

## モジュール構成

SDK は 11 のモジュールで構成されています。必要なモジュールだけを `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` |

このほか、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/basic/develop/quickstart/quickstart-sdk.md) の Lab 節を参照してください。

## クイックスタート

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

```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/basic/develop/quickstart/quickstart-sdk.md) で最小構成のエージェントを構築  |
| **既存エージェントの移行** | [アーキテクチャガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/architecture.md) でモジュール構成を理解してから段階的に導入 |

## ガイド

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

## リファレンス

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