deploy-ai-agent

name	deploy-ai-agent
description	Deploy and manage AI agent workloads with GPU checks, API key management, and health monitoring
activation	auto
tools	["app_deploy","app_list","app_logs","app_stop","app_restart","app_remove","system_discover","system_health","system_query","shell_exec","file_write","file_read","memory_store","journal_logs","watcher_add"]

Deploy AI Agent

Deploy AI agent workloads (LangChain, CrewAI, AutoGen, custom frameworks) as managed systemd services with resource monitoring, API key management, and health checks.

Deploy Workflow

1. Understand — Ask what agent framework they're using and what it needs (model provider, API keys, GPU, dependencies)
2. Check resources — Use system_health to verify RAM, disk, and CPU are sufficient. Check for GPU with shell_exec running nvidia-smi or ls /dev/dri
3. Set up environment — Create a Python venv, install Node.js deps, or verify Go binary. Write API keys to the secrets directory.
4. Deploy — Use app_deploy with appropriate resource limits, environment variables pointing to secrets, and a health-check-friendly port
5. Verify — Check app_logs for successful startup. Use system_discover to confirm the agent's port is listening.
6. Monitor — Set up a watcher via watcher_add to auto-restart on failure
7. Remember — Use memory_store to save deployment details for future reference

Common Patterns

FastAPI Agent Server (LangChain / LangServe)

app_deploy({
  name: "my-agent",
  command: "/var/lib/osmoda/apps/my-agent/venv/bin/uvicorn",
  args: ["app:app", "--host", "0.0.0.0", "--port", "8000"],
  working_dir: "/var/lib/osmoda/apps/my-agent",
  env: {
    ANTHROPIC_API_KEY_FILE: "/var/lib/osmoda/secrets/anthropic-key",
    OPENAI_API_KEY_FILE: "/var/lib/osmoda/secrets/openai-key"
  },
  port: 8000,
  memory_max: "1G",
  cpu_quota: "200%"
})

CrewAI Kickoff

app_deploy({
  name: "crew-agent",
  command: "/var/lib/osmoda/apps/crew-agent/venv/bin/python",
  args: ["-m", "crew_agent.main"],
  working_dir: "/var/lib/osmoda/apps/crew-agent",
  env: {
    ANTHROPIC_API_KEY_FILE: "/var/lib/osmoda/secrets/anthropic-key"
  },
  port: 8001,
  memory_max: "2G"
})

Custom Node.js Agent

app_deploy({
  name: "node-agent",
  command: "/usr/bin/node",
  args: ["index.js"],
  working_dir: "/home/user/agent",
  env: {
    NODE_ENV: "production",
    PORT: "3000",
    API_KEY_FILE: "/var/lib/osmoda/secrets/agent-api-key"
  },
  port: 3000,
  memory_max: "512M"
})

API Key Management

Never put API keys in environment variables directly. Write them to the secrets directory:

1. Ask the user for their API key
2. file_write to /var/lib/osmoda/secrets/<key-name> (0600 permissions)
3. Pass the file path as an env var (*_FILE convention) or read it in the app's entrypoint
4. The app reads the key from disk at startup

Resource Checklist

Before deploying, verify:

Resource	Check	Minimum
RAM	system_health → memory_available	1 GB free for small agents, 4 GB+ for GPU workloads
Disk	system_health → disks[0].available	2 GB for deps + model cache
CPU	system_health → cpu_usage	2+ cores recommended
GPU	shell_exec: nvidia-smi or ls /dev/dri	Optional — needed for local model inference
Python	shell_exec: python3 --version	3.10+ for most frameworks
Node.js	shell_exec: node --version	18+ for modern agent frameworks

Health Monitoring

After deployment, set up a watcher:

watcher_add({
  name: "my-agent-health",
  check: {
    type: "http_get",
    url: "http://127.0.0.1:8000/health",
    expected_status: 200
  },
  interval_secs: 30,
  actions: ["restart", "notify"]
})

For agents without HTTP endpoints, use a process check:

watcher_add({
  name: "my-agent-alive",
  check: {
    type: "systemd_unit",
    unit: "osmoda-app-my-agent.service"
  },
  interval_secs: 60,
  actions: ["restart", "notify"]
})

Troubleshooting

• Agent won't start — Check app_logs({ name: "my-agent", lines: 50 }) for Python import errors or missing dependencies
• Out of memory — Increase memory_max or check if the model is too large for available RAM
• API key errors — Verify the key file exists and is readable: file_read({ path: "/var/lib/osmoda/secrets/anthropic-key" })
• Port already in use — Use system_discover to find what's on that port, then pick another