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

Prerequisites

• Docker 24.0 or higher
• Access to Azure Container Registry (ACR) or a compatible registry
• Access permissions to the AGENTIC STAR admin console

Step 1: Create the Dockerfile

DockerfileDockerfile

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 . .

# Health check
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"

# Expose port
EXPOSE 8000

# Entry point
CMD ["python", "start_api_server.py"]

requirements.txt

agenticstar-platform[all]==0.5.3
fastapi>=0.115.0
uvicorn>=0.34.0
openai>=1.60.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

curl

# 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

curl

# 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

This is the configuration file for registering with the platform. Include the following in your config.toml.

config.tomlToml

[agent]
name = "my-custom-agent"
version = "1.0.0"
description = "Custom agent"
port = 8000

[postgresql]
host = "${POSTGRESQL_HOST}"
port = 5432
database = "${POSTGRESQL_DATABASE}"
user = "${POSTGRESQL_USER}"
password = "${POSTGRESQL_PASSWORD}"

[postgresql.azure_ad]
enabled = true
tenant_id = "${AZURE_TENANT_ID}"

The platform automatically injects environment variables such as PostgreSQL connection information and Azure AD settings at Pod startup. Use ${VAR_NAME} format placeholders in your config.toml.

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:

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	Full registry path
Port	8000	Port exposed by the container
Health Check Path	/health	Endpoint checked by Kubernetes

4. LLM Settings — Configure the Azure OpenAI model and endpoint to use
5. Resource Settings — Configure CPU / memory requests and limits
6. Save & Deploy

Step 5: Verification

Verify via API Endpoint

curl

# Health check
curl https://your-platform.example.com/agents/my-custom-agent/health

# 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
  }'

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

Pod Lifecycle

Using the SDK's PodRuntime class, you can notify the platform of Pod startup and shutdown states.

start_api_server.pyPython

from agenticstar_platform.db.pod_runtime import PodRuntime

runtime = PodRuntime(db_manager)

# Notify Pod startup
await runtime.report_pod_start(
    conversation_id=conversation_id,
    pod_name=os.environ.get("HOSTNAME", "unknown"),
)

# --- Agent processing ---

# Notify Pod shutdown (auto scale-down)
await runtime.report_pod_final(
    conversation_id=conversation_id,
    status="completed",
)

Troubleshooting

Symptom	Cause	Solution
Pod is in CrashLoopBackOff	Failed to load config.toml	Verify that environment variables are correctly injected
DB connection timeout	Cannot reach PostgreSQL over the network	Check NetworkPolicy and Service configuration
Health check failure	/health endpoint not implemented	Add a /health route to FastAPI
Image pull error	Registry authentication failed	Check imagePullSecrets configuration

Next Steps

Architecture Guide

SDK module structure and design philosophy

ガイドを見る

SDK API Reference

Complete specifications for all modules, classes, and methods

ガイドを見る