# Develop

The `agenticstar-platform` SDK is an infrastructure SDK for developing custom AI agents in Python that run on the AGENTIC STAR platform. Developers freely design agent logic, while the SDK provides platform infrastructure such as databases, event delivery, memory, storage, RAG, and security.

## What is the Agent SDK?

| Item                  | Value                                                                |
| --------------------- | -------------------------------------------------------------------- |
| **Package**           | `agenticstar-platform`                                               |
| **Version**           | v3.3.0                                                               |
| **Language**          | Python 3.12+                                                         |
| **Distribution**      | PyPI                                                                 |
| **Design Philosophy** | SDK provides infrastructure only. Agent logic is up to the developer |

> **About version numbers**
>
> From v3.0.0 the SDK version follows the AGENTIC STAR product version (3.0.1, 3.0.2, … from here on). The previous series on PyPI were 0.5.x → 1.0.x; the jump aligns the numbering with the product and is not a blanket compatibility guarantee. When upgrading from 0.5.40, check the following: (1) `ActionAudit` requires `actor_ref` when recording human / system decision events such as `gate.resolved` or `policy.changed` (since 1.0.0; a missing value raises `ValueError`), (2) `PostgreSQLManager.execute_query()` now returns row lists for `WITH … SELECT` / `VALUES` / `TABLE` (fixed in 0.5.41; review code that relied on the old return shape), (3) the metering ledger gains two columns (see the reference below; confirm the columns exist before you start writing), (4) `ActionAudit` stores floats and integers with an absolute value of 2^53 or more in `metadata` as strings (since 1.0.0, so that `row_hash` matches across languages; review code that reads ledger `metadata` values as numbers). If you are on 1.0.x, also review the workflow / audit vocabulary removed in 3.0.0 (`items_advanced` / `no_items` / `claim.stale`) and the removal of `verification.completed` from `KNOWN_EVENT_TYPES` in 3.0.1 (`event_type` remains a free string; only code that looks up or enumerates the dict directly is affected). If you use the workflow runner, the result format became version 2 in 3.0.1 (the outcome vocabulary and the `counts` key names changed), and the platform accepts only the new format (see the [Workflow Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/workflow-guide.md)).

## Module Structure

The SDK consists of 13 modules. You can selectively install only the modules you need via `extras`.

| Module       | Description                                                                                                                                                                             | Key Classes                                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| **events**   | Async event delivery (SSE / Webhook / DB)                                                                                                                                               | `EventEmitter`, `StreamingEvent`                                                        |
| **db**       | PostgreSQL connection + Azure AD auth                                                                                                                                                   | `PostgreSQLManager`, `DataAccess`                                                       |
| **rag**      | Qdrant vector search + Azure OpenAI Embedding                                                                                                                                           | `QdrantManager`, `EmbeddingGenerator`                                                   |
| **storage**  | Multi-cloud storage (Azure / S3 / GCS)                                                                                                                                                  | `AzureBlobStorageClient`, `S3StorageClient`                                             |
| **auth**     | AGENTIC STAR Auth API client                                                                                                                                                            | `AgenticStarAuthClient`                                                                 |
| **memory**   | Semantic memory (Mem0 + Qdrant)                                                                                                                                                         | `SemanticMemoryClient`                                                                  |
| **security** | Content moderation + PII detection                                                                                                                                                      | `AzureSecurityClient`, `ContentSafetyValidator`                                         |
| **common**   | Common utilities (validation, secret masking)                                                                                                                                           | `SecretMasker`, `validate_identifier`                                                   |
| **metering** | LLM usage & cost metering (ledger + daily rollup, v0.5.15+)                                                                                                                             | `UsageMeter`                                                                            |
| **runner**   | Marketplace-compatible execution lifecycle (identity check → fetch input → run → persist result/Webhook → terminal exactly once → cleanup, v0.5.30+)                                    | `run_marketplace_agent`                                                                 |
| **audit**    | Action-audit ledger (append-only record of approvals / tool authorizations / policy violations; callers pass SHA-256 digests instead of raw content, v0.5.31+; alerts writers v0.5.32+) | `ActionAudit`, `GatewayActionAudit`, `GuardrailAlertWriter`, `GuardrailAlertAggregates` |
| **workflow** | Runner for agents that run in steps of a project workflow (`mp-workflow/1`; Marketplace edition 3.2.0 and later, v1.0.1+)                                                               | `run`, `WorkflowContext`, `AuditApi`                                                    |
| **policy**   | Tool-call governance policy (pure computation that combines the tenant and project layers and decides allow / forbid, v1.0.0+)                                                          | `tighten_merge`, `evaluate`                                                             |

The SDK also bundles the **Local Integration Lab** (`python -m agenticstar_platform.lab`, v0.5.35+) — a credential-free, one-command integration journey across DB / RAG / storage. See the Lab section of the [Quickstart](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/quickstart/quickstart-sdk.md) for details.

## Quick Start

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

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

# Database connection
db_manager = PostgreSQLManager(PostgreSQLConfig.from_toml("config.toml"))
da = DataAccess(db_manager)
await da.initialize()

# Event delivery
emitter = EventEmitter(execution_id="exec-001")
await emitter.emit_event(EventType.PHASE_START, message="Starting processing")
```

## Getting Started

| Audience                              | Steps                                                                                                                                                                                       |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **New development**                   | Build a minimal agent with the [Quick Start](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/quickstart/quickstart-sdk.md)                                     |
| **Agents that run in workflow steps** | See the [Workflow Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/workflow-guide.md) for the contract and how to write `run(context)`             |
| **Migrating existing agents**         | Understand the module structure with the [Architecture Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/architecture.md), then adopt incrementally |

## Guides

- [Architecture Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/architecture.md) — SDK module structure and design philosophy
- [Deploy Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/deploy.md) — Docker build and platform registration
- [Events / Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/events-guide.md) — Implementing SSE event delivery
- [Memory Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/memory-guide.md) — Leveraging semantic memory (Mem0)
- [Storage Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/storage-guide.md) — Multi-cloud object storage
- [Security Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/security-guide.md) — Content moderation and PII detection
- [Workflow Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/workflow-guide.md) — Agents that run in steps of a project workflow

## Reference

- [SDK API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/reference/sdk-ref.md) — Complete specifications for all modules, classes, and methods
