Agent anatomy - AgentGG

Examples

Example 1: A complete agent

This example shows every frontmatter field and a one-line prompt body.

---
slug: sql-injection
name: SQL Injection
description: SQL built from untrusted input instead of parameterized queries.
version: 0.1.0
author: your-github-handle
noiseTier: normal
precondition:                      # optional, omit to always run
  regex:
    patterns:
      - regex: "\\.(query|execute)\\s*\\("
        in: ["**/*.{ts,js,py,go,php}"]
  # prompt: "Run only if this project talks to a SQL database."   # optional LLM gate
where:
  extensions: [ts, js, py, go, php]
  excludePatterns: ["**/*.{test,spec}.*"]
  preFilter:
    - { regex: "\\.(query|execute)\\s*\\(", label: "raw SQL call" }
  maxFilesPerBatch: 3
  maxTurnsPerBatch: 40
validationPrompt: |                # optional, replaces the validator's default rules
  Return 'confirmed' when untrusted input reaches the query as concatenated SQL.
  Return 'false-positive' when the value is a bound parameter.
liveProofRule: |                   # optional, adds to the live proof rules
  The response must show data that the injected input selected.
liveReproducible: true             # optional, false skips live validation
references:
  - CWE-89
  - OWASP-A03:2021
---

You are reviewing source code for SQL injection...

Example 2: An agent with no file scope

This example declares no where block, so it has no file scope. Its scope is the whole repository, and it finds its own targets with Read, Glob, and Grep. See Agents with no file scope.

---
slug: no-authz-anywhere
name: No Authorization Layer Anywhere
description: The codebase has no authorization check on any route, not one route missing a check.
version: 0.1.0
author: your-github-handle
noiseTier: normal
precondition:
  prompt: "Run only if this project exposes at least one HTTP API."
references:
  - CWE-862
---

You are reviewing this entire repository for the absence of any
authorization layer...

This example leaves maxTurnsPerBatch out, so it gets 150 turns, the default for an agent with no file scope. The default is 50 for an agent with a file scope. A declared value wins over either default, so the agent in example 1 gets the 40 it asks for.

Frontmatter fields

Field	Required	Description
`slug`	Required	A unique identifier in kebab-case. The `-t` flag can select the agent by this value.
`name`	Required	A human-readable name for the agent.
`description`	Required	A one-line summary. The `agentgg agents list` command shows it.
`version`	Optional	A semantic version string, for example `0.1.0`. The default is `0.0.1`.
`author`	Optional	The author’s GitHub handle. Official agents use `agentgg`. The default is no author.
`noiseTier`	Optional	One of `precise`, `normal`, or `noisy`. See the table below. The default is `normal`.
`precondition`	Optional	A gate that decides whether the agent runs on a repository. Omit it to always run.
`where`	Optional	The files the agent scans, chosen by extension, glob, or a prefilter regex. Declaring neither `extensions` nor `filePatterns` leaves the agent with no file scope: its scope is the whole repository. See Targeting.
`validationPrompt`	Optional	Validation rules for this agent’s own findings. They replace the validator’s default rules whenever `--validate` classifies a finding this agent reported. See Agent-supplied validation rules. The default is the validator’s own rules.
`liveProofRule`	Optional	What a live test must show before a finding from this agent counts as reproduced. It adds to the general proof rules and never replaces them. Write one only when the general rules are not enough for the bug class, and state the rule itself. See Test findings against a running app. The default is the general rules only.
`liveReproducible`	Optional	Set it to `false` when the agent reports a missing control, such as a missing security header, that no attacker action can show in a browser. Live validation then skips the agent’s findings and records `not-reproducible`. The default is `true`.
`references`	Optional	A list of identifiers for triage, for example `CWE-89` or `OWASP-A03:2021`.

The slug rule

The slug value must match the filename. The filename must be <slug>.md.

noiseTier

The noiseTier field sets the false-positive rate to expect from the agent. It does not change how the agent runs.

Value	What to expect
`precise`	This tier has few false positives.
`normal`	This tier has a typical rate of false positives.
`noisy`	This tier has many false positives. Expect to dismiss some findings.