# Deploy Guide

This guide explains how to build a custom agent as a Docker container and register it on the AGENTIC STAR platform for execution.

## Overview

The deployment flow consists of 4 steps:

1. **Create Dockerfile** — Containerize the agent
2. **Docker Build & Push** — Register to a container registry
3. **Platform Registration** — Register the agent in the admin console
4. **Verification** — Test via the Chat Web App

## Execution Model

A marketplace custom agent runs as a **"one execution = one process" batch, not a long-running HTTP server**.

1. When a user sends a message, the platform starts the agent's Pod and injects the context variables (`EXECUTION_ID` / `CONVERSATION_ID` / `USER_ID` / `MESSAGE_ID`, etc.) as environment variables
2. The process started by the container's `CMD` calls `run_marketplace_agent()`. The SDK runner handles fetching the input message → running your agent → persisting the result to the DB and notifying the webhook (delivering the terminal event exactly once)
3. When processing finishes, the process **exits with code 0** (the Pod does not stay resident)

Because of this, **you do not need to expose a port, implement a `/health` endpoint, or use a web framework such as FastAPI**. For how to write the agent function, see the "Run Marketplace-compatible (runner)" section of the [SDK Quickstart](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/develop/quickstart/quickstart-sdk.md).

## Prerequisites

- Docker 24.0 or higher
- Access to Azure Container Registry (ACR) or a compatible registry (permission to push images; the `AcrPush` role on Azure)
- Access permissions to the AGENTIC STAR admin console

## Step 1: Create the Dockerfile

```dockerfile
FROM python:3.12-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Non-root user (a NUMERIC UID is required under runAsNonRoot-enforced namespaces;
# a name-only USER cannot be verified as non-root by the kubelet and is rejected)
RUN useradd -u 1000 -m -s /usr/sbin/nologin appuser \
 && chown -R 1000:1000 /app
USER 1000

# Entry point (a one-shot process that calls run_marketplace_agent.
# Not a resident server — no port exposure or health-check endpoint needed)
CMD ["python", "marketplace_agent.py"]
```

> **runAsNonRoot / readOnlyRootFilesystem assumptions**
>
> The marketplace runtime enforces `runAsNonRoot: true`. A Dockerfile with no `USER` (runs as root), or one that uses a **name** like `USER appuser`, is rejected at startup with `container has runAsNonRoot and image will run as root`. Always specify a **numeric UID** (e.g. `USER 1000`). Also, under `readOnlyRootFilesystem: true`, temporary writes (e.g. `/tmp` for file sharing) fail — mount `/tmp` as an `emptyDir` or point writes at a writable volume.

```text
agenticstar-platform[all]==0.5.40
openai>=1.60.0
qdrant-client>=1.13.0
```

Use **0.5.30 or later** for the default `run_marketplace_agent` configuration (the DB connection fallback used when `data_access` is omitted). 0.5.29 has a connection-construction bug that crashes with an `AttributeError` at startup unless you pass `data_access=` explicitly.

If your Kubernetes cluster runs on AMD64 architecture, make sure to specify `--platform linux/amd64` when building.

## Step 2: Docker Build & Push

**Azure Container Registry**

```bash
# Build
docker build --platform linux/amd64 \
  -t your-acr.azurecr.io/my-agent:v1.0.0 .

# Login to ACR
az acr login --name your-acr

# Push
docker push your-acr.azurecr.io/my-agent:v1.0.0
```

**Amazon ECR**

```bash
# Build
docker build --platform linux/amd64 \
  -t 123456789.dkr.ecr.ap-northeast-1.amazonaws.com/my-agent:v1.0.0 .

# Login to ECR
aws ecr get-login-password --region ap-northeast-1 | \
  docker login --username AWS --password-stdin 123456789.dkr.ecr.ap-northeast-1.amazonaws.com

# Push
docker push 123456789.dkr.ecr.ap-northeast-1.amazonaws.com/my-agent:v1.0.0
```

## Step 3: Agent Configuration File

`config.toml` is the file the SDK modules (DB / RAG / memory) read to build their connection info. Since `PostgreSQLConfig.from_toml()` and friends read this file to construct their config, **your agent needs a `config.toml`** (bundle it into the container image you build). For how to create it, see [Quickstart — Step 2: Create the Configuration File](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/develop/quickstart/quickstart-sdk.md#step-2-create-the-configuration-file).

```toml
# [agent] is metadata; the SDK does not read it (optional)
[agent]
name = "my-custom-agent"
version = "1.0.0"
description = "Custom agent"

# [database] is read by PostgreSQLConfig.from_toml() (required)
[database]
host = "${POSTGRESQL_HOST}"
port = 5432
database = "${POSTGRESQL_DATABASE}"
username = "${POSTGRESQL_USER}"
password = "${POSTGRESQL_PASSWORD}"
use_azure_ad = true

[database.azure_ad]
tenant_id = "${AZURE_TENANT_ID}"
client_id = "${AZURE_CLIENT_ID}"
client_secret = "${AZURE_CLIENT_SECRET}"
```

`from_toml()` only reads the sections for the modules you use — by default `[database]` (not `[postgresql]`; the field is `username`), plus `[database.azure_ad]` when `use_azure_ad = true`, and `[memory]` / `[rag.embedding]` / `[rag.qdrant]` when used. `[agent]` is metadata the SDK does not read (name etc. are set in the Console).

No default path: `from_toml("config.toml")` reads exactly the path you pass, so keep `config.toml` in the agent's working directory, bundle it into the image, and pass its path. (The auth config `AgenticStarAuthConfig.from_config()` additionally auto-detects `config.toml` in the current directory, then the project root, when no path is given.) Use `${VAR_NAME}` placeholders instead of literal values; `from_toml()` expands `${VAR}` / `${VAR:-default}` from `os.environ` at load time (stdlib `tomllib`, no external `toml`).\
\
**Register the env vars your `config.toml` references (`POSTGRESQL_*` / `AZURE_*`) under \[Agent Settings → Environment Variables].** Only context vars (`EXECUTION_ID`, `USER_ID`, …) are auto-injected.

## Step 4: Platform Registration

1. **Log in to the admin console** — Access the AGENTIC STAR Console
2. **Agent management screen** — Navigate to "Agents" then "New Registration"
3. **Enter basic information** (see [Settings Guide — Agent Settings](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/build/guide/settings-guide.md#agent-settings)):

| Field                 | Value                                      | Description                                                                                                                                                                                           |
| --------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent Name            | `my-custom-agent`                          | Unique identifier (alphanumeric and hyphens)                                                                                                                                                          |
| Display Name          | `My Custom Agent`                          | Name displayed in the UI                                                                                                                                                                              |
| Container Image       | `your-acr.azurecr.io/my-agent:v1.0.0`      | Registry, image name, and tag                                                                                                                                                                         |
| Environment Variables | `DB_HOST / DB_PASSWORD / WEBHOOK_URL etc.` | DB connection (PostgreSQLConfig.from\_env() contract) and webhook target. Context variables (EXECUTION\_ID etc.) are auto-injected and must not be registered (registering the same name is an error) |

4. **LLM Settings** — Configure the Azure OpenAI model and endpoint to use (see [Settings Guide — LLM Settings](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/build/guide/settings-guide.md#llm-settings))
5. **Resource Settings** — Configure CPU / memory requests and limits (see [Settings Guide — Resources](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/build/guide/settings-guide.md#resources))
6. **Save & Deploy**

## Step 5: Verification

### Verify via API Endpoint

```bash
# Chat request
curl -X POST https://your-platform.example.com/conversation/v1/chat/completions \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-custom-agent",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
```

For how to obtain `<access_token>`, see [Call the API — Step 2: Obtain Token](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/api/quickstart/call-api.md#step-2-obtain-token).

### Verify via Chat Web App

1. Access the Chat Web App
2. Select "My Custom Agent" from the agent selection dropdown
3. Send a message to verify operation

## Execution Lifecycle and Pod Management

Pod lifecycle management (startup, execution-state recording, shutdown, cleanup) is **the platform's responsibility**. No agent-side implementation is required.

- Execution state (the `execution_pods` table) is recorded by the Marketplace executor. Your agent does not need to call the SDK's `PodRuntime` (doing so would double-write against the executor's records; furthermore, Pods in the marketplace-agents namespace get no ServiceAccount token, so code that calls the Kubernetes API from inside the Pod will not work)
- The terminal event (`COMPLETION_SUCCESS` / `COMPLETION_FAILURE`) is delivered **exactly once** by `run_marketplace_agent()`. Even when the agent function raises an exception, the runner delivers `COMPLETION_FAILURE` and then terminates the process normally
- After processing completes, the process exits with code 0 and the platform cleans up the Pod

The `PodRuntime` class ([SDK API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/basic/develop/reference/sdk-ref.md)) is a building block for deployments that manage their own Pods outside the marketplace; it is not used by marketplace custom agents.

## Troubleshooting

| Symptom                                   | Cause                                                              | Solution                                                                                                                                                 |
| ----------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Pod keeps restarting`                    | The process exits non-zero (restartPolicy: OnFailure restarts it)  | Check the logs for the error. Structure the agent to exit 0 after processing via run\_marketplace\_agent (do not start a resident server)                |
| `Pod is in CrashLoopBackOff`              | Failed to load config.toml                                         | Verify that environment variables are correctly injected                                                                                                 |
| `Stops with MarketplaceRunnerConfigError` | WEBHOOK\_URL or a context variable (EXECUTION\_ID etc.) is missing | Check that WEBHOOK\_URL is registered under \[Agent Settings → Environment Variables] (missing DB\_\* causes a connection error instead, not this error) |
| `DB connection timeout`                   | Cannot reach PostgreSQL over the network                           | Check NetworkPolicy and Service configuration                                                                                                            |
| `No response appears in Chat`             | WEBHOOK\_URL is unset or wrong                                     | Check the WEBHOOK\_URL environment variable                                                                                                              |
| `Image pull error`                        | Registry authentication failed                                     | Check imagePullSecrets configuration                                                                                                                     |

## Next Steps

Architecture Guide

SDK module structure and design philosophy

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

SDK API Reference

Complete specifications for all modules, classes, and methods

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