# Architecture Guide

This guide explains the module structure and design philosophy of the agenticstar-platform SDK.

## Design Philosophy

The agenticstar-platform SDK provides only platform infrastructure (DB, events, memory, storage, RAG, security). Developers have complete freedom to design agent logic (prompt design, tool selection, execution flow).

## SDK Layer Architecture

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

The SDK is composed of a 3-layer architecture.

| Layer              | Role                                 | Responsibility                     |
| ------------------ | ------------------------------------ | ---------------------------------- |
| **Your AI Agent**  | Agent logic (prompts, tools, flow)   | Freely designed by developers      |
| **SDK**            | Access to platform infrastructure    | Provided by `agenticstar-platform` |
| **Infrastructure** | Databases, vector DBs, storage, etc. | Managed by the platform            |

## Module List

Each module can be installed and used independently. There are no implicit dependencies between modules.

| Module     | pip extras   | External Deps                                         | Description                                                                                      |
| ---------- | ------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `events`   | `(core)`     | None                                                  | SSE / Webhook / DB event delivery                                                                |
| `db`       | `[db]`       | asyncpg, azure-identity                               | PostgreSQL + Azure AD auth                                                                       |
| `rag`      | `[rag]`      | qdrant-client, openai                                 | Vector search + Embedding                                                                        |
| `storage`  | `[storage]`  | azure-storage-blob, boto3, google-cloud-storage       | Multi-cloud object storage                                                                       |
| `auth`     | `(core)`     | httpx                                                 | AGENTIC STAR Auth API client                                                                     |
| `memory`   | `[memory]`   | mem0ai                                                | Semantic memory (Mem0 + Qdrant)                                                                  |
| `security` | `[security]` | httpx, google-cloud-dlp                               | Content moderation + PII detection                                                               |
| `common`   | `(core)`     | None                                                  | Validation + secret masking                                                                      |
| `metering` | `(core)`     | litellm (optional)                                    | LLM usage & cost metering (ledger + daily rollup, v0.5.15+)                                      |
| `runner`   | `[runner]`   | asyncpg, azure-identity, aiohttp                      | Marketplace-compatible run lifecycle for chat agents (run\_marketplace\_agent, v0.5.30+)         |
| `audit`    | `(core)`     | None                                                  | Append-only action-audit ledgers and guardrail alert writers (v0.5.31+)                          |
| `workflow` | `(core)`     | httpx, pyyaml                                         | Runner for agents in project workflow steps (mp-workflow/1, Marketplace edition 3.2.0+, v1.0.1+) |
| `policy`   | `(core)`     | None                                                  | Tool-call governance policy evaluation (v1.0.0+)                                                 |
| `lab`      | `[lab]`      | asyncpg, azure-identity, qdrant-client, openai, boto3 | Credential-free local integration lab (Docker Compose, v0.5.35+)                                 |

## Data Flow

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

1. **User Request** — A request from the user reaches the agent
2. **Your AI Agent** — Processes while streaming progress via the SDK's `EventEmitter`
3. **SDK** — Calls modules such as DB, RAG, Storage, and Memory
4. **Infrastructure** — Accesses PostgreSQL, Qdrant, cloud storage, etc.
5. **Response** — Delivers the final response via SSE with `EventType.COMPLETION_SUCCESS`

## Configuration Management

SDK modules read configuration from `config.toml` (workflow and policy do not use `config.toml`). Settings can be loaded uniformly via the `from_toml()` method.

```toml
[database]
host = "your-db.postgres.database.azure.com"
port = 5432
database = "agenticstar"
username = "agent_user"
pool_min_size = 2
pool_max_size = 10
# Set to true for Azure AD auth (otherwise set password for password auth)
use_azure_ad = true

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

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

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

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

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

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

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

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

## Example Project Structure

```text
my-agent/
├── config.toml              # SDK settings
├── main.py                  # Agent entry point
├── agent.py                 # Your agent logic
├── tools/                   # Custom tools
│   ├── search.py
│   └── file_ops.py
├── Dockerfile
└── requirements.txt
```

## Next Steps

Deploy Guide

Docker build and platform registration steps

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/deploy.md)

Events / Streaming Guide

Implementation details for SSE event delivery

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/events-guide.md)
