docs
// EEM Guides

Author a Chat Template

Chat templates pin the system prompt, the allowed tool set, and the approval cadence for a specific procedure. This walkthrough takes you from a blank page to a working, version-controlled template callable from any chat in your project. Expected time: 15 minutes.

Prerequisites

  • An API key with the management scope.
  • A working erectl install on your workstation (run erectl --version to confirm).
  • An operational workspace the chat will run tools in, served by an Erebine Execution Manager (EEM), and a chat workspace to hold the chat. Name either by its ws_ id or its name.
  • Familiarity with workspaces and approvals.

Scenario

Your team drains Kubernetes nodes for maintenance a couple of times a week. The procedure is repetitive: cordon the node, drain gracefully with a short grace period, verify no stuck pods, then proceed to maintenance. We will encode this procedure as a chat template so the next operator runs it with a consistent system prompt and an approval gate.

Step 1: Draft the Template

Create a file drain-node.json on your workstation.

json
{ "name": "drain-kubernetes-node", "scope": "project", "system_prompt": "You are a Kubernetes operator. When asked to drain a node, cordon it first, drain with grace-period 60, verify no stuck pods, and stop. If the drain fails, do not retry without human input.", "allowed_tools": [ "k8s_get_nodes", "k8s_describe_pod", "k8s_cordon_node", "k8s_drain_node" ], "approval_policy": "elevated", "metadata": { "description": "Safely drain a node for maintenance", "tags": ["kubernetes", "node-maintenance"] } }
  1. The system prompt is imperative and bounded: it states what to do, in what order, and what to refuse.
  2. The allowed_tools list is the full set of tools the model may call during a session bound to this template, nothing else. Tool names must match the platform registry exactly (the Kubernetes tool family uses the k8s_* prefix; see the Kubernetes tools reference for the full list).
  3. Destructive and irreversible tools always wait for approval, whatever the template's policy, so k8s_drain_node waits. The approval_policy value (standard, elevated or restricted) is recorded on every chat the template seeds and shown on the workspace page's Templates tab; it does not decide which calls wait.
  4. The scope field in the file is informational only. The effective scope is decided by the upload route: if you pass --workspace to erectl templates create the template is workspace-scoped, otherwise it is project-scoped. When the two disagree the route wins and the CLI prints a note.

Step 2: Upload the Template

bash
erectl templates create --file drain-node.json

Transcript on success:

text
template drain-kubernetes-node created version: 1 scope: project id: ctpl_01HX...

The CLI returns the template ID and the version. Every edit creates a new version; the ID is stable.

Step 3: Test Against a Chat

A chat cannot live in an operational workspace. Create the chat from the template in the chat workspace, then link it to the operational workspace where its tools run:

bash
erectl chat new --workspace team-chat --template drain-kubernetes-node --message "Drain node worker-07 for maintenance" erectl chats link-exec-workspace <chat_id> prod-k8s

chat new prints the new chat's chat_id. Both commands take a workspace's ws_ id or its name; find them with erectl workspaces list. See Connect a Chat to an EEM.

Watch the SSE output. The model will use the template's system prompt and work through the drain procedure. When it reaches k8s_drain_node, the router holds the invocation and emits an x_exec.approval_required event.

Approve it from another terminal. List the open approvals to find the id, then approve it with a short note (see Approvals for the full decision payload):

bash
erectl approvals list erectl approvals approve <approval_id> --note "Scheduled maintenance for worker-07"

Step 4: Iterate and Version

You noticed during testing that the system prompt is not explicit about which namespaces are in scope. Edit drain-node.json:

json
{ ... "system_prompt": "You are a Kubernetes operator. When asked to drain a node, cordon it first, drain with grace-period 60, verify no stuck pods in any namespace, and stop. Assume cluster-wide namespace scope unless the operator restricts it.", ... }

Push the update:

bash
erectl templates update drain-kubernetes-node --file drain-node.json

Version 2 replaces version 1 as the active version. New chats pick up version 2 automatically; in-flight chats keep the version they started on.

Step 5: Promote Platform-Wide

Other projects in your organization could use this template too. Promote it from project scope to platform scope:

bash
erectl templates promote drain-kubernetes-node --scope platform

Platform-scope templates are visible to every project in the deployment. Promotion is one-way: platform scope cannot be demoted without deleting and recreating at project scope.

Next Steps

  • Publish more templates and keep them together in a git repository; synchronize with erectl templates apply-from-dir <directory> (the directory is a positional argument; add --workspace ws_<hex> for workspace-scoped syncs). The command walks every *.json file in the directory and reports each one as created (new name), updated (existing name with changed fields), or unchanged (existing name with identical fields), no template is ever deleted by this command.
  • See Approvals for tuning the workspace approval policy's SLA and escalation chain.
  • Browse the built-in tool catalog -- Cloud, Kubernetes, OpenStack, and Ecosystem, to find tool names your templates can reference.