# アーキテクチャガイド

agenticstar-platform SDK のモジュール構成と設計思想を解説します。

## 設計思想

agenticstar-platform SDK はプラットフォームインフラ（DB・イベント・メモリ・ストレージ・RAG・セキュリティ）のみを提供します。エージェントのロジック（プロンプト設計・ツール選択・実行フロー）は開発者が完全に自由に設計できます。

## SDK レイヤー構成

![SDK Architecture](https://developers.fd.agenticstar.tm.softbank.jp/img/sdk/sdk-architecture.png)

SDK は 3 層のアーキテクチャで構成されます。

| レイヤー               | 役割                        | 担当                         |
| ------------------ | ------------------------- | -------------------------- |
| **Your AI Agent**  | エージェントロジック（プロンプト・ツール・フロー） | 開発者が自由に設計                  |
| **SDK**            | プラットフォームインフラへのアクセス        | `agenticstar-platform` が提供 |
| **Infrastructure** | データベース・ベクトルDB・ストレージ等      | プラットフォームが管理                |

## モジュール一覧

各モジュールは独立してインストール・使用できます。モジュール間に暗黙の依存はありません。

| Module     | pip extras   | External Deps                                         | Description                                                      |
| ---------- | ------------ | ----------------------------------------------------- | ---------------------------------------------------------------- |
| `events`   | `(core)`     | None                                                  | SSE / Webhook / DB event delivery                                |
| `db`       | `[db]`       | asyncpg, azure-identity                               | PostgreSQL + Azure AD auth                                       |
| `rag`      | `[rag]`      | qdrant-client, openai                                 | Vector search + Embedding                                        |
| `storage`  | `[storage]`  | azure-storage-blob, boto3, google-cloud-storage       | Multi-cloud object storage                                       |
| `auth`     | `(core)`     | httpx                                                 | AGENTIC STAR Auth API client                                     |
| `memory`   | `[memory]`   | mem0ai                                                | Semantic memory (Mem0 + Qdrant)                                  |
| `security` | `[security]` | httpx, google-cloud-dlp                               | Content moderation + PII detection                               |
| `common`   | `(core)`     | None                                                  | Validation + secret masking                                      |
| `metering` | `(core)`     | litellm (optional)                                    | LLM usage & cost metering (ledger + daily rollup, v0.5.15+)      |
| `lab`      | `[lab]`      | asyncpg, azure-identity, qdrant-client, openai, boto3 | Credential-free local integration lab (Docker Compose, v0.5.35+) |

## データフロー

![SDK Data Flow](https://developers.fd.agenticstar.tm.softbank.jp/img/sdk/sdk-dataflow.png)

1. **User Request** — ユーザーからのリクエストがエージェントに到達
2. **Your AI Agent** — SDK の `EventEmitter` で進捗をストリーミング配信しながら処理
3. **SDK** — DB・RAG・Storage・Memory 等のモジュールを呼び出し
4. **Infrastructure** — PostgreSQL・Qdrant・クラウドストレージ等にアクセス
5. **Response** — `EventType.COMPLETION_SUCCESS` で最終レスポンスを SSE 配信

## 設定管理

SDK の全モジュールは `config.toml` から設定を読み取ります。`from_toml()` メソッドで統一的にロードできます。

```toml
[database]
host = "your-db.postgres.database.azure.com"
port = 5432
database = "agenticstar"
username = "agent_user"
pool_min_size = 2
pool_max_size = 10
# Azure AD 認証を使う場合は true（パスワード認証の場合は password を設定）
use_azure_ad = true

[database.azure_ad]
tenant_id = "your-tenant-id"
client_id = "your-client-id"
client_secret = "your-client-secret"

[rag.qdrant]
url = "http://qdrant.internal:6333"
collection_name = "knowledge_base"
vector_size = 1536

[rag.embedding]
base_url = "https://your-endpoint.openai.azure.com/"
api_key = "your-api-key"
model = "text-embedding-3-large"

[storage.azure]
bucket_name = "agent-files"
connection_string = "DefaultEndpointsProtocol=https;..."

[memory.llm]
model = "azure_openai/gpt-4.1"
api_key = "your-api-key"
base_url = "https://your-endpoint.openai.azure.com/"

[security]
provider = "azure"
content_safety_endpoint = "https://your-cs.cognitiveservices.azure.com/"
content_safety_api_key = "your-key"
```

```python
from agenticstar_platform.db import PostgreSQLConfig
from agenticstar_platform.rag import QdrantConfig, EmbeddingConfig

db_config = PostgreSQLConfig.from_toml("config.toml")
qdrant_config = QdrantConfig.from_toml("config.toml")
embed_config = EmbeddingConfig.from_toml("config.toml")
```

## プロジェクト構成の例

```text
my-agent/
├── config.toml              # SDK 設定
├── main.py                  # エージェントのエントリーポイント
├── agent.py                 # エージェントロジック
├── tools/                   # カスタムツール
│   ├── search.py
│   └── file_ops.py
├── Dockerfile
└── requirements.txt
```

## 次のステップ

デプロイガイド

Docker ビルドとプラットフォームへの登録手順

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/deploy.md)

イベント / ストリーミングガイド

SSE イベント配信の実装詳細

[ガイドを見る](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/basic/develop/guide/events-guide.md)
