Deploying Agents Best Practices

Ten practices for choosing a host, packaging the runtime, and hardening secrets so agent workloads stay within time, budget, and blast-radius limits.

Use this list when you first ship an agent or when timeouts, leaks, or surprise bills force a re-platform.

How to Use This Checklist

Work top to bottom: placement before polish.
Tick items only when true in production (or staging with prod-like config).
Re-run after model, tool, or platform limit changes.
Assign an owner for every unchecked item.

A - Placement and Runtime Shape

1. Choose the target from workload shape, not habit. Map duration, tools, and state needs to serverless, container, or VPS (Choosing a Deployment Target for an Agent Workload).
2. Keep intake fast when work is slow. Accept → queue → worker when loops exceed function timeouts (Cold Starts and Long-Running Agent Loops: A Serverless Mismatch).
3. Bound every run. Max turns, app-level deadline below platform max, max tokens, and dollar or tool-call budgets.

B - Packaging and Process

4. Ship immutable artifacts. Docker tags or function versions pinned to git SHA; never "only latest" in prod (Containerizing an Agent with Docker).
5. Health checks must be cheap. /healthz without model calls; process managers restart on failure (Long-Running Agents on a VPS: Process Management and Restarts).
6. Externalize session and job state. Survive cold starts, multi-instance deploys, and reboots without amnesia.

C - Secrets and Safety

7. Separate secrets per environment and risk tier. No shared prod keys in preview; least-privilege tool credentials (Environment and Secrets Management Across Deployment Targets).
8. Make tools safe under retry. Idempotency keys and checkpointing so timeouts do not double-apply side effects.

D - Observe and Evolve

9. Log stop reasons and cost drivers. completed | app_deadline | platform_timeout | provider_error; model, tokens, latency per step.
10. Rehearse deploy, rollback, and key rotation. CI gates and rollback paths for prompt/config/code (CI/CD and Agent Lifecycle Basics).

Applying the Habits in Order

Stage	Habits	Exit criterion
Design	1-3	Target chosen; duration budget written; stop conditions defined
Package	4-6	Immutable artifact; health; external state
Harden	7-8	Key topology + idempotent tools
Operate	9-10	Metrics, drills, rollback proven

Quick Anti-Patterns

Multi-minute ReAct loop on a short serverless timeout with no queue.
API keys baked into Docker layers or committed .env.
In-memory chat history as the only session store.
One unlimited provider key for dev, CI, and prod.
Health probes that call the LLM.
Client retries without idempotency on write tools.
No max-turn guard "because the model usually stops."
Production deploys that cannot roll back to a prior image/version.

Minimal Reference Layout

repo/
  Dockerfile                 # multi-stage, non-root
  .dockerignore              # excludes .env
  .env.example               # names only
  src/agent_app.py           # bounds + deadlines
  deploy/
    systemd/agent.service    # or k8s/lambda/vercel config
    README.md                # env matrix + rollback

# pattern: fail closed + bound
import os
 
if os.getenv("APP_ENV") == "production":
    assert os.getenv("OPENROUTER_API_KEY"), "missing key"
 
MAX_TURNS = int(os.getenv("AGENT_MAX_TURNS", "8"))
# loop with turn < MAX_TURNS and deadline.remain() > margin

FAQs

Which three habits are non-negotiable?

Workload-matched placement (1), run bounds (3), and per-environment secrets (7). Everything else amplifies those.

Can best practices differ for personal bots vs SaaS?

Yes on scale and multi-tenancy, not on secret hygiene or restart discipline. Personal bots still need process managers and key caps.

Do we need Kubernetes to be "production"?

No. Production means observability, rollback, secrets, and SLOs - on a VPS, PaaS, or cluster.

How often should we revisit placement?

After timeout incidents, 10× traffic, new heavy tools (browser/GPU), or cost cliffs. At least when annual planning resets budgets.

Where do evals fit?

As a deploy gate: latency and success thresholds must pass before artifacts promote (Running Eval Suites as a CI Gate Before Deploy).

Is scale-to-zero always cheaper?

Only if cold starts and timeouts do not destroy conversion or burn retries. Model fully loaded cost per successful task.

Should every agent be a container?

Containers are the best default portable unit, but pure functions are fine for short stateless turns. Avoid religious packaging.

How does this relate to security checklists?

This page is runtime placement and ops. Pair with Security Checklist Before Shipping an Agent to Production for tool and sandbox controls.

Related: Choosing a Deployment Target for an Agent Workload

Related: Deploying Agents Basics

Related: Containerizing an Agent with Docker

Related: Deploying an Agent to Vercel or AWS Lambda Serverless Functions

Related: Long-Running Agents on a VPS: Process Management and Restarts

Related: Cold Starts and Long-Running Agent Loops: A Serverless Mismatch

Related: Environment and Secrets Management Across Deployment Targets

Related: CI/CD and Agent Lifecycle Basics

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Deploying Agents Best Practices

Ten practices for choosing a host, packaging the runtime, and hardening secrets so agent workloads stay within time, budget, and blast-radius limits.

Use this list when you first ship an agent or when timeouts, leaks, or surprise bills force a re-platform.

How to Use This Checklist

Work top to bottom: placement before polish.
Tick items only when true in production (or staging with prod-like config).
Re-run after model, tool, or platform limit changes.
Assign an owner for every unchecked item.

A - Placement and Runtime Shape

1. Choose the target from workload shape, not habit. Map duration, tools, and state needs to serverless, container, or VPS (Choosing a Deployment Target for an Agent Workload).
2. Keep intake fast when work is slow. Accept → queue → worker when loops exceed function timeouts (Cold Starts and Long-Running Agent Loops: A Serverless Mismatch).
3. Bound every run. Max turns, app-level deadline below platform max, max tokens, and dollar or tool-call budgets.

B - Packaging and Process

4. Ship immutable artifacts. Docker tags or function versions pinned to git SHA; never "only latest" in prod (Containerizing an Agent with Docker).
5. Health checks must be cheap. /healthz without model calls; process managers restart on failure (Long-Running Agents on a VPS: Process Management and Restarts).
6. Externalize session and job state. Survive cold starts, multi-instance deploys, and reboots without amnesia.

C - Secrets and Safety

7. Separate secrets per environment and risk tier. No shared prod keys in preview; least-privilege tool credentials (Environment and Secrets Management Across Deployment Targets).
8. Make tools safe under retry. Idempotency keys and checkpointing so timeouts do not double-apply side effects.

D - Observe and Evolve

9. Log stop reasons and cost drivers. completed | app_deadline | platform_timeout | provider_error; model, tokens, latency per step.
10. Rehearse deploy, rollback, and key rotation. CI gates and rollback paths for prompt/config/code (CI/CD and Agent Lifecycle Basics).

Applying the Habits in Order

Stage	Habits	Exit criterion
Design	1-3	Target chosen; duration budget written; stop conditions defined
Package	4-6	Immutable artifact; health; external state
Harden	7-8	Key topology + idempotent tools
Operate	9-10	Metrics, drills, rollback proven

Quick Anti-Patterns

Multi-minute ReAct loop on a short serverless timeout with no queue.
API keys baked into Docker layers or committed .env.
In-memory chat history as the only session store.
One unlimited provider key for dev, CI, and prod.
Health probes that call the LLM.
Client retries without idempotency on write tools.
No max-turn guard "because the model usually stops."
Production deploys that cannot roll back to a prior image/version.

Minimal Reference Layout

repo/
  Dockerfile                 # multi-stage, non-root
  .dockerignore              # excludes .env
  .env.example               # names only
  src/agent_app.py           # bounds + deadlines
  deploy/
    systemd/agent.service    # or k8s/lambda/vercel config
    README.md                # env matrix + rollback

# pattern: fail closed + bound
import os
 
if os.getenv("APP_ENV") == "production":
    assert os.getenv("OPENROUTER_API_KEY"), "missing key"
 
MAX_TURNS = int(os.getenv("AGENT_MAX_TURNS", "8"))
# loop with turn < MAX_TURNS and deadline.remain() > margin

FAQs

Which three habits are non-negotiable?

Workload-matched placement (1), run bounds (3), and per-environment secrets (7). Everything else amplifies those.

Can best practices differ for personal bots vs SaaS?

Yes on scale and multi-tenancy, not on secret hygiene or restart discipline. Personal bots still need process managers and key caps.

Do we need Kubernetes to be "production"?

No. Production means observability, rollback, secrets, and SLOs - on a VPS, PaaS, or cluster.

How often should we revisit placement?

After timeout incidents, 10× traffic, new heavy tools (browser/GPU), or cost cliffs. At least when annual planning resets budgets.

Where do evals fit?

As a deploy gate: latency and success thresholds must pass before artifacts promote (Running Eval Suites as a CI Gate Before Deploy).

Is scale-to-zero always cheaper?

Only if cold starts and timeouts do not destroy conversion or burn retries. Model fully loaded cost per successful task.

Should every agent be a container?

Containers are the best default portable unit, but pure functions are fine for short stateless turns. Avoid religious packaging.

How does this relate to security checklists?

This page is runtime placement and ops. Pair with Security Checklist Before Shipping an Agent to Production for tool and sandbox controls.

Related: Choosing a Deployment Target for an Agent Workload

Related: Deploying Agents Basics

Related: Containerizing an Agent with Docker

Related: Deploying an Agent to Vercel or AWS Lambda Serverless Functions

Related: Long-Running Agents on a VPS: Process Management and Restarts

Related: Cold Starts and Long-Running Agent Loops: A Serverless Mismatch

Related: Environment and Secrets Management Across Deployment Targets

Related: CI/CD and Agent Lifecycle Basics

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Deploying Agents Best Practices

Search Documentation

Deploying Agents Best Practices