terraform-provider-stackgen

sg_agent (Resource)

⚠️ Experimental — This resource is part of the Guild platform and may change in future releases.

Manages a StackGen AI agent. Agents are registered with the Guild platform and can be governed by policies attached via sg_agent_policy_attachment.

409 conflict adoption is controlled by the provider attribute adopt_on_conflict (default true).

Import using the agent name.

Example Usage

# When to use: Start with a bare agent when you only need a named target for
# webhooks, schedules, or workflow stage_bindings. Add persona/models/integrations
# later (see resource_extended.tf) once the agent should talk to tools/LLMs.
#
# Prefer data.sg_agent when the agent is owned by an installed app (e.g. SRE
# investigator) and this stack should not recreate it.
#
# Related: sg_guild_model (+ provider), sg_guild_integration, sg_agent_policy_attachment,
# sg_agent_budget, sg_workflow, sg_webhook, sg_agent_schedule, sg_remote_runner.
resource "sg_agent" "example" {
  name = "my-first-agent"
}

# HITL bypass rules (Guild AutoApproveToolRule). Use tool wildcards for integration prefixes.
resource "sg_agent" "example_auto_approve" {
  name = "mcp-consumer"

  auto_approve_tools = [
    { tool = "terraform_plan" },
    { tool = "stackgen-mcp_*" },
    {
      tool              = "browser_navigate"
      when_args_contain = jsonencode({ url = "https://internal.example.com" })
    },
  ]
}

# When to use: Mid-complexity agent with tools, tags, models, integrations, and
# middleware context budgets. Prefer resource_production.tf when you also need
# diary / PII / remote runners.
#
# Agent with tools, tags, models, and integrations (Guild — experimental).
resource "sg_agent" "example_full" {
  name        = "infra-bot"
  description = "Answers infra questions and runs approved tools."
  persona     = "You are an SRE assistant with read-only production access."

  tools = ["kubectl_get", "terraform_plan"]
  auto_approve_tools = [
    { tool = "kubectl_get" },
  ]
  auto_deny_tools = ["terraform_apply"]
  tags            = ["sre", "production"]
  model_names     = ["gpt-4o"]
  integrations    = ["slack"]

  knowledge = {
    memory_enabled = true
  }

  middleware = {
    # Compress oversized tool output locally, but give observability queries a
    # larger evidence budget than the global defaults.
    context_mode = {
      threshold  = 10000
      max_chunks = 10
      per_tool = {
        "*_observability_query" = {
          threshold  = 50000
          max_chunks = 40
          chunk_size = 1200
        }
      }
    }
  }
}

# When to use: Production-shaped agent with persona, models, integrations,
# remote runners, diary summarization, and PII overlays. Create models and
# integrations first (Layer 0–1), then attach this agent (Layer 2).
#
# Prerequisites: sg_guild_model names in model_names; integration names that
# already exist; optional remote runner names/IDs.
resource "sg_agent" "example_production" {
  name           = "sre-copilot"
  description    = "On-call assistant with read-only cloud and observability tools."
  persona        = "You are an SRE assistant. Prefer evidence over speculation. Never mutate production without HITL."
  model_names    = ["gpt-4o-default"]
  integrations   = ["example-grafana", "example-aws", "example-slack"]
  remote_runners = ["onprem-runner"]
  tags           = ["sre", "production"]

  auto_approve_tools = [
    { tool = "grafana_*" },
    { tool = "kubectl_get" },
  ]
  auto_deny_tools = ["terraform_apply", "kubectl_delete"]

  knowledge = {
    memory_enabled = true
  }

  diary = {
    enabled               = true
    compression           = "relaxed"
    max_sample_events     = 50
    max_error_warn_events = 25
    max_payload_bytes     = 262144
    max_episodic_entries  = 20
    max_feedback_entries  = 10
  }

  pii_redaction = {
    enabled = true
    deny = [
      {
        name    = "password-assignment"
        pattern = "(?i)password\\s*[:=]\\s*\\S+"
      },
    ]
  }
}

Import

Import an existing sg_agent using its name:

terraform import sg_agent.example 'my-first-agent'

Operational notes

Attach only integration names already registered in the same organization. model_names must likewise refer to existing Guild models; provision those first. Imported agents should be refreshed before changing nested configuration.

Schema

Required

Optional

Read-Only

Nested Schema for auto_approve_tools

Required:

Optional:

Nested Schema for autonomy_budget

Optional:

Nested Schema for diary

Optional:

Nested Schema for eval

Optional:

Nested Schema for hitl

Optional:

Nested Schema for knowledge

Optional:

Nested Schema for middleware

Optional:

Nested Schema for middleware.circuit_breaker

Optional:

Nested Schema for middleware.concurrency

Optional:

Nested Schema for middleware.context_mode

Optional:

Nested Schema for middleware.context_mode.per_tool

Optional:

Nested Schema for middleware.metrics

Optional:

Nested Schema for middleware.retry

Optional:

Nested Schema for middleware.sanitize

Optional:

Nested Schema for middleware.timeout

Optional:

Nested Schema for middleware.tracing

Optional:

Nested Schema for middleware.validation

Optional:

Nested Schema for model_config

Optional:

Nested Schema for model_config.providers

Required:

Optional:

Nested Schema for pii_redaction

Optional:

Nested Schema for pii_redaction.allow

Required:

Nested Schema for pii_redaction.deny

Required:

Nested Schema for rca

Optional:

Nested Schema for rca.git

Optional:

Nested Schema for runbook

Optional:

Nested Schema for runbook.git

Optional:

Nested Schema for autonomy_tier_snapshot

Read-Only: