docs(#6599): add scheduled agent example guide - #6601
docs(#6599): add scheduled agent example guide#6601fullsend-ai-coder[bot] wants to merge 3 commits into
Conversation
Add docs/guides/user/scheduled-agent-example.md showing how to run a fullsend agent on a cron schedule using a minimal GitHub Actions workflow with a pre-computed matrix and reusable-dispatch.yml@v0. The guide covers building the dispatch matrix directly (without needing fullsend dispatch), passing it to reusable-dispatch, posting status to a tracking issue, and running multiple agents on the same schedule. Cross-link from bring-your-own-agent.md (new "Scheduling agents" section and See Also entry), custom-poller-example.md (callout for simpler use case), and docs/guides/README.md. Add sidebar entry in docs/.vitepress/config.ts. Pre-commit could not fetch remote hook repos (network-restricted sandbox). Ran hooks directly: trailing-whitespace, end-of-file-fixer, lint-docs-links, lychee (lint-md-links), and prettier all passed. Closes #6599
Site previewPreview: https://3aca09f3-site.fullsend-ai.workers.dev Commit: |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
|
🤖 Finished Review · ✅ Success · Started 5:10 PM UTC · Completed 5:24 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $4.83 |
|
Looks good to me Previous runReviewFindingsLow
Labels: All changed files are under docs/ - documentation-only PR adding a new user guide Previous run (2)ReviewFindingsHigh
Medium
Low
Next steps:
|
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
🤖 Finished Fix · ✅ Success · Started 5:26 PM UTC · Completed 5:35 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $2.78 |
- Populate event_payload with valid issue object (html_url, number) in
all three example variants; empty {} payload causes harness-run
"Export dispatch context env" step to fail
- Wire workflow_dispatch dry_run input into event_payload via DRY_RUN
env variable so agents can read it from the payload file
- Update Tips section to describe the dry_run wiring accurately
- Add tracking-issue prerequisite explaining the event_payload
requirement
- Switch Variables/Secrets list separators from em dashes to plain
hyphens to match custom-poller-example.md
Addresses review feedback on #6601
🔧 Fix agent — iteration 1 (bot-triggered)Addressed all 3 review findings. Fixed empty event_payload (which would fail the harness-run step) by populating it with a valid issue object in all example variants, wired the dry_run workflow_dispatch input into the payload, and aligned list separators with the sibling doc. Fixed (3):
Tests: passedNext steps:
|
|
🤖 Finished Review · ✅ Success · Started 5:38 PM UTC · Completed 5:53 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $3.15 |
|
Risk Assessment: moderate (2/5) DetailsPurely additive documentation PR authored by a bot with well-aligned issue scope. All changes are docs-only with no protected paths, security-sensitive files, or CI/dependency changes. Previous runRisk Assessment: low (1/5) DetailsDocumentation-only PR by a bot adding a scheduled agent example guide with minor cross-reference additions to existing docs; no protected paths, no security-sensitive files, no dependency or CI changes. |
Superseded by updated review
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
fullsend-ai-review
Bot
added
ready-for-merge
|
/fs-fix see my inline comments -> simplify |
|
🤖 Finished Fix · ✅ Success · Started 6:09 PM UTC · Completed 6:18 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $2.37 |
Remove the build-matrix job and pass a matrix literal directly to reusable-dispatch.yml. Remove the "Posting status to an issue" section (ISSUE_URL is already in the main example). Drop the dry_run workflow_dispatch input and simplify the "Running multiple agents", "How it works", and "Tips" sections accordingly. Addresses review feedback on #6601
🔧 Fix agent — iteration 2 (human-triggered)Simplified the scheduled agent example guide from 225 to ~110 lines per human reviewer's inline comments. Eliminated the build-matrix job (replaced with a matrix literal), removed the Posting status to an issue section, dropped dry_run complexity, and simplified all related sections. Fixed (4):
Tests: passedNext steps:
|
|
🤖 Finished Review · ✅ Success · Started 6:21 PM UTC · Completed 6:36 PM UTC Commit: Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $4.29 |
fullsend-ai-review
Bot
added
risk/moderate
| permissions: | ||
| actions: write | ||
| contents: write | ||
| id-token: write | ||
| issues: write | ||
| packages: read | ||
| pull-requests: write |
There was a problem hiding this comment.
That's a really powerful permission set that probably needs a rationale...
And also, is really highlighting Fullsend's lack of a https://github.github.com/gh-aw/reference/safe-outputs/ equivalent (or reusing the code!).
There was a problem hiding this comment.
On safe-outputs, we rely on a combination of declarative safety for the agent to (for example) limit agent activities to read-only but imperative safety in the post script that respects things like create_issues.allowed_repos to accomplish something similar to gh-aw's safe-outputs.create-issue.allowed-repos. That safe-outputs schema from gh-aw is clearer for a user to understand as things stand now.
On the permission set, agreed - let's document the rationale here or dilute it before this PR moves forwards.
There was a problem hiding this comment.
Related to this and our private chat, I created #6614
| uses: fullsend-ai/fullsend/.github/workflows/reusable-dispatch.yml@v0 | ||
| with: | ||
| # Matrix literal — replace "my-nightly-agent" and "42" (see Prerequisites). | ||
| matrix: '{"include":[{"agent":"my-nightly-agent","source_repo":"${{ github.repository }}","role":"harness","event_payload":"{\"issue\":{\"html_url\":\"https://github.com/${{ github.repository }}/issues/42\",\"number\":42}}","status_repo":"","status_number":""}]}' |
There was a problem hiding this comment.
This is ugly.
Compare with e.g. https://github.github.com/gh-aw/engines/copilot/#example-scheduled-repository-report
There was a problem hiding this comment.
Yeah, agreed. Let's redo this APIbefore merging guidance to use it.
| with: | ||
| # Matrix literal — replace "my-nightly-agent" and "42" (see Prerequisites). | ||
| matrix: '{"include":[{"agent":"my-nightly-agent","source_repo":"${{ github.repository }}","role":"harness","event_payload":"{\"issue\":{\"html_url\":\"https://github.com/${{ github.repository }}/issues/42\",\"number\":42}}","status_repo":"","status_number":""}]}' | ||
| mint_url: ${{ vars.FULLSEND_MINT_URL }} |
There was a problem hiding this comment.
I have a failure trying
shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
env:
MINT_URL: https://......
ROLE: harness
REPOS: kdn
Requesting token: role=harness repos=kdn
curl: (22) The requested URL returned error: 403
curl: (22) The requested URL returned error: 403
is that harness is the correct role to use ?
| 2. **Repository variables and secrets** configured for fullsend (see [Variables and secrets](#variables-and-secrets) below). | ||
| 3. **GCP Workload Identity Federation** provisioned for your repo — run [`fullsend inference provision`](../../cli/inference.md) first. |
There was a problem hiding this comment.
I think "fullsend installed" covers these two.
|
@ralphbean remember to keep this healthy, the bot can only do so much |
4 participants
Summary
Adds a new user guide (
docs/guides/user/scheduled-agent-example.md) documenting the recommended way to run a fullsend agent on a recurring cron schedule via GitHub Actions. The guide provides a copy-paste-able workflow that constructs a pre-computed matrix and callsreusable-dispatch.yml@v0, covering single-agent, multi-agent, and status-reporting variants.Related Issue
Closes #6599
Changes
docs/guides/user/scheduled-agent-example.md— minimal nightly workflow example withschedule+workflow_dispatchtriggers, matrix construction, status posting, multi-agent support, prerequisites, and tipsbring-your-own-agent.md: new "Scheduling agents" section and See Also entry pointing to the new guidecustom-poller-example.md: callout at the top for users who need a simpler nightly schedule without external pollingdocs/guides/README.md: added the new guide to the User Guides indexdocs/.vitepress/config.ts: added sidebar entry next to "Bring Your Own Agent"Testing
lycheelink checker passes on all changed markdown files (105 total, 0 errors)lint-docs-linkspasses (no docs/ links escape repo root)prettierpasses onconfig.tsgitlintpasses on commit messagescan-secrets --staged)Closes #6599
Post-script verification
agent/6599-scheduled-agent-docs)8fc412bbd86c77e42d2063bc37f581ae8879b199..HEAD)