Lesson 03 — Add an integration

You are here: Lesson 3 of 8 · ← Knowledge · Hub · Next: LLM model →

Goal

Create a GitHub integration with raw sg_* resources, attach it to aac-tutor so the agent can call that integration’s tools, and wire a GitHub knowledge source so the aac-docs base can sync real documents.

This series teaches Agent as Code the hard way: provider resources in your root, not wrapped aios-* modules.

What you will change

  • sg_secret — vault entry for the GitHub PAT
  • sg_integration — the GitHub integration itself
  • sg_agent.integrations — this is what makes the integration’s tools available to the agent
  • HITL allowlist for a safe starter tool (…_test_connection)
  • sg_knowledge_source pointing at a GitHub directory/file
  • Full root: steps/03-integration/

Why it matters

Listing an integration on an agent is how Aiden exposes that integration’s tool set in chat and workflows. The same GitHub credentials can also power a knowledge source that syncs docs — one wiring, two jobs.

Without integrations = […] on the agent, the integration may exist in the tenant but the agent cannot use its tools.

ELI5: You buy a toolbox (sg_integration) and put the key in the vault (sg_secret). Clipping the toolbox onto the agent’s belt (integrations = […]) is what lets it pick up the wrenches.

HCL — secret + integration + agent

resource "sg_secret" "github" {
  name        = "aac-github-vault"
  description = "GitHub PAT for the Agent as Code tutorial"
  category    = "SCM"
  subcategory = "github"
  metadata = {
    provider = "github"
    token    = var.github_token
  }
}

resource "sg_integration" "github" {
  name           = "aac-github"
  description    = "GitHub SCM for the Agent as Code tutorial"
  type           = "github"
  scope          = "PROJECT"
  secret_ref_ids = [sg_secret.github.id]
  enabled        = true

  image = {
    name = "ghcr.io/appcd-dev/stackgen-guild-integration-github:main"
  }
}

resource "sg_knowledge_source" "github" {
  knowledge_base_id = sg_knowledge_hub.docs.id
  type              = "github"
  name              = "aac-github-docs"
  integration_name  = sg_integration.github.name
  knowledge_type    = "KNOWLEDGE"
  targets           = var.knowledge_targets  # [{ target_type = "directory", input = "https://..." }]
}

resource "sg_agent" "tutor" {
  # ...
  # Attaching the integration here exposes its MCP tools to this agent.
  integrations = [sg_integration.github.name]

  hitl = {
    always_allowed = [
      # Tool names are ${integration_name}_${tool}.
      "${sg_integration.github.name}_test_connection",
    ]
  }
}

Default knowledge_targets points at this repo’s docs/ tree — override for private docs.

To reuse an integration that already exists, skip creating sg_secret / sg_integration and set integrations = ["my-existing-github"] (see the step folder’s create_github_integration flag).

Apply & verify

cd examples/scenarios/agent-as-code/steps/03-integration
export TF_VAR_github_token="ghp_..."
tofu init && tofu apply
tofu output github_integration_name

Arrange: GitHub integration visible in Aiden; aac-tutor lists it under integrations / available tools.

Sample prompts (chat with aac-tutor):

Test the GitHub connection for your integration and tell me if it succeeded.

Using knowledge, what does the Agent as Code tutorial say about skills sync? Cite the document path.

Assert: The agent can invoke a GitHub tool (not only answer from memory). Knowledge answers cite a path, or clearly say content is not synced yet.

Gotchas

  • Creating the integration alone is not enough — it must appear in sg_agent.integrations for that agent to call its tools.
  • HITL tool names are ${integration_name}_toolname. Tools not in always_allowed may prompt for approval.
  • Private repos need a PAT that can read them.
  • Later you can wrap this pattern in aios-integration-github; learn the resources first.

Checkpoint

  • sg_secret + sg_integration applied (or existing name reused)
  • Integration name listed on aac-tutor
  • Agent can use at least one GitHub tool (for example connection test)
  • Knowledge source created against aac-docs

Next: Lesson 04 — Add an LLM model