Side Quest: Agentic Workflow Security Architecture (Explain Like You're 5)

Optional: work through this visual primer if you want an intuitive mental model for why gh-aw uses a sandbox, where the agent runs, and what outputs are considered safe.

:clipboard: Before You Start

• You understand the basics of agentic workflows from What Are Agentic Workflows?.
• You have a workflow with permissions and tools frontmatter from Write Your First Agentic Workflow.
• You have started or are about to start Give Your Agent More Tools with MCP.

Think of your workflow like a smart helper in a playroom.

• The repository is your toy box.
• The agent is the helper who can look at toys and organize them.
• The sandbox is the play area boundary that keeps the helper from running into the street.

---

Why you need a sandbox

A powerful helper without boundaries can accidentally do unsafe things.

The sandbox gives your helper clear rules:

• It can only use the tools you allowed.
• It can only do actions covered by your declared permissions.
• It cannot reach random places outside the workflow environment.

Without a sandbox, one mistake could affect too much. With a sandbox, mistakes stay contained.

---

Where the agent is actually running

The agent does not run on your laptop by default. In this workshop flow, it runs inside a GitHub Actions job on a temporary runner.

That means:

• The environment is created for the run.
• The agent reads your workflow brief and repository context there.
• When the run ends, that runtime is discarded.

This design reduces long-lived risk because the environment is short-lived and isolated.

---

What "safe output" means

Safe output is useful information that avoids harmful leakage or unsafe actions.

Good output usually:

• Summarizes repository activity (issues, PRs, commits, CI status).
• Uses approved tool results and avoids guessing hidden data.
• Avoids secrets, tokens, credentials, and private personal data.
• Stays within the permissions and intent you defined.

---

Security architecture in one sentence

You declare permissions + tools + task intent, the runner enforces boundaries, and the agent produces constrained output from allowed data.

Here is what a well-scoped workflow frontmatter looks like in practice:

---
permissions:
  contents: read
  issues: read
tools:
  github:
    mode: gh-proxy
safe-outputs:
  add-comment: # presence flag — declares this output surface is allowed
network:
  allowed:
    - api.github.com
    - copilot-proxy.githubusercontent.com
---

:thinking: Predict: What would happen if you removed network.allowed from the frontmatter above and an injected prompt told the agent to send data to an external URL?

---

:white_check_mark: Checkpoint

• You can explain why sandbox boundaries reduce risk in agentic workflows
• You can describe where the agent runs during a workshop workflow execution
• You can list what makes an output safe vs. unsafe
• You can explain how permissions, tools, and task brief work together as a security architecture

---

Return to Give Your Agent More Tools with MCP.