# 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/develop/quickstart/quickstart-sdk.md).

> **Agents that run in workflow steps**
>
> Agents used in project workflows (Marketplace edition 3.2.0 and later) call `agenticstar_platform.workflow.run()` from the start command instead of `run_marketplace_agent`. When registering them in the admin console, enable "Use in workflows" and register a contract; they cannot be started in workflows until certification information such as the image digest is registered. See the [Workflow Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/guide/workflow-guide.md) for details.

## 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]==3.3.0
openai>=1.60.0
qdrant-client>=1.13.0
```

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, **agents that use SDK modules such as memory or RAG need a `config.toml`** (bundle it into the container image you build). Agents that only use `run_marketplace_agent` can pass the DB connection info in the environment variables `DB_HOST`, `DB_DATABASE`, `DB_USER` and `DB_PASSWORD` instead of `config.toml` (if you omit `db_config`, the SDK builds the connection info from these environment variables). For how to create it, see [Quickstart — Step 2: Create the Configuration File](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/quickstart/quickstart-sdk.md#step-2-create-the-configuration-file).

The following example connects with Azure AD. To connect with a password, either omit `use_azure_ad` and `[database.azure_ad]` and use `password` in `[database]`, or pass the connection info in the environment variables `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USER` and `DB_PASSWORD` without `config.toml`.

```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 \[Marketplace AI Agents → Environment Variables].** Only context vars (`EXECUTION_ID`, `USER_ID`, …; see the list in [Settings Guide — Environment Variables](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/settings-guide.md#environment-variables)) and the notify token `ASTER_NOTIFY_TOKEN` are auto-injected.

## Step 4: Platform Registration

1. **Log in to the admin console** — Access the AGENTIC STAR Console
2. **Create Agent screen** — Open "AI Agents" → "Marketplace AI Agents" and create an agent
3. **Enter basic information** (see [Settings Guide — Marketplace AI Agents](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/settings-guide.md#agent-settings)):

| Field                       | Value                                                  | Description                                                                                                                                                                                                                    |
| --------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Agent ID                    | `my-custom-agent`                                      | Unique identifier (lowercase letters, numbers, and hyphens)                                                                                                                                                                    |
| Display Name                | `My Custom Agent`                                      | Name displayed in the UI                                                                                                                                                                                                       |
| Registry / Image Name / Tag | `your-registry.example.com / my-org/my-agent / v1.0.0` | Enter the container image in three fields (the image name does not include the registry)                                                                                                                                       |
| Environment Variables       | `DB_HOST / DB_PASSWORD / WEBHOOK_URL etc.`             | DB connection (PostgreSQLConfig.from\_env() contract) and webhook target. Context variables (EXECUTION\_ID etc.) and ASTER\_NOTIFY\_TOKEN are auto-injected and must not be registered (registering the same name is an error) |

After you enter it, you can use "**Check image**" in the Docker image section to see whether this cluster can pull the image (see [Settings Guide — Check image](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/settings-guide.md#check-image)).

4. **Generation Model Connections** — Register the LLM provider and model to use in the separate "Generation Model Connections" menu, not in the agent registration (see [Settings Guide — Generation Model Connections](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/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/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/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 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, agent Pods 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
- A cycle execution (a conversation the platform starts on a schedule) is not counted as completed just because it exits 0 ("finished, completion not measured"). To have it counted as a success, your agent reports completion with `report_completion` (v3.0.14+, see the [Quickstart](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/develop/quickstart/quickstart-sdk.md#report-completion))
- An execution that keeps exiting abnormally after it starts, or that does not finish within the "execution time limit" set in the admin console plus 10 minutes (or, when no limit is set, by 10 minutes before the end of the execution's lifetime), is closed by the platform as failed, and a message saying the agent was stopped is shown in the chat (when `WEBHOOK_URL` points to the platform's notification endpoint)

The `PodRuntime` class ([SDK API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/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 error in "Pod status" and "View logs" in the execution history (see below). 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                                                                                                                                          |
| `A cycle execution never finishes and the next trigger is skipped`                              | The process stays alive after the work is done (still a server answering health checks). The platform decides that an execution has finished from the container exit code | Close the server and exit after the work completes (\[Quickstart]\(/docs/marketplace/develop/quickstart/quickstart-sdk#exit-after-run))                                                           |
| `Stops with MarketplaceRunnerFenceTaken (v3.0.12+)`                                             | In a cycle execution, the pod was recreated after a previous runner had already started your agent                                                                        | No action needed (the stop prevents running the same execution twice). The platform closes the execution as failed with unknown effects                                                           |
| `Cycle executions are never counted as successes (result: "finished, completion not measured")` | Your agent does not report completion (a clean process exit is not treated as completion)                                                                                 | Call report\_completion at the end of your agent to report completion (v3.0.14+). The report is adopted only when the container exits 0                                                           |
| `Stops with MarketplaceRunnerConfigError`                                                       | WEBHOOK\_URL or a context variable (EXECUTION\_ID etc.) is missing                                                                                                        | Check that WEBHOOK\_URL is registered under \[Marketplace AI Agents → 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, wrong image reference, or the registry cannot be reached                                                                                  | Check the reason with "Check image" for the Marketplace AI agent (see below)                                                                                                                      |

When the image cannot be pulled, you can see the reason with "Check image" for the Marketplace AI agent (see [Settings Guide — Check image](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/build/guide/settings-guide.md#check-image)).

To see the Pod status and logs of each run, open the run in "Project Management" → "Execution history" in the admin console. "Pod status" shows the state ("Waiting to start", "Running", "Finished abnormally", and so on). The exit code is shown when it is recorded, and the reason it stopped is shown when it is known. Enter a reason in "View logs" to retrieve the agent's logs for that run (nothing is shown when there was no output or the retention period has passed). Organization administrators of the target organization can view the logs, and the viewer and the reason are recorded. Logs are kept for 7 days by default.

## Next Steps

Architecture Guide

SDK module structure and design philosophy

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/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/develop/reference/sdk-ref.md)
