From 3e44734b4cc782826d814577c6f26a61e85362f0 Mon Sep 17 00:00:00 2001 From: "Claude Sonnet 4.5" Date: Thu, 22 Jan 2026 13:29:44 +0000 Subject: [PATCH] Unbloat deterministic-agentic-patterns.md documentation Reduced file from 303 to 195 lines (35.6% reduction) by: - Condensing verbose "When to Use This Pattern" section into concise prose - Streamlining code examples by removing redundant explanations - Consolidating "Pattern Examples" section (removed duplicative content) - Compressing "Best Practices" from multiple code blocks to concise bullet points - Simplifying "Agent Data Directory" section - Removing filler words and redundant phrases throughout All essential technical information preserved. Co-Authored-By: Claude Sonnet 4.5 --- .../guides/deterministic-agentic-patterns.md | 158 +++--------------- 1 file changed, 25 insertions(+), 133 deletions(-) diff --git a/docs/src/content/docs/guides/deterministic-agentic-patterns.md b/docs/src/content/docs/guides/deterministic-agentic-patterns.md index 0e881877189..79f3b047b78 100644 --- a/docs/src/content/docs/guides/deterministic-agentic-patterns.md +++ b/docs/src/content/docs/guides/deterministic-agentic-patterns.md @@ -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 @@ -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: @@ -98,8 +79,7 @@ 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/ @@ -107,16 +87,13 @@ steps: # 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: @@ -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" @@ -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: @@ -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 @@ -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. - -
-Full Details - -Detailed content here. - -
-``` -``` - -Import in workflows: +Define reusable guidance in shared files and import them: ```yaml wrap title=".github/workflows/analysis.md" --- @@ -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