Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (55 loc) · 4.42 KB

AGENTS.md

File metadata and controls

75 lines (55 loc) · 4.42 KB

Agentic Starter Kits

Collection of production-ready LLM agent templates for Red Hat OpenShift (LangGraph, LlamaIndex, CrewAI, AutoGen, Langflow, Google ADK, and more). See agents/ for the full list. Most agents share a common FastAPI API contract and Helm-based deployment; see Non-standard agents for exceptions.

Structure

  • agents/<framework>/templates/<agent_name>/ - self-contained agent templates (Makefile, Dockerfile, pyproject.toml, src/, tests/)
  • agents/<framework>/examples/<agent_name>/ - business use-case demos built on templates
  • agents/<framework>/deployment/ - per-framework Helm charts for deployment
  • components/<component_name>/ - shared reusable Python packages (for cross-agent concerns like auth/tracing)
  • docs/ - guides for local dev, deployment, and adding new agents

Commands

# Run from any standard agent directory (e.g., agents/langgraph/templates/react_agent/)
make init       # create .env from .env.example
make env        # create venv + install deps with uv
make run-app    # start FastAPI dev server (port 8000)
make test       # run pytest
make build      # build container image (podman/docker)
make push       # pushes to the registry specified in CONTAINER_IMAGE
make deploy     # deploy to OpenShift/K8s via Helm
make dry-run    # preview Helm manifests

Code style

  • Python >=3.12, <3.14. Use uv as package manager -- never pip directly
  • FastAPI for all web endpoints
  • All agents must expose POST /chat/completions (JSON + SSE) and GET /health
  • Source code in src/<agent_name>/ within each agent directory
  • Keep agents self-contained -- never import from another agent's src/
  • Shared cross-agent code belongs in components/ and should be consumed as package dependencies (not path imports into agent src/)

Workflow

  • cd into the agent directory first -- Makefiles use relative paths and read agent.yaml at runtime
  • Check agent.yaml to discover required env vars before editing .env.example
  • Run make test before committing (prefer over bare pytest). Some agents have placeholder tests only -- check before assuming coverage
  • Never commit .env files -- only .env.example templates
  • Standard containers: UBI9 base (registry.access.redhat.com/ubi9/python-312), non-root UID 1001, port 8080

Boundaries

  • Don't modify agents/<framework>/deployment/ chart templates unless explicitly requested
  • Don't modify CONTRIBUTING.md, CI config, or root Makefile without asking
  • Don't refactor other agents when working on one agent
  • Don't change the API contract (POST /chat/completions, GET /health) without discussion
  • When unsure if an agent is standard, check its Makefile and Dockerfile first

Non-standard agents

Several agents diverge significantly from the standard pattern:

langflow/templates/simple_tool_calling_agent - Podman Compose flow-import deployment, not standalone FastAPI. No Dockerfile, pyproject.toml, main.py, src/, or tests/. Different Makefile targets (init, ollama, run, stop, clean). Uses infra-only env vars (PostgreSQL, Langfuse, Ollama) -- not API_KEY/BASE_URL/MODEL_ID.

a2a/templates/langgraph_crewai_agent - Uses python:3.12-slim (not UBI9), PYTHONPATH /app (not /opt/app-root/src), agents/a2a/deployment/ chart, template.env (not .env.example), entrypoint.sh (not main.py), Starlette (not FastAPI). No tests/ directory.

openclaw/deployment - Kustomize-based deployment of OpenClaw on OpenShift. Uses pre-built image (ghcr.io/openclaw/openclaw:latest), not a Dockerfile. Kustomize overlays for customization (model endpoint, storage class). No Makefile, no FastAPI, no src/. Port 18789 (gateway).

Common gotchas

  • agent.yaml is read at runtime by Makefile -- if malformed, all make targets break
  • Port mapping: local dev = 8000, container = 8080, Llama Stack = 8321 -- don't mix these up
  • images/ dir is copied into build context temporarily by make build -- don't put large files there
  • Makefile auto-detects podman over docker -- set CONTAINER_CLI to override
  • Helm secrets via .helm-secrets.yaml (generated by Makefile, never committed)

References