Lesson 01 — Create an agent

You are here: Lesson 1 of 8 · ← Prerequisites · Hub · Next: Knowledge →

Goal

Register your first Aiden agent from Terraform: an sg_agent whose persona lives in a markdown file in Git.

What you will change

Why it matters

Clicking an agent together in the UI works for demos. Putting the same agent in Git means every change is reviewable, repeatable across tenants, and recoverable. That is Agent as Code.

ELI5: You wrote a character sheet (persona) and a name tag (sg_agent). Apply hangs the name tag in the office (Aiden). Edit the sheet, apply again — the character updates.

HCL — the agent

provider "sg" {
  stackgen_url   = var.stackgen_url
  stackgen_token = var.stackgen_token
  project_id     = var.stackgen_project_id != "" ? var.stackgen_project_id : null
}

resource "sg_agent" "tutor" {
  name        = "aac-tutor"
  description = "Agent as Code tutorial — lesson 01"
  persona     = file("${path.module}/personas/aac-tutor.md")
  # Optional: omit model_names to use Aiden's built-in base model.
  # model_names = compact(var.model_names)
}
Argument Meaning
name Stable identity in the tenant (and for later agent_ref)
persona System instructions — keep procedures in skills/runbooks later, not novels here
model_names Optional. Omit to use Aiden’s built-in base model; set to pin specific registered models

Lesson 01 does not require an LLM API key. Aiden ships with one base model. Lesson 04 teaches registering more models with raw sg_secret / sg_guild_model_*.

Apply & verify

cd examples/scenarios/agent-as-code/steps/01-agent
export TF_VAR_stackgen_url="https://your-tenant.example.com"
export TF_VAR_stackgen_token="sg_pat_..."
# Optional: pin a specific model instead of the built-in base model
# export TF_VAR_model_names='["your-existing-model-name"]'
tofu init
tofu plan
tofu apply
tofu output agent_name

Arrange: Aiden UI open, agent list visible.
Sample prompt (chat with aac-tutor):

Who are you, and how were you created?

Assert: Reply mentions Terraform / persona / Agent as Code.

Change as code (the punchline)

  1. Edit personas/aac-tutor.md (add one sentence).
  2. tofu apply again.
  3. Chat again with the same sample prompt — behavior should reflect the new persona.

Gotchas

  • Omitting model_names is fine — Aiden’s base model is used. Use TF_VAR_model_names only to pin another registered model, or Lesson 04 to add your own.
  • Persona files can hit length limits in larger agents — keep tutorial personas short.
  • Prefer file("${path.module}/personas/…") over huge inline strings.

Checkpoint

  • tofu apply succeeded and agent_name is aac-tutor
  • Chat works
  • You edited the persona and re-applied once

Next: Lesson 02 — Add knowledge