# SDK API リファレンス

agenticstar-platform SDK（v3.3.0）の全モジュール・クラス・メソッドの完全仕様です。

## インストール

pip を使用して SDK をインストールしてください。

```bash
pip install agenticstar-platform==3.3.0
```

extras を指定しない基本インストールの依存は `httpx` / `pydantic` / `pyyaml` です（`pyyaml>=6.0` は v1.0.1+ で追加）。ベースイメージや他のパッケージで PyYAML の版を固定している場合は、6.0 以上であることを確認してください。

特定モジュールのみインストールする場合は、extras を指定してください。

| Extra          | 説明                                                   |
| -------------- | ---------------------------------------------------- |
| `[[db]]`       | PostgreSQL database support                          |
| `[[rag]]`      | RAG (embedding + vector search) support              |
| `[[storage]]`  | Cloud storage (Azure, S3, GCS) support               |
| `[[security]]` | Security (content moderation, PII detection) support |
| `[[auth]]`     | AGENTIC STAR Auth service integration                |
| `[[memory]]`   | Semantic Memory (Mem0 + Qdrant) support              |
| `[[all]]`      | 全モジュール                                               |

```bash
# RAG モジュール
pip install agenticstar-platform[rag]==3.3.0

# DB + RAG + Storage
pip install agenticstar-platform[db,rag,storage]==3.3.0

# Storage（provider 別、v0.5.28+）
pip install agenticstar-platform[storage-aws]==3.3.0

# 全モジュール
pip install agenticstar-platform[all]==3.3.0
```

---

## モジュール一覧

SDK は以下の 13 のモジュールで構成されています。

| モジュール    | 説明                                                                                                      | 主要クラス                                                                           |
| -------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| events   | 非同期イベント配信システム（SSE / Webhook / DB）                                                                       | EventEmitter, StreamingEvent                                                    |
| db       | PostgreSQL 接続 + Azure AD 認証。サイクル型の実行の完遂報告（v3.0.14+）                                                     | PostgreSQLManager, DataAccess, report\_completion                               |
| rag      | RAG（embedding + vector search via Qdrant）                                                               | EmbeddingGenerator, QdrantManager                                               |
| storage  | クラウドストレージ（Azure, S3, GCS。provider 別 extra: `storage-azure` / `storage-aws` / `storage-gcp`）             | AzureBlobStorageClient, S3StorageClient                                         |
| auth     | AGENTIC STAR 認証 API クライアント                                                                              | AgenticStarAuthClient                                                           |
| memory   | セマンティックメモリ（Mem0 + Qdrant）                                                                               | SemanticMemoryClient                                                            |
| security | コンテンツモデレーション + PII 検出                                                                                   | AzureSecurityClient, ContentSafetyValidator                                     |
| common   | 共通ユーティリティ（シークレットマスク）                                                                                    | SecretMasker                                                                    |
| 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, EffectivePolicy                                       |

---

## events イベントモジュール

非同期イベント配信システム。EventEmitter でイベントを発行し、SSE / Webhook / DB に配信します。

### 列挙型

#### EventType

フロントエンド UI に表示されるイベントタイプ。各メンバーをどう実装すれば表示されるかは[イベント / ストリーミングガイドの実装ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/events-guide.md#%E8%A1%A8%E7%A4%BA%E6%96%B9%E6%B3%95%E3%81%94%E3%81%A8%E3%81%AE%E5%AE%9F%E8%A3%85%E3%82%AC%E3%82%A4%E3%83%89)を参照してください。

PHASE\_START = "phase\_start"

PROGRESS\_UPDATE = "progress\_update"

THOUGHT\_MESSAGE = "thought\_message"

COMPLETION\_SUCCESS = "completion\_success"

COMPLETION\_FAILURE = "completion\_failure"

USER\_INTERACTION\_REQUIRED = "user\_interaction\_required"

UNEXPECTED\_ERROR = "unexpected\_error"

HITL\_REQUIRED\_BROWSER\_VNC = "hitl\_required\_browser\_vnc"

HITL\_REQUIRED\_BROWSER\_CLI = "hitl\_required\_browser\_cli"

HITL\_COMPLETED = "hitl\_completed"

FILE\_CREATED = "file\_created"

PERMISSION\_REQUEST = "permission\_request"

PERMISSION\_RESPONSE = "permission\_response"

TOOL\_START = "tool\_start"

TOOL\_RESULT = "tool\_result"

PROGRESS\_MESSAGE = "progress\_message"

#### SubEventType

イベントを細分化するサブイベントタイプ。`sub_event_type` だけでは表示は変わりません。表示の出し分けは [`metadata.actionType`](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/events-guide.md#subeventtype-actiontype) で指定してください。

SEARCH\_WEB = "search\_web"

COMMAND\_EXECUTION = "command\_execution"

FILE\_OPERATION = "file\_operation"

LOCAL\_ASSISTANT = "local\_assistant"

MCP\_TOOL = "mcp\_tool"

FILE\_EDITED = "file\_edited"

FILE\_READ = "file\_read"

FILE\_SEARCHED = "file\_searched"

BASH\_EXECUTED = "bash\_executed"

WEB\_FETCHED = "web\_fetched"

TASK\_LAUNCHED = "task\_launched"

TODO\_UPDATED = "todo\_updated"

VIDEO\_GENERATED = "video\_generated"

IMAGE\_GENERATED = "image\_generated"

SLIDE\_CREATED = "slide\_created"

MACOS\_AUTOMATION = "macos\_automation"

### データクラス

#### StreamingEvent

リアルタイム SSE 配信用のイベントデータ。

```python
@dataclass
class StreamingEvent:
  event_type: EventType
  execution_id: str
  message: str
  timestamp: float
  metadata: Optional[Dict[str, Any]]= None
  sub_event_type: Optional[SubEventType]= None

  def to_dict() -> Dict[str, Any]: ...
```

#### SequencedEvent

順序保証付きイベント。

```python
@dataclass
class SequencedEvent:
  sequence: int           # 0以上
  event_type: EventType
  execution_id: str
  message: str
  timestamp: float
  metadata: Optional[Dict[str, Any]]= None
  sub_event_type: Optional[SubEventType]= None

  def __post_init__(): ...  # sequence >= 0 を検証
  def to_streaming_event() -> StreamingEvent: ...
  def to_dict() -> Dict[str, Any]: ...
```

#### ExecutionMessage

マーケットプレイス UI 統合用のデータベース格納メッセージ。

```python
@dataclass
class ExecutionMessage:
  user_id: str
  conversation_id: str
  message_id: str
  chunk_type: str
  content_data: Dict[str, Any]

  def to_dict() -> Dict[str, Any]: ...
  @classmethod
  def from_streaming_event(
      event: StreamingEvent,
      user_id: str,
      conversation_id: str,
      message_id: str,
      chunk_type: Optional[str]= None
  ) -> ExecutionMessage: ...
```

### クラス

#### EventEmitter

非同期イベントキュー。イベント発行・消費を非ブロッキングで実行。

```python
class EventEmitter:
  def __init__(
      execution_id: str,
      handler: Optional[EventHandler]= None
  ): ...

  @property
  def is_completed() -> bool: ...

  @property
  def sequence_number() -> int: ...

  async def emit_event(
      event_type: EventType,
      message: str,
      metadata: Optional[Dict[str, Any]]= None,
      sub_event_type: Optional[SubEventType]= None
  ) -> None: ...

  async def emit(
      event_type: EventType,
      message: str,
      metadata: Optional[Dict[str, Any]]= None,
      sub_event_type: Optional[SubEventType]= None
  ) -> None: ...

  async def consume_events(
      timeout: float = 0.1
  ) -> AsyncGenerator[str,None]: ...

  async def drain(
      timeout: float = 0.1
  ) -> None: ...

  def mark_completed() -> None: ...

  async def cleanup() -> None: ...
```

Returns

emit\_event() → Noneイベントをキューに追加。ハンドラーが設定されている場合は非同期で呼び出される

emit() → Noneemit\_event() のエイリアス（短縮形）

consume\_events() → AsyncGenerator\[str, None]SSE フォーマットの文字列を非同期に yield。完了時に自動停止

drain() → None登録ハンドラーを駆動してキューを消費（SSE を yield しない用途向け）。内部で consume\_events() を回し、完了イベント後に自動終了

```python
from agenticstar_platform import EventEmitter, EventType

emitter = EventEmitter(execution_id="exec-abc-123")

# イベント発行
await emitter.emit_event(
    event_type=EventType.PHASE_START,
    message="ドキュメント分析を開始します",
    metadata={"phase": "analysis", "total_pages": 42}
)

# イベント消費（SSE ストリーミング）
async for chunk in emitter.consume_events():
    print(chunk)
```

#### DatabaseEventHandler

PostgreSQL の execution\_messages テーブルにイベントを永続化。

```python
class DatabaseEventHandler:
  def __init__(
      data_access: Any,
      user_id: str,
      conversation_id: str,
      message_id: str,
      table_name: str = "execution_messages",
      chunk_type_map: Optional[Dict[EventType, str]]= None
  ): ...

  async def __call__(event: StreamingEvent) -> Optional[str]: ...
```

#### WebhookEventHandler

HTTP webhook エンドポイントにイベントを送信。

```python
class WebhookEventHandler:
  def __init__(
      webhook_url: str,
      conversation_id: str,
      message_id: str,
      headers: Optional[Dict[str, str]]= None,
      timeout_seconds: int = 30,
      message_type: str = "append_message",
      token_provider: Optional[Callable[[], Optional[str]]]= None,
      chunk_type_map: Optional[Dict[EventType, str]]= None,
      request_source: Optional[str]= None,
      message_type_map: Optional[Dict[EventType, str]]= None,
      failure_finish_reason: str = "error"
  ): ...

  async def __call__(event: StreamingEvent) -> Optional[str]: ...
```

v3.2.3+ — `failure_finish_reason` は `COMPLETION_FAILURE` の `finish_reason` です（既定 `"error"`）。AgenticStar のチャットは `"stop"` のときだけメッセージを終わらせるので、プラットフォームの Webhook へ送るときは `"stop"` を渡します（`create_marketplace_handler` はそうして作ります）。

#### CompositeEventHandler

複数の EventHandler を並列実行。

```python
class CompositeEventHandler:
  def __init__(
      handlers: List[Callable],
      return_first_chunk: bool = True
  ): ...

  async def __call__(event: StreamingEvent) -> Optional[str]: ...
```

### ファクトリ関数

```python
def create_sse_handler() -> EventHandler
```

SSE (Server-Sent Events) 形式のハンドラーを作成。

```python
def create_json_handler() -> EventHandler
```

JSON 形式のハンドラーを作成。

```python
def create_marketplace_handler(
  data_access: Any,
  webhook_url: str,
  user_id: str,
  conversation_id: str,
  message_id: str,
  token_provider: Optional[Callable[[], Optional[str]]]= None,
  request_source: Optional[str]= None
) -> CompositeEventHandler
```

マーケットプレイス UI 用の複合ハンドラー（DB + Webhook）を作成。

v3.2.3+ — `COMPLETION_FAILURE` も `finish_reason: "stop"` で送ります（失敗でもチャットのターンが閉じる。`WebhookEventHandler` 単体の既定 `"error"` とは違う）。`token_provider` を渡さなければ、送るたびに環境変数 `ASTER_NOTIFY_TOKEN`（executor が実行ごとに注入する完了の知らせ用のトークン）を読み、`Authorization: Bearer` に付けます（無い・空なら付けない）。

### プロトコル

#### EventHandler

イベント処理の汎用インターフェース。

```python
class EventHandler(Protocol):
  async def __call__(
      self, event: StreamingEvent
  ) -> Optional[str]: ...
```

Related

[データベースモジュール](#-データベースモジュール) —

<!-- -->

DatabaseEventHandler の data\_access に DataAccess を渡して永続化\
[ストレージモジュール](#-ストレージモジュール) —

<!-- -->

イベントログのクラウドストレージへのアーカイブ

---

## db データベースモジュール

PostgreSQL 接続プール + Azure AD 認証。

### 設定

#### AzureADConfig

Azure Active Directory 認証設定。

```python
@dataclass
class AzureADConfig:
  tenant_id: str
  client_id: str
  client_secret: str  # 非表示
  username: str = ""

  @classmethod
  def from_dict(data: Dict[str, Any]) -> AzureADConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "azure_ad") -> AzureADConfig: ...
```

#### PostgreSQLConfig

PostgreSQL 接続設定（Azure AD サポート）。

```python
class PostgreSQLConfig:
  provider: str = "postgresql"
  host: str = "localhost"
  port: int = 5432
  database: str = "agenticstar_db"
  use_azure_ad: bool = False
  username: Optional[str]= None
  password: Optional[str]= None  # 非表示
  pool_min_size: int = 5
  pool_max_size: int = 20
  command_timeout: int = 60
  pool_timeout: Optional[int]= 30
  max_overflow: Optional[int]= 10
  azure_ad: Optional[AzureADConfig]= None
  api_url: Optional[str]= None
  ssl_mode: str = "require"

  @classmethod
  def from_dict(data: Dict[str, Any]) -> PostgreSQLConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "database") -> PostgreSQLConfig: ...

  @classmethod
  def from_env(prefix: str = "DB_") -> PostgreSQLConfig: ...
```

**TOML 設定例:**

```toml
[database]
provider = "postgresql"
host = "db.example.com"
port = 5432
database = "agenticstar_db"
use_azure_ad = true
pool_min_size = 5
pool_max_size = 20
command_timeout = 60

[azure_ad]
tenant_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
client_id = "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
client_secret = "your-secret-here"
username = "dbuser@example.onmicrosoft.com"
```

### 接続管理

#### PostgreSQLManager

非同期 PostgreSQL 接続プール（Azure AD トークン管理対応）。

```python
class PostgreSQLManager:
  def __init__(config: PostgreSQLConfig): ...

  @property
  def config() -> PostgreSQLConfig: ...

  @property
  def pool() -> Optional[asyncpg.Pool]: ...

  async def __aenter__() -> PostgreSQLManager: ...
  async def __aexit__(...) -> None: ...

  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def close() -> None: ...

  async def execute_query(
      query: str,
      params: tuple = ()
  ) -> Dict[str, Any]: ...

  async def fetch_one(
      query: str,
      params: tuple = ()
  ) -> Optional[Dict[str, Any]]: ...

  async def fetch_all(
      query: str,
      params: tuple = ()
  ) -> List[Dict[str, Any]]: ...

  async def execute(
      query: str,
      params: tuple = ()
  ) -> str: ...
```

Returns

execute\_query() → Dict\[str, Any]{"success": bool, "data": list（SELECT / RETURNING 時の行リスト）または {"result": str}（その他 DML 時の PostgreSQL ステータス）}

fetch\_one() → Optional\[Dict\[str, Any]]1行の結果辞書、または該当なしで None

fetch\_all() → List\[Dict\[str, Any]]結果行のリスト（0件の場合は空リスト）

execute() → strPostgreSQL のステータス文字列（例: "INSERT 0 1"）

✓

Context manager 対応: `async with PostgreSQLManager(config) as mgr:`

```python
from agenticstar_platform.db import PostgreSQLConfig, PostgreSQLManager

config = PostgreSQLConfig.from_toml("config.toml")

async with PostgreSQLManager(config) as mgr:
    await mgr.initialize()

    # SELECT クエリ
    result = await mgr.fetch_all(
        "SELECT * FROM conversations WHERE user_id = $1",
        ("user-123",)
    )

    # INSERT
    await mgr.execute(
        "INSERT INTO events (event_type, data) VALUES ($1, $2)",
        ("phase_start", '{}')
    )
```

### データアクセス層

#### DataAccess

SQL インジェクション防止を備えた汎用テーブル操作ラッパー。

```python
class DataAccess:
  def __init__(
      db: PostgreSQLManager| ApiPostgreSQLManager
  ): ...

  async def __aenter__() -> DataAccess: ...
  async def __aexit__(...) -> None: ...

  async def initialize() -> None: ...
  async def close() -> None: ...

  def is_initialized() -> bool: ...
  async def ensure_initialized() -> None: ...

  async def execute_query(
      query: str,
      params: tuple = ()
  ) -> Dict[str, Any]: ...

  async def insert(
      table: str,
      data: Dict[str, Any],
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...

  async def upsert(
      table: str,
      data: Dict[str, Any],
      conflict_columns: List[str],
      update_columns: Optional[List[str]]= None,
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...

  async def select(
      table: str,
      columns: Optional[List[str]]= None,
      where: Optional[Dict[str, Any]]= None,
      order_by: Optional[str]= None,
      limit: Optional[int]= None
  ) -> Dict[str, Any]: ...

  async def select_one(
      table: str,
      columns: Optional[List[str]]= None,
      where: Optional[Dict[str, Any]]= None
  ) -> Optional[Dict[str, Any]]: ...

  async def update(
      table: str,
      data: Dict[str, Any],
      where: Dict[str, Any],
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...

  async def delete(
      table: str,
      where: Dict[str, Any],
      returning: Optional[List[str]]= None
  ) -> Dict[str, Any]: ...
```

Returns

insert() / upsert() → Dict\[str, Any]{"success": bool, "data": list または {"result": str}}。returning 指定時はカラム値の行リスト、未指定時は {"result": str}

select() → Dict\[str, Any]{"success": bool, "data": list}

update() / delete() → Dict\[str, Any]{"success": bool, "data": {"result": str}}。returning 指定時は行リスト

主要メソッドの使用例:

```python
# INSERT
result = await da.insert("users", {"name": "Alice"}, returning=["id"])

# UPSERT（競合時は更新）
result = await da.upsert("users", {"email": "a@example.com", "name": "Alice"}, conflict_columns=["email"])

# SELECT with WHERE + ORDER + LIMIT
result = await da.select("users", columns=["id", "name"], where={"active": True}, order_by="created_at DESC", limit=10)
```

#### ConfigAccess

エージェント・ツール・ガードレール・MCP などの設定情報へのアクセス層。

```python
class ConfigAccess:
  def __init__(db: DataAccess): ...

  async def get_agent_instructions(agent_type: str) -> Dict[str, Any]: ...
  async def get_all_agent_configs() -> Dict[str, Any]: ...
  async def get_agent_config(agent_type: str, requested_level: str = "default") -> Dict[str, Any]: ...
  async def get_tool_config(tool_name: str) -> Dict[str, Any]: ...
  async def get_all_tool_configs() -> Dict[str, Any]: ...
  async def get_banned_urls() -> Dict[str, Any]: ...
  async def get_guardrails_settings() -> Dict[str, Any]: ...
  async def get_system_settings() -> Dict[str, Any]: ...
  async def get_mcp_configurations(execution_mode: Optional[str]= None) -> Dict[str, Any]: ...
```

`get_mcp_configurations()` は有効な MCP サーバー設定を `{"success": True, "data": [...]}` で返します。`data` の各要素は `id` / `name` / `server_url` / `cache_tools_list` / `headers` / `only_pod` / `use_oauth` / `oauth_service` / `transport_type` を持ちます。`id`（MCP サーバー設定の ID）は v3.0.2+ で追加されました。`name` は管理画面で自由に付けられる表示名なので、接続を識別・照合するときは `id` を使ってください。

> **禁止 URL の制限粒度を拡張する**
>
> `get_banned_urls()` は管理画面で登録された「禁止 URL」一覧を取得します。基本機能（ExtAuth Service）はドメイン単位の制限ですが、本メソッドで取得したパターンをエージェントのツール内で `re.search` 等により URL 文字列に照合することで、**URL（パス）単位の制限**を拡張機能として実装できます。設定は管理画面で一元管理されるため、運用上の重複は発生しません。

> **PII のマスクが効く範囲**
>
> `get_guardrails_settings()` の `pii_masking_enabled` は、管理コンソールの PII マスキングのスイッチの値を返すだけです。マスクは、この値を読んでマスクする Agent にだけ効きます（マーケットプレイスの実行基盤はマスクしません）。

#### ExecutionAccess

実行メッセージの取得層。

```python
class ExecutionAccess:
  def __init__(db: DataAccess): ...

  async def get_messages(
      execution_id: str
  ) -> Optional[List[Dict[str, Any]]]: ...
```

#### TelemetryAccess

NIST 監査テレメトリの保存・取得層。

```python
class TelemetryAccess:
  def __init__(db: DataAccess): ...

  async def save_telemetry(
      telemetry_data: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  async def list_telemetry(
      conversation_id: Optional[str]= None,
      service: Optional[str]= None,
      limit: int = 100,
      offset: int = 0
  ) -> Dict[str, Any]: ...

  async def get_telemetry(
      telemetry_id: str
  ) -> Optional[Dict[str, Any]]: ...
```

#### PodRuntime

Pod ライフサイクル管理（開始通知・終了通知・任意の自己スケールダウン）。

```python
class PodRuntime:
  def __init__(
      db: DataAccess,
      execution_id: str,
      pod_name: str,
      scale_down_callback: Optional[Callable[[str], Awaitable[None]]] = None
  ): ...

  async def start() -> Dict[str, Any]: ...
  async def final(status: str = "completed") -> Dict[str, Any]: ...
```

`scale_down_callback` は Pod 終了時に呼び出される自己スケールダウンハンドラ（`async def (execution_id: str) -> None`）。未指定の場合、`final()` は状態更新のみを行い、自己スケールダウンは実行しない。Pod を自身で終了（この実行の SandboxClaim を削除するなど）させたい場合に注入する。

#### ApiPostgreSQLManager

HTTP API プロキシ経由の PostgreSQL アクセス（CLI モード用）。`PostgreSQLManager` と同一の非同期インターフェースを持つ。

v3.1.0+ — プロキシ（cli-api）が処理の前に返す `503`（入れ替え中の `cli-api is draining ...`、呼び出し元の Pod をまだ確かめられない `caller binding unavailable (retryable)`。JSON の `detail` が完全に一致するものだけ）は、`Retry-After` 以上（秒か HTTP の日付。上限 10 秒。無い・使えない値なら間隔を空けて）待って送り直す。接続できなかったときと合わせて 5 回まで（待ちは 1・2・4・8 秒で計約 15 秒、最大約 40 秒）。それ以外の `503` や `5xx`（途中の中継が返したものを含む）は処理の後かもしれないので送り直さず、従来どおり `API_ERROR` を返す。使っていない接続は 4 秒で捨てる（プロキシは 5 秒で閉じるため、閉じる瞬間に送った要求が失敗するのを避ける。接続数の上限は httpx の既定のまま）。`headers_provider` を渡すと要求ごとにヘッダを足せる（実行の ID など）。足すのは送れるものだけで、名前は HTTP の token、値は前後に空白の無い可視 ASCII（`str` か `int`）。`Authorization`・`Host`・`Content-Type` など client が持つヘッダは上書きできず、例外を上げる provider は何も足さない。

v3.0.15+ — クエリのパラメータに型（`date` / `datetime`）の添字を付けて送るので、TEXT 列に渡す `"2026-10-09"` のような文字列がプロキシ側で日付型に変わらなくなった。`date` / `datetime` の値は従来どおり日付型のまま届く。対応する cli-api（Marketplace 3.2.0 以降）より前の環境では従来どおり文字列の形から推定する。

```python
class ApiPostgreSQLManager:
  def __init__(
      config: PostgreSQLConfig,
      *,
      token_provider: Callable[[], Optional[str]],
      headers_provider: Optional[Callable[[], Optional[Mapping[str, str]]]]= None,  # v3.1.0+
  ): ...

  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def close() -> None: ...

  async def fetch_one(query: str, params: tuple = ()) -> Optional[Dict[str, Any]]: ...
  async def fetch_all(query: str, params: tuple = ()) -> List[Dict[str, Any]]: ...
  async def execute(query: str, params: tuple = ()) -> str: ...
  async def execute_query(query: str, params: tuple = ()) -> Dict[str, Any]: ...
```

### ファクトリ関数

```python
def create_postgresql_manager(
  config: PostgreSQLConfig
) -> Union[PostgreSQLManager, ApiPostgreSQLManager]
```

`config.api_url` の有無に応じて `PostgreSQLManager`（直接接続）または `ApiPostgreSQLManager`（API プロキシ）を自動選択して返す。

### サイクル型の実行の完遂報告

v3.0.14+ — サイクル型の実行（`execution_data.runtime_protocol` = `mp-chat/1`。プラットフォームが予定で起動する会話）で、エージェントが目的を果たしたかを報告します。報告が無い実行は、exit 0 で終わっても「実行終了（完遂は未計測）」（`outcome` なし・`runner_exited`）として記録され、成功にも失敗にも数えられません。プロセスの正常終了をプラットフォームが完遂と読み替えることはありません。書き方の例は [クイックスタート](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/quickstart/quickstart-sdk.md#report-completion) を参照してください。

```python
async def report_completion(
  pool: asyncpg.Pool,           # PostgreSQLManager.pool（DB 直結の接続プール）
  *,
  user_id: str,                 # USER_ID
  conversation_id: str,         # CONVERSATION_ID
  message_id: str,              # MESSAGE_ID
  execution_id: str,            # EXECUTION_ID
  outcome: str,
  reason: Optional[str]= None,
  had_mutating_success: Optional[bool]= None,
  summary: Optional[str]= None,
) -> bool
```

| 引数                     | 説明                                                                                                                                                                                              |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcome`              | `completed` / `incomplete` / `failed` / `timeout` / `stopped` / `denied` / `skipped` のいずれか。それ以外は `ValueError`                                                                                   |
| `reason`               | 理由コード（`outcome_reason_code`）。小文字の snake\_case で 32 文字まで（`^[a-z][a-z0-9_]{0,31}$`。`-` と空白は `_` に、大文字は小文字に直します）。省略時と、合わない値（文章・例外の文字列など）のときは `outcome` と同じ値になり、警告をログに出します。自由な文は `summary` に入れてください |
| `had_mutating_success` | 外部への書き込みの成功があったか（`True` / `False`。分からなければ `None`）。報告の行に残ります（現在のプラットフォームは実行の結果に `outcome` と理由コードだけを使います）                                                                                         |
| `summary`              | 人が読む補足（任意）                                                                                                                                                                                      |

- `from agenticstar_platform import report_completion`（`agenticstar_platform.db` からも import できます）。`[db]` extra（asyncpg）が必要です
- 戻り値は、報告を書いたら `True`、書かなかったら `False` です
- **報告は任意**です。報告しないエージェントは従来どおり未計測のままで、挙動は変わりません
- **報告は 1 回**です。同じ実行に報告が既にあれば書かずに警告をログに出し、`False` を返します（最初の報告が残ります）。同時に呼ばれても書かれるのは 1 行だけです
- **DB の失敗でエージェントの処理を失敗させません**。書き込みに失敗したら（接続を 30 秒待っても取れない場合を含む）警告をログに出して `False` を返し、その実行は未計測のままになります。例外を送出するのは `outcome` が語彙外のときだけです。なお、commit の応答だけを失った場合は、保存されていても `False` になることがあります
- プラットフォームが報告を採用するのは、**コンテナが exit 0 で終わったのを確かめたときだけ**です。それ以外で実行を閉じた場合（非 0 の終了・Pod の消失 = 効果不明の失敗、取消 = `stopped/cancelled`、agent の実行中に期限を過ぎた = `timeout/execution_timeout`）は、報告は使われません。`run_marketplace_agent` は agent の例外でもプロセスを exit 0 で終えるため、報告済みならその報告が採用されます
- 報告は `execution_messages` の 1 行です（`content_data.kind` = `sdk.runner.completion`。開始済みの印と同じ `CONVERSATION_ID` / `MESSAGE_ID` で対応付けます）。DDL はありません。サイクル型のエージェントには runtime API が渡らないため、DB 直結で書きます
- 通常の会話（チャット）の実行で呼んでも結果は変わりません（報告は読まれません）。管理画面のダッシュボードでは、開始済みの印と同じく実行の 1 チャンクとして数えられます

### エラー処理

データベース操作の例外処理。

```python
from agenticstar_platform.db import PostgreSQLConfig, PostgreSQLManager, DataAccess

config = PostgreSQLConfig.from_toml("config.toml")

try:
    db_manager = PostgreSQLManager(config)
    da = DataAccess(db_manager)
    await da.initialize()

    result = await da.select("users", where={"id": "user-123"})
    if result["success"] and result["data"]:
        print(f"User: {result['data'][0]['username']}")
except Exception as e:
    print(f"Database error: {e}")
finally:
    await da.close()
```

Related

[イベントモジュール](#-イベントモジュール) —

<!-- -->

DatabaseEventHandler でイベントを DB に永続化\
[RAG モジュール](#-rag-モジュール) —

<!-- -->

DB から取得したデータを Embedding 化して検索可能にする

---

## rag RAG モジュール

RAG (Retrieval-Augmented Generation): Embedding + Vector Search via Qdrant。

### 列挙型

#### VectorStoreProvider

RAG で使用するベクトルストアプロバイダー種別。

QDRANT = "qdrant"

### 例外

```text
VectorStoreError (Exception)
├── VectorStoreConfigError
│   └── QdrantConfigError
└── VectorStoreConnectionError

EmbeddingError (Exception)
├── RateLimitExceededError
└── EmbeddingDimensionError  # v3.1.1+
```

### データクラス

#### SearchResult

単一の検索結果。

```python
@dataclass
class SearchResult:
  point_id: str
  payload: Dict[str, Any]
  score: float
  similarity: float = 0.0
```

#### UpsertResult

Upsert 操作の結果。

```python
@dataclass
class UpsertResult:
  success: bool
  point_id: str = ""
  error: Optional[str]= None
  error_code: Optional[str]= None
```

#### SearchResponse

検索操作の結果。

```python
@dataclass
class SearchResponse:
  success: bool
  results: List[SearchResult]= field(default_factory=list)
  total_found: int = 0
  query: str = ""
  error: Optional[str]= None
  error_code: Optional[str]= None
```

### エンベッディング設定

#### EmbeddingConfig

Azure OpenAI / OpenAI 互換エンドポイントのエンベッディング設定。

`provider = "openai"`（v0.5.24+）で Azure AI inference の embed-v-4-0 等の OpenAI 互換エンドポイントに接続できます（`base_url` は `/models` まで含めて指定、`api_version` は未使用）。`model` に LiteLLM 形式のプレフィックス（`azure/...` / `openai/...`）を付けた場合は provider が自動導出され、プレフィックスはデプロイメント名から除去されます。

v3.1.1+ — `dimensions` を設定すると API の `dimensions` に渡し（`text-embedding-ada-002` で終わるモデル名・デプロイ名には渡さない）、返ってきたベクトルの長さが違えば `EmbeddingDimensionError`（`EmbeddingError` のサブクラス。キャッシュに入れず、再試行しない）。設定しなければ今までどおり（`None` のまま。1536 とみなし、API に渡さず、長さも確かめない）。正の整数でない値は設定を作るときに `ValueError`。実際の次元は `EmbeddingGenerator.dimensions`（整数）で、`QdrantConfig(vector_size=...)` にはこれを渡す。既存のコレクションの次元を変えるには入れ直しが要ります。

```python
class EmbeddingConfig:
  base_url: str
  api_key: str  # 非表示
  model: str = "text-embedding-ada-002"
  api_version: str = "2024-02-15-preview"
  max_cache_size: int = 10000
  dimensions: Optional[int]= None  # v3.1.1+: 設定すれば API に渡し長さを確かめる。None = 1536 とみなす
  provider: str = "azure"  # "azure" | "openai"（v0.5.24+）
  max_retries: int = 5
  base_delay: float = 1.0
  max_delay: float = 60.0

  @classmethod
  def from_dict(data: Dict[str, Any]) -> EmbeddingConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "rag.embedding") -> EmbeddingConfig: ...
```

#### EmbeddingGenerator

キャッシング機能とリトライロジック付きエンベッディング生成。

```python
class EmbeddingGenerator:
  def __init__(config: EmbeddingConfig): ...

  dimensions: int  # 実際の次元（config.dimensions、未設定は 1536）

  async def generate(text: str) -> List[float]: ...
  async def batch_generate(
      texts: List[str],
      batch_size: int = 16
  ) -> List[List[float]]: ...

  def clear_cache() -> None: ...
  def get_cache_stats() -> Dict[str, Any]: ...
```

Returns

generate() → List\[float]ベクトル（次元数は config.dimensions、未設定は 1536）。設定した次元と長さが違えば EmbeddingDimensionError（v3.1.1+）。キャッシュ済みの場合は即返却

batch\_generate() → List\[List\[float]]入力テキスト順のベクトルリスト。batch\_size 単位で API 呼び出し（デフォルト 16）

get\_cache\_stats() → Dict\[str, Any]キャッシュ統計情報（cache\_size / max\_cache\_size / cache\_utilization / model\_name）

```python
# 単一テキストの Embedding
vector = await generator.generate("Hello, world!")  # → [0.012, -0.034, ...]

# バッチ Embedding
vectors = await generator.batch_generate(["text1", "text2", "text3"])
```

### ベクトルデータベース

#### QdrantConfig

Qdrant データベース設定。

```python
class QdrantConfig:
  url: str
  collection_name: str
  vector_size: Optional[int]= 1536  # None = 1536（v3.1.1+）。EmbeddingGenerator.dimensions と同じ値にする
  distance: str = "cosine"  # cosine, euclid, dot
  on_disk_vectors: bool = False
  on_disk_payload: bool = True
  hnsw_m: int = 16
  hnsw_ef_construct: int = 256
  payload_indexes: List[PayloadIndexConfig]
  auth_token_provider: Optional[Callable[[], str]]= None
  prefer_grpc: bool = True
  check_compatibility: bool = True

  @classmethod
  def from_dict(data: Dict[str, Any]) -> QdrantConfig: ...

  @classmethod
  def from_toml(toml_path: str, section: str = "rag.qdrant") -> QdrantConfig: ...
```

#### PayloadIndexConfig

Payload フィールドのインデックス設定。

```python
@dataclass
class PayloadIndexConfig:
  field_name: str
  field_schema: str = "keyword"  # keyword, integer, float, bool

  @classmethod
  def from_dict(data: Dict[str, Any]) -> PayloadIndexConfig: ...
```

**TOML 設定例:**

```toml
[embedding]
provider = "openai"
model = "text-embedding-3-small"
api_key = "sk-..."
dimension = 1536

[qdrant]
host = "qdrant.example.com"
port = 6333
api_key = "your-qdrant-key"
use_ssl = true
```

#### VectorStoreClientBase

ベクトルストアクライアントの抽象基底クラス（`abc.ABC`）。

```python
class VectorStoreClientBase(ABC):
  def __init__(): ...

  async def __aenter__() -> VectorStoreClientBase: ...
  async def __aexit__(...) -> None: ...

  def is_initialized() -> bool: ...
  async def ensure_initialized() -> None: ...

  @abstractmethod
  async def initialize() -> None: ...

  @abstractmethod
  async def upsert(
      point_id: str,
      text: str,
      payload: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def batch_upsert(
      items: List[Dict[str, Any]],
      batch_size: int = 256
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def search(
      query_text: str,
      limit: int = 10,
      score_threshold: float = 0.4,
      filter_conditions: Optional[Dict[str, Any]]= None
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def delete(
      point_ids: List[str]
  ) -> Dict[str, Any]: ...

  @abstractmethod
  async def get_statistics() -> Dict[str, Any]: ...

  @abstractmethod
  async def close() -> None: ...
```

Returns

upsert() → Dict\[str, Any]{"success": bool, "data": {"id": str}}

batch\_upsert() → Dict\[str, Any]{"success": bool, "data": {"total\_upserted": int}}

search() → Dict\[str, Any]{"success": bool, "data": {"query": str, "results": List\[SearchResult], "total\_found": int, "score\_threshold": float}}

get\_statistics() → Dict\[str, Any]{"success": bool, "data": {"total\_objects": int, "vectors\_count": int, "content\_type\_breakdown": dict, "collection\_name": str, "status": str}}

基底契約の `upsert(point_id, text, payload)` は具象実装 `QdrantManager.upsert(id, content, metadata)` と引数名が異なります。

#### VectorStoreClientProtocol

ベクトルストアクライアントのプロトコル（`typing.Protocol`、`@runtime_checkable`）。

```python
@runtime_checkable
class VectorStoreClientProtocol(Protocol):
  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def ensure_initialized() -> None: ...

  async def upsert(
      point_id: str,
      text: str,
      payload: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  async def batch_upsert(
      items: List[Dict[str, Any]],
      batch_size: int = 256
  ) -> Dict[str, Any]: ...

  async def search(
      query_text: str,
      limit: int = 10,
      score_threshold: float = 0.4,
      filter_conditions: Optional[Dict[str, Any]]= None
  ) -> Dict[str, Any]: ...

  async def delete(
      point_ids: List[str]
  ) -> Dict[str, Any]: ...

  async def get_statistics() -> Dict[str, Any]: ...

  async def close() -> None: ...
```

Returns

upsert() → Dict\[str, Any]{"success": bool, "data": {"id": str}}

batch\_upsert() → Dict\[str, Any]{"success": bool, "data": {"total\_upserted": int}}

search() → Dict\[str, Any]{"success": bool, "data": {"query": str, "results": List\[SearchResult], "total\_found": int, "score\_threshold": float}}

get\_statistics() → Dict\[str, Any]{"success": bool, "data": {"total\_objects": int, "vectors\_count": int, "content\_type\_breakdown": dict, "collection\_name": str, "status": str}}

#### QdrantManager

Qdrant ベクトル検索クライアント。

```python
class QdrantManager:
  def __init__(
      config: QdrantConfig,
      embedding_generator: EmbeddingGenerator
  ): ...

  async def __aenter__() -> QdrantManager: ...
  async def __aexit__(...) -> None: ...

  def is_initialized() -> bool: ...
  async def initialize() -> None: ...
  async def ensure_initialized() -> None: ...

  async def upsert(
      id: str,
      content: str,
      metadata: Dict[str, Any]
  ) -> Dict[str, Any]: ...

  async def batch_upsert(
      items: List[Dict[str, Any]],
      batch_size: int = 256
  ) -> Dict[str, Any]: ...

  async def search(
      query_text: str,
      limit: int = 10,
      score_threshold: float = 0.4,
      filter_conditions: Optional[Dict[str, Any]]= None,
      ef: Optional[int]= None
  ) -> Dict[str, Any]: ...

  async def delete(
      point_ids: List[str]
  ) -> Dict[str, Any]: ...

  async def get_statistics() -> Dict[str, Any]: ...

  async def collection_exists(
      collection_name: Optional[str]= None
  ) -> bool: ...

  async def create_payload_index(
      field_name: str,
      field_schema: str = "keyword"
  ) -> Dict[str, Any]: ...

  async def delete_collection(
      collection_name: Optional[str]= None
  ) -> Dict[str, Any]: ...

  async def close() -> None: ...
```

Returns

upsert() → Dict\[str, Any]{"success": bool, "data": {"id": str}}

batch\_upsert() → Dict\[str, Any]{"success": bool, "data": {"total\_upserted": int}}

search() → Dict\[str, Any]{"success": bool, "data": {"query": str, "results": List\[SearchResult], "total\_found": int, "score\_threshold": float}}

get\_statistics() → Dict\[str, Any]{"success": bool, "data": {"total\_objects": int, "vectors\_count": int, "content\_type\_breakdown": dict, "collection\_name": str, "status": str}}

collection\_exists() → boolコレクションが存在すれば True。\`collection\_name\` 省略時は \`config.collection\_name\` を使用

create\_payload\_index() → Dict\[str, Any]payload field にインデックスを作成。\`field\_schema\` は "keyword" / "integer" / "float" / "bool" 等

delete\_collection() → Dict\[str, Any]コレクションを削除。\`collection\_name\` 省略時は \`config.collection\_name\` を使用

✓

Context manager 対応: `async with QdrantManager(config, generator) as qdrant:`

```python
from agenticstar_platform.rag import (
    EmbeddingConfig, EmbeddingGenerator,
    QdrantConfig, QdrantManager
)

emb_config = EmbeddingConfig.from_toml("config.toml")
qd_config = QdrantConfig.from_toml("config.toml")

generator = EmbeddingGenerator(emb_config)

async with QdrantManager(qd_config, generator) as qdrant:
    # ドキュメントの追加
    await qdrant.upsert(
        id="doc-001",
        content="AGENTIC STAR は AI エージェント開発プラットフォームです",
        metadata={"source": "docs", "category": "overview"}
    )

    # セマンティック検索
    results = await qdrant.search(
        query_text="AI プラットフォームとは？",
        limit=5,
        score_threshold=0.5
    )
    for r in results["data"]:
        print(f"Score: {r['score']}, Text: {r['payload']['text']}")
```

Related

[データベースモジュール](#-データベースモジュール) —

<!-- -->

DB から取得したデータを RAG に投入\
[ストレージモジュール](#-ストレージモジュール) —

<!-- -->

ドキュメントファイルをストレージから取得して Embedding 化\
[セキュリティモジュール](#-セキュリティモジュール) —

<!-- -->

Embedding 前にコンテンツの安全性を検証

---

## storage ストレージモジュール

クラウドストレージ統合（Azure Blob Storage / AWS S3 / Google Cloud Storage）。

### 列挙型

#### StorageProvider

Cloud storage provider type.

AZURE\_BLOB = "azure\_blob"

AWS\_S3 = "aws\_s3"

GCS = "gcs"

### 例外

```text
StorageError (Exception) - Base exception
├── StorageConfigError - Configuration error
├── StorageConnectionError - Connection error
└── StorageOperationError - Operation error with error_code attribute
```

### 結果型

#### UploadResult

File upload result.

```python
@dataclass
class UploadResult:
  success: bool  # Upload succeeded
  object_name: str = ""  # Object name
  object_url: str = ""  # Object URL
  file_size: int = 0  # File size
  content_type: str = ""  # Content type
  error: Optional[str]= None  # Error message
  error_code: Optional[str]= None  # Error code
  metadata: Dict[str, Any]= field(default_factory=dict)  # Metadata
```

#### DownloadResult

File download result.

```python
@dataclass
class DownloadResult:
  success: bool  # Download succeeded
  object_name: str = ""  # Object name
  local_path: str = ""  # Local file path
  file_size: int = 0  # File size
  error: Optional[str]= None  # Error message
  error_code: Optional[str]= None  # Error code
```

#### ObjectInfo

Cloud object metadata.

```python
@dataclass
class ObjectInfo:
  name: str  # Object name
  size: int  # Object size
  last_modified: Optional[str]= None  # Last modified timestamp
  content_type: Optional[str]= None  # Content type
  metadata: Dict[str, Any]= field(default_factory=dict)  # Metadata
```

#### ListResult

List operation result.

```python
@dataclass
class ListResult:
  success: bool  # Operation succeeded
  objects: List[ObjectInfo]= field(default_factory=list)  # Objects
  count: int = 0  # Object count
  prefix: str = ""  # Search prefix
  error: Optional[str]= None  # Error message
  error_code: Optional[str]= None  # Error code
```

### 設定

#### StorageConfig

Common storage configuration (base class).

```python
class StorageConfig:
  provider: StorageProvider# Provider type
  bucket_name: str  # Bucket/container name
  enabled: bool = True  # Enabled flag
  max_file_size: int = 5*1024*1024*1024  # Max file size (5GB)
  auto_create_bucket: bool = False  # Auto-create bucket
  prefix: str = ""  # Object name prefix
  custom_domain: Optional[str]= None  # Custom domain
  connection_timeout: int = 30  # Connection timeout (seconds)
  read_timeout: int = 300  # Read timeout (seconds)
```

#### AzureBlobConfig

Azure Blob Storage configuration.

v3.1.0+ — `connection_string` を省略（空文字も省略扱い）すると、`storage_account_name`（と `endpoint_suffix`、既定 `core.windows.net`）からアカウントの URL を組み、`DefaultAzureCredential`（AKS では Workload Identity / Managed Identity、手元では Azure CLI）で認証する。Storage Account の Shared Key 認証を無効にした環境ではこちらを使う。ID には Storage Blob Data Contributor が必要。どちらも無ければ `AzureBlobStorageClient` の作成時に `StorageConfigError`。`storage-azure` extra に `azure-identity` が入った（この経路でだけ読み込む）。

```python
class AzureBlobConfig:
  bucket_name: str  # Container name
  connection_string: Optional[str]= None  # 非表示。v3.1.0+ で省略可
  enabled: bool = True
  max_file_size: int = 5*1024*1024*1024
  auto_create_bucket: bool = False
  prefix: str = ""
  custom_domain: Optional[str]= None
  connection_timeout: int = 30
  read_timeout: int = 300
  max_block_size: int = 8*1024*1024  # Max block size (8MB)
  max_single_put_size: int = 256*1024*1024  # Max single upload (256MB)
  storage_account_name: Optional[str]= None  # v3.1.0+
  endpoint_suffix: str = "core.windows.net"  # v3.1.0+

  @classmethod
  def from_dict(data: Dict[str, Any]) -> AzureBlobConfig: ...
  @property
  def provider(self) -> StorageProvider: return StorageProvider.AZURE_BLOB
```

#### S3Config

AWS S3 configuration.

```python
class S3Config:
  bucket_name: str  # Bucket name
  aws_access_key_id: Optional[str]= None  # 非表示
  aws_secret_access_key: Optional[str]= None  # 非表示
  region_name: str = "us-east-1"  # AWS region
  enabled: bool = True
  max_file_size: int = 5*1024*1024*1024
  auto_create_bucket: bool = False
  prefix: str = ""
  custom_domain: Optional[str]= None
  connection_timeout: int = 30
  read_timeout: int = 300
  endpoint_url: Optional[str]= None  # S3-compatible endpoint (MinIO, etc.)

  @classmethod
  def from_dict(data: Dict[str, Any]) -> S3Config: ...
  @property
  def provider(self) -> StorageProvider: return StorageProvider.AWS_S3
```

v3.2.3+ — `aws_access_key_id`・`aws_secret_access_key` は任意です。両方とも省く（空でもよい）と鍵を渡さず、boto3 の既定の探し方（EKS の IRSA・環境変数・`~/.aws` の設定・EKS Pod Identity・EC2 のインスタンスロールなど。どれを先に使うかは boto3 が決め、環境変数は IRSA より先に見られます）で認証します。EKS の IRSA で動かすときはこの形にし、Pod に `AWS_ACCESS_KEY_ID` を渡さないでください。片方だけを渡すと `StorageConfigError` です。

```python
config = S3Config(bucket_name="my-bucket", region_name="us-east-1")
```

#### GCSConfig

Google Cloud Storage configuration.

```python
class GCSConfig:
  bucket_name: str  # Bucket name
  project_id: str  # GCP project ID
  enabled: bool = True
  max_file_size: int = 5*1024*1024*1024
  auto_create_bucket: bool = False
  prefix: str = ""
  custom_domain: Optional[str]= None
  connection_timeout: int = 30
  read_timeout: int = 300
  credentials_path: Optional[str]= None  # 非表示 - Path to service account JSON
  credentials_json: Optional[str]= None  # 非表示 - Service account JSON string
  credentials_base64: Optional[str]= None  # 非表示 - Base64-encoded service account JSON

  @classmethod
  def from_dict(data: Dict[str, Any]) -> GCSConfig: ...
  @property
  def provider(self) -> StorageProvider: return StorageProvider.GCS
```

### ストレージクライアント

#### AzureBlobStorageClient

Azure Blob Storage client. Supports async context manager (`async with`).

```python
class AzureBlobStorageClient:
  def __init__(config: AzureBlobConfig): ...

  @property
  def provider(self) -> StorageProvider: return StorageProvider.AZURE_BLOB
  @property
  def container_name(self) -> str: ...

  async def ensure_bucket_exists() -> bool: ...

  async def upload_file(
      file_path: str,
      object_name: Optional[str]= None,
      prefix: Optional[str]= None,
      metadata: Optional[Dict[str, Any]]= None
  ) -> UploadResult: ...

  async def download_file(
      object_name: str,
      download_path: str,
      version_id: Optional[str]= None
  ) -> DownloadResult: ...

  async def list_objects(
      prefix: str = "",
      max_results: Optional[int]= None
  ) -> ListResult: ...

  async def delete_object(
      object_name: str
  ) -> bool: ...

  async def object_exists(
      object_name: str
  ) -> bool: ...

  async def close() -> None: ...
```

Returns

upload\_file() → UploadResultsuccess, object\_url, file\_size, content\_type を含む

download\_file() → DownloadResultsuccess, local\_path, file\_size を含む

list\_objects() → ListResultsuccess, objects: List\[ObjectInfo], count を含む

delete\_object() → bool削除に成功したら True

#### S3StorageClient

AWS S3 storage client. Supports async context manager (`async with`).

```python
class S3StorageClient:
  def __init__(config: S3Config): ...

  @property
  def provider(self) -> StorageProvider: return StorageProvider.AWS_S3
  @property
  def bucket_name(self) -> str: ...

  async def ensure_bucket_exists() -> bool: ...

  async def upload_file(
      file_path: str,
      object_name: Optional[str]= None,
      prefix: Optional[str]= None,
      metadata: Optional[Dict[str, Any]]= None
  ) -> UploadResult: ...

  async def download_file(
      object_name: str,
      download_path: str,
      version_id: Optional[str]= None
  ) -> DownloadResult: ...

  async def list_objects(
      prefix: str = "",
      max_results: Optional[int]= None
  ) -> ListResult: ...

  async def delete_object(
      object_name: str
  ) -> bool: ...

  async def object_exists(
      object_name: str
  ) -> bool: ...

  async def close() -> None: ...
```

#### GCSStorageClient

Google Cloud Storage client. Supports async context manager (`async with`).

```python
class GCSStorageClient:
  def __init__(config: GCSConfig): ...

  @property
  def provider(self) -> StorageProvider: return StorageProvider.GCS
  @property
  def bucket_name(self) -> str: ...

  async def ensure_bucket_exists() -> bool: ...

  async def upload_file(
      file_path: str,
      object_name: Optional[str]= None,
      prefix: Optional[str]= None,
      metadata: Optional[Dict[str, Any]]= None
  ) -> UploadResult: ...

  async def download_file(
      object_name: str,
      download_path: str,
      version_id: Optional[str]= None
  ) -> DownloadResult: ...

  async def list_objects(
      prefix: str = "",
      max_results: Optional[int]= None
  ) -> ListResult: ...

  async def delete_object(
      object_name: str
  ) -> bool: ...

  async def object_exists(
      object_name: str
  ) -> bool: ...

  async def close() -> None: ...
```

v3.3.0+ — 3 つのクライアントの `download_file` は `version_id` を受けます。指すと、最新ではなくその版を取ります。値は、Azure Blob では `versionId`、S3 では `VersionId`、GCS では generation（数字の文字列）です。無い版と空の値は、オブジェクトが無いときと同じ失敗（`success=False`。`error_code` は Azure が `BLOB_NOT_FOUND`、S3・GCS が `OBJECT_NOT_FOUND`）で、GCS では数字でない値も同じです。上書き・削除の前の版を残すには、ストレージ側でバージョン管理を有効にします（Azure はストレージアカウントの BLOB のバージョン管理、S3・GCS はバケットのバージョニング）。`version_id` を省くと、今までどおり最新の版を取ります。`StorageClientBase` を継承した自前のクライアントは、`download_file` にこのキーワード引数を足してください（渡さない呼び出し元には影響しません）。

```python
from agenticstar_platform.storage import (
    S3Config, S3StorageClient
)

config = S3Config.from_dict({
    "bucket_name": "my-bucket",
    "aws_access_key_id": "AKIA...",
    "aws_secret_access_key": "secret...",
    "region_name": "ap-northeast-1"
})

# async with によるコンテキストマネージャー
async with S3StorageClient(config) as storage:
    # ファイルアップロード
    upload_result = await storage.upload_file(
        file_path="/tmp/report.pdf",
        object_name="report.pdf",
        prefix="documents/",
        metadata={"source": "documents"}
    )
    if upload_result.success:
        print(f"URL: {upload_result.object_url}")

    # オブジェクト一覧
    list_result = await storage.list_objects(prefix="documents/")
    for obj in list_result.objects:
        print(f"{obj.name} ({obj.size} bytes)")

    # ダウンロード
    download = await storage.download_file(
        object_name="documents/report.pdf",
        download_path="/tmp/downloaded.pdf"
    )
```

```python
from agenticstar_platform.storage import (
    StorageError, StorageConfigError,
    StorageConnectionError, StorageOperationError
)

try:
    result = await storage.upload_file("/tmp/large-file.zip")
except StorageConnectionError as e:
    print(f"Connection failed: {e}")
except StorageOperationError as e:
    print(f"Operation failed: {e}, code: {e.error_code}")
except StorageError as e:
    print(f"Storage error: {e}")
```

Related

[RAG モジュール](#-rag-モジュール) —

<!-- -->

ストレージのドキュメントを取得して Embedding に投入\
[セキュリティモジュール](#-セキュリティモジュール) —

<!-- -->

アップロード前のコンテンツモデレーション

---

## auth 認証モジュール

AGENTIC STAR 認証サービス統合。ユーザー・トークン・デバイス情報を管理。

### 例外

```text
AuthError (Exception)
├── AuthConfigError
└── AuthAPIError
  ├── AuthUnauthorizedError  (401)
  ├── AuthNotFoundError      (404)
  └── AuthRateLimitError     (429)
```

### 設定

#### AgenticStarAuthConfig

AGENTIC STAR 認証 API クライアントの接続設定。

v3.2.0+ — `auth_type` は `"bearer"`（既定）だけを受け付けます。旧方式の `"api_key"`（`api_key` を `X-Internal-API-Key` ヘッダーで送る方式。認証 API はこのヘッダーをもう受け付けません）やほかの値を渡すと、設定を作るとき（`create`・コンストラクター・`dataclasses.replace`）に `AuthConfigError` になります。作った後に `auth_type` を書き換えた設定で `AgenticStarAuthClient` を作ると、`AuthConfigError` になります。`api_key` には Bearer トークン（`Authorization: Bearer ...` で送ります）を入れるか、トークンを返す `token_provider` を渡してください。`auth_type` を省くか `"bearer"` を渡すコードは、そのまま動きます。

```python
class AgenticStarAuthConfig:
  base_url: str
  api_key: str  # 非表示
  auth_type: str = "bearer"
  timeout: float = 30.0
  token_provider: Optional[Callable[[], Optional[str]]]= None

  @classmethod
  def create(
      base_url: str,
      api_key: str = "",
      auth_type: str = "bearer",
      token_provider: Optional[Callable[[], Optional[str]]]= None,
      timeout: float = 30.0
  ) -> AgenticStarAuthConfig: ...

  @classmethod
  def from_config(config_path: Optional[Path]= None) -> AgenticStarAuthConfig: ...
```

### データモデル

#### ApiUser

認証ユーザー情報（Pydantic BaseModel）。

```python
class ApiUser(BaseModel):
  id: str
  username: Optional[str]= None
  email: Optional[str]= None
  first_name: Optional[str]= None
  last_name: Optional[str]= None
  display_name: Optional[str]= None
  email_verified: bool = False
  enabled: bool = True
  created_timestamp: Optional[int]= None
  attributes: Optional[Dict[str, Any]]= None
  organization: Optional[str]= None
  organization_label: Optional[str]= None
  job: Optional[str]= None
  job_label: Optional[str]= None
  bio: Optional[str]= None
  last_login_at: Optional[str]= None
```

#### DeviceInfo

デバイス情報。

```python
class DeviceInfo(BaseModel):
  id: Optional[str]= None
  device_code: str
  device_name: Optional[str]= None
  device_type: Optional[str]= None
  device_info: Optional[Dict[str, Any]]= None
  is_active: Optional[bool]= None
  created_at: Optional[str]= None
  last_used_at: Optional[str]= None
```

#### MCPTokenInfo

MCP トークン情報。`expires_at` は `None` が「期限なし」を表します（個人トークン (PAT) の provider ではトークン供給 API が期限を返さないため。v0.5.34+）。

```python
class MCPTokenInfo(BaseModel):
  access_token: str
  token_type: str
  expires_at: Optional[datetime]= None
  scopes: List[str]
```

#### UserPagination

ページネーション情報（`get_users()` の戻り値 `pagination`）。

```python
class UserPagination(BaseModel):
  page: int
  limit: int
  total: int
  total_pages: int
  has_next: bool
  has_previous: bool
```

#### LoginHistoryEntry

ログイン履歴エントリ（`get_user()` の戻り値 `login_history` の要素）。

```python
class LoginHistoryEntry(BaseModel):
  timestamp: int
  ip_address: str
  user_agent: str
  platform: str
  location: Optional[Dict[str, Optional[str]]]= None
  success: bool
```

#### MCPTokenError

MCP トークン取得エラー（`get_mcp_tokens()` の戻り値 `errors` の値）。`code` は `CONNECTION_NOT_FOUND` / `TOKEN_EXPIRED` / `REFRESH_FAILED` など。

```python
class MCPTokenError(BaseModel):
  code: str
  message: str
```

#### OAuthProviderName

OAuth プロバイダー名を表す型エイリアス。値は DB の `oauth_providers.service` に対応し、`get_mcp_tokens(providers=[...])` に渡す識別子および `tokens` / `errors` 辞書のキーとして使用される（例: `github`、`slack`）。

```python
OAuthProviderName = str
```

### クライアント

#### AgenticStarAuthClient

AGENTIC STAR 認証 API の HTTP クライアント。

```python
class AgenticStarAuthClient:
  def __init__(config: AgenticStarAuthConfig): ...

  async def __aenter__() -> AgenticStarAuthClient: ...
  async def __aexit__(...) -> None: ...

  async def get_users(
      page: int = 1,
      limit: int = 20,
      search: Optional[str]= None,
      is_approved: Optional[str]= None,
      job: Optional[str]= None,
      organization: Optional[str]= None,
      sort_by: Optional[str]= None,
      order: Optional[str]= None,
      include_last_login: bool = False
  ) -> GetUsersResult: ...

  async def get_user(
      user_id: str
  ) -> GetUserResult: ...

  async def get_mcp_tokens(
      user_id: str,
      providers: Optional[List[str]]= None,
      rejected_token_sha256: Optional[Dict[str, str]]= None  # v3.0.10+
  ) -> GetMCPTokensResult: ...

  async def close() -> None: ...
```

Returns

get\_users() → GetUsersResultsuccess, users: List\[ApiUser], pagination: UserPagination, error, error\_code

get\_user() → GetUserResultsuccess, user: ApiUser, devices: List\[DeviceInfo], login\_history, is\_deleted, deleted\_at, deleted\_by, deletion\_reason, error, error\_code

get\_mcp\_tokens() → GetMCPTokensResultsuccess, tokens: Dict\[str, MCPTokenInfo], errors, error, error\_code

`get_user()` は `user_id` を URL のパス要素 1 つとしてエンコードして送ります（`/` や `?` を含む値でも別の API パスに届きません。v3.0.5+）。空文字と `.` / `..`（v3.0.5+）は要求を送らずに `success=False`、`error_code="INVALID_PARAMETER"` を返します。

`get_mcp_tokens()` の `rejected_token_sha256`（v3.0.10+）は、MCP サーバーに 401 で拒否されたアクセストークンの SHA-256（トークン文字列を UTF-8 で。16 進の小文字 64 桁）を provider ごとに渡します。保存中のトークンがまだそのトークンなら、期限前でも取り直します。既に別のトークンに替わっていれば新しい方を返します。個人トークン（PAT）・refresh できない接続・発行から 1 分未満のトークンは取り直しません（保存中のトークンを返します）。トークンそのものは渡さないでください。対応していない認証サービスでは無視されます。

```python
# ユーザー一覧の取得（ページネーション）
result = await auth_client.get_users(page=1, limit=20)
for user in result.users:
  print(f"{user.username} ({user.email})")
```

```python
from pathlib import Path

from agenticstar_platform.auth import (
    AgenticStarAuthConfig, AgenticStarAuthClient
)

config = AgenticStarAuthConfig.from_config(Path("config.toml"))

async with AgenticStarAuthClient(config) as auth_client:
    # ユーザー情報取得
    result = await auth_client.get_user("user-123")
    if result.success:
        print(f"User: {result.user.username}")

    # MCP トークン取得
    tokens = await auth_client.get_mcp_tokens(
        user_id="user-123",
        providers=["slack", "gitlab"],
    )
    for provider, token in tokens.tokens.items():
        print(f"{provider}: expires={token.expires_at}")
```

Related

[イベントモジュール](#-イベントモジュール) —

<!-- -->

WebhookEventHandler の token\_provider に認証トークンを供給\
[メモリモジュール](#-メモリモジュール) —

<!-- -->

認証済みユーザーのセマンティックメモリ管理

---

## memory メモリモジュール

セマンティックメモリ（Mem0 + Qdrant）統合。ユーザーの知識・好み・事実をベクトル検索で想起。

### 設定

#### SemanticMemoryConfig

Mem0 + Qdrant によるセマンティックメモリの設定。

```python
@dataclass
class LLMProviderConfig:
  model: str                                    # "azure_openai/gpt-4.1"
  api_key: str                                  # 非表示
  base_url: Optional[str]= None
  api_version: Optional[str]= None
  aws_access_key_id: Optional[str]= None       # Bedrock 用
  aws_secret_access_key: Optional[str]= None   # Bedrock 用
  aws_region_name: Optional[str]= None          # Bedrock 用

  @classmethod
  def from_dict(data: Dict[str, Any]) -> LLMProviderConfig: ...
  @classmethod
  def from_toml(toml_path: str, section: str) -> LLMProviderConfig: ...
  @classmethod
  def from_env(prefix: str = "LLM_") -> LLMProviderConfig: ...
```

```python
@dataclass
class SemanticMemoryConfig:
  llm_config: LLMProviderConfig
  embedder_config: LLMProviderConfig
  vector_store: Optional[Dict[str, Any]]= None
  rerank: Optional[Dict[str, Any]]= None
  custom_fact_extraction_prompt: Optional[str]= None
  custom_update_memory_prompt: Optional[str]= None

  @classmethod
  def from_dict(data: Dict[str, Any]) -> SemanticMemoryConfig: ...
  @classmethod
  def from_toml(toml_path: str, section: str = "memory") -> SemanticMemoryConfig: ...
```

#### QdrantVectorStoreConfig

Qdrant Vector Store 設定を簡潔に組み立てるヘルパー dataclass。

```python
@dataclass
class QdrantVectorStoreConfig:
  url: str
  collection_name: str
  embedding_dims: int = 1536

  def to_dict() -> Dict[str, Any]: ...

  @classmethod
  def from_dict(data: Dict[str, Any]) -> QdrantVectorStoreConfig: ...
```

#### SemanticMemoryClient

セマンティックメモリの追加・検索・削除クライアント（同期 API）。

```python
class SemanticMemoryClient:
  def __init__(config: SemanticMemoryConfig): ...

  @property
  def enabled() -> bool: ...

  # 同期メソッド（await 不要）
  def add(
      messages: List[Dict[str, str]],
      user_id: str,
      metadata: Optional[Dict[str, Any]]= None
  ) -> Dict[str, Any]: ...

  def search(
      query: str,
      user_id: str,
      limit: int = 10
  ) -> Dict[str, Any]: ...

  def get_all(
      user_id: str
  ) -> Dict[str, Any]: ...

  def delete(
      memory_id: str
  ) -> Dict[str, Any]: ...

  def delete_all(
      user_id: str
  ) -> Dict[str, Any]: ...

  # 非同期メソッド
  async def cleanup() -> None: ...
```

Returns

add() → Dict\[str, Any]Mem0 の結果辞書。messages は OpenAI 形式の \[{"role": "user", "content": "..."}]

search() → Dict\[str, Any]{"results": \[...]}。各要素に memory, score 等を含む

get\_all() → Dict\[str, Any]ユーザーの全メモリを返す

delete() / delete\_all() → Dict\[str, Any]削除結果

### 例外

```text
SemanticMemoryError (Exception)
└── SemanticMemoryConfigError
```

### ユーティリティ関数

```python
def normalize_provider(provider: str) -> str
```

プロバイダー名を正規化（エイリアス対応。例: `"Azure_OpenAI"` → `"azure"`）。

```python
def parse_model_string(model: str) -> tuple[str, str]
```

モデル文字列をプロバイダーとモデル名に分割（例: `"azure_openai/gpt-4.1"` → `("azure", "gpt-4.1")`）。

```python
def get_api_key(config: LLMProviderConfig) -> str
```

LLMProviderConfig から API キーを取得（SecretStr 対応）。

```python
def convert_llm_to_mem0(llm_config: LLMProviderConfig) -> Dict[str, Any]
```

LLMProviderConfig を Mem0 形式の LLM 設定辞書に変換。

```python
def convert_embedder_to_mem0(embedder_config: LLMProviderConfig) -> Dict[str, Any]
```

LLMProviderConfig を Mem0 形式の Embedder 設定辞書に変換。openai プロバイダ（`openai/...` モデル）で `base_url` が設定されている場合は `openai_base_url` として引き渡します（v0.5.24+。embed-v-4-0 等の OpenAI 互換エンドポイント用。未設定時は公式 api.openai.com に接続されるため注意）。v0.5.35 以前は `SemanticMemoryClient` 内部の変換経路にこの引き渡しが適用されないバグがあり、v0.5.36 で修正されました。

```python
from agenticstar_platform.memory import (
    SemanticMemoryConfig, SemanticMemoryClient
)

config = SemanticMemoryConfig.from_toml("config.toml")
memory = SemanticMemoryClient(config)

# メモリ追加（同期メソッド）
memory.add(
    messages=[
        {"role": "user", "content": "私は Python が得意です"},
        {"role": "assistant", "content": "承知しました"},
    ],
    user_id="user-123",
)

# メモリ検索（同期メソッド）
result = memory.search(query="ユーザーの技術スキルは？", user_id="user-123")
for r in result.get("results", []):
    print(f"{r['memory']}")

# クリーンアップ（非同期）
await memory.cleanup()
```

Related

[認証モジュール](#-認証モジュール) —

<!-- -->

認証済みユーザー ID をメモリの user\_id として使用\
[RAG モジュール](#-rag-モジュール) —

<!-- -->

メモリ内容を Embedding 化して類似検索を強化

---

## security セキュリティモジュール

Content Moderation（Azure / AWS / GCP）+ PII Detection。AWS の PII 検出は Bedrock Guardrails `sensitiveInformationPolicy`（多言語対応、日本語含む）または Amazon Comprehend（en/es）から選択可能（`AWSSecurityConfig.pii_service`）。

### 列挙型

#### SecurityProvider

セキュリティプロバイダー種別。

AZURE = "azure"

AWS = "aws"

GCP = "gcp"

#### ContentCategory

コンテンツモデレーション分類。

HATE = "hate"

SEXUAL = "sexual"

SELF\_HARM = "self\_harm"

VIOLENCE = "violence"

PROFANITY = "profanity"

INSULT = "insult"

THREAT = "threat"

#### PIICategory

PII（個人識別情報）分類。

PERSON\_NAME = "person\_name"

EMAIL = "email"

PHONE\_NUMBER = "phone\_number"

ADDRESS = "address"

AGE = "age"

DATE\_OF\_BIRTH = "date\_of\_birth"

NATIONAL\_ID = "national\_id"

PASSPORT\_NUMBER = "passport\_number"

DRIVERS\_LICENSE = "drivers\_license"

SOCIAL\_SECURITY = "social\_security"

TAX\_ID = "tax\_id"

CREDIT\_CARD = "credit\_card"

BANK\_ACCOUNT = "bank\_account"

SWIFT\_CODE = "swift\_code"

IBAN = "iban"

MEDICAL\_RECORD = "medical\_record"

HEALTH\_INSURANCE = "health\_insurance"

IP\_ADDRESS = "ip\_address"

MAC\_ADDRESS = "mac\_address"

URL = "url"

PASSWORD = "password"

API\_KEY = "api\_key"

AWS\_ACCESS\_KEY = "aws\_access\_key"

CONNECTION\_STRING = "connection\_string"

OTHER = "other"

### 例外

```text
SecurityError (Exception)
├── SecurityConfigError
└── SecurityAPIError (status_code, error_code)
```

### 結果型

#### ContentModerationResult

コンテンツモデレーション結果。`categories` の値は severity（0-6）。

```python
@dataclass
class ContentModerationResult:
  blocked: bool                                 # しきい値以上でTrue
  categories: Dict[ContentCategory, int]= {}   # severity 0-6
  threshold: int = 2                            # 適用しきい値
  raw_response: Dict[str, Any]= {}
  error: Optional[str]= None
  error_code: Optional[str]= None
```

#### PromptShieldResult

プロンプトインジェクション検出結果。

```python
@dataclass
class PromptShieldResult:
  attack_detected: bool
  attack_type: Optional[str]= None
  confidence: float = 0.0
  raw_response: Dict[str, Any]= {}
  error: Optional[str]= None
  error_code: Optional[str]= None
  user_prompt_attack: Optional[bool]= None   # v0.5.40+ direct(userPrompt) 経路の検知内訳
  documents_attack: Optional[bool]= None     # v0.5.40+ indirect(documents) 経路の検知内訳
```

`user_prompt_attack` / `documents_attack` は攻撃経路の内訳（v0.5.40+）。`None` は「未取得」（旧版・未評価）であり `False`（評価済み非検知）と区別されます。両方既知のとき `attack_detected == (user_prompt_attack or documents_attack)` が成り立ちます。

#### PIIEntity

検出された PII エンティティ。

```python
@dataclass
class PIIEntity:
  category: PIICategory
  text: str                    # 検出されたテキスト
  offset: int                  # テキスト内の開始位置
  length: int                  # 検出テキストの長さ
  confidence: float
  provider_category: str = ""  # プロバイダー固有のカテゴリ名
```

#### PIIDetectionResult

PII 検出結果。

```python
@dataclass
class PIIDetectionResult:
  success: bool
  masked_text: str = ""
  entities: List[PIIEntity]= []
  categories_detected: List[PIICategory]= []
  raw_response: Dict[str, Any]= {}
  error: Optional[str]= None
  error_code: Optional[str]= None
```

#### SecurityCheckResult

統合セキュリティチェック結果。

```python
@dataclass
class SecurityCheckResult:
  allowed: bool                                          # 許可/ブロック
  violations: List[str]= []                             # 違反理由リスト
  content_moderation: Optional[ContentModerationResult]= None
  prompt_shield: Optional[PromptShieldResult]= None
  pii_detection: Optional[PIIDetectionResult]= None
```

#### SanitizationResult

`ContentSafetyValidator.validate_and_sanitize()` のサニタイズ結果。`marked_content` は unsafe 判定時は空文字。

```python
@dataclass
class SanitizationResult:
  is_safe: bool
  marked_content: str = ""
  metadata: Dict[str, Any]= {}
```

### 設定

#### AzureSecurityConfig

Azure Content Safety + Language Service 接続設定。

```python
class AzureSecurityConfig:
  content_safety_endpoint: str
  content_safety_api_key: str  # 非表示
  language_endpoint: Optional[str]= None     # PII 検出用
  language_api_key: Optional[str]= None      # 非表示
  enabled: bool = True
  prompt_shield_enabled: bool = True          # Prompt Shield 有効化
  moderation_enabled: bool = True             # コンテンツモデレーション有効化
  moderation_threshold: int = 2               # severity 0-6
  pii_enabled: bool = True
  pii_confidence_threshold: float = 0.7
  pii_mask_string: str = "***"                # PII マスク文字列
  timeout: float = 30.0
```

#### AWSSecurityConfig

AWS Bedrock Guardrails / Comprehend によるセキュリティ設定。

```python
class AWSSecurityConfig:
  aws_access_key_id: str = ""   # 非表示
  aws_secret_access_key: str = ""  # 非表示
  region_name: str = "us-east-1"
  guardrail_id: str = ""
  guardrail_version: str = "DRAFT"
  pii_service: str = "bedrock_guardrails"     # PII 検出経路 ("bedrock_guardrails" / "comprehend")
  enabled: bool = False
  prompt_shield_enabled: bool = True          # Prompt Shield 有効化
  moderation_enabled: bool = True             # コンテンツモデレーション有効化
  moderation_threshold: int = 2
  pii_enabled: bool = True
  pii_confidence_threshold: float = 0.7
  pii_mask_string: str = "***"                # PII マスク文字列
  timeout: float = 30.0
```

#### GCPSecurityConfig

GCP Model Armor + DLP によるセキュリティ設定。

```python
class GCPSecurityConfig:
  project_id: str
  credentials_path: Optional[str]= None  # 非表示
  # Content Safety 経路: "model_armor"(既定) | "vertex_ai_safety"(全リージョン対応)
  content_safety_backend: str = "model_armor"
  model_armor_template: str = ""
  model_armor_region: str = ""
  # Vertex AI Safety Filters + Gemini judge (content_safety_backend="vertex_ai_safety" 時)
  vertex_ai_location: str = "global"
  vertex_harm_thresholds: Dict[str, str]= {}
  vertex_judge_model: str = "gemini-2.5-flash"
  dlp_location: str = "global"
  enabled: bool = False
  prompt_shield_enabled: bool = True          # Prompt Shield 有効化
  moderation_enabled: bool = True             # コンテンツモデレーション有効化
  moderation_threshold: int = 2
  pii_enabled: bool = True
  pii_confidence_threshold: float = 0.7
  pii_mask_string: str = "***"                # PII マスク文字列
  timeout: float = 30.0
```

#### GuardrailsConfig

`ContentSafetyValidator` のガードレール設定（マーケットプレイス顧客が管理 UI で設定する値を想定）。DB の `guardrails_settings` 辞書から `from_dict()` で生成できる。`moderation_threshold` は severity 0-6（0=無効, 2=推奨, 6=極度のみ）。

```python
@dataclass
class GuardrailsConfig:
  prompt_shield_enabled: bool = True
  moderation_threshold: int = 2
  fail_on_error: bool = True
  mark_content: bool = True

  @classmethod
  def from_dict(data: Dict[str, Any]) -> GuardrailsConfig: ...
```

### クライアント

#### SecurityClientBase

全セキュリティクライアント（Azure / AWS / GCP）の抽象基底クラス。`enabled` は設定の有効状態を反映し、`provider` はサブクラスで実装される抽象プロパティ（プロバイダー種別を返す）。

```python
class SecurityClientBase:
  @property
  def enabled() -> bool: ...

  @property
  def provider() -> SecurityProvider: ...
```

#### AzureSecurityClient

Azure Content Safety（コンテンツモデレーション）と Language Service（PII 検出）のクライアント。

v3.1.3+ — コンテンツモデレーション・Prompt Shield・PII 検出の要求が、送る前に失敗したとき（egress のプロキシが `CONNECT` を断った `httpx.ProxyError`、接続を拒まれた `httpx.ConnectError`、接続の時間切れ `httpx.ConnectTimeout`）だけ、0.5・1・2 秒待って送り直す（初回を含めて最大 4 回。1 回ごとに `timeout` がかかり、間の待ちの計 3.5 秒はその外。既定の 30 秒で接続の時間切れが続くと約 2 分）。使い切ったら従来どおり、モデレーションと Prompt Shield は `SecurityAPIError` を上げ、PII 検出は `success=False` の結果を返す（どちらも `error_code="REQUEST_ERROR"`）。要求は Azure に届いていないので、二重には送られない。送った後の失敗（エラーの status・読み取りの時間切れ）は送り直さず、PII 検出の 429 の再試行もこれまでどおり。マーケットプレイスの Agent の Pod は Envoy のサイドカーを通って外へ出るが、サイドカーは起動直後の約 0.5 秒、`CONNECT` に `503` を返す。そのため、最初の外への呼び出しが入力のガードレールになるワークフロー型の Agent が、毎回この呼び出しで失敗していた。

```python
class AzureSecurityClient(SecurityClientBase):
  def __init__(config: AzureSecurityConfig): ...

  async def __aenter__() -> AzureSecurityClient: ...
  async def __aexit__(...) -> None: ...

  @property
  def enabled() -> bool: ...

  @property
  def provider(self) -> SecurityProvider: return SecurityProvider.AZURE

  async def check_content_moderation(
      text: str,
      threshold: Optional[int]= None
  ) -> ContentModerationResult: ...

  async def check_prompt_shield(
      user_prompt: str,
      documents: Optional[List[str]]= None
  ) -> PromptShieldResult: ...

  async def detect_pii(
      text: str,
      mask: bool = True,
      language: str = "ja",
      confidence_threshold: Optional[float]= None
  ) -> PIIDetectionResult: ...

  async def detect_pii_batch(  # v0.5.23+
      texts: List[str],
      mask: bool = True,
      language: str = "ja",
      confidence_threshold: Optional[float]= None
  ) -> List[PIIDetectionResult]: ...

  async def check_security(
      text: str,
      check_moderation: bool = True,
      check_prompt_shield: bool = True,
      check_pii: bool = False,
      fail_on_error: bool = True
  ) -> SecurityCheckResult: ...

  async def close() -> None: ...
```

Returns

check\_content\_moderation() → ContentModerationResultblocked（ブロック判定）, categories（severity 0-6）

check\_prompt\_shield() → PromptShieldResultattack\_detected, attack\_type, confidence

detect\_pii() → PIIDetectionResultsuccess, entities（PIIEntity リスト）, masked\_text

detect\_pii\_batch() → List\[PIIDetectionResult]入力と同順・同長。Azure は 5 documents/request でバッチ送信（呼び出し数最大 1/5）。429 は Retry-After 尊重で自動リトライし、枯渇継続時は error\_code="RATE\_LIMITED" でテキスト単位に fail-closed（v0.5.23+）

check\_security() → SecurityCheckResultallowed, violations, 各検出結果

```python
# PII マスク結果の利用
result = await security.detect_pii("Email: user@example.com", mask=True)
print(result.masked_text)  # → "Email: ***"
print(result.entities[0].category)  # → PIICategory.EMAIL
```

#### AWSSecurityClient / GCPSecurityClient

Azure と同一のインターフェース（`SecurityClientBase` 継承）。`check_content_moderation()`, `check_prompt_shield()`, `detect_pii()`, `check_security()`, `close()` を実装。`detect_pii_batch()` は基底クラスの逐次デフォルト実装を継承（プロバイダ側バッチ最適化は Azure のみ、v0.5.23+）。

```python
from agenticstar_platform.security import (
    AzureSecurityConfig, AzureSecurityClient
)

config = AzureSecurityConfig(
    content_safety_endpoint="https://your-cs.cognitiveservices.azure.com/",
    content_safety_api_key="your-key",
)

async with AzureSecurityClient(config) as security:
    # コンテンツモデレーション
    moderation = await security.check_content_moderation(
        text="This is a sample message",
        threshold=2,
    )

    if moderation.blocked:
        print(f"Content blocked: {moderation.categories}")

    # 統合チェック
    result = await security.check_security(
        text="Contact me at user@example.com or 123-456-7890",
        check_pii=True,
    )

    if not result.allowed:
        print(f"Violations: {result.violations}")
    if result.pii_detection and result.pii_detection.entities:
        print(f"PII found: {result.pii_detection.masked_text}")
```

#### ContentSafetyValidator

外部から取得したコンテンツ（Web / MCP など）を `SecurityClientProtocol` 実装（`AzureSecurityClient` 等）で検証し、`GuardrailsConfig` に基づいてサニタイズ・マーキングするラッパー。`validate_and_sanitize()` は単一コンテンツ、`validate_multiple()` は複数コンテンツを一括処理する。`mark_content()` / `unmark_content()` はマーカー（`[EXT:...]...[/EXT]`）を付与・除去する静的メソッド。

```python
class ContentSafetyValidator:
  def __init__(
      security_client: SecurityClientProtocol,
      guardrails: Optional[GuardrailsConfig]= None
  ): ...

  @property
  def guardrails() -> GuardrailsConfig: ...

  def update_guardrails(guardrails: GuardrailsConfig) -> None: ...

  async def validate_and_sanitize(
      content: str,
      source_type: str,
      source_url: Optional[str]= None,
      user_prompt: Optional[str]= None
  ) -> SanitizationResult: ...

  async def validate_multiple(
      contents: List[Tuple[str, str, Optional[str]]],
      user_prompt: Optional[str]= None
  ) -> Tuple[bool, List[str], List[Dict[str, Any]]]: ...

  @staticmethod
  def mark_content(
      content: str,
      source_type: str,
      source_url: Optional[str]= None
  ) -> str: ...

  @staticmethod
  def unmark_content(marked_content: str) -> Tuple[str, Optional[str], Optional[str]]: ...
```

Returns

validate\_and\_sanitize() → SanitizationResultis\_safe（安全判定）, marked\_content（マーキング済み）, metadata

validate\_multiple() → Tuple\[bool, List\[str], List\[Dict\[str, Any]]]全体の安全判定, マーキング済みコンテンツリスト, メタデータリスト

mark\_content() → strソース情報を付与したマーキング済みコンテンツ

unmark\_content() → Tuple\[str, Optional\[str], Optional\[str]]オリジナルコンテンツ, source\_type, source\_url

### ファクトリ関数

config JSON からプロバイダーを自動判別し、適切な SecurityClient を生成するモジュールレベル関数。

```python
def detect_provider(config: Dict[str, Any]) -> SecurityProvider
```

config JSON からセキュリティプロバイダー（Azure / AWS / GCP）を自動判別。判別できない場合は `SecurityConfigError`。

```python
def create_security_client(
  config: Dict[str, Any],
  pii_config: Optional[Dict[str, Any]]= None
) -> SecurityClientBase
```

config JSON から対応する SecurityClient を生成。`pii_config` を渡すと content\_safety と pii\_language の設定を統合（Azure）。

```python
def create_content_safety_client(config: Dict[str, Any]) -> SecurityClientBase
```

Content Moderation / Prompt Shield 用のショートカット。`create_security_client(config)` に委譲。

```python
def create_pii_client(config: Dict[str, Any]) -> SecurityClientBase
```

PII 検出／マスク用のショートカット。Azure では Language Service エンドポイントとして設定。

Related

[RAG モジュール](#-rag-モジュール) —

<!-- -->

Embedding 投入前のコンテンツ検証パイプライン\
[ストレージモジュール](#-ストレージモジュール) —

<!-- -->

ファイルアップロード前の PII スクリーニング\
[イベントモジュール](#-イベントモジュール) —

<!-- -->

モデレーション結果をイベントとして配信

---

## common 共通モジュール

共通ユーティリティ。SQL インジェクション防止・シークレットマスク・非同期コンテキストマネージャーミックスイン。

### SecretMasker

シークレット値（パスワード・トークン等）をキー名に基づいてマスクするユーティリティ。

```python
class SecretMasker:
  def __init__(
      secret_keys: Optional[Set[str]]= None,
      mask_string: str = "***",
      case_sensitive: bool = False,
  ): ...

  def mask_value(key: str, value: Any) -> Any: ...
  def mask_dict(data: Dict[str, Any]) -> Dict[str, Any]: ...
```

Returns

mask\_value() → Anykey がシークレットキーなら mask\_string、それ以外は元の値を返す

mask\_dict() → Dict\[str, Any]dict を再帰走査し、シークレット値をマスクした新しい dict を返す

```python
def mask_secret(value: str, visible_chars: int = 0, mask_string: str = "***") -> str
```

単一文字列をマスクするショートカット関数。

```python
from agenticstar_platform.common import SecretMasker, mask_secret

masker = SecretMasker()
safe = masker.mask_dict({
    "username": "alice",
    "password": "p@ssw0rd",
    "api_key": "sk-12345",
})
# → {"username": "alice", "password": "***", "api_key": "***"}

mask_secret("my-secret-api-key-12345")                   # → "***"
mask_secret("my-secret-api-key-12345", visible_chars=4)  # → "my-s***"
```

### validate\_identifier

テーブル名・カラム名など単一の識別子を検証するユーティリティ。SQL インジェクション対策として、英数字とアンダースコアのみを許可する。`DataAccess` 内部で自動的に使用されるが、カスタムクエリを構築する際にも直接使用できる。

```python
def validate_identifier(identifier: str, identifier_type: str = "identifier") -> str
```

Returns

str検証を通過した識別子をそのまま返す。不正な場合は IdentifierValidationError を送出

`identifier_type` はエラーメッセージ用の識別子種別ラベルで、既定値は `"identifier"`。

### validate\_identifiers

識別子（カラム名・テーブル名等）のリストを一括で検証するユーティリティ。SQL インジェクション対策として、英数字とアンダースコアのみを許可する。

```python
def validate_identifiers(identifiers: List[str], identifier_type: str = "column") -> List[str]
```

Returns

List\[str]検証を通過した識別子のリストを入力順で返す。不正な識別子が含まれる場合は IdentifierValidationError を送出

`identifier_type` は検証対象の種別を表し、既定値は `"column"`。単数版の `validate_identifier`（既定値 `"identifier"`）とは既定値が異なる点に注意。

### validate\_order\_by

ORDER BY 句を検証するユーティリティ。`column_name ASC|DESC` 形式のみ許可する。

```python
def validate_order_by(order_by: str) -> str
```

Returns

str検証を通過した ORDER BY 句をそのまま返す。不正な場合は IdentifierValidationError を送出

```python
from agenticstar_platform.common import validate_identifier, validate_order_by

table = validate_identifier("users")        # OK: "users"
validate_identifier("users; DROP TABLE --")  # → IdentifierValidationError

order = validate_order_by("created_at DESC") # OK: "created_at DESC"
```

### AsyncContextManagerMixin

非同期コンテキストマネージャーのミックスインクラス。SDK 内部で `async with` パターンを統一的に実装するために使用。

```python
class AsyncContextManagerMixin:
  async def __aenter__(self) -> Self: ...
  async def __aexit__(...) -> None: ...
  @abstractmethod
  async def close(self) -> None: ...
```

### IdentifierValidationError

`validate_identifier` / `validate_order_by` が不正な識別子に対して送出する例外。`Exception` を直接継承する。

```python
class IdentifierValidationError(Exception): ...
```

---

## エラーハンドリング

全モジュールで共通の例外処理パターンを使用します。各モジュールはモジュール固有の基底例外クラスを持ち、サブクラスで具体的なエラーを区別します。

### 例外階層一覧

```text
Exception
├── IdentifierValidationError
├── VectorStoreError
│   ├── VectorStoreConfigError
│   │   └── QdrantConfigError
│   └── VectorStoreConnectionError
├── EmbeddingError
│   ├── RateLimitExceededError
│   └── EmbeddingDimensionError
├── StorageError
│   ├── StorageConfigError
│   ├── StorageConnectionError
│   └── StorageOperationError
├── AuthError
│   ├── AuthConfigError
│   └── AuthAPIError
│       ├── AuthUnauthorizedError (401)
│       ├── AuthNotFoundError (404)
│       └── AuthRateLimitError (429)
├── SemanticMemoryError
│   └── SemanticMemoryConfigError
└── SecurityError
  ├── SecurityConfigError
  └── SecurityAPIError
```

### 共通パターン

全モジュールで「具体的な例外 → 基底例外 → Exception」の順にキャッチします。

```python
from agenticstar_platform.storage import StorageError, StorageOperationError
from agenticstar_platform.auth import AuthError, AuthAPIError
from agenticstar_platform.security import SecurityError, SecurityAPIError

async def process_document(doc_id: str):
    try:
        # 1. DB からドキュメント取得
        doc = await db.fetch_one(
            "SELECT * FROM documents WHERE id = $1", (doc_id,)
        )

        # 2. セキュリティチェック
        moderation = await security.check_content_moderation(doc["content"])
        if moderation.blocked:
            raise ValueError("Content policy violation")

        # 3. Embedding 生成 + ベクトル DB に保存
        await qdrant.upsert(
            id=doc_id,
            content=doc["content"],
            metadata={"source": "documents"}
        )

        # 4. 処理結果をストレージに保存
        await storage.upload_bytes(
            data=doc["content"].encode(),
            object_name=f"processed/{doc_id}.txt"
        )

    except StorageOperationError as e:
        # ストレージ操作エラー → error_code で判断
        logger.error(f"Storage op failed: {e.error_code}")
    except AuthAPIError as e:
        # 認証 API エラー → status_code で判断
        logger.error(f"Auth failed: {e.status_code}")
    except (StorageError, AuthError, SecurityError) as e:
        # モジュール基底例外でフォールバック
        logger.error(f"Module error: {type(e).__name__}: {e}")
    except Exception as e:
        # 予期しないエラー
        logger.critical(f"Unexpected: {e}")
        raise
```

---

## metering 計測モジュール

v0.5.15+ — LLM の**利用量・コスト**を計測する純インフラ。LLM 応答/トークンからコストを算出し、**1 呼び出し = 1 行**で `llm_usage_ledger` に記録、日次集計（`llm_usage_daily`）とコスト可視化クエリを提供します。エージェントロジック非依存で、自社ホスト・マーケットプレイス BYO で同一に使えます（プロセス内記録のためヘッダ伝播は不要）。

- **コスト算出はプラガブル**: 既定は **litellm**（`completion_cost` / `cost_per_token`）を使用し、long-context / プロンプトキャッシュ / tier 価格を反映。litellm 非導入時はトークンのみ記録（`cost_usd = NULL`）。`cost_fn=` で任意エンジンに差し替え可。
- **DB**: `execute_query(query, params) -> {success, data, error}` を持つハンドル（SDK の `DataAccess` / `PostgreSQLManager`）をそのまま渡せます。

### UsageMeter

```python
from agenticstar_platform.metering import UsageMeter

meter = UsageMeter(db=data_access)                  # cost_fn=, currency= は任意
await meter.ensure_schema()                          # 台帳/集計表/集計関数を冪等作成し、既存の台帳には新しい列を追加（migration で反映済みなら不要）

# 1 LLM 呼び出しを記録（コストは自動算出・記録失敗は握り潰し安全）
await meter.record(
    model="gpt-5.5", response=resp, endpoint="chat/completions",
    labels={"execution_id": eid, "message_id": mid, "conversation_id": cid, "user_id": uid},
)

# 呼び出しをラップして自動記録
resp = await meter.track(model="gpt-5.5", labels=ids)(litellm.acompletion)(**params)

# コストのみ（記録なし）
usd = UsageMeter.cost_usd("gpt-5.5", response=resp)

# 日次集計 + コスト可視化（ダッシュボード/請求）
await meter.rollup_recent()
rows = await meter.daily_cost(by="model", since_days=30)   # by = "model" | "user" | "agent" | "day"
```

### メソッド

| メソッド                                                                                                                                                                                                          | 説明                                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UsageMeter(db, *, cost_fn=None, currency="USD")`                                                                                                                                                             | DB ハンドルとコスト関数で初期化                                                                                                                                                                                    |
| `UsageMeter.cost_usd(model, response=None, usage=None, cost_fn=None)`                                                                                                                                         | コスト(USD)のみ算出（static）                                                                                                                                                                                 |
| `await ensure_schema(*, with_rollup=True)`                                                                                                                                                                    | `llm_usage_ledger` / `llm_usage_daily` / `rollup_llm_usage_daily()` を冪等作成                                                                                                                            |
| `await record(*, model, response=None, usage=None, endpoint=None, agent_type=None, level=None, labels=None, stream=False, success=True, request_id=None, cost_usd=None, missing_reason=None, fail_safe=True)` | 1 行記録し算出コストを返す（`missing_reason` は usage 欠落時の理由。usage 取得行は NULL 保存。v0.5.21+）                                                                                                                          |
| `track(*, model=None, endpoint=None, labels=None, ...)`                                                                                                                                                       | async LLM 呼び出しをラップして自動記録するデコレータ                                                                                                                                                                      |
| `await rollup_recent()`                                                                                                                                                                                       | 前日・当日を集計表へ反映（冪等）                                                                                                                                                                                     |
| `await daily_cost(*, by="model", since_days=30)`                                                                                                                                                              | 集計表からコスト内訳を取得                                                                                                                                                                                        |
| `default_cost_fn(model, response=None, usage=None)`                                                                                                                                                           | モジュール関数。`UsageMeter` の既定コスト算出関数（`cost_fn` 未指定時に使用）。litellm 経由でコスト(USD)を算出、算出不可時は None                                                                                                                |
| `extract_usage(usage)`                                                                                                                                                                                        | モジュール関数。usage オブジェクト/dict から `{"input_tokens", "output_tokens", "total_tokens"}` を抽出（取得不可時は None）。prompt cache の内訳が取れたときは `cache_read_tokens` / `cache_creation_tokens` も返す（v3.0.0+。取れなければキー自体を返さない） |
| `round_cost_usd(v)`                                                                                                                                                                                           | モジュール関数。コスト(USD) を `Decimal`（小数点以下8桁）へ整形するユーティリティ                                                                                                                                                    |

`llm_usage_ledger` の既定 DDL は可搬（任意の PostgreSQL）。各行は `usage_status`（`present`/`missing`）と `missing_reason`（欠落理由・v0.5.21+）を持ち、`cost_usd IS NULL`（価格未マップ）・`usage_status='missing'`・true-zero を区別できます。v3.0.0+ は prompt cache の読出し / 書込みを `cache_read_tokens` / `cache_creation_tokens`（どちらも NULL 可）に分けて記録します（`cached_tokens` は従来どおり）。読出しと書込みは単価が大きく違うため、合算では「書いているのに読めていない」劣化を検知できません。明示した内訳値は 0 を含めて優先され、未指定なら従来の `cached_tokens`（読出し）と `cache_creation_input_tokens`（書込み）を使います。`cached_tokens` に合算値を渡している場合は内訳を明示してください。日次集計表と集計関数は変わらず、内訳は台帳から集計します。v3.0.0 の `record()` はこの 2 列を前提に書き込むため、**書き込みを始める前に** `ensure_schema()` または migration（同じ `ADD COLUMN IF NOT EXISTS`）で列を追加し、列の実在と、更新後に台帳へ行が保存されていることを確認してください（DB 側の失敗が例外として通知されない場合があります）。大規模では月次パーティション化（pg\_partman 等）を推奨します。

---

## audit 行為監査モジュール

v0.5.31+ — エージェント実行系の**行為イベント**（承認/却下、ツール認可、ポリシー違反、キルスイッチ、外部エージェント呼び出し等）を append-only 台帳（`agent_action_audit` / `llm_gateway_action_audit`）へ記録する純インフラ。利用量・コスト（metering）とは**書き込み保証で区別**された証跡です。追加依存なし（標準ライブラリのみ・core に同梱）。

- **本文は渡さない（使用契約）**: プロンプト・ツール引数等の生値は台帳へ渡さず、`canonical_digest()`（SHA-256）で片方向化して `payload_digest` へ。**SDK は機密の自動検出・redaction は行いません**。フィールド上限（`reason` 300 字截断 / `payload_digest` は 64 桁の小文字 hex 以外を破棄 / `metadata` はキー順正規化 JSON が 2KB 超で本体破棄 = digest + サイズのみ、常に deep-copy 正規化）は誤混入時の**被害量を制限する**ガードであり、それ自体が漏洩防止ではありません。
- **書き込みモードは 3 種**: `record()` = プロセス生存中 at-least-once（bounded retry → 失敗時は `action_audit_spill` マーカー付きログ行へサニタイズ済み row を JSON 出力）／ `record_sync()` = **audit-before-act**（DB へ書けなければ `ActionAuditWriteError` — 監査に書けない承認は成立させない）／ `record_nowait()` = ホットパス用 fire-and-forget（strong ref 保持・backlog 上限 512 超過は即 spill・開始前 cancel も spill。**プロセス即死時は失われうる best-effort**）。
- **決定イベントは `actor_ref` 必須**: `approval.*` / `gate.resolved` / `content.deleted` / `forensic.*` / `policy.changed` / `item.quarantine_released` / `workitem.*` は `actor_ref` が無いと同期 `ValueError`（v1.0.0+。それ以前は `approval.*` のみ）。
- **DB**: `execute_query(query, params) -> {success, data, error}` を持つハンドル（SDK の `DataAccess` / `PostgreSQLManager`）。

### ActionAudit / GatewayActionAudit

```python
from agenticstar_platform.audit import ActionAudit, GatewayActionAudit, canonical_digest

audit = ActionAudit(db=data_access, source="my-agent", system_version=image_tag)  # source = 書き込むコンポーネントの名前
await audit.ensure_schema()                       # 初期化時に owner ロールで 1 回: 台帳/索引を冪等作成し、旧い表には新しい列を追加

# ホットパス（ツール認可等）: fire-and-forget
audit.record_nowait(
    event_type="tool.access", actor_type="agent", decision="deny",
    resource="bash", action="execute", reason="blocked_command",
    conversation_id=cid, execution_id=eid,
    payload_digest=canonical_digest({"command": cmd}),
)

# 承認（audit-before-act）: 送出されたら行為を中断する
await audit.record_sync(
    event_type="approval.granted", actor_type="human", actor_ref=approver_id,
    decision="granted", resource=tool_name, conversation_id=cid,
)

await audit.aclose()                              # 終了時: pending を drain（timeout 分は cancel + spill）

gw = GatewayActionAudit(db=gateway_da)            # LLM Gateway ポリシー判定用（virtual key 識別）
await gw.record(event_type="policy.mcp_stripped", decision="stripped",
                virtual_key_id=vk, request_id=rid)
```

### メソッド

| メソッド                                                                     | 説明                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ActionAudit(db, *, source, system_version=None, agent_ref=None)`        | `agent_action_audit` writer。`source`（書き込むコンポーネントの名前。任意の文字列で、行の `source` 列に入る）必須。`agent_ref` は `actor_kind='agent'` の行に `actor_ref` が無いとき自動で入れる識別子（省略時 `agent:<source>`。v1.0.0+）                                                                                                                                                                              |
| `GatewayActionAudit(db, *, system_version=None)`                         | `llm_gateway_action_audit` writer（virtual key 識別）                                                                                                                                                                                                                                                                                                            |
| `await ensure_schema()`                                                  | 台帳/索引を冪等作成 + `REVOKE UPDATE/DELETE`（best-effort。本番の append-only 強制は insert-only ロール分離を推奨）。`ActionAudit` は旧い SDK が作った表に v1.0.0 の 4 列を追加します（`ACTION_AUDIT_UPGRADE_DDL`）。CREATE / ALTER には表の owner 権限が要るため、環境の初期化時に owner ロールで 1 回呼びます（実行時の writer は INSERT 権限だけでよい）。migration で表を管理している環境では呼ばないでください。`source_event_id` の重複行が既にあると UNIQUE index を作れません（先に重複を解消） |
| `await record(**fields)`                                                 | at-least-once 記録。DB へ書けたら `True`、spill 退避のみなら `False`（validation の `ValueError` は同期送出、cancel は伝播）                                                                                                                                                                                                                                                            |
| `await record_sync(**fields)`                                            | audit-before-act 記録。DB 書き込み失敗時 `ActionAuditWriteError`（validation は `ValueError`）                                                                                                                                                                                                                                                                            |
| `record_nowait(**fields)`                                                | fire-and-forget（`asyncio.Task` を返す。close 中/backlog 超過/loop 無しは即 spill で `None`）                                                                                                                                                                                                                                                                              |
| `await aclose(timeout=10.0)`                                             | pending を drain。timeout 分は cancel され行は spill、以後の新規は即 spill                                                                                                                                                                                                                                                                                                   |
| `canonical_digest(payload)`                                              | モジュール関数。任意 payload の SHA-256 digest（キー順正規化 JSON・非 JSON 型は文字列化 fallback。`None` は `None`）                                                                                                                                                                                                                                                                      |
| `reference_keys(**refs)`                                                 | モジュール関数。`metadata` に入れる相関キー（`project_id` / `run_id` / `step_id` / `item_id` / `tool_call_id` / `root_execution_id` 等）の辞書を作る。`None` と空文字は落とし、値は文字列化（v1.0.0+）                                                                                                                                                                                                  |
| `actor_kind_from_type(actor_type)`                                       | モジュール関数。`actor_type` から `actor_kind` を決める（`agent` / `assistant` / `worker` → `agent`、`human` / `user` / `approver` → `human`、`system` / `scheduler` / `policy` → `system`、それ以外 → `unknown`。v1.0.0+）                                                                                                                                                          |
| `KNOWN_EVENT_TYPES`                                                      | 定数。既知の `event_type` とその意味の辞書（説明用。writer は強制しない。v1.0.0+）                                                                                                                                                                                                                                                                                                      |
| `ACTOR_KINDS`                                                            | 定数。`actor_kind` の閉語彙 `("agent", "human", "system", "human_external", "unknown")`（v1.0.0+）                                                                                                                                                                                                                                                                    |
| `ACTION_AUDIT_DDL` / `ACTION_AUDIT_INDEXES` / `ACTION_AUDIT_UPGRADE_DDL` | 定数。`ensure_schema()` が使う DDL（migration を持たない環境向け。v1.0.0+）                                                                                                                                                                                                                                                                                                    |

主なフィールド: `event_type` ／ `actor_type`（推奨: `human` | `agent` | `system`。実装は非空のみ検証）／ `actor_kind`（閉語彙 `ACTOR_KINDS`。省略時は `actor_type` から決まり、閉語彙外は `ValueError`。v1.0.0+）／ `actor_ref`（上記の決定イベントは必須）／ `on_behalf_of_ref` ／ `decision` ／ `reason` ／ `resource` ／ `action` ／ `policy_id` / `policy_version` ／ 相関キー（`execution_id` / `conversation_id` / `message_id` / `request_id`。v1.0.0+ は `project_id`（UUID 文字列）/ `root_execution_id` も）／ `source_event_id`（重複除去キー。`^[A-Za-z0-9_.:@+-]{1,160}$`。v1.0.0+）／ `payload_digest` ／ `metadata`。各行には内容の完全性検証用に `row_hash`（SHA-256）が自動付与されます。

**v1.0.0 で追加された列**: `actor_kind` / `project_id` / `root_execution_id` / `source_event_id` はどれも省略でき、従来の呼び出し形（`actor_type` だけ）はそのまま動きます。これらの列が無い旧い表に書き込むと、writer は列の不存在を 1 回検出して従来の列だけの INSERT に切り替え、監査行を失いません。切り替えている間は新しい 4 列の値は保存されず、`row_hash` は実際に保存した列から計算されます（`ensure_schema()` で列を足すか、列を追加した後にプロセスを再起動すると新しい INSERT に戻ります）。`source_event_id` の UNIQUE index がある表で同じ値を書くと、`record()` は `False`（spill 退避）を返し、`record_sync()` は例外を送出します。

**`metadata` の数値と `row_hash`**: `metadata` の数値のうち、絶対値 2^53 未満の整数以外（小数・それ以上の整数・NaN / Inf）は文字列として保存されます（v1.0.0+）。どの言語で計算しても `row_hash` が一致するようにするためです。SDK を使わずに同じ表へ直接書き込む場合は、パッケージ同梱の `agenticstar_platform/audit/ROW_HASH_SPEC.md`（正規化の規則）と `row_hash_fixture.json`（検証用 fixture）に合わせてください。循環参照などで JSON にできない `metadata` は `{"unserializable": true}` に置き換えられ、行そのものは保存されます。

### GuardrailAlertWriter / GuardrailAlertAggregates（v0.5.32+）

Admin トリアージ用 `guardrail_alerts`（**非権威的**運用ビュー。権威は行為監査台帳）と、非連結日次集計 `guardrail_alert_daily_aggregates` の producer writer です。配送保証は上記 writer と同一（bounded FAF + retry → spill → `aclose()` drain）。

```python
from agenticstar_platform.audit import GuardrailAlertWriter, GuardrailAlertAggregates

alerts = GuardrailAlertWriter(db=data_access, system_version=image_tag)
await alerts.ensure_schema()                       # 行 + 集計テーブル + index + REVOKE
alerts.record_nowait(                              # confirmed block のみ。冪等 (event_key v2)
    source_surface="llm_gateway", policy_outcome="blocked",
    policy_source="llm_gateway_guardrails_settings", decision_point="input",
    request_id=rid, detection_types=["harmful_content"],
    moderation_categories={"Violence": 4},         # カテゴリ別**実測** severity (2/4/6)
)
agg = GuardrailAlertAggregates(db=data_access)
agg.record_nowait(source_surface="llm_gateway", category="SelfHarm", severity=6)
```

設計上の強制事項: 行スキーマに利用者 ID 列なし（人物特定不可）／ SelfHarm を行に載せると同期 `ValueError`（表記ゆれ・ネスト・str-Enum `.value` も検出。SelfHarm は集計のみ、集計 writer は相関 ID 引数を持たない）／ 行の `policy_outcome` は `blocked` のみ／ replay は `ON CONFLICT (event_key) DO NOTHING` で Admin の lifecycle 変更を巻き戻さない。権限は行 = producer INSERT のみ、集計 = INSERT + UPDATE(count) + SELECT(count)。集計値は at-least-once 由来の二重加算があり得る近似値（課金・規制報告に使用しない）。

v0.5.40+: `source_surface` に `agent_worker`（会話 Pod worker 面）を追加。行に `policy_category`（攻撃方式の閉語彙: `prompt_injection` / `system_prompt_extraction` / `implementation_access` / `credential_request` / `file_system_access` / `security_bypass` / `custom_policy` / `unclassified`）を追加 — 閉語彙外は同期 `ValueError`（自由文・rule 名の流入防止）で、SelfHarm 検査は `prompt_shield_origin` / `policy_category` にも適用されます。

---

## workflow ワークフローモジュール

v1.0.1+ — プロジェクトのワークフローの工程で 1 回実行されるエージェント用の runner（protocol `mp-workflow/1`。マーケットプレイス版 3.2.0 以降。実行結果の形式が v3.0.1 で変わったため、マーケットプレイス版 3.2.0 で使うには v3.0.1 以降が必要）。チャット用の `run_marketplace_agent` とは別の入口です。core に同梱され、データベースのドライバは要りません（契約で宣言した YAML ファイルは、core 依存の `pyyaml` で厳格に読んで検証します）。書き方は [ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md) を参照してください。

- **注入される環境変数だけで動く**: `ASTER_RUNTIME_PROTOCOL` / `ASTER_RUNTIME_BASE_URL` / `ASTER_RUNTIME_TOKEN` / `EXECUTION_ID`。DB 設定などへの fallback はしません。
- **親子プロセス**: runner（親）が入力の取得と展開・開始の記録・成果物の回収と保存・結果の保存を担い、エージェントの関数を子プロセスで実行します。
- **終了コード**: 0 = 結果を保存した（既に終端していた場合と、エージェントの例外・エントリポイントを import できなかった場合の `failed/agent_error` を含む）、取消の後にプラットフォームが保存を断った場合（v3.0.13+）も 0、2 = 保存できなかった、3 = 環境変数または実行の文脈が不正。そのほかの障害は例外のまま 0 以外で終わることがあります（保証しません）。

### 入口

```python
def run(entrypoint: str, *, env: Optional[Mapping[str, str]]= None,
      workspace: Optional[str]= None, exit_process: bool = True,
      stop_on_sigterm: Optional[bool]= None) -> WorkflowResult: ...  # stop_on_sigterm: v3.0.13+

async def arun(entrypoint: str, *, env: Optional[Mapping[str, str]]= None,
             workspace: Optional[str]= None,
             transport: Optional[httpx.AsyncBaseTransport] = None, **kwargs) -> WorkflowResult: ...

def validate_env(env: Mapping[str, str]) -> Dict[str, str]: ...
```

| 関数 / 定数                                                                                 | 説明                                                                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run(entrypoint, *, env=None, workspace=None, exit_process=True, stop_on_sigterm=None)` | イメージの起動コマンドから呼ぶ入口。`entrypoint` は `"module.path:function"`。`exit_process=True`（既定）なら終了コードでプロセスを終え、SIGTERM（Pod の停止）を受けると、子プロセスを止めて回収する協調停止に切り替えます。`exit_process=False` なら `WorkflowResult` を返し、設定の誤りは `WorkflowConfigError` を送出します。`stop_on_sigterm`（v3.0.13+）は SIGTERM の協調停止を `exit_process` と別に指定します（既定は `exit_process` と同じ）。v3.0.13 から、runner の token をエージェントのプロセスから `/proc` で読めなくする処理と、ログの出力先（未設定のときだけ標準エラー）も入れます |
| `await arun(entrypoint, ...)`                                                           | 非同期版。シグナルハンドラー・token の保護・ログの出力先は入れません（`stop_on_sigterm=True` / `protect_token=True` で指定できます）。`transport` には runtime API への通信に使う httpx の transport を渡せます（試験では `FakeRuntime.transport`。[FakeRuntime](#fakeruntime%E8%A9%A6%E9%A8%93%E7%94%A8)）                                                                                                                                                                        |
| `validate_env(env)`                                                                     | 必須の環境変数を検証します（欠落・形の誤りは `WorkflowConfigError`）                                                                                                                                                                                                                                                                                                                                                                       |
| `PROTOCOL` / `REQUIRED_ENV`                                                             | `"mp-workflow/1"` / 必須の環境変数名                                                                                                                                                                                                                                                                                                                                                                                        |

`WorkflowResult` は `execution_id` / `outcome` / `outcome_reason_code` / `had_mutating_success` / `completion_saved` / `already_terminal` / `exit_code` / `artifacts` を持ちます。

### WorkflowContext

エントリポイント（`async def run(context)`）が受け取る、読み取り専用の実行文脈です。

```python
class WorkflowContext:
  execution_id: str
  project_id: str
  run_id: str
  agent_id: str
  marketplace_agent_id: str
  root_execution_id: str
  entry_ref: str
  operation_key: str
  attempt: int
  effect_mode: str                       # read_only | idempotent_write | non_idempotent_write
  parameters: Mapping[str, Any]# 読み取り専用
  connections: Mapping[str, str]# 接続 slot 名 → 接続先 ID
  input_dir: Path# /workspace/input（読み取り専用）
  work_dir: Path# /workspace/work
  output_dir: Path# /workspace/output
  manifest: Mapping[str, Any]
  deadlines: Mapping[str, Optional[str]]
  gate_decision: Optional[Mapping[str, Optional[str]]]# v3.0.9+
  start_input: Optional[Mapping[str, Any]]# v3.1.2+
  audit: AuditApi

  def deadline_remaining() -> Optional[float]: ...
  async def is_cancel_requested(*, max_age: float = 5.0) -> bool: ...
  async def ensure_can_act() -> None: ...
  async def skip(reason: str) -> None: ...
  async def policy_unavailable() -> None: ...
  async def incomplete(reason: str, comment: Optional[str]= None) -> None: ...  # v3.2.1+
  async def log(message: str) -> None: ...
  async def connection_token(slot: str, *, min_ttl: float = 300.0) -> Mapping[str, Any]: ...  # v3.0.5+
```

| メソッド                                             | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deadline_remaining()`                           | エージェントが止められるまでの残り秒数（不明なら `None`）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `await is_cancel_requested(max_age=5.0)`         | 取消・期限・停止を知っていれば `True`。前回の確認から `max_age` 秒以内なら runner に問い合わせず、既に知っている停止だけで答えます                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `await ensure_can_act()`                         | 外部操作の前に呼びます。取消・期限の後は `WorkflowError`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `await skip(reason)`                             | 処理対象が無い工程を skip します。`reason` は `no_target` / `not_applicable` / `nothing_to_do`（それ以外は `ValueError`）。記録するだけで処理は止まらないので、呼んだら関数から戻ります                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `await policy_unavailable()`                     | 外部操作の**前**に操作の可否を確かめられなかったことを伝えます（`skipped/policy_unavailable`）。記録するだけなので、呼んだら関数から戻ります。書き込みを始めた後に呼ぶと `failed/skip_after_effect` になります                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `await incomplete(reason, comment=None)`         | やり直しても同じ結果になる理由（指示が無い・設定の誤りなど）で、工程を「完遂できなかった」で終えます（`incomplete/<reason>`。プラットフォームは自動で再実行せず、人の確認に回します）。`reason` は `report_completion()` と同じ規則の理由コード（前後の空白を除き、小文字にし、`-` と空白を `_` にした値が `^[a-z][a-z0-9_]{0,31}$` に合わなければ `incomplete` にして警告）。`comment` は確認する人に向けた説明で、終了時の報告に載ります（2,048 文字（UTF-16 の単位）まで。文字列でない値は載せずに警告）。宣言は 1 回で、2 回目は記録されません。記録するだけなので、呼んだら関数から戻ります。宣言の後に例外で抜けても `incomplete` です（v3.2.1+。[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E5%AE%8C%E9%81%82%E3%81%A7%E3%81%8D%E3%81%AA%E3%81%8B%E3%81%A3%E3%81%9F%E3%81%A8%E3%81%8D)） |
| `await log(message)`                             | runner のログ（Pod の標準エラー）に書きます（2000 文字まで）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `await connection_token(slot, *, min_ttl=300.0)` | 接続先の access token を `{access_token, token_type, expires_at}`（読み取り専用）で返します。期限まで `min_ttl` 秒を切ったら取り直し、期限が分からない token は 600 秒ごとに取り直します。束ねていない slot・失効した接続・取消や期限の後は `WorkflowError`（v3.0.5+）                                                                                                                                                                                                                                                                                                                                                                                                                          |

`gate_decision` は、確認依頼の決定を受けて起動した実行（差し戻した後の戻り先の工程の再実行・進めた後に続く工程）でだけ `{gate_id, decision, decided_by, note, decided_at}`（読み取り専用）になり、それ以外の実行では `None` です。`decision` は `send_back` / `proceed`、`decided_by` は `human` / `system`、`note` は担当者が書いた理由・コメント（無いとき・自動の決定では `None`）です。開始の記録（`manifest`）には `gate_id` / `decision` / `decided_by` だけが入ります（v3.0.9+。[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E7%A2%BA%E8%AA%8D%E3%81%AE%E6%B1%BA%E5%AE%9A%E3%82%92%E5%8F%97%E3%81%91%E3%81%9F%E5%AE%9F%E8%A1%8C)）。

`start_input` は、外から依頼つきで始めた run の最初の工程（分岐の後はレーンごとの最初の工程）でだけ `{kind, payload, subject, text, external}`（読み取り専用）になり、それ以外では `None` です。`kind` が文字列でない・`external` が真偽値でないときも全体が `None`、`subject` / `text` が文字列でないときはその欄が `None` です。`kind` は `api` / `mail`、`payload` は `api` のときの呼び出し元の依頼、`subject` / `text` は `mail` のときの件名と本文です。外から来た値なので、データとして扱ってください。開始の記録（`manifest`）には入りません（v3.1.2+。[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E5%A4%96%E3%81%8B%E3%82%89%E5%A7%8B%E3%82%81%E3%81%9F-run-%E3%81%AE%E4%BE%9D%E9%A0%BC)）。

### AuditApi

`context.audit` で使う監査の送信窓口です。

```python
class AuditApi:
  async def tool_invoked(tool: str, *, effect_kind: str, action_ref: Optional[str]= None,
                         target: Optional[str]= None, **extra) -> str: ...
  async def tool_effect(invoked_event_id: str, *, status: str = "ok", count: Optional[int]= None,
                        action_ref: Optional[str]= None, **extra) -> str: ...
  async def tool_denied(tool: str, *, reason: str, reason_code: str = "tool_denied",
                        effect_kind: str = "write", **extra) -> str: ...
```

| メソッド                                                                 | 説明                                                                                                                                                                                                                       |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `await tool_invoked(tool, *, effect_kind, ...)`                      | 外部操作の**前**に呼びます。記録が保存されてから event ID を返し、保存できなければ `AuditNotPersisted`（その操作に進まない）。`effect_kind` は `read` / `list` / `query` / `fetch` または `write` / `create` / `update` / `delete` / `send` / `mutate`（それ以外は `ValueError`） |
| `await tool_effect(invoked_event_id, *, status="ok", ...)`           | 操作の結果を `tool_invoked` の戻り値に対応付けます。`status` は `ok` / `failed` / `unknown`（結果が分からなければ `unknown` = 効果不明）                                                                                                                    |
| `await tool_denied(tool, *, reason, reason_code="tool_denied", ...)` | 操作を実行しなかったことを記録します。結果は `denied` になります（判定の順で上にある取消・期限などが優先）                                                                                                                                                               |

`**extra` で渡した値のうち、metadata に残るのは文字列・整数・有限の小数・真偽値だけです（それ以外は SDK が捨て、v3.0.13 からは捨てたキーの名前を警告に出します）。本文・token・引数の値は渡さないでください。

### 実行結果

| 名前                                                      | 説明                                                                                                      |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `OUTCOMES`                                              | `("completed", "incomplete", "failed", "timeout", "stopped", "denied", "skipped")`                      |
| `ENVELOPE_VERSION`                                      | 保存する結果（completion envelope）の形式の版。現在は `2`（v3.0.1+）                                                       |
| `EffectTally` / `decide_outcome()` / `build_envelope()` | runner が結果を組み立てる低レベル API。エージェントから呼ぶ必要はありません（`build_envelope()` は v3.2.1 から `completion_report` を受け取ります） |

v3.2.1+ — `incomplete` と `failed/agent_error` の結果には、終了時の報告 `completion_report`（`{"completed": false, "reason_code": ..., "comment": ...}`）が入ります。`incomplete` では `reason_code` は宣言の理由、`comment` はエージェントの説明（渡さなかったときは欄なし）です。`failed/agent_error` では `reason_code` は `agent_error`、`comment` は標準エラーに出るのと同じ原因の連鎖の要約（クラス名・SDK の `error_code`・HTTP の status・接続先のホスト名だけ。2,048 文字まで）です。ほかの終わり方では入りません（[ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E7%B5%82%E4%BA%86%E6%99%82%E3%81%AE%E5%A0%B1%E5%91%8A)）。

結果の `counts` には `tool_calls` / `read_calls` / `mutating_invoked` / `mutating_success` / `mutating_failed` / `mutating_unresolved` / `orphan_effects` / `effect_conflicts` / `denied` / `audit_persist_failures` が入ります（`tool_calls` / `read_calls` は v3.0.1 で `tools_invoked` / `reads` から改名）。outcome と理由コードの一覧は [ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E5%AE%9F%E8%A1%8C%E7%B5%90%E6%9E%9Coutcome) を参照してください。

### 例外

```text
WorkflowError (RuntimeError)
├── WorkflowConfigError      # 注入された環境変数の欠落・不一致、別の実行・プロトコルの文脈
├── RuntimeApiError          # runtime API の応答が契約外（status / code / message）
├── ExecutionTerminal        # 実行は既に終端している（エージェントを再実行する理由にしない）
├── AuditNotPersisted        # 監査の記録を保存できなかった（取消・期限の後を含む。その操作に進まない）
├── InputIntegrityError      # 入力ファイルの digest / size / path が一致しない
└── OutputCollectionError    # 成果物の回収で契約違反（path / size / regular file / symlink）
```

`connection_token()` / `ensure_can_act()` などが取消・期限の後に送出するのも `WorkflowError` です。v3.0.6 からは、runner が制御用の接続を閉じた後の呼び出しも `WorkflowError`（`runner closed the control channel`）になります。

### FakeRuntime（試験用）

v3.2.1+ — `agenticstar_platform.workflow.testing` の `FakeRuntime` は、プラットフォームの runtime API にメモリの中で応える偽のランタイムです。プラットフォーム無しでワークフローのエージェントを 1 工程通して試せます。`import agenticstar_platform.workflow` では読み込まれません。今の runtime API の振る舞いを写したもので、パラメータを `parameters_schema` で検査せず、契約も検証しません（プラットフォームは実行の前に検査します）。使い方は [ワークフローガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/develop/guide/workflow-guide.md#%E3%83%97%E3%83%A9%E3%83%83%E3%83%88%E3%83%95%E3%82%A9%E3%83%BC%E3%83%A0%E7%84%A1%E3%81%97%E3%81%A7-1-%E5%B7%A5%E7%A8%8B%E3%82%92%E8%A9%A6%E3%81%99) を参照してください。

```python
from agenticstar_platform.workflow.testing import FakeRuntime

class FakeRuntime:
  def __init__(*, contract: Optional[Mapping[str, Any]]= None,
               parameters: Optional[Mapping[str, Any]]= None,
               inputs: Optional[Mapping[str, Union[bytes, str]]]= None,
               connections: Optional[Mapping[str, Union[str, Tuple[str, Union[str, datetime,None]]]]] = None,
               effect_mode: Optional[str]= None,
               deadline_seconds: Optional[int]= 600,
               instructions: bytes = b"# do it\n"): ...

  transport: httpx.MockTransport

  @staticmethod
  def runner_env() -> Dict[str, str]: ...
  def saved_artifacts() -> Dict[str, Dict[str, Any]]: ...
  def saved_audit_events() -> List[Dict[str, Any]]: ...
  def saved_completion() -> Optional[Dict[str, Any]]: ...
```

| 引数 / メソッド              | 説明                                                                                                                                                  |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contract`             | エージェントの契約（`files` / `outputs` / `effect_mode` / `limits` / `env_bindings` など）。コピーして持ちます。省くと `sample_contract()`（サンプル `workflow_reply_agent.py` の契約） |
| `parameters`           | 工程の解決済みのパラメータ。そのまま渡します（既定値は埋めません）。省くと、`contract` も省いたときは `sample_parameters()`、それ以外は `{}`                                                           |
| `inputs`               | 入力ファイル。契約の `files` の `name` → 内容（`bytes` / `str`）。その file の `path` と `format` で置かれます。省くと、契約に `instructions` という file があれば `instructions` の内容        |
| `connections`          | 起動時に束ねる接続 slot。`{slot: access_token}` または `{slot: (access_token, expires_at)}`（`expires_at` は ISO の日時・`datetime`・`None` = 不明）                       |
| `effect_mode`          | 契約の `effect_mode` を置き換えます                                                                                                                           |
| `deadline_seconds`     | 今からの実行期限（秒。回収期限はその 300 秒後）。`None` = 期限がまだ決まっていない（runner は契約の `limits.execution_timeout_seconds` を使います）                                              |
| `instructions`         | `inputs` を省いたときの `instructions` 入力の内容                                                                                                               |
| `runner_env()`         | プラットフォームが Pod に注入する環境変数（この偽のランタイムを指す）。`arun()` の `env` に渡します                                                                                        |
| `transport`            | `arun()` の `transport` に渡す httpx の transport                                                                                                        |
| `saved_artifacts()`    | runner が保存した成果物。`{name: {artifact_id, logical_name, path, source, format, sha256, size_bytes, content}}`（`content` は `bytes`）                       |
| `saved_audit_events()` | 保存された監査（順に。最初の 2 件は runner の `context.manifest`）                                                                                                    |
| `saved_completion()`   | 保存された結果 `{completion_id, envelope, output_artifact_ids}`。保存前は `None`                                                                                |

このほか、`agenticstar_platform.workflow.testing` のモジュールの関数 `sample_contract()` / `sample_parameters()`・定数 `EXECUTION_ID` / `TOKEN` / `BASE_URL` と、`FakeRuntime` のプラットフォームの状態をまねる属性（実行の前にも途中にも変えられます）を使えます: `contract`（以後の応答に反映）、`cancel_requested_at`（ISO の日時 = 取消を求めた）、`run_closed`（run が終わった）、`deadline_passed`（期限を過ぎた）、`gate_decision` / `start_input`（context の値）、`fail_audit_types`（この種類の監査を `503` にする）、`fail_upload_times` / `fail_completion_times` / `fail_download_times`（次の N 回の成果物の保存・結果の保存・入力の取得を `503` にする）。ほかの属性・メソッドは内部のもので、予告なく変わることがあります。

---

## policy ポリシーモジュール

v1.0.0+ — tool 呼び出しを許すかどうかを、テナントの統制ポリシーとプロジェクトのポリシーを合成した結果から allow / forbid の二値で判定する純計算です。I/O もフレームワーク依存もなく、core に同梱されています。

- **2 層**: テナント層の `L1Policy`（既定の profile、誰も外せない `floor`、根拠本文を保持するか、版）と、プロジェクト層の `ProjectPolicy`（profile、`deny` / `allow`、gate の設定）。`tighten_merge()` は次を保証します: `floor` はプロジェクトで外せない、profile はテナントの既定より緩くできない、`strict` の `allow` はテナントの profile が許す操作クラスの中でだけ効く。
- **profile**: `open`（すべて allow）< `guarded`（destructive を forbid）< `strict`（read は allow、write / destructive は `allow` に明示したものだけ）。
- **判定の順**: policy が無い → forbid / `floor`・`deny` に一致 → forbid / MCP・A2A の呼び出し → allow（`mcp_unrestricted` / `a2a_unrestricted`。v3.0.3+ / v3.0.4+）/ 引数を解釈できない → forbid / 分類の無い tool → `open`・`guarded` は allow（`unregistered=True`）、`strict`・委譲・`dry_run` は forbid / 分類あり → profile の表（`dry_run=True` は read 以外を forbid）。
- **禁止規則**: scope なし = tool 名の glob（MCP は `mcp:<接続名>:<tool>` と `<tool>` の両方で照合）。引数の条件（`args`）と操作クラスの条件（`op_class`）も付けられます。`op_class` の条件は組み込みツールの判定にだけ効きます（MCP・A2A の呼び出しは操作クラスで分類しないため掛かりません。MCP を禁止するときは、接続 ID とメソッドの glob の external 規則か、tool 名の glob で書きます）。`internal` = 組み込みツールの操作種別（`kind` + `mapping_version`）。`external` = 接続 ID + メソッドの glob（`connection_kind` は `mcp` / `a2a`。A2A は接続単位で、tool は持たない）。外部の接続は名前ではなく ID で照合します（v3.0.2+）。
- **保存と照合**: `EffectivePolicy.to_dict()` / `from_dict()` で保存・復元し、`digest`（SHA-256）で「どの設定で判定したか」を後から突き合わせられます。保存形の `schema_version` は、A2A の規則があれば 4、scope 付きの規則があれば 3、それ以外は 2 です。

```python
from agenticstar_platform.policy import L1Policy, ProjectPolicy, tighten_merge, evaluate

l1 = L1Policy.from_row({"version": 3, "default_profile": "guarded", "floor": {"forbid": ["mcp:*:delete_*"]}})
project = ProjectPolicy.from_json({"profile": "strict", "allow": ["write_file"]})
policy = tighten_merge(l1, project, project_id="p1")

evaluate(policy, "delete_repo", None, mcp=True, mcp_server="gitlab", connection_id="12")  # forbid（floor）
evaluate(policy, "create_issue", None, mcp=True, mcp_server="gitlab", connection_id="12") # allow（mcp_unrestricted）
evaluate(policy, "write_file", "write")        # allow（strict_allowlist）
evaluate(policy, "delete_file", "destructive")  # forbid（strict_allowlist）
policy.digest                                   # 判定に使った設定の SHA-256
```

### 関数・クラス

| 名前                                                                                                                                                                                               | 説明                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tighten_merge(l1, project, *, project_id=None)`                                                                                                                                                 | 2 層を合成して `EffectivePolicy` を返します（`l1` が `None` ならテナント側の基準は `open`・floor なしで、プロジェクトの制限はそのまま効きます）                                                                                                                                                                                                                                                                                                                 |
| `evaluate(policy, tool, op_class, *, args=None, args_unparseable=False, dry_run=False, delegated=False, mcp_server=None, connection_id=None, mcp=None, connection_kind=None, tool_aliases=None)` | `Decision` を返します。`op_class` は呼び出し側が分類した `read` / `write` / `destructive`（不明は `None`）。MCP は `mcp=True` と `connection_id`、A2A は `connection_kind="a2a"` と `connection_id` を渡します。接続を識別できないのにその種類の external 規則があれば forbid。管理画面で登録した接続ではない、プロセス内の MCP サーバーには `LOCAL_CONNECTION`（`"local"`）を渡します（external 規則の対象外）                                                                                                     |
| `Decision`                                                                                                                                                                                       | `mode`（`allow` / `forbid`）/ `reason` / `policy_version` / `unregistered` / `matched`（一致した禁止パターン）/ `layer`（v3.0.11+。forbid を決めた規則の層: `project` = プロジェクトの設定（禁止規則・profile・allowlist・dry run）で変えられる、`tenant` = テナントの既定の profile、`floor` = テナントの floor（誰も緩められない）、`system` = 規則ではなく判定できない（policy が無い・引数を解釈できない）。allow は `None`。定数 `LAYER_PROJECT` / `LAYER_TENANT` / `LAYER_FLOOR` / `LAYER_SYSTEM`）と、`allowed` プロパティ |
| `L1Policy.from_row(row)` / `ProjectPolicy.from_json(raw)`                                                                                                                                        | 入力を DB の行 / JSON から作ります                                                                                                                                                                                                                                                                                                                                                                                         |
| `EffectivePolicy.to_dict()` / `EffectivePolicy.from_dict(raw)` / `.digest`                                                                                                                       | 保存・復元と SHA-256。`from_dict()` は未対応の `schema_version` を `ValueError` で拒否します（呼び出し側は全 forbid として扱う）                                                                                                                                                                                                                                                                                                                 |
| `policy_digest(policy)`                                                                                                                                                                          | `EffectivePolicy` の SHA-256                                                                                                                                                                                                                                                                                                                                                                                     |
| `verify_connections(policy, connections)`                                                                                                                                                        | 規則が指す接続が存在するかを確かめます（無ければ `ValueError`）。`connections` は `{"mcp": {...}, "a2a": {...}}`、または MCP の対応表 / 集合（v3.0.2+。v3.0.4 で種類別に）                                                                                                                                                                                                                                                                                   |
| `requires_schema(floor, forbid)`                                                                                                                                                                 | 規則に必要な `schema_version`                                                                                                                                                                                                                                                                                                                                                                                         |
| `profile_rank()` / `tighten_profile()` / `profile_permits(profile, op_class)`                                                                                                                    | profile の順序・厳しい方・その profile が単独で操作クラスを許しうるか                                                                                                                                                                                                                                                                                                                                                                     |
| `internal_operation_kinds(mapping_version=1)`                                                                                                                                                    | 内部操作種別（`text_write` / `file_read` / `file_transfer` / `command_exec` / `browser` / `desktop`）の ID・表示名・説明と版（画面に出してよい形）                                                                                                                                                                                                                                                                                           |

理由コード: `policy_unavailable` / `floor` / `project_forbid` / `unevaluable_args` / `unknown_tool` / `dry_run_read_only` / `profile` / `strict_allowlist` / `mcp_unrestricted` / `a2a_unrestricted`。定数: `PROFILE_ORDER` / `CONNECTION_KINDS`（`("mcp", "a2a")`）/ `LOCAL_CONNECTION`（`"local"`）/ `SCHEMA_VERSION_SCOPED`（3）/ `SCHEMA_VERSION_TYPED_CONNECTION`（4）/ `SUPPORTED_SCHEMA_VERSIONS` / `INTERNAL_OPERATIONS_MAPPING_VERSION`。

---

## まとめ

AGENTIC STAR Platform SDK v3.3.0 は、以下の 13 の専門モジュールで構成された包括的なツールキットです:

- **Events** — 非同期イベント配信（SSE / Webhook / DB）
- **Database** — PostgreSQL + Azure AD 認証 + 専門アクセス層（Config / Execution / Telemetry / PodRuntime）
- **RAG** — Embedding + Vector Search（Qdrant）
- **Storage** — Cloud Storage（Azure / S3 / GCS）
- **Auth** — AGENTIC STAR 認証サービス統合
- **Memory** — Semantic Memory（Mem0 + Qdrant）
- **Security** — Content Moderation + PII Detection（Azure / AWS / GCP マルチクラウド対応）
- **Common** — 共通ユーティリティ（SQL インジェクション防止・シークレットマスク）
- **Metering** — LLM 利用量・コスト計測（台帳 + 日次集計, v0.5.15+）
- **Runner** — Marketplace 互換の実行ライフサイクル（`run_marketplace_agent`: identity 検証 → 入力取得 → 実行 → 結果保存/Webhook → terminal 正確に 1 回 → cleanup, v0.5.30+）
- **Audit** — 行為監査台帳（`ActionAudit` / `GatewayActionAudit`: 承認・ツール認可・ポリシー違反等の append-only 記録。本文は digest 化して渡す設計, v0.5.31+）
- **Workflow** — プロジェクトのワークフローの工程で動くエージェントの runner（`run` / `WorkflowContext`: 入力の展開 → 実行 → 成果物の回収 → 結果の保存、外部操作の監査、取消・期限、接続先の token, v1.0.1+）
- **Policy** — tool 呼び出しの統制ポリシー（`tighten_merge` / `evaluate`: テナントとプロジェクトの 2 層を合成して allow / forbid を判定, v1.0.0+）

各モジュールは独立してインストール・利用可能であり、組み合わせることで強力な AI エージェントアプリケーションを構築できます。SDK はインフラのみを提供し、エージェントロジックは開発者が自由に設計します。
