AGENTICSTAR Platform SDK

Enterprise AI Agent Infrastructure SDK for building autonomous agent systems.

Installation

Requires Python 3.11+.

# Core (minimal) — Events / Storage paths / Metering / Auth / Security が使える
pip install agenticstar-platform

# With specific modules
pip install agenticstar-platform[db]           # PostgreSQL
pip install agenticstar-platform[rag]          # Qdrant + Embedding
pip install agenticstar-platform[storage]      # Azure Blob, S3, GCS
pip install agenticstar-platform[storage-azure] # Azure Blob only (AzureBlobStorageClient)
pip install agenticstar-platform[storage-aws]   # AWS S3 only (S3StorageClient)
pip install agenticstar-platform[storage-gcp]   # GCS only (GCSStorageClient)
pip install agenticstar-platform[memory]       # Semantic memory (Mem0)
pip install agenticstar-platform[security]     # PII detection
pip install agenticstar-platform[webhook]      # aiohttp (WebhookEventHandler)
pip install agenticstar-platform[all]          # All modules

Extra を入れていないコンポーネントに触れると、必要な extra を示す ImportError が出ます （生の ModuleNotFoundError は出しません）。

ImportError: 'PostgreSQLManager' requires the 'db' extra of agenticstar-platform.
Install it with:  pip install 'agenticstar-platform[db]'  (missing dependency: No module named 'asyncpg')

Storage の provider client も同じ契約です。StorageConfig / StoragePaths 等の core 型は extra なしで import でき、AzureBlobStorageClient（storage-azure）/ S3StorageClient（storage-aws）/ GCSStorageClient（storage-gcp）は シンボル取得の時点で（constructor まで遅延せず）対応する extra を案内します。 from agenticstar_platform import S3StorageClient と from agenticstar_platform.storage import S3StorageClient のどちらの経路でも 成功・失敗の境界は同一です。

Quick Start

1. 最小のエージェント（外部サービス不要・コピーしてそのまま動く）

エージェントのロジック・LLM・フレームワークは利用者が自由に選ぶもので、SDK は提供しません。 SDK が担当するのは「進捗と結果をフロントエンドへ届ける」などの基盤部分です。 まずは外部サービスなしで、進捗イベント → 終端イベントまでを一本通します。

hello_agent.py:

import asyncio

from agenticstar_platform import EventEmitter, EventType, create_json_handler


async def my_agent(emitter: EventEmitter, request: str) -> None:
    """あなたのエージェント本体。ロジックは自由（LangChain / OpenAI Agents SDK / 自作）。"""
    await emitter.emit_event(EventType.PHASE_START, f"received: {request}")
    try:
        answer = request.upper()  # ここを実際の処理に置き換える
        await emitter.emit_event(EventType.COMPLETION_SUCCESS, answer)
    except Exception as e:
        # 終端イベントは必ず 1 回送る（送らないとフロントの表示が完了しない）
        await emitter.emit_event(EventType.COMPLETION_FAILURE, str(e))


async def main() -> None:
    emitter = EventEmitter(execution_id="demo-001", handler=create_json_handler())
    asyncio.create_task(my_agent(emitter, "hello agenticstar"))

    # COMPLETION_SUCCESS / COMPLETION_FAILURE を受け取ると自動で終了する
    async for chunk in emitter.consume_events():
        print(chunk)  # create_json_handler は改行を含まないので print で 1 行にする


if __name__ == "__main__":
    asyncio.run(main())

pip install agenticstar-platform
python hello_agent.py

出力（create_json_handler() は JSON 行、create_sse_handler() は SSE 形式を返します）:

{"event_type": "phase_start", "execution_id": "demo-001", "message": "received: hello agenticstar", "timestamp": 1785162261.27}
{"event_type": "completion_success", "execution_id": "demo-001", "message": "HELLO AGENTICSTAR", "timestamp": 1785162261.27}

answer = ... の行を raise RuntimeError("upstream timeout") に変えると、 completion_failure が終端イベントとして出ます。

なお emit_event() はキューに積むだけです。上の例のように consume_events() を回さない 構成（SSE を使わない場合）では、EventEmitter.drain() を呼ばないとハンドラーが発火しません。

2. 同じ関数を Marketplace 互換で動かす（runner）

ローカルで動いた agent 関数は、run_marketplace_agent に渡すだけでそのまま Marketplace 互換の終端ライフサイクルで実行できます。identity （EXECUTION_ID 等）の受領・検証、入力メッセージの取得、結果の DB 保存、 webhook 通知、終端イベント（何が起きても正確に 1 回）、cleanup は runner が 担い、agent 側には一切書きません。

marketplace_agent.py:

from agenticstar_platform import run_marketplace_agent


async def my_agent(emitter, message: str) -> str:
    """あなたのエージェント本体。ロジックは自由（LangChain / OpenAI Agents SDK / 自作）。"""
    return message.upper()  # ここを実際の処理に置き換える


if __name__ == "__main__":
    run_marketplace_agent(my_agent)

pip install 'agenticstar-platform[runner]'
python marketplace_agent.py

環境変数契約:

終端イベントの規約:

• agent 関数の戻り値が completion_success の本文として保存・通知されます
• agent 関数が例外を投げると completion_failure に収束します（traceback はログのみ、イベント本文には出ません）
• ローカルサンプルのように agent 関数が自分で終端イベントを emit する形でも二重送信にはなりません（同じ関数が両方で動きます）
• 必須 env が欠けている場合は agent を呼ばずに MarketplaceRunnerConfigError で停止します

低レベル API が必要な場合（handler 構成を自分で組みたい場合）は、従来どおり create_marketplace_handler(data_access, webhook_url, user_id, conversation_id, message_id) （DB 保存 + webhook 通知の複合ハンドラー、[db] + [webhook] extra が必要）を EventEmitter に直接渡してください。

3. 基盤コンポーネントの初期化

以下は各コンポーネントの初期化例です（抜粋。実行には対応する外部サービスの 接続情報・資格情報と、該当 extra のインストールが必要です）。

from agenticstar_platform import (
    # Database
    PostgreSQLManager, ApiPostgreSQLManager, PostgreSQLConfig, DataAccess,
    # RAG (Vector DB + Embedding)
    QdrantManager, QdrantConfig, EmbeddingGenerator, EmbeddingConfig,
    # Storage
    AzureBlobStorageClient, AzureBlobConfig,
    # Events
    EventEmitter, EventType,
    # Auth
    AgenticStarAuthClient, AgenticStarAuthConfig,
    # Memory
    SemanticMemoryClient, SemanticMemoryConfig,
)

# Example: Initialize SDK components
async def main():
    # Database (direct connection)
    db_config = PostgreSQLConfig.from_toml("config.toml", section="database")
    manager = PostgreSQLManager(db_config)
    da = DataAccess(manager)
    await da.initialize()
    users = await da.fetch_all("SELECT * FROM users WHERE active = $1", (True,))

    # Database (HTTP API)
    db_config = PostgreSQLConfig(api_url="https://your-api.example.com/db")
    manager = ApiPostgreSQLManager(db_config, token_provider=lambda: "your-token")
    da = DataAccess(manager)
    users = await da.fetch_all("SELECT * FROM users WHERE active = $1", (True,))

    # RAG System
    embedding_config = EmbeddingConfig.from_toml("config.toml", section="rag.embedding")
    embedding_gen = EmbeddingGenerator(embedding_config)

    qdrant_config = QdrantConfig.from_toml("config.toml", section="rag.qdrant")
    async with QdrantManager(qdrant_config, embedding_gen) as qdrant:
        results = await qdrant.search("How to use the SDK?", limit=5)

    # Storage (uses from_dict, not from_toml)
    storage_config = AzureBlobConfig.from_dict({
        "bucket_name": "your-container",
        "connection_string": "your-connection-string",
    })
    storage = AzureBlobStorageClient(storage_config)

Modules

Auth Module

from agenticstar_platform.auth import AgenticStarAuthClient, AgenticStarAuthConfig

# From config.toml [auth.agenticstar] section
config = AgenticStarAuthConfig.from_config("config.toml")
client = AgenticStarAuthClient(config)

# Get user info
user = await client.get_user(user_id="user-001")

# Get MCP tokens
tokens = await client.get_mcp_tokens(user_id="user-001")

Memory Module

Semantic memory powered by Mem0 + Qdrant (requires pip install agenticstar-platform[memory]):

from agenticstar_platform.memory import SemanticMemoryClient, SemanticMemoryConfig

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

# Add memory (methods are synchronous; only cleanup() is async)
memory.add(
    [{"role": "user", "content": "User prefers dark mode"}],
    user_id="user-001",
)

# Search memory
results = memory.search("user preferences", user_id="user-001")

Storage Module

Note: AzureBlobConfig uses from_dict() (not from_toml()):

from agenticstar_platform.storage import AzureBlobStorageClient, AzureBlobConfig

config = AzureBlobConfig.from_dict({
    "bucket_name": "your-container",
    "connection_string": "DefaultEndpointsProtocol=https;...",
    "prefix": "uploads/",
})
client = AzureBlobStorageClient(config)
result = await client.upload_file("local/file.pdf", prefix="docs/")

Telemetry / LLM Usage Tracking (Marketplace)

TelemetryAccess (under db module) writes records to the ai_telemetry table. Unknown fields are stored in the metadata jsonb column automatically — no schema migration is required to add new tracking dimensions.

For Marketplace agents that wrap LLM calls, the SDK defines recommended field names for token and model usage. Following this convention enables cross-agent cost / utilization analytics in shared dashboards.

from agenticstar_platform.db import TelemetryAccess

telemetry = TelemetryAccess(data_access)

# After an LLM call from your custom agent:
response = await openai_client.chat.completions.create(...)

await telemetry.save_telemetry({
    "conversation_id": conversation_id,
    "agent_type": "my_marketplace_agent",
    "service": "my-agent-service",
    "operation": "generate_response",
    "duration_ms": elapsed_ms,
    "success": True,

    # Recommended convention fields (stored automatically in metadata jsonb)
    "prompt_tokens": response.usage.prompt_tokens,
    "completion_tokens": response.usage.completion_tokens,
    "total_tokens": response.usage.total_tokens,
    "model": "azure/gpt-4.1",  # LiteLLM-style identifier
})

Recommended convention fields

These fields are not known columns — they land in metadata jsonb automatically. No SDK code change, no DB schema migration. Use the recommended names so that your data joins with platform-level analytics.

Cross-agent analytics example

-- Per-model token usage in the last 30 days
SELECT
  metadata->>'model' AS model,
  agent_type,
  SUM((metadata->>'prompt_tokens')::int)     AS total_prompt_tokens,
  SUM((metadata->>'completion_tokens')::int) AS total_completion_tokens,
  COUNT(*)                                    AS invocations,
  AVG(duration_ms)::int                       AS avg_duration_ms
FROM ai_telemetry
WHERE timestamp > NOW() - INTERVAL '30 days'
  AND metadata ? 'prompt_tokens'
GROUP BY model, agent_type
ORDER BY total_prompt_tokens DESC;

Updated in SDK ≥ 0.5.15: Cost conversion is no longer out of scope. The new Metering module (UsageMeter) below computes cost via a pluggable engine (litellm by default — its community-maintained price map solves the "changes too frequently" problem; graceful NULL when litellm is absent). TelemetryAccess remains the place for agent operational telemetry (intent / tools / duration → ai_telemetry); UsageMeter is the dedicated per-LLM-call cost ledger. Use whichever fits; they are complementary.

Metering Module — UsageMeter (SDK ≥ 0.5.15)

Dedicated LLM usage & cost infrastructure: computes cost from an LLM response/usage and records one row per call to llm_usage_ledger, with a daily rollup (llm_usage_daily) and cost-visualization queries. Pure infra — agent-logic agnostic, identical for self-hosted and Marketplace BYO (in-process; no proxy/header coupling).

• Pluggable cost: default uses litellm (completion_cost / cost_per_token) — reflects long-context, prompt-cache and tier pricing. If litellm is absent, tokens are still recorded (cost_usd = NULL). Pass cost_fn=... to override.
• DB: any handle exposing execute_query(query, params) -> {success, data, error} (the SDK's DataAccess / PostgreSQLManager).
• Usage status (SDK ≥ 0.5.21): each row records usage_status (present/missing); when usage is absent, pass missing_reason= (e.g. provider_omitted / stream_interrupted). It is stored on the row (not just logs) so offline exports can tell cost_usd IS NULL (unpriced) vs usage_status='missing' vs true-zero apart. Present rows always store NULL (no contradiction).

from agenticstar_platform.metering import UsageMeter

meter = UsageMeter(db=data_access)
await meter.ensure_schema()                        # create ledger/daily/rollup if absent (idempotent)

# Record one LLM call (cost computed automatically; fire-and-forget safe)
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},
)

# ...or wrap the call so it records on completion
resp = await meter.track(model="gpt-5.5", labels=ids)(litellm.acompletion)(**params)

# Cost only (no record)
usd = UsageMeter.cost_usd("gpt-5.5", response=resp)

# Daily rollup + cost visualization (for dashboards / billing)
await meter.rollup_recent()
rows = await meter.daily_cost(by="model", since_days=30)   # by = "model" | "user" | "agent" | "day"

Schema (ensure_schema): llm_usage_ledger — one row per call (execution / message / conversation / user, model, in/out/total/cached tokens, usage_status + missing_reason, cost_usd, currency) — plus llm_usage_daily (rollup) and rollup_llm_usage_daily(day). The default DDL is portable (any PostgreSQL); at scale, partition llm_usage_ledger monthly (e.g. pg_partman).

Audit Module — ActionAudit / GatewayActionAudit (SDK ≥ 0.5.31)

Dedicated action-audit ledger infrastructure: records agent-side action events (approvals, tool authorizations, policy violations, kill-switch, external-agent egress) into append-only ledgers (agent_action_audit / llm_gateway_action_audit). Distinct from metering by its write guarantees — this is an audit trail, not telemetry. Pure infra, no extra dependencies (stdlib only, available in the core install).

• Callers pass no raw content (usage contract): never hand prompts / tool arguments to the ledger — one-way them with canonical_digest() (SHA-256) into payload_digest. The SDK performs no automatic secret detection or redaction. Field caps (reason truncated to 300 chars, payload_digest must be 64 lowercase-hex chars or it is dropped, metadata over 2KB of key-sorted JSON replaced by {truncated, size_bytes, digest}, always deep-copied) bound the blast radius of accidental leakage — they are not leak prevention by themselves.
• Three write modes: record() = at-least-once while the process lives (bounded retry, then the sanitized row is spilled as JSON to a log line tagged action_audit_spill for manual reconcile) / record_sync() = audit-before-act (raises ActionAuditWriteError on DB write failure — an approval that cannot be audited must not take effect) / record_nowait() = fire-and-forget for hot paths (strong task refs, backlog capped at 512 — overflow spills instead of blocking; pre-start cancellation also spills; best-effort — lost if the process dies abruptly).
• approval.* events require actor_ref (missing it raises ValueError synchronously).

Guardrail Alerts — GuardrailAlertWriter / GuardrailAlertAggregates (SDK ≥ 0.5.32)

Producer writers for the Admin-facing guardrail alert triage view (guardrail_alerts) and the unlinked daily aggregates (guardrail_alert_daily_aggregates). Non-authoritative operational view — the authority remains the action-audit ledger. Same delivery contract as the audit writers (bounded FAF + retry → spill → drain).

• No end-user identity: the row schema has no user-id column by design; the aggregates writer takes no correlation-id arguments at all (structural unlinking).
• SelfHarm never appears on rows: normalized detection (case / space / _ / - variants, str-Enum .value) raises ValueError synchronously; SelfHarm-only detections are recorded as aggregates only. Row policy_outcome is blocked-only in Phase 1.
• Idempotent rows: event_key (v2:{surface}:{correlation_kind}:{correlation}:{decision_point}:{outcome})
  • ON CONFLICT (event_key) DO NOTHING — replays never clobber Admin lifecycle state.
• Grants differ per table: rows = producer INSERT-only; aggregates = INSERT + UPDATE(count) + SELECT(count) (the UPSERT references the existing counter). Severities are measured Azure category severities (2/4/6) — do not substitute thresholds; aggregate counts are approximate (at-least-once may double-count).
• DB: any handle exposing execute_query(query, params) -> {success, data, error} (the SDK's DataAccess / PostgreSQLManager).

from agenticstar_platform.audit import ActionAudit, GatewayActionAudit, canonical_digest

audit = ActionAudit(db=data_access, source="worker", system_version=image_tag)
await audit.ensure_schema()                       # create ledger + indexes if absent (idempotent)

# Hot path (tool authorization etc.): 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}),
)

# Approval (audit-before-act): abort the action if this raises
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()                              # shutdown: drain pending writes (timeout → cancel + spill)

gw = GatewayActionAudit(db=gateway_da)            # LLM Gateway policy decisions (virtual-key identity)
await gw.record(event_type="policy.mcp_stripped", decision="stripped",
                virtual_key_id=vk, request_id=rid)

Schema (ensure_schema): agent_action_audit (source, event_type, actor, decision, reason, policy, correlation ids, payload_digest, metadata jsonb, row_hash) and llm_gateway_action_audit (virtual key, request ids, event/decision, detail_digest, row_hash). ensure_schema applies REVOKE UPDATE/DELETE best-effort; for production append-only enforcement use a dedicated insert-only role.

Platform Class Example

Below is an example of a Platform class that wraps SDK components for your agent system:

"""
Platform class example - Using AGENTICSTAR Platform SDK
"""
import asyncio
from dataclasses import dataclass
from typing import Optional

from agenticstar_platform import (
    PostgreSQLManager, PostgreSQLConfig, DataAccess,
    QdrantManager, QdrantConfig,
    EmbeddingGenerator, EmbeddingConfig,
    EventEmitter, EventType,
    SemanticMemoryClient, SemanticMemoryConfig,
    AzureBlobStorageClient, AzureBlobConfig,
    AgenticStarAuthClient, AgenticStarAuthConfig,
)


@dataclass
class PlatformConfig:
    """Platform configuration"""
    db_config: PostgreSQLConfig
    qdrant_config: QdrantConfig
    embedding_config: EmbeddingConfig
    storage_config: Optional[AzureBlobConfig] = None
    memory_config: Optional[SemanticMemoryConfig] = None
    auth_config: Optional[AgenticStarAuthConfig] = None

    @classmethod
    def from_toml(cls, path: str) -> "PlatformConfig":
        """Load all configurations from TOML file"""
        return cls(
            db_config=PostgreSQLConfig.from_toml(path, section="database"),
            qdrant_config=QdrantConfig.from_toml(path, section="rag.qdrant"),
            embedding_config=EmbeddingConfig.from_toml(path, section="rag.embedding"),
            storage_config=AzureBlobConfig.from_dict({
                # Load from environment or config
                "bucket_name": "your-container",
                "connection_string": "your-connection-string",
            }),
            auth_config=AgenticStarAuthConfig.from_config(path),
        )


class AgentPlatform:
    """
    Platform class wrapping SDK components.

    Example:
        >>> config = PlatformConfig.from_toml("config.toml")
        >>> platform = AgentPlatform(config)
        >>> await platform.initialize()
        >>>
        >>> # Use database
        >>> users = await platform.db.fetch_all("SELECT * FROM users")
        >>>
        >>> # Use RAG
        >>> results = await platform.search_knowledge("How to deploy?")
        >>>
        >>> # Clean up
        >>> await platform.cleanup()
    """

    def __init__(self, config: PlatformConfig):
        self.config = config
        self._db: Optional[DataAccess] = None
        self._qdrant: Optional[QdrantManager] = None
        self._embedding: Optional[EmbeddingGenerator] = None
        self._storage: Optional[AzureBlobStorageClient] = None
        self._memory: Optional[SemanticMemoryClient] = None
        self._auth: Optional[AgenticStarAuthClient] = None

    async def initialize(self) -> None:
        """Initialize all SDK components"""
        # Database
        db_manager = PostgreSQLManager(self.config.db_config)
        self._db = DataAccess(db_manager)
        await self._db.initialize()

        # Embedding generator
        self._embedding = EmbeddingGenerator(self.config.embedding_config)

        # Vector DB (RAG)
        self._qdrant = QdrantManager(self.config.qdrant_config, self._embedding)
        await self._qdrant.initialize()

        # Storage (optional)
        if self.config.storage_config:
            self._storage = AzureBlobStorageClient(self.config.storage_config)

        # Memory (optional)
        if self.config.memory_config:
            self._memory = SemanticMemoryClient(self.config.memory_config)

        # Auth (optional)
        if self.config.auth_config:
            self._auth = AgenticStarAuthClient(self.config.auth_config)

    @property
    def db(self) -> DataAccess:
        if not self._db:
            raise RuntimeError("Platform not initialized. Call initialize() first.")
        return self._db

    @property
    def qdrant(self) -> QdrantManager:
        if not self._qdrant:
            raise RuntimeError("Platform not initialized. Call initialize() first.")
        return self._qdrant

    @property
    def storage(self) -> Optional[AzureBlobStorageClient]:
        return self._storage

    @property
    def memory(self) -> Optional[SemanticMemoryClient]:
        return self._memory

    @property
    def auth(self) -> Optional[AgenticStarAuthClient]:
        return self._auth

    async def search_knowledge(self, query: str, limit: int = 10):
        return await self.qdrant.search(query, limit=limit)

    async def cleanup(self) -> None:
        """Clean up all resources"""
        if self._qdrant:
            await self._qdrant.close()
        if self._db:
            await self._db.close()
        if self._storage:
            await self._storage.close()
        if self._memory:
            await self._memory.cleanup()

Configuration (config.toml example)

[database]
host = "your-postgresql.postgres.database.azure.com"
port = 5432
database = "agenticai"
username = "admin"
password = "your-password"
use_azure_ad = false
pool_min_size = 2
pool_max_size = 10
# api_url = "https://your-api.example.com/db"  # Set for HTTP API mode

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

[auth.agenticstar]
base_url = "https://auth.agenticstar.tm.softbank.jp"
api_key = ""
timeout = 30.0
max_retries = 3

[rag.embedding]
# provider = "azure" (default): Azure OpenAI deployments path
base_url = "https://your-openai.openai.azure.com/"
api_key = "your-api-key"
model = "text-embedding-3-small"
dimensions = 1536

# OpenAI-compatible endpoints (e.g. embed-v-4-0 on Azure AI inference) — SDK >= 0.5.24:
# [rag.embedding]
# provider = "openai"
# base_url = "https://your-resource.services.ai.azure.com/models"  # include /models
# api_key = "your-api-key"
# model = "embed-v-4-0"   # "openai/embed-v-4-0" also accepted (prefix is stripped)
# dimensions = 1536       # api_version is not used with provider = "openai"

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

[storage.azure]
bucket_name = "your-container"
connection_string = "DefaultEndpointsProtocol=https;..."
prefix = "uploads/"

[memory.llm]
model = "azure/gpt-4"
api_key = "your-api-key"
base_url = "https://your-openai.openai.azure.com/"
api_version = "2024-02-15-preview"

[memory.embedder]
model = "azure/text-embedding-ada-002"
api_key = "your-api-key"
base_url = "https://your-openai.openai.azure.com/"
api_version = "2024-02-15-preview"

# OpenAI-compatible embedder (e.g. embed-v-4-0 on Azure AI inference) — SDK >= 0.5.24:
# [memory.embedder]
# model = "openai/embed-v-4-0"
# api_key = "your-api-key"
# base_url = "https://your-resource.services.ai.azure.com/models"  # include /models;
#                       # without base_url the client would connect to api.openai.com

API Reference

Generated API documentation is available under docs/ (pdoc). The developer portal SDK guides are the narrative reference.

Changelog

0.5.34 (2026-08-24)

• Feat: MCP トークンの expires_at=null（期限なし）を受理 — MCP 認証プロファイル 3 本柱化で追加された個人トークン (PAT, custom_config.authMode='api_token') は長期/無期限のため、供給 API (chatboardlogin) が expires_at: null を明示返却する。従来の get_mcp_tokens() は expires_at 欠損を INVALID_TOKEN_DATA として当該 provider のトークンを破棄していたため、PAT が一切利用できなかった。MCPTokenInfo.expires_at を Optional[datetime] = None に緩め（None = 期限なし）、client 側は null / キー欠損を正常形として受理する。null 以外の不正値は provider 単位の INVALID_EXPIRES_AT に統一（意図的なエラーコード変更: 空文字・0 等の falsy は従来 INVALID_TOKEN_DATA、truthy な非文字列は従来 broad except へ漏れて取得全体が UNKNOWN_ERROR になっていた）。cli-api と worker の両方が本バージョンで揃って初めて PAT が通る（トークンは cli-api → worker の 2 段で同モデル検証されるため）。

0.5.33 (2026-08-21)

• Fix: rollup_llm_usage_daily() の複数レプリカ同時実行による llm_usage_daily_pkey 衝突を解消（autonomous #2098）— 複数レプリカが毎時タイマーで rollup を並走させると、READ COMMITTED 下で後発の DELETE が先発コミット前の行を見えず 0 行削除 → INSERT が PK 衝突していた（stg 実測 38件/24h）。SQL 関数冒頭に pg_try_advisory_xact_lock(hashtext('rollup_llm_usage_daily'), p_day - date '2000-01-01') ガードを追加し、ロックを取れなかった側は skip（勝ち側が同一 ledger から同一集計を書くため冗長）。関数は ensure_schema() の CREATE OR REPLACE で配布されるため、ensure_schema() を実行するコンポーネント（cli-api 等）が 0.5.33 で起動して初めて DB に反映される点に注意（旧版コンポーネントの再起動は旧定義へ巻き戻すため、混在期間後に pg_get_functiondef で確認推奨）。

0.5.32 (2026-08-12)

• Guardrail Alerts writer を追加（GuardrailAlertWriter / GuardrailAlertAggregates、molt#1415 Phase1-A）— Admin トリアージ用 guardrail_alerts（非権威的運用ビュー・権威は行為監査台帳）と非連結日次集計 guardrail_alert_daily_aggregates の公開 producer writer。行スキーマに利用者 ID 列なし・SelfHarm は行構築を同期 ValueError で拒否（表記ゆれ正規化 + str-Enum .value 対応）し集計のみへ、という PO 決定（AI 倫理レビュー）を構造的に強制。event_key v2 冪等（replay が Admin lifecycle を巻き戻さない、実 DB 検証済み）。severity はカテゴリ別実測値（threshold 代用禁止）。権限は行 = INSERT のみ / 集計 = INSERT + UPDATE(count) + SELECT(count)。配送は行為監査と同一の bounded FAF + spill 契約。

0.5.31 (2026-08-10)

• 行為監査モジュール agenticstar_platform.audit を追加（ActionAudit / GatewayActionAudit / ActionAuditWriteError / canonical_digest）— 承認・ツール認可・ポリシー違反・キルスイッチ・外部エージェント呼び出し等の行為イベントを append-only 台帳（agent_action_audit / llm_gateway_action_audit）へ記録する純インフラ。書き込みモードは 3 種: record() = プロセス生存中 at-least-once（bounded retry → 失敗時は action_audit_spill マーカー付きログ行へサニタイズ済み row を JSON 出力）/ record_sync() = audit-before-act（DB 書き込み失敗時 ActionAuditWriteError 送出 — 監査に書けない承認は成立させない）/ record_nowait() = ホットパス用 fire-and-forget（backlog 上限 512、開始前 cancel も spill 退避。プロセス即死時は失われうる best-effort）。本文は digest 化して渡す使用契約（canonical_digest）+ フィールド上限（reason 300 字截断 / payload_digest は 64 桁小文字 hex のみ / metadata 2KB 超は digest 化 + deep-copy 正規化）で誤混入時の被害量を制限（機密の自動検出・redaction は行わない）。approval.* は actor_ref 必須（欠落は同期 ValueError）。追加依存なし（標準ライブラリのみ・core に同梱）。

0.5.30 (2026-08-07)

• Fix: run_marketplace_agent / arun_marketplace_agent が data_access 省略時に必ず AttributeError で落ちる問題を修正 — db_config / PostgreSQLConfig.from_env() フォールバック経路が生の PostgreSQLConfig を DataAccess へ渡していたため、'PostgreSQLConfig' object has no attribute 'initialize' で agent 未実行のまま即死していました（0.5.29 のドキュメント通りの最小構成 run_marketplace_agent(my_agent) が全滅する致命バグ）。create_postgresql_manager(config) でマネージャ化してから接続するよう修正。api_url（DB_API_PROXY_URL）設定時は runner が token_provider を供給できないため、明示的に MarketplaceRunnerConfigError を送出します。フォールバック経路の回帰テストを tests/runner/test_marketplace_runner_db_fallback.py に追加（0.5.29 の contract テストは全ケースで data_access= を注入していたため本経路のカバレッジがゼロでした）。

0.5.29 (2026-08-01)

• Marketplace runner を追加（run_marketplace_agent / arun_marketplace_agent, molt #1409） — ローカルで動いた agent 関数をそのまま Marketplace 互換の終端ライフサイクル（identity 検証 → 入力取得 → 実行 → 結果保存/webhook → terminal を正確に 1 回 → cleanup）へ渡せます。従来この main ボイラープレートは開発者の手書きで、終端イベントの送り漏れ・二重送信は開発者品質に依存していました。identity env（EXECUTION_ID 等）の欠落時は agent を呼ばずに MarketplaceRunnerConfigError で停止します。pip install 'agenticstar-platform[runner]'（新 extra: db + webhook 相当）。契約は tests/runner/ の contract テストで固定（success / agent 例外 / 入力取得失敗 / 保存失敗 / webhook 失敗の 5 分岐 × terminal exactly-once）。

0.5.26 (2026-07-27)

• [security] から boto3 を [security-aws] へ分離 — 0.5.25 で AWSSecurityClient のために [security] へ boto3 を追加しましたが、[storage-azure,security] を pin している Desktop ビルドは boto3 を意図的に外して 30MB 削減しているため、そこへ boto3 が戻ってしまいます。AWS 系の Content Safety を使う場合は pip install 'agenticstar-platform[security-aws]' を指定してください（[all] には従来どおり含まれます）。

0.5.25 (2026-07-27)

Packaging: 軽量インストールが実際に機能するようになりました（従来は [all] 以外が壊れていました）。

• import agenticstar_platform が core install で成功する — __init__.py が全モジュールを無条件 import していたため、pip install agenticstar-platform（core）は ModuleNotFoundError: asyncpg、[db] は ModuleNotFoundError: openai で import 自体が失敗していました。PEP 562 の遅延 import に変更し、pyproject の extra 分割どおりに動作します。公開 API 名・import の書き方は変更ありません。
• extra 不足が actionable なエラーになる — 生の ModuleNotFoundError ではなく「どの extra を入れれば直るか」を示します。実装内部の import ミスや循環 import を extra 不足と誤診しないよう、変換対象はその extra が担う依存が実際に無い場合に限定しています。
• WebhookEventHandler / create_marketplace_handler は aiohttp 不在をシンボル取得時に検出 — 従来は aiohttp が無くてもオブジェクトを生成でき、実行時にログを残して webhook を送らず沈黙していました。
• pydantic>=2.0.0 を core 依存に追加 — auth モジュールが使用しているにもかかわらず未宣言で、[all] では他パッケージの推移的依存で偶然動いていました。
• [security] に boto3 を追加 — AWSSecurityClient（Comprehend / Bedrock Guardrails）に必須ですが未宣言でした。
• [all] が [security] の依存（google-cloud-dlp / google-cloud-aiplatform）を包含 — [all] なのに GCPSecurityClient が使えない状態を解消しました。
• README の Quick Start が実行可能に — 従来は async def main() を定義するだけで呼び出しがなく、コピーしても何も起きませんでした。外部サービス不要で progress → terminal outcome まで通る最小例に差し替え、README 本文からコードを抽出して実行する drift テストを追加しています。

0.5.24 (2026-07-21)

RAG/Memory: OpenAI-compatible embedding endpoints (embed-v-4-0 class) support.

• RAG: EmbeddingConfig gains a provider field ("azure" default / "openai") — provider = "openai" targets OpenAI-compatible endpoints such as embed-v-4-0 on Azure AI inference (base_url must include /models; api_version is not used). Model strings with a LiteLLM-style prefix (azure/... / openai/...) derive the provider automatically and the prefix is stripped from the deployment/model name.
• Memory: convert_embedder_to_mem0() passes openai_base_url for the openai provider — when [memory.embedder] uses an openai/... model with base_url set, the Mem0 embedder now connects to that endpoint. ⚠️ Without this release, the base_url was silently dropped and the client connected to api.openai.com, causing 401s with non-OpenAI keys.
• RAG: embedding inputs are truncated with a model-aware token budget — 8,000 tokens for 8k-class models, a 100k sanity cap for long-context embed-v* models; disallowed_special=() so special-token literals (e.g. <|endoftext|>) in documents cannot crash encoding; character-based fallback when tiktoken is unavailable.

0.5.23 (2026-07-09)

Security: Azure PII detection batching and quota-aware 429 retry (LLM Gateway 502/504 incident fix).

• Security: detect_pii_batch() — Azure PII calls are batched at 5 documents/request — all sliding windows across the input texts are packed into a single documents array (Azure sync PII allows 5 docs/request), cutting Azure call volume by up to 5×. Long conversation histories previously issued one Azure call per text element (a captured 743-message request = 1,314 calls vs the S0 limit of 300 req/min), exhausting the quota in a single request. SecurityClientBase gains a sequential default implementation, so AWS / GCP clients inherit the API unchanged. detect_pii() is now a single-text wrapper over the batch path — external behavior (fail-closed empty string, error codes, signature) is unchanged.
• Security: Azure PII 429s are retried honoring Retry-After, then abort with RATE_LIMITED — throttled requests are retried (default 2 retries, AGENTICSTAR_AZURE_LANG_429_RETRIES, delay capped at 5s). If throttling persists, the remaining batch chunks are aborted (no further quota pressure) and unresolved texts fail with error_code="RATE_LIMITED", letting callers surface 429 + Retry-After to their clients instead of a retry-inducing 502. Previously any non-200 (including 429) failed closed immediately with no retry.
• Security: fail-closed hardening for partial batch responses — a 200 response missing a submitted document (absent from both documents and errors) now fails that text closed instead of silently passing it through unscanned.

0.5.22 (2026-07-08)

Security (GCP Content Safety), RAG error hierarchy, and DB identifier validation.

• Security: GCP Content Safety gains a Vertex AI Safety Filters path (+ Gemini judge) — GCPSecurityClient can now moderate content via Vertex AI safety filters across all Marketplace regions, with a Gemini-based semantic judge as an additional layer. Adds google-cloud-aiplatform>=1.60.0 to the [security] extra. (#1952)
• Security: guardrail input-inspection window count is now env-configurable — the number of sliding windows scanned on large inputs is tunable, relaxing the earlier "large-input tail not inspected" gap (P3-1).
• RAG: QdrantConfigError folded into the VectorStoreError hierarchy; initialize() is idempotent — init-failure wrapping now passes already-typed exceptions through (config errors are no longer mislabeled), and calling initialize() on an existing collection re-ensures the payload indexes instead of raising. (#1938)
• DB: identifier validation consolidated into common.validation; errors returned as a uniform dict — select_one returning None on error is now documented, and identifier-validation failures return a consistent shape. (#1959)

0.5.21 (2026-06-25)

Metering: persist missing_reason on the ledger.

• UsageMeter.record(..., missing_reason=...) + new missing_reason column on llm_usage_ledger — the usage-missing reason (provider_omitted / stream_interrupted / …) is now stored on the row (previously logs only), so offline exports can distinguish cost_usd IS NULL (unpriced) vs usage_status='missing' vs true-zero. Present rows store NULL (no contradiction). ensure_schema() adds the column idempotently (ADD COLUMN IF NOT EXISTS) — backward-compatible, propagates to existing monthly partitions; no change to existing columns.

0.5.20 (2026-06-24)

Metering: billing-clean cost storage + cache-read fallback.

• round_cost_usd helper + UsageMeter.record stores cost as a rounded Decimal — avoids float-repr drift (0.00089999…) in the cost_usd numeric column; 8-dp rounding does not change billing sums, and NaN/Inf are stored as NULL. Exported from both agenticstar_platform and agenticstar_platform.metering.
• extract_usage reads top-level cache_read_input_tokens as an additional cached_tokens fallback (complements the 0.5.19 details-based extraction), improving cache-aware cost on the token-only path. No public API change.

0.5.19 (2026-06-20)

Metering cost-accuracy fixes (cache-aware). Supersedes 0.5.18.

• default_cost_fn fallback applies prompt-cache pricing — passes cache_read_input_tokens / cache_creation_input_tokens to litellm.cost_per_token when completion_cost(response) is unavailable, so cache-heavy calls are no longer priced at the full input rate.
• extract_usage covers Responses API + cache-creation — reads cached_tokens from input_tokens_details (Responses) as well as prompt_tokens_details (Chat), and propagates cache_creation_input_tokens (Anthropic). Previously cached tokens on Responses calls were missed on the token-only/fallback path. No public API change.

0.5.17 (2026-06-19)

• Security: AWS PII detection now defaults to Bedrock Guardrails (multilingual) — AWSSecurityConfig gains a pii_service field ("bedrock_guardrails" default / "comprehend" legacy). AWS detect_pii() routes through Bedrock Guardrails sensitiveInformationPolicy by default, fixing multilingual (including Japanese) PII masking — Amazon Comprehend DetectPiiEntities only supports en / es (previously ja etc. slipped through and raised a ValidationException). ⚠️ Behavior change: with the new default, AWS PII requires guardrail_id to be set (otherwise it returns NOT_CONFIGURED); set pii_service="comprehend" to keep the legacy en/es path. Configs that already set pii_service explicitly are unaffected.

0.5.16 (2026-06-14)

Marketplace SDK reliability fixes (surfaced while building agents from the guides alone):

• Config: from_toml() resolves ${ENV} placeholders and uses the stdlib tomllib (no external toml dependency). host = "${POSTGRESQL_HOST}"-style values in config.toml are expanded from the environment; unresolved placeholders are left intact. Supports ${VAR} and ${VAR:-default}.
• Memory: mem0 2.x compatibility — SemanticMemoryClient.search() / get_all() now use mem0 2.x filters / top_k internally (the public user_id / limit arguments are unchanged). Azure gpt-5.x / o-series memory models no longer fail with max_tokens is not supported (the unsupported parameter is suppressed; the real Azure deployment is still targeted). mem0ai is pinned to >=2.0.0,<3.0.0.
• Events: EventEmitter.drain() — drives registered handlers (e.g. the marketplace webhook handler) for non-SSE flows. emit_event(...) only enqueues; without an SSE consume_events() loop, call drain() so handlers actually fire (previously emit + cleanup silently dropped events). The [webhook] extra now includes aiohttp (required by WebhookEventHandler); [all] includes it too.
• Storage: StoragePaths.input_uploads_prefix(user_id, conversation_id, message_id) — builds the owner-scoped prefix (users/{user_id}/uploads/{conv}/{msg}) for input attachments uploaded from the chat UI. Use with download_objects_by_prefix.
• Runtime: wait_for_egress() — waits for the egress sidecar to accept connections before the first outbound call, avoiding a startup race that could skip first-turn input moderation / PII.
• PodRuntime: injectable self scale-down — PodRuntime(..., scale_down_callback=...); when omitted and no bundled scaler is present, scale-down is skipped cleanly instead of raising No module named 'src'.

0.5.15 (2026-06-13)

• New: Metering module (UsageMeter) — dedicated LLM usage & cost ledger. meter.record(...) computes cost from a response/usage and writes one row per call to llm_usage_ledger; rollup_recent() / daily_cost(...) provide daily aggregation and cost-visualization queries; ensure_schema() creates the (portable) tables/rollup function idempotently. Cost is pluggable — default default_cost_fn uses litellm if installed (long-context / cache / tier aware), gracefully records tokens-only (cost_usd = NULL) when litellm is absent, and cost_fn= overrides. Agent-logic agnostic; identical for self-hosted and Marketplace BYO. Exports: UsageMeter, default_cost_fn, extract_usage.

0.5.7 (2026-05-10)

• Security: PII confidence threshold per-call — detect_pii() now accepts an optional confidence_threshold parameter on Azure / AWS / GCP clients (and the SecurityClientProtocol / SecurityClientBase). Passing None falls back to the value in *SecurityConfig.pii_confidence_threshold. This lets a single long-lived SecurityClient instance serve callers that need different thresholds, instead of constructing a new client per request. Backward compatible — existing callers that omit the new argument get the previous behavior.
• Security: GCP threshold now respects config — GCPSecurityClient.detect_pii() previously hardcoded a LIKELY (likelihood ≥ 4) cutoff and ignored GCPSecurityConfig.pii_confidence_threshold. It now compares likelihood / 5.0 against the configured threshold, matching Azure / AWS behavior. With the default pii_confidence_threshold = 0.7 the effective cutoff stays at likelihood ≥ 4, so most callers see no change. Callers that had set pii_confidence_threshold below 0.7 will start seeing additional POSSIBLE (likelihood 3) findings.
• Reuse the client to avoid leaks — AzureSecurityClient (and AWS/GCP equivalents) hold an httpx.AsyncClient (TLS context + connection pool) internally. Construct one client per process and call await client.close() on shutdown (or use async with); creating a new client per request without closing leaks resources.

0.5.2 (2026-03-28)

• Memory: Removed episodic memory (Graphiti/FalkorDB) — episodic.py was unused dead code. SDK now provides semantic memory (Mem0) only.
• Extras: [semantic] / [episodic] replaced with [memory] — unified extra for Mem0-based semantic memory.
• Extras: [all] no longer includes graphiti-core[falkordb].
• README updated to reflect episodic memory removal.

0.5.0 (2026-03-25)

Breaking Changes:

• DB: DataAccess now takes a manager instance instead of (config, use_proxy, token_provider). Callers create PostgreSQLManager or ApiPostgreSQLManager and pass it directly.
• DB: use_proxy parameter removed from DataAccess, create_postgresql_manager().
• DB: api_proxy_url renamed to api_url in PostgreSQLConfig.
• DB: ApiPostgreSQLManager exported as public API for HTTP API access.

Improvements:

• DB: is_initialized() method added to both PostgreSQLManager and ApiPostgreSQLManager.
• Qdrant: prefer_grpc / check_compatibility are now explicit QdrantConfig fields (no longer hardcoded based on auth_token_provider).
• Error messages no longer reference use-case specific terms (CLI/Desktop mode).

0.4.0 (2026-03-21)

• Security: Prompt Shield documents trimming - check_prompt_shield() now trims each document to 10,000 characters to comply with Azure API limits. Previously, WebFetch results exceeding 10,000 characters were blocked even without violations.
• Security: PII detection language support - detect_pii() now accepts a language parameter (default: "ja") for accurate multi-language PII detection. Previously hardcoded to Japanese.
• Security: Protocol/ABC updated - SecurityClientProtocol and SecurityClientBase updated with language parameter in detect_pii().

0.3.2

• Storage module: Multi-cloud support (Azure Blob, S3, GCS)
• Auth module: AgenticStar Auth API client
• Memory module: Semantic memory (Mem0)

Version

0.5.34