Prometheus Agent Template¶
An interactive scaffolding tool that generates a ready-to-run A2A agent from a template. Run the setup script, answer a few prompts, and get a complete agent with Dockerfile, configuration, and authentication.
Quick start¶
cd prometheus_core/agent-template
# Run the scaffolding script
python setup_agent.py
The script prompts for:
| Prompt | Example | Default |
|---|---|---|
| Agent name | Plant Analysis | (required) |
| Description | Analyzes plant thermal output | -- |
| Slug | plant-analysis | derived from name |
| Class name | PlantAnalysis | derived from name |
| Skill ID | analyze_plant | derived from name |
| Skill name | Analyze Plant | derived from name |
| Skill description | Runs plant thermal analysis | -- |
| Trim comments? | y/n | n |
After confirmation, it creates a new directory with all files ready to go.
Run the generated agent¶
cd ../<output-directory>
cp .env.example .env # only if setup didn't create one
uv sync && source .venv/bin/activate
AGENT_SECRET_REQUIRED=false python agent.py
Install prometheus_api at the platform's commit first; the
agent template README
has the command.
cd ../<output-directory>
make up # set PROMETHEUS_API_BASE_IMAGE_HASH in .env first
Generated files¶
The template produces these files:
| File | Purpose |
|---|---|
agent.py |
Agent implementation -- subclass of PrometheusAgent with _execute() to customize |
agent_card.json |
A2A agent metadata (name, description, skills, capabilities) |
prompts/ |
LLM prompt templates, loaded with load_prompt() |
workflows/ |
Optional agent-owned workflow templates published through the served agent card |
.env.example |
Environment variable template |
Dockerfile |
Container build on the Prometheus SDK base image, with proxy build args |
docker-compose.yml |
Service definition with the /healthz health check; docker-compose.net_*.yml select the network mode |
Makefile |
make up, make up-fg, tests and checks |
pyproject.toml |
Package metadata and Python dependencies |
uv.lock |
Locked dependency versions; the Docker build installs from it |
tests/ |
pytest tests for the agent |
README.md |
Agent-specific documentation |
.python-version |
Pinned to 3.12 |
Template placeholders¶
The setup script replaces these tokens across all files:
| Placeholder | Replaced with |
|---|---|
TEMPLATE_NAME |
Agent name |
TEMPLATE_DESCRIPTION |
Agent description |
TEMPLATE_SLUG |
Kebab-case identifier |
TEMPLATE_CLASS |
PascalCase class name |
TEMPLATE_SKILL_ID |
Snake-case skill ID |
TEMPLATE_SKILL_NAME |
Skill display name |
TEMPLATE_SKILL_DESCRIPTION |
Skill description |
Customizing the agent¶
Override _execute¶
The only method you need to implement:
from prometheus_api.agent import PrometheusAgent
class MyAgent(PrometheusAgent):
async def _execute(self, params, context, event_queue):
input_data = params.get("input_data")
if not input_data:
raise ValueError("input_data is required")
# Your logic here
result = do_analysis(input_data)
return {"status": "success", "result": result}
Send progress updates¶
For long-running tasks, use the base class helper rather than building A2A events by hand:
async def _execute(self, params, context, event_queue):
await self.send_status_update(context, event_queue, message="Loading input data...")
# ... continue processing
Add skills¶
Edit agent_card.json to register additional skills:
{
"skills": [
{
"id": "primary_analysis",
"name": "Primary Analysis",
"description": "Main analysis skill",
"tags": ["analysis"]
},
{
"id": "secondary_check",
"name": "Secondary Check",
"description": "Validation step",
"tags": ["validation"]
}
]
}
Add workflow templates¶
Use workflows/ when this agent should publish reusable workflow templates to the platform workflow library.
PrometheusAgent loads *.yaml, *.yml, and *.json workflow files from that directory and inserts them into
the served agent card. The client-agent discovers those definitions, compiles them against available skill schemas,
and exposes them in the shared workflow catalog.
The generated template ships workflows/example_workflow.yaml.example so a new agent does not publish a sample
workflow by accident. Rename it to .yaml only after reviewing the workflow ID, inputs, step bindings, and output
mapping. See Workflow Templates for the complete schema and authoring rules.
Use the StorageClient¶
Agents can interact with the storage backend:
from prometheus_api.storage_client import StorageClient, ConnectionConfig, ItemCreate
class MyAgent(PrometheusAgent):
def __init__(self):
super().__init__("My Agent")
self.storage_config = ConnectionConfig.from_env()
async def _execute(self, params, context, event_queue):
with StorageClient(self.storage_config) as client:
item = client.items.create(ItemCreate(
name="Analysis Result",
properties=params
))
return {"item_id": item.id}
Environment variables¶
| Variable | Required | Default | Description |
|---|---|---|---|
AGENT_PORT |
No | 8000 | Port to listen on |
AGENT_HOST |
No | localhost | Hostname for agent card URL |
AGENT_SECRET |
Prod | -- | Shared secret for Bearer token auth |
AGENT_SECRET_REQUIRED |
No | true | Enforce authentication. Do not disable this in normal development or deployment. |
REGISTRY_URL |
No | -- | Agent registry base URL used for registration and A2A routing (on the platform, the backend: http://backend:8000) |
LITELLM_MASTER_KEY |
No | -- | Registry token the SDK sends when registering (name kept for SDK compatibility); on the platform, set it to AGENT_SECRET |
DEEPLYNX_KEY |
If using storage | -- | API key for DeepLynx |
DEEPLYNX_SECRET |
If using storage | -- | API secret for DeepLynx |
DEEPLYNX_ORG_ID |
If using storage | -- | Organization ID |
DEEPLYNX_PROJECT_ID |
If using storage | -- | Project ID |
See .env.example for the full list including proxy settings.
Docker deployment¶
The generated Dockerfile:
- Base image: the Prometheus SDK image,
${PROMETHEUS_API_BASE_IMAGE_REPO}:${PROMETHEUS_API_BASE_IMAGE_HASH}, which bundles Python 3.12 andprometheus_api. Change the hash, not theFROMline. - Installs dependencies from
uv.lock(uv sync --locked); the build stops ifuv.lockis missing - Supports
HTTP_PROXY/HTTPS_PROXY/NO_PROXYbuild args
The health check on /healthz is in the generated docker-compose.yml (every 15 seconds), not the Dockerfile.
Docker Compose (multi-agent)¶
services:
agent-one:
build: ./agent-one
ports:
- "8300:8000"
env_file: ./agent-one/.env
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/healthz"]
interval: 30s
retries: 3
agent-two:
build: ./agent-two
ports:
- "8301:8000"
env_file: ./agent-two/.env
Agent endpoints¶
Every generated agent exposes:
| Path | Auth | Description |
|---|---|---|
GET /healthz |
No | Health check |
GET /.well-known/agent.json |
No | Agent card (A2A discovery) |
POST /message |
Yes | A2A JSON-RPC 2.0 message endpoint |
A2A protocol¶
Agents communicate using JSON-RPC 2.0 with the message/send method:
If you test this request against a Dockerized target agent on localhost, run that agent in external network mode; see the agent template run instructions.
Request:
{
"jsonrpc": "2.0",
"method": "message/send",
"id": "req-1",
"params": {
"message": {
"messageId": "msg-1",
"role": "user",
"parts": [{"text": "{\"input_data\": \"value\"}"}]
}
}
}
Response:
{
"jsonrpc": "2.0",
"id": "req-1",
"result": {
"history": [
{
"role": "agent",
"parts": [{"text": "{\"status\": \"success\"}"}]
}
]
}
}
Development commands¶
From the agent-template/ directory:
make lint # Ruff linter
make format # Ruff formatter check
make typecheck # mypy on setup_agent.py
make fix # Auto-fix lint + format
make check # All checks
make test # Run pytest