docs: add responsible AI agent use & token-budget guide#17
Open
oto-macenauer-absa wants to merge 6 commits into
Open
docs: add responsible AI agent use & token-budget guide#17oto-macenauer-absa wants to merge 6 commits into
oto-macenauer-absa wants to merge 6 commits into
Conversation
Add docs/responsible-agent-use.md: a guide to using AI agents (primarily GitHub Copilot) without wasting the token/credit budget. Covers Copilot usage-based billing, the input/output/cached token types and their different rates, where budget goes (context, model choice, agent mode, MCP, code review), context maintaining vs clearing reconciled with prompt-cache behaviour, MCP/plugin/skill cost discipline, per-token-type cuts, and a must-do checklist. Also deduplicate the skill-activation explanation across getting-started and troubleshooting via cross-references, and add the new page to the docs index. Closes #16
oto-macenauer-absa
added
the
documentation
oto-macenauer-absa
requested review from
lsulak,
miroslavpojer and
tmikula-dev
as code owners
oto-macenauer-absa
added
the
documentation
Reframe the recommendations for agent-mode work (the default) rather than manual chat: scope what the agent reads instead of pasting files, favour targeted edits over "ask for a diff", bound the loop with a stop condition, plan before editing, and run targeted tests so verification output doesn't bloat context each turn. Update the token-type notes, levers table, checklist, and TL;DR to match.
miroslavpojer
left a comment
miroslavpojer
left a comment
Contributor
There was a problem hiding this comment.
I like it. I am missing one concept which can protect scope size and still provide a lot of agent work - usage of sub-agents.
- source: https://www.youtube.com/watch?v=DFqzYxMmQDw&list=WL&index=13
- there is said that sub-agent has own scope which is not transfered into main one
- we could motivate agents and skill to work this way - delegate complex tasks into subagent and got just summary what has been done.
Address PR review feedback: cover sub-agents as a way to protect the main context. A sub-agent runs in its own context window and returns only a summary, so heavy read/search/analysis tokens are paid once and discarded instead of accumulating in the main thread. Includes the honest caveat that multi-agent use costs more tokens overall (Anthropic reports ~4x single-agent, ~15x multi-agent vs chat), so delegation pays off only when it replaces context that would otherwise pile up or when workers run a cheaper model. Adds checklist item, TL;DR clause, sources.
Contributor
Author
|
Good call — added a Sub-agents section (commit 7ebce76). It covers exactly your point: a sub-agent runs in its own context window, does the heavy reading/searching, and returns only a summary to the main thread, so the intermediate noise never pollutes the parent context. I also web-researched it and added the honest caveat: sub-agents aren't free — each opens its own window, and Anthropic reports a single agent uses ~4x a chat's tokens and multi-agent ~15x. So the section frames delegation as a net win only when it replaces context that would otherwise pile up in the main thread, or when workers run a cheaper model (reported 5-10x cuts with a premium orchestrator + lightweight workers). Sources added to the doc. Thanks for the video reference. |
Apply fixes from a full read-through: - intro now lists agent mode and sub-agents (the two largest sections) - add an availability caveat to the sub-agents section: native spawning is a Claude Code/SDK feature; in Copilot it surfaces via custom agents, and the cited token figures come from the Claude ecosystem - standardise terminology on "session" (was a mix of conversation / chat / thread for the same thing)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/responsible-agent-use.md— a guide to using AI agents (primarily GitHub Copilot) without wasting the token / credit budget — and deduplicates overlapping content in the existing docs.Why
Copilot moved to usage-based, per-token billing (June 1 2026). Without guidance, a user can burn a month of credits in a few agent prompts. There was no doc explaining the cost model or how to control it.
Contents of the new page
(input × input_rate) + (output × output_rate) + (cached × cached_rate).Dedup
getting-started.md, the fix introubleshooting.md, each cross-references the other instead of restating.responsible-agent-use.mdreferences the loading model rather than re-explaining it.docs/index.Notes
docs/at build time (guidelines/is generated, gitignored), so no website code changes are needed.feature/websiteto keep this diff scoped to the docs work.Closes #16