Document Agent Network prompt-cache token and cost accounting#886
Conversation
Access-log and usage-overview pages describe the hover breakdowns for prompt-cache reads/writes and the cache share of cost; the API reference picks up cached_input_tokens, cache_creation_tokens, and cache_cost_usd (regenerated with npm run gen against the updated spec).
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
📝 WalkthroughWalkthroughUpdated Agent Network documentation wording and formatting across overview, integration, policy, usage, and quickstart pages. Added prompt-cache token and cost descriptions to usage documentation and corresponding API response examples and schemas. ChangesAgent Network documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 ESLint
src/pages/agent-network/global-limits.mdxOops! Something went wrong! :( ESLint: 9.39.2 TypeError: Converting circular structure to JSON src/pages/agent-network/how-it-works.mdxOops! Something went wrong! :( ESLint: 9.39.2 TypeError: Converting circular structure to JSON src/pages/agent-network/index.mdxOops! Something went wrong! :( ESLint: 9.39.2 TypeError: Converting circular structure to JSON
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/pages/agent-network/integrations/bedrock.mdx`:
- Line 14: Update the Bedrock API key documentation and its “Generate a Bedrock
API Key” flow to state that these long-term keys are for
exploration/development, tied to IAM user credentials, and may expire on a
configured date. Direct production users to the appropriate production
credential path or establish a key rotation plan before deployment.
In `@src/pages/agent-network/integrations/claude-code.mdx`:
- Line 33: Fix the comma splice in the provider-save instruction by replacing
the comma after “held server-side” with a period or semicolon in
src/pages/agent-network/integrations/claude-code.mdx:33,
src/pages/agent-network/integrations/codex.mdx:33,
src/pages/agent-network/integrations/bedrock.mdx:48,
src/pages/agent-network/integrations/litellm.mdx:23, and
src/pages/agent-network/integrations/vertex-ai.mdx:95-96.
In `@src/pages/agent-network/policies/index.mdx`:
- Around line 16-17: Update the sentence in the note near the Access Control
link to replace the period before “See” with a comma, keeping the link as part
of the same sentence.
In `@src/pages/agent-network/quickstart.mdx`:
- Around line 99-100: Update the tab-selection sentence in the quickstart
instructions to place a colon before the list of tools, clearly separating
“matches your tool” from the examples Claude Code, Codex, OpenAI SDK, and cURL.
In `@src/pages/agent-network/usage-and-logs/access-logs.mdx`:
- Around line 63-66: Align the documented token totals with the API contract:
total_tokens must represent input plus output tokens, while cache-read and
cache-write tokens remain separate buckets and are not added to the total.
Update the field descriptions, example values, and hover text at
src/pages/agent-network/usage-and-logs/access-logs.mdx lines 63-66, and at
src/pages/ipa/resources/agent-network.mdx lines 271-274, 589-592, and 959-962 so
the breakdown and headline consistently use these semantics.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: f93a3571-3a74-42f4-a750-ec338739a53c
⛔ Files ignored due to path filters (3)
public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-cost-breakdown.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-token-breakdown.pngis excluded by!**/*.pngpublic/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.pngis excluded by!**/*.png
📒 Files selected for processing (19)
src/pages/agent-network/global-limits.mdxsrc/pages/agent-network/how-it-works.mdxsrc/pages/agent-network/index.mdxsrc/pages/agent-network/integrations/bedrock.mdxsrc/pages/agent-network/integrations/claude-code.mdxsrc/pages/agent-network/integrations/codex.mdxsrc/pages/agent-network/integrations/index.mdxsrc/pages/agent-network/integrations/litellm.mdxsrc/pages/agent-network/integrations/vertex-ai.mdxsrc/pages/agent-network/integrations/vllm.mdxsrc/pages/agent-network/policies/guardrails.mdxsrc/pages/agent-network/policies/index.mdxsrc/pages/agent-network/policies/limits.mdxsrc/pages/agent-network/providers.mdxsrc/pages/agent-network/quickstart.mdxsrc/pages/agent-network/usage-and-logs/access-logs.mdxsrc/pages/agent-network/usage-and-logs/index.mdxsrc/pages/agent-network/usage-and-logs/usage-overview.mdxsrc/pages/ipa/resources/agent-network.mdx
| on the way to Bedrock. | ||
|
|
||
| Bedrock authenticates with a **Bedrock API key** — a long-term key you generate in AWS that | ||
| Bedrock authenticates with a **Bedrock API key**, a long-term key you generate in AWS that |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file excerpt =="
sed -n '1,80p' src/pages/agent-network/integrations/bedrock.mdx
echo
echo "== Bedrock key references in repository =="
rg -n "Bedrock(API key| API key|API keys|long-term|expires|expiry|expiration|expires on|credential|production)" src/pages/agent-network/integrations/bedrock.mdx src -g '*.mdx' -g '*.md' || trueRepository: netbirdio/docs
Length of output: 6661
🌐 Web query:
AWS Bedrock API keys long-term only for exploration development expire AWS documentation
💡 Result:
Amazon Bedrock provides two types of API keys for authentication, and AWS explicitly states that long-term keys are recommended only for exploration and development purposes [1][2][3]. Key Details: - Short-term API keys: These are the recommended standard for production applications [1][2]. They expire after a maximum of 12 hours or when the console session ends, whichever occurs first, and they inherit the permissions of the IAM principal used to generate them [1][2][4]. - Long-term API keys: These are intended specifically for exploration and development [1][4]. When generated, they create a dedicated IAM user and associate the key with that user [2][4][5]. You can configure an expiration date for these keys, ranging from one day to an indefinite duration [4][5]. Security Warnings: AWS strongly emphasizes that long-term keys should only be used when temporary credentials (such as those provided by AWS STS) or short-term API keys are not viable [5]. For production environments, you should transition to more secure methods like IAM roles or temporary credentials [3][6][7]. When using long-term keys, it is important to apply the principle of least privilege, protect the keys, and regularly monitor their usage through AWS CloudTrail and other auditing tools [5]. Generation and Management: - You can generate both key types via the Amazon Bedrock console [4]. - For long-term keys, you can specify an expiration time at the time of creation [8][4]. - Once created, the associated IAM user's permissions can be managed through the IAM service [2][4]. - API key generation and usage can be controlled using specific IAM policy conditions, such as limiting the age of service-specific credentials or restricting usage to certain types of bearer tokens [1][4]. For further guidance, consult the official Amazon Bedrock documentation on API keys [1] and security best practices [5].
Citations:
- 1: https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html
- 2: https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-how.html
- 3: https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started-api-keys.html
- 4: https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/
- 5: https://aws.amazon.com/blogs/security/securing-amazon-bedrock-api-keys-best-practices-for-implementation-and-management/
- 6: https://docs.aws.amazon.com/bedrock/latest/userguide/setting-up.html
- 7: https://docs.aws.amazon.com/bedrock/latest/userguide/getting-started.html
- 8: https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys-generate.html
Warn about Bedrock API key expiry and production use.
Long-term Bedrock API keys are only intended for exploration/development, are tied to IAM user credentials, and can expire on a configured date. Clarify this in the “Generate a Bedrock API Key” flow and point users to the production credential path or a rotation plan before deployment.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/integrations/bedrock.mdx` at line 14, Update the
Bedrock API key documentation and its “Generate a Bedrock API Key” flow to state
that these long-term keys are for exploration/development, tied to IAM user
credentials, and may expire on a configured date. Direct production users to the
appropriate production credential path or establish a key rotation plan before
deployment.
| 1. Go to **Agent Network → Providers** and click **Connect Provider**. | ||
| 2. Select **Anthropic** and paste your Anthropic API key. | ||
| 3. Save the provider. The key is now held server-side — the next step authorizes who can use it. | ||
| 3. Save the provider. The key is now held server-side, the next step authorizes who can use it. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the repeated provider-save comma splice across the integration guides.
src/pages/agent-network/integrations/claude-code.mdx#L33-L33: replace the comma after “held server-side” with a period or semicolon.src/pages/agent-network/integrations/codex.mdx#L33-L33: apply the same sentence-boundary fix.src/pages/agent-network/integrations/bedrock.mdx#L48-L48: apply the same sentence-boundary fix.src/pages/agent-network/integrations/litellm.mdx#L23-L23: apply the same sentence-boundary fix.src/pages/agent-network/integrations/vertex-ai.mdx#L95-L96: apply the same sentence-boundary fix.
📍 Affects 5 files
src/pages/agent-network/integrations/claude-code.mdx#L33-L33(this comment)src/pages/agent-network/integrations/codex.mdx#L33-L33src/pages/agent-network/integrations/bedrock.mdx#L48-L48src/pages/agent-network/integrations/litellm.mdx#L23-L23src/pages/agent-network/integrations/vertex-ai.mdx#L95-L96
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/integrations/claude-code.mdx` at line 33, Fix the
comma splice in the provider-save instruction by replacing the comma after “held
server-side” with a period or semicolon in
src/pages/agent-network/integrations/claude-code.mdx:33,
src/pages/agent-network/integrations/codex.mdx:33,
src/pages/agent-network/integrations/bedrock.mdx:48,
src/pages/agent-network/integrations/litellm.mdx:23, and
src/pages/agent-network/integrations/vertex-ai.mdx:95-96.
| looking for a guide on how to manage access to internal resources. See | ||
| [Access Control](/manage/access-control). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the sentence break in the note.
The conditional sentence ends with a period before “See,” producing incorrect grammar. Use a comma so the link remains part of the same sentence.
Proposed fix
- looking for a guide on how to manage access to internal resources. See
+ looking for a guide on how to manage access to internal resources, see📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| looking for a guide on how to manage access to internal resources. See | |
| [Access Control](/manage/access-control). | |
| looking for a guide on how to manage access to internal resources, see | |
| [Access Control](/manage/access-control). |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/policies/index.mdx` around lines 16 - 17, Update the
sentence in the note near the Access Control link to replace the period before
“See” with a comma, keeping the link as part of the same sentence.
| 2. Pick the tab that matches your tool, Claude Code, Codex, OpenAI SDK, or cURL. The | ||
| dashboard pre-fills your endpoint for you. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use a colon before the tool list.
“Matches your tool, Claude Code…” is grammatically ambiguous. Introduce the examples with a colon.
Proposed fix
-2. Pick the tab that matches your tool, Claude Code, Codex, OpenAI SDK, or cURL. The
+2. Pick the tab that matches your tool: Claude Code, Codex, OpenAI SDK, or cURL. The📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| 2. Pick the tab that matches your tool, Claude Code, Codex, OpenAI SDK, or cURL. The | |
| dashboard pre-fills your endpoint for you. | |
| 2. Pick the tab that matches your tool: Claude Code, Codex, OpenAI SDK, or cURL. The | |
| dashboard pre-fills your endpoint for you. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/quickstart.mdx` around lines 99 - 100, Update the
tab-selection sentence in the quickstart instructions to place a colon before
the list of tools, clearly separating “matches your tool” from the examples
Claude Code, Codex, OpenAI SDK, and cURL.
| All four buckets are listed even when one costs nothing, so a zero cache-write | ||
| line tells you this request read the cache rather than populating it. The total | ||
| is always the sum of the four, so the breakdown and the headline figure can | ||
| never disagree. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate files =="
git ls-files | rg 'src/pages/(agent-network/usage-and-logs/access-logs\.mdx|ipa/resources/agent-network\.mdx)$' || true
echo "== relevant snippets =="
for f in \
src/pages/agent-network/usage-and-logs/access-logs.mdx \
src/pages/ipa/resources/agent-network.mdx
do
if [ -f "$f" ]; then
lines=$(wc -l < "$f")
echo "--- $f ($lines lines) ---"
fi
done
for range in "55,75" "255,285" "575,605" "938,970"; do
start=${range%,*}
end=${range#*,}
echo "--- access-logs.mdx lines $start-$end ---"
sed -n "${start},${end}p" src/pages/agent-network/usage-and-logs/access-logs.mdx | cat -n
echo "--- agent-network.mdx lines $start-$end ---"
sed -n "${start},${end}p" src/pages/ipa/resources/agent-network.mdx | cat -n
done
echo "== search cache/token/total occurrences =="
rg -n '"total_tokens"|"total_cost_usd"|"cache_creation_tokens"|"cached_input_tokens"|"cache_cost_usd"|"cost_usd"|total [A-Za-z]|breakdown|sum of' \
src/pages/agent-network/usage-and-logs/access-logs.mdx \
src/pages/ipa/resources/agent-network.mdx || trueRepository: netbirdio/docs
Length of output: 10736
Align documented totals with token accounting semantics.
The API examples consistently keep total_tokens as input + output even when cache tokens are present, while the usage docs describe the total as including all buckets. Update the total semantics so field names, values, and hover-copy match the same contract.
📍 Affects 2 files
src/pages/agent-network/usage-and-logs/access-logs.mdx#L63-L66(this comment)src/pages/ipa/resources/agent-network.mdx#L271-L274src/pages/ipa/resources/agent-network.mdx#L589-L592src/pages/ipa/resources/agent-network.mdx#L959-L962
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/pages/agent-network/usage-and-logs/access-logs.mdx` around lines 63 - 66,
Align the documented token totals with the API contract: total_tokens must
represent input plus output tokens, while cache-read and cache-write tokens
remain separate buckets and are not added to the total. Update the field
descriptions, example values, and hover text at
src/pages/agent-network/usage-and-logs/access-logs.mdx lines 63-66, and at
src/pages/ipa/resources/agent-network.mdx lines 271-274, 589-592, and 959-962 so
the breakdown and headline consistently use these semantics.
2 participants
Documents the prompt-cache accounting added in netbirdio/netbird#6900 and surfaced in netbirdio/dashboard#731: the access-log and usage-overview pages now describe the hover breakdowns for cache read/write tokens and the cache share of cost, including why a session's first request (cache write, ~1.25× the input rate) costs more than its input/output counts suggest. The API reference is regenerated with
npm run genagainst the updated spec, picking upcached_input_tokens,cache_creation_tokens, andcache_cost_usd. Validated withnpm run build.Generated by Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.Summary by CodeRabbit