docs(designs): Add agent guidelines#523
Conversation
Documentation Deployment CompleteYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-523/ |
| ### Security | ||
|
|
||
|
|
||
| ### Scope Credentials to the Task |
There was a problem hiding this comment.
AKA: Principle of least privilege
|
|
||
| For task-specific agents (code review, documentation generation, issue triage), use tokens scoped to exactly those capabilities. A code review agent doesn't need write access to the repository; it needs read access to code and write access to comments. | ||
|
|
||
| For general-purpose agents where scoping is difficult, use credentials from an external account (like `strands-agent`) rather than maintainer accounts. External accounts have the same permissions as any community member—they can comment and open PRs, but they can't merge, delete, or modify protected resources. The worst case becomes "excessive commenting" rather than "repository corruption." |
There was a problem hiding this comment.
I get why this was included, because we did this, but its never meant as a permanent solution - just for testing. I dont think it really add too much, so I would remove it. What do you think?
|
|
||
| For general-purpose agents where scoping is difficult, use credentials from an external account (like `strands-agent`) rather than maintainer accounts. External accounts have the same permissions as any community member—they can comment and open PRs, but they can't merge, delete, or modify protected resources. The worst case becomes "excessive commenting" rather than "repository corruption." | ||
|
|
||
| **Never give agents maintainer tokens.** Maintainer tokens allow destructive actions that may be difficult or impossible to reverse. No experiment is worth that risk. |
There was a problem hiding this comment.
Again, this feels a bit like stating the obvious. I dont think we should be re-stating how to securely build an agent here, but more talk about helpful ways to have it engage with our github community
There was a problem hiding this comment.
I think it's better to state the obvious. Especially with what is happening with the autonomous agents in the news recently. Agents are a powerful tool, but we need to be reminded that they need to be used responsibly.
|
|
||
| Even when an agent is doing good work, too much activity becomes overwhelming. If an agent opens ten PRs in an hour, maintainers can't review them thoughtfully. If it comments on every issue in a day, the notification noise becomes unbearable. | ||
|
|
||
| **Default limit: 5 actions per hour per agent** (PRs opened, reviews posted, comments made, etc.). This can be adjusted with team agreement for specific use cases, but the default should be conservative. |
There was a problem hiding this comment.
This seems arbitrary, and is probably because we dont know how to use autonomous agents correctly yet. I might just say that in this section:
"While we like the idea of autonomous agents, and want to figure out helpful ways to utilize them, we have yet determined a robust framework for utilizing them. While we figure that out, please be vocal, kind, and patent with our experimentation"
or something like that.
There was a problem hiding this comment.
I agree with the call on this; setting a limit is a good thing, I just think these limits are too high even for humans. 5 per hour, 24 hours a day, 7 days a week means humans can't work alongside agents.
I think having it execute only when we work is more reasonable. So M-F 9-5 so that it is acting more like humans and we can partner with it.
| The goal is sustainable pace. Agents should work at a speed that humans can follow and respond to. Remember: our repositories exist for humans to collaborate. Agents are there to help, not to dominate. The community should feel like they're interacting with a project maintained by people, with agents as helpful assistants—not the other way around. | ||
|
|
||
|
|
||
| ### Monitor What Agents Do |
There was a problem hiding this comment.
I think maybe a better way to frame this is "Treat agents like any other contributor"
We should be able to see contributions from an agent, track pr's they are creating, and anything else. We dont build system specifc for agents, we utilize existing features to better scale out our agent experiments.
|
|
||
| **Every agent needs an owner. If there are problems, someone fixes them or shuts them down.** | ||
|
|
||
| Autonomous agents can't be orphans. When an agent misbehaves—posting incorrect information, spamming repositories, or just not working as intended—someone needs to be responsible for addressing it. |
There was a problem hiding this comment.
nit: Regarding my previous comment, we still dont know how to use autonomous agents well yet, so when we do use them, it will be as an experiment, and we need tight monitoring around that.
|
|
||
| No matter how well-designed an agent is, there needs to be an escape hatch. Repository maintainers must have the ability to disable any agent operating on their repository, immediately and without negotiation. | ||
|
|
||
| This is the Andon cord principle: anyone who sees a problem can stop the line. For agents, this means: |
|
|
||
| **Default limit: 5 actions per hour per agent** (PRs opened, reviews posted, comments made, etc.). This can be adjusted with team agreement for specific use cases, but the default should be conservative. | ||
|
|
||
| The goal is sustainable pace. Agents should work at a speed that humans can follow and respond to. Remember: our repositories exist for humans to collaborate. Agents are there to help, not to dominate. The community should feel like they're interacting with a project maintained by people, with agents as helpful assistants—not the other way around. |
There was a problem hiding this comment.
Yes, agreed, we need to work at the same pace for it to be effective. If an agent is working at 50 times the pace we are, then we aren't able to collaborate effectively.
4 participants
Description
Adds design document for agent guidelines — principles governing how we develop and deploy AI agents that interact with Strands repositories.
This document captures learnings from our experiments with agents across the development workflow (PR reviews, issue triage, documentation, autonomous improvements). It establishes guardrails that enable bold experimentation while ensuring we can always recover from mistakes.
Key guidelines covered:
Once aligned, a condensed version will be added to
team/AGENT_GUIDELINES.mdfollowing theDECISIONS.mdformat.Related Issues
N/A
Type of Change
Checklist
mkdocs serveBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.