Lesson 08 — Create a runbook and attach it to the agent

You are here: Lesson 8 of 8 · ← Second agent · Hub

Goal

Author a new runbook SOP (aac-signoff) and attach it to the tutor agent’s work by listing it on the greet stage’s runbook_refs (and optionally on the workflow).

What you will change

  • New templates/signoff.md + sg_runbook_sop.signoff
  • Expand stage_bindings for greet to include both SOPs
  • Optional sg_workflow.runbook_refs catalog
  • Full root: steps/08-runbook-attach/

Why it matters

“Attach a runbook to an agent” in Agent as Code means: bind the SOP to the workflow stage that agent runs. This repository does not set runbook_refs on sg_agent itself — stages are the attachment point.

ELI5: The script (runbook) is clipped to the scene (stage). The actor (agent) who plays that scene gets the script automatically.

HCL — create and attach

resource "sg_runbook_sop" "signoff" {
  name        = "aac-signoff"
  approve     = true
  description = trimspace(templatefile("${path.module}/templates/signoff.md", {}))
}

resource "sg_workflow" "tutorial" {
  # Optional workflow-level catalog:
  runbook_refs = [
    sg_runbook_sop.greet.name,
    sg_runbook_sop.signoff.name,
    sg_runbook_sop.research.name,
  ]

  stage_bindings = [
    {
      stage_id  = "greet"
      agent_ref = sg_agent.tutor.name
      runbook_refs = [
        sg_runbook_sop.greet.name,
        sg_runbook_sop.signoff.name, # attached to tutor's stage
      ]
      skill_refs = ["aac-hello"]
    },
    # research binding unchanged...
  ]
}

Apply & verify

cd examples/scenarios/agent-as-code/steps/08-runbook-attach
tofu init && tofu apply
tofu output tutor_stage_runbooks

Arrange: Workflow greet stage lists both aac-greet and aac-signoff.

Sample prompt (run aac-tutorial-workflow):

Say hello using the tutorial skill, then research Agent as Code from knowledge.

Assert: Greeting appears, then the sign-off line:

— signed off by aac-tutor (Agent as Code)

Then the research stage summary (or empty-KB honesty).

Gotchas

  • Adding a SOP resource without putting it in runbook_refs creates the document but does not inject it into a stage.
  • knowledge_type = "RUNBOOK" on a GitHub source is a different path (sync files as SOPs) — this lesson uses declared sg_runbook_sop resources.
  • Chat-only agents without a workflow do not get stage runbooks; wrap a one-stage workflow when you need a pinned SOP.

Checkpoint

  • aac-signoff exists
  • Tutor greet stage lists both runbooks
  • Workflow run shows sign-off line

Series complete

You now have Agent as Code end-to-end: agent → knowledge → integration → models → skill → workflow → multi-agent → runbook attach.

Where next