Skip to content

[docs] Unbloat deterministic-agentic-patterns.md documentation #11293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 1 commit into from
Jan 22, 2026
Merged

[docs] Unbloat deterministic-agentic-patterns.md documentation #11293

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 25 additions & 133 deletions docs/src/content/docs/guides/deterministic-agentic-patterns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,11 @@ sidebar:
order: 6
---

GitHub Agentic Workflows combine deterministic computation with AI reasoning. This enables data preprocessing, custom trigger filtering, and post-processing patterns.
GitHub Agentic Workflows combine deterministic computation with AI reasoning, enabling data preprocessing, custom trigger filtering, and post-processing patterns.

## When to Use This Pattern
## When to Use

Use deterministic steps with AI agents to:

- Precompute data to ground AI with structured context
- Filter triggers with custom logic
- Preprocess inputs before AI consumption
- Post-process AI output deterministically
- Build multi-stage computation and reasoning pipelines
Combine deterministic steps with AI agents to precompute data, filter triggers, preprocess inputs, post-process outputs, or build multi-stage computation and reasoning pipelines.

## Architecture

Expand All @@ -41,47 +35,34 @@ Define deterministic jobs in frontmatter alongside agentic execution:
└────────────────────────┘
```

## Basic Example: Precomputation

Prepare data for the AI agent:
## Precomputation Example

```yaml wrap title=".github/workflows/release-highlights.md"
---
on:
push:
tags:
- 'v*.*.*'
tags: ['v*.*.*']
engine: copilot
safe-outputs:
update-release:

steps:
- name: Fetch release data
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
- run: |
gh release view "${GITHUB_REF#refs/tags/}" --json name,tagName,body > /tmp/gh-aw/agent/release.json
gh pr list --state merged --limit 100 --json number,title,labels > /tmp/gh-aw/agent/prs.json
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
---

# Release Highlights Generator

Generate engaging release highlights for version `${GITHUB_REF#refs/tags/}`.

The agent has access to precomputed data in `/tmp/gh-aw/agent/`:
- `release.json` - Release metadata
- `prs.json` - Merged PRs

Analyze the PRs, categorize changes, and use the update-release tool
to prepend highlights to the release notes.
Generate release highlights for `${GITHUB_REF#refs/tags/}`. Analyze PRs in `/tmp/gh-aw/agent/prs.json`, categorize changes, and use update-release to prepend highlights to the release notes.
```

Files in `/tmp/gh-aw/agent/` are automatically uploaded as workflow artifacts, making them available to the AI agent and subsequent jobs.
Files in `/tmp/gh-aw/agent/` are automatically uploaded as artifacts and available to the AI agent.

## Multi-Job Pattern

Define multiple deterministic jobs with dependencies:

```yaml wrap title=".github/workflows/static-analysis.md"
---
on:
Expand All @@ -98,25 +79,21 @@ jobs:
- run: ./gh-aw compile --zizmor --poutine > /tmp/gh-aw/agent/analysis.txt

steps:
- name: Download analysis
uses: actions/download-artifact@v6
- uses: actions/download-artifact@v6
with:
name: analysis-results
path: /tmp/gh-aw/
---

# Static Analysis Report

Parse the findings in `/tmp/gh-aw/agent/analysis.txt`, cluster by severity,
and create a discussion with fix suggestions.
Parse findings in `/tmp/gh-aw/agent/analysis.txt`, cluster by severity, and create a discussion with fix suggestions.
```

Custom jobs pass data through artifacts, job outputs, or environment variables.
Pass data between jobs via artifacts, job outputs, or environment variables.

## Custom Trigger Filtering

Use deterministic `steps:` for custom trigger logic:

```yaml wrap title=".github/workflows/smart-responder.md"
---
on:
Expand All @@ -127,8 +104,7 @@ safe-outputs:
add-comment:

steps:
- name: Filter issues
id: filter
- id: filter
run: |
if echo "${{ github.event.issue.body }}" | grep -q "urgent"; then
echo "priority=high" >> "$GITHUB_OUTPUT"
Expand All @@ -139,15 +115,11 @@ steps:

# Smart Issue Responder

Respond to urgent issue: "${{ github.event.issue.title }}"

Priority: ${{ steps.filter.outputs.priority }}
Respond to urgent issue: "${{ github.event.issue.title }}" (Priority: ${{ steps.filter.outputs.priority }})
```

## Post-Processing Pattern

Use custom safe output jobs for deterministic post-processing:

```yaml wrap title=".github/workflows/code-review.md"
---
on:
Expand All @@ -161,9 +133,7 @@ safe-outputs:
description: "Format and post review"
runs-on: ubuntu-latest
inputs:
summary:
required: true
type: string
summary: {required: true, type: string}
steps:
- run: |
echo "## 🤖 AI Code Review\n\n${{ inputs.summary }}" > /tmp/report.md
Expand All @@ -174,34 +144,12 @@ safe-outputs:

# Code Review Agent

Review the pull request and use the format-and-notify tool to post your summary.
Review the pull request and use format-and-notify to post your summary.
```

## Importing Shared Steps
## Importing Shared Instructions

Define reusable steps in shared files:

```yaml wrap title=".github/workflows/shared/reporting.md"
---
---

## Report Formatting

Structure reports with an overview followed by expandable details:

```markdown
Brief overview paragraph.

<details>
<summary><b>Full Details</b></summary>

Detailed content here.

</details>
```
```

Import in workflows:
Define reusable guidance in shared files and import them:

```yaml wrap title=".github/workflows/analysis.md"
---
Expand All @@ -216,83 +164,27 @@ safe-outputs:

# Daily Analysis

Follow the report formatting guidelines from the imported instructions.
```

## Pattern Examples

### Release Workflow
`.github/workflows/release.md` - Multi-job pipeline with AI highlights generation

```yaml
jobs:
release: # Build binaries
generate-sbom: # Security manifests
# Agent generates release highlights
```

### Static Analysis Report
`.github/workflows/static-analysis-report.md` - Run scanners then AI analysis

```yaml
steps:
- Run ./gh-aw compile with security tools
- Save to /tmp/gh-aw/agent/analysis.txt
# Agent clusters findings, creates discussion
Follow the report formatting guidelines from shared/reporting.md.
```

## Agent Data Directory

The `/tmp/gh-aw/agent/` directory is the standard location for sharing data with AI agents:
Use `/tmp/gh-aw/agent/` to share data with AI agents. Files here are automatically uploaded as artifacts and accessible to the agent:

```yaml
steps:
- name: Prepare data
run: |
- run: |
gh api repos/${{ github.repository }}/issues > /tmp/gh-aw/agent/issues.json
gh api repos/${{ github.repository }}/pulls > /tmp/gh-aw/agent/pulls.json
```

**Key features:**
- Files in this directory are automatically uploaded as workflow artifacts
- The agent has read access to all files in `/tmp/gh-aw/agent/`
- Use for JSON data, text files, or any structured content the agent needs
- Directory is created automatically by the workflow runtime

**Example prompt reference:**

```markdown
Analyze the issues in `/tmp/gh-aw/agent/issues.json` and pull requests
in `/tmp/gh-aw/agent/pulls.json`. Summarize the top 5 most active threads.
```
Reference in prompts: "Analyze issues in `/tmp/gh-aw/agent/issues.json` and PRs in `/tmp/gh-aw/agent/pulls.json`."

## Best Practices

Store data in `/tmp/gh-aw/agent/` for automatic artifact upload:

```bash
gh api repos/${{ github.repository }}/issues > /tmp/gh-aw/agent/issues.json
```

Define job dependencies with `needs:`:

```yaml
jobs:
fetch-data:
steps: [...]
process-data:
needs: [fetch-data]
steps: [...]
```

Pass data via environment variables:

```yaml
steps:
- run: echo "RELEASE_TAG=v1.0.0" >> "$GITHUB_ENV"
```
**Data sharing**: Store data in `/tmp/gh-aw/agent/` for automatic artifact upload, or pass via environment variables (`echo "KEY=value" >> "$GITHUB_ENV"`).

Reference in prompts: `Analyze release ${RELEASE_TAG}`.
**Job dependencies**: Use `needs: [job-name]` to define execution order between jobs.

## Related Documentation

Expand Down