diff --git a/public/docs-static/img/agent-network/policies/agent-network-guardrails.png b/public/docs-static/img/agent-network/policies/agent-network-guardrails.png new file mode 100644 index 00000000..a57c8772 Binary files /dev/null and b/public/docs-static/img/agent-network/policies/agent-network-guardrails.png differ diff --git a/public/docs-static/img/agent-network/policies/agent-network-policy-limits.png b/public/docs-static/img/agent-network/policies/agent-network-policy-limits.png new file mode 100644 index 00000000..f5a73f4e Binary files /dev/null and b/public/docs-static/img/agent-network/policies/agent-network-policy-limits.png differ diff --git a/public/docs-static/img/agent-network/providers/agent-network-create-provider.png b/public/docs-static/img/agent-network/providers/agent-network-create-provider.png new file mode 100644 index 00000000..80968d18 Binary files /dev/null and b/public/docs-static/img/agent-network/providers/agent-network-create-provider.png differ diff --git a/public/docs-static/img/agent-network/providers/agent-network-providers-list.png b/public/docs-static/img/agent-network/providers/agent-network-providers-list.png new file mode 100644 index 00000000..4175febf Binary files /dev/null and b/public/docs-static/img/agent-network/providers/agent-network-providers-list.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png new file mode 100644 index 00000000..25b99199 Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-log-filters.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png new file mode 100644 index 00000000..17d85341 Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-access-logs.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png new file mode 100644 index 00000000..e3f80f0a Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-log-collection.png differ diff --git a/public/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png b/public/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png new file mode 100644 index 00000000..3d934340 Binary files /dev/null and b/public/docs-static/img/agent-network/usage-and-logs/agent-network-usage-overview.png differ diff --git a/src/components/NavigationDocs.jsx b/src/components/NavigationDocs.jsx index 5b420c21..c648193c 100644 --- a/src/components/NavigationDocs.jsx +++ b/src/components/NavigationDocs.jsx @@ -94,7 +94,6 @@ export const docsNavigation = [ { title: 'Guardrails', href: '/agent-network/policies/guardrails' }, ], }, - { title: 'Global Limits', href: '/agent-network/global-limits' }, { title: 'Usage & Logs', href: '/agent-network/usage-and-logs', @@ -113,7 +112,7 @@ export const docsNavigation = [ }, ], }, - { title: 'Self-Hosting', href: '/agent-network/self-hosting' }, + { title: 'Global Limits', href: '/agent-network/global-limits' }, ], }, { diff --git a/src/pages/agent-network/global-limits.mdx b/src/pages/agent-network/global-limits.mdx new file mode 100644 index 00000000..41414a63 --- /dev/null +++ b/src/pages/agent-network/global-limits.mdx @@ -0,0 +1,70 @@ +export const description = + 'Account-wide token and spend caps applied across every Agent Network policy, scoped to groups or users or left account-wide.' + +# Global Limits + +Global limits are account-wide caps on token usage and spend that apply across +**every** policy and **every provider** — a backstop independent of any single policy's +limits. They are **limit-only** rules: unlike a policy, a global limit never selects a +provider or authorizes traffic, and it isn't tied to one. It caps a caller's total +consumption no matter which provider or gateway the request is routed to. + +

+ agent network global limits list +

+ +A global limit acts as an **always-on ceiling**. It is evaluated before any policy, +on every request, and every applicable rule must pass. Because rules can only tighten a +caller's effective limit and never loosen it, adding one is always safe. + +## Scope + +Each rule targets who it applies to: + +- **Target groups** — the rule binds when the caller's groups intersect the rule's groups. +- **Target users** — the rule binds a specific user directly. +- **Untargeted** — a rule with no target groups or users applies to **every** caller (the + account-wide default). + +A request can be bound by several rules at once (for example an account-wide rule plus a +group-specific one); all of them are enforced. + +## Caps and Windows + +A global limit carries the same cap shape as a [policy limit](/agent-network/policies/limits): + +- A **token cap** and/or a **budget (USD) cap**. +- Each cap can be set **per user** and/or **per group**, over a fixed **window**. + +Windows and counting work exactly as described in +[Token & Budget Limits](/agent-network/policies/limits#how-the-window-works): caps apply to +a fixed, epoch-aligned window, and the check is run **before** the request against usage +already accumulated — so a request that starts under the cap is allowed even if it crosses +it, and the next one is blocked. + +## How Enforcement Works + +On every request, NetBird first evaluates all global limits that bind the caller. Each +applicable rule must pass; the first rule whose token or budget cap is exhausted denies the +request, before any policy is considered. The denial surfaces in the +[access logs](/agent-network/usage-and-logs/access-logs) as a **Token limit exceeded** or +**Budget limit exceeded** reason. For per-group caps, usage is attributed to the lowest +matching target group. + +## How It Combines with Policy Limits + +Global limits and [policy limits](/agent-network/policies/limits) are enforced together: a +request must pass **both** the global ceiling and the selected policy's own limits. Because +every applicable cap binds and the most restrictive one wins, a global limit can only +tighten what a policy allows, never widen it. Use global limits to set an overall account +ceiling, and policy limits for finer-grained, per-policy control. + +## Create a Global Limit + +Go to **Agent Network → Configuration → Global Limits** and add a rule with the token +and/or budget caps and an optional target. Leave the target empty to apply it account-wide, +or pick groups or users to scope it. + +

+ create global limit modal with token and budget caps +

\ No newline at end of file diff --git a/src/pages/agent-network/policies/guardrails.mdx b/src/pages/agent-network/policies/guardrails.mdx new file mode 100644 index 00000000..542fc0a1 --- /dev/null +++ b/src/pages/agent-network/policies/guardrails.mdx @@ -0,0 +1,34 @@ +export const description = + 'Guardrails restrict which models a policy can use and control prompt capture, including PII redaction.' + +# Guardrails + +Guardrails are checks you configure on a policy to constrain what its callers can +do. They are defined per policy and apply only to that policy. + +

+ agent network guardrails on a policy +

+ +## Model Allowlist + +Restrict a policy to a specific set of models. Requests for any other model are +denied. + +## Prompt Capture + +Optionally store request prompts and response completions on logged requests. +Prompt capture only runs when **both** the account-level prompt collection +setting and a policy guardrail enable it — see +[Log Collection & Retention](/agent-network/usage-and-logs/log-collection). + +### PII Redaction + +When capture is enabled, you can strip personally identifiable information from +prompts and completions before they're stored. Effective redaction is the OR of +the account setting and the guardrail setting. + +## Configuring Guardrails + +Open the policy's **Guardrails** tab when creating or editing a policy and enable +the checks you want. They take effect for that policy only. \ No newline at end of file diff --git a/src/pages/agent-network/policies/limits.mdx b/src/pages/agent-network/policies/limits.mdx index f3e4ce63..9ded33b9 100644 --- a/src/pages/agent-network/policies/limits.mdx +++ b/src/pages/agent-network/policies/limits.mdx @@ -1,26 +1,75 @@ export const description = - 'Cap LLM token usage and spend per user or per group within a policy, over a rolling window.' + 'Cap LLM token usage and spend per user or per group within a policy, over a fixed time window.' # Token & Budget Limits Limits cap how much a policy's callers can consume. They come in two halves, -each enforceable per user and per group over a rolling window. +each enforceable per user and per group over a fixed time window. -## Token limits +

+ agent network token and budget limits on a policy +

+ +To enable limits, open the policy's **Limits** tab when creating or editing a policy, turn +on the token and/or budget limit, and set the per-user and per-group caps and window. + +## Token Limits - **User cap** — maximum tokens per user in the window. - **Group cap** — maximum tokens per group in the window. -- **Window** — the rolling period the cap applies to. +- **Window** — the fixed period the cap applies to (see [below](#how-the-window-works)). -## Budget limits +## Budget Limits - **User cap (USD)** — maximum spend per user in the window. - **Group cap (USD)** — maximum spend per group in the window. -- **Window** — the rolling period the cap applies to. +- **Window** — the fixed period the cap applies to (see [below](#how-the-window-works)). -## How enforcement works +## How the Window Works -Before each request, NetBird checks the applicable caps; when a cap is -exhausted, the request is denied with a reason surfaced in the -[access logs](/agent-network/usage-and-logs/access-logs). For account-wide caps -that apply across all policies, see [Global Limits](/agent-network/global-limits). \ No newline at end of file +A cap applies to a **fixed window**, not a sliding one. NetBird divides time into +back-to-back buckets of the window's length, aligned to a fixed grid starting from the +Unix epoch (`1970-01-01T00:00:00Z`). Each request is counted into the bucket its timestamp +falls in, and the cap is compared against the total accumulated in the **current** bucket. +When the window rolls over to the next bucket, the counter effectively starts again at +zero. + +The bucket boundary is computed as: + +```text +window_start = floor(now / window) * window +``` + +This alignment is deliberate: because every node derives the same boundaries from the same +clock, usage adds up consistently across a clustered deployment instead of drifting with +each node's first request. + +**Example — a 1-hour (3600s) window.** Buckets run from the top of each hour in UTC: +`13:00:00–13:59:59`, `14:00:00–14:59:59`, and so on. A request at `13:45` counts toward the +`13:00` bucket; a request at `14:02` lands in a fresh `14:00` bucket with the counter back +at zero — regardless of when the user's first request of the day was. + +## How Enforcement Works + +Caps are checked **before** the request runs, against usage already accumulated in the +current window. The check is `used >= cap`: if the running total has not yet reached the +cap, the request is allowed; once it has, the request is denied with a reason surfaced in +the [access logs](/agent-network/usage-and-logs/access-logs). + +Because the check uses the total **before** the request (NetBird doesn't reserve or +pre-estimate the request's own cost), a single request can push usage past the cap. The +request that crosses the line still completes; the **next** one is blocked. + +**Example.** A token cap is set to `1000` for a group, and the group has used `999` in the +current window: + +- The next request is checked: `999 >= 1000` is false, so it **goes through** — even though + it then consumes, say, 250 tokens and pushes the total to `1249`. +- The following request is checked: `1249 >= 1000` is true, so it is **blocked** until the + window rolls over. + +So a cap is a floor for *when blocking starts*, not a hard ceiling on the exact total — plan +caps with a little headroom if you need a strict upper bound. + +For account-wide caps that apply across all policies, see +[Global Limits](/agent-network/global-limits). \ No newline at end of file diff --git a/src/pages/agent-network/providers.mdx b/src/pages/agent-network/providers.mdx new file mode 100644 index 00000000..199415d3 --- /dev/null +++ b/src/pages/agent-network/providers.mdx @@ -0,0 +1,86 @@ +export const description = + 'Connect AI providers and gateways — OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Mistral, LiteLLM, Portkey, Bifrost, Cloudflare, Vercel, OpenRouter, or any OpenAI-compatible endpoint — to NetBird Agent Network and expose a single keyless endpoint.' + +# Providers + +A **provider** is an upstream LLM service that NetBird routes requests to. Connecting one +stores its API key server-side and exposes it through your keyless, tunnel-only +[agent network endpoint](/agent-network/how-it-works#llm-apis-and-ai-gateways), so agents +never hold a provider key. + +

+ agent network providers list +

+ +## Supported Providers + +When you connect a provider, the picker groups the catalog into first-party **AI +Providers**, multi-provider **AI Gateways**, and a **Custom** catch-all. + +### AI Providers + +First-party vendor APIs: + +- OpenAI +- Anthropic +- Azure OpenAI +- AWS Bedrock +- Google Vertex AI +- Mistral + +### AI Gateways + +Routing and aggregation layers that sit in front of multiple providers. NetBird can also +forward the calling agent's identity to these so the gateway can apply its own attribution +and budgets (see [How It Works](/agent-network/how-it-works#llm-apis-and-ai-gateways)): + +- LiteLLM Proxy +- Portkey AI Gateway +- Bifrost +- Cloudflare AI Gateway +- Vercel AI Gateway +- OpenRouter + +### Custom + +- Custom / Self-hosted — any OpenAI-compatible endpoint, including local models served by + Ollama, vLLM, or a private GPU host. + +## Connect a Provider + +1. Go to **Agent Network → Providers** and click **Connect Provider**. +2. Select the provider or gateway. NetBird pre-fills the upstream URL and the correct auth + header for that vendor. +3. Paste the provider's **API key**. It is stored encrypted server-side and never sent to + callers. +4. _(Optional)_ Restrict the **allowed models** and set **per-model pricing** used for cost + estimates in usage and logs. +5. _(Optional, gateways)_ Fill any gateway-specific fields (for example a Portkey config + ID) and the identity headers used for attribution. +6. Save the provider. + +

+ agent network connect provider modal +

+ +## Models and Pricing + +Each provider carries a list of models it serves. Leaving the list empty makes the +provider a catch-all that accepts any model (typical for gateways); listing specific models +restricts routing to them. Per-model input/output prices drive the cost figures shown in +[Usage & Logs](/agent-network/usage-and-logs); adjust them if your negotiated rates differ +from the catalog defaults. + +## The Keyless Endpoint + +All connected providers share a single account endpoint, generated when you connect your +first provider and reachable only over the NetBird overlay. + +

+ agent network endpoint on the Providers page +

+ +Agents send normal provider requests to the endpoint without an API key; which identities +may reach which providers is governed by [Policies](/agent-network/policies). + + diff --git a/src/pages/agent-network/usage-and-logs/access-logs.mdx b/src/pages/agent-network/usage-and-logs/access-logs.mdx new file mode 100644 index 00000000..5365c30b --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/access-logs.mdx @@ -0,0 +1,46 @@ +export const description = + 'The per-request Agent Network access log: caller identity, provider, model, tokens, cost, decision, and reason, with server-side filtering.' + +# Access Logs + +The access log is a per-request audit trail of agent-network traffic. Each entry +records the caller, provider and model, tokens and cost, the policy decision, +and the reason a request was allowed or denied. + +

+ agent network access logs table +

+ +## Columns + +- **Time** +- **User / Agent** — the resolved caller identity. +- **Auth Group** — the groups that authorized the request. +- **Provider** — resolved provider and model. +- **Tokens** — input and output. +- **Cost** +- **Status** and **Reason** — for denials, the mapped policy reason; for + allowed requests, a link to the policy that authorized it. + +## Filtering + +

+ agent network access log filters +

+ +Filter the log by: + +- **Date** — defaults to the last 14 days. +- **User** +- **Group** +- **Provider** +- **Model** +- **Path** — match requests whose path starts with a given prefix (e.g. `/v1/messages`). + +All filtering is applied server-side. + +## Availability + +Access logs are retained only when log collection is enabled for the account. +Usage and cost are still recorded when it's off — see +[Log Collection & Retention](/agent-network/usage-and-logs/log-collection). \ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/index.mdx b/src/pages/agent-network/usage-and-logs/index.mdx new file mode 100644 index 00000000..7677f733 --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/index.mdx @@ -0,0 +1,23 @@ +export const description = + 'Operate Agent Network: token and cost dashboards, per-request access logs, and log collection controls.' + +# Usage & Logs + +Once traffic flows, Agent Network gives you a per-request audit with real caller +identity, cost attribution, and token usage. + +## In This Section + +- [Usage Overview](/agent-network/usage-and-logs/usage-overview) — token and + cost trends over time. +- [Access Logs](/agent-network/usage-and-logs/access-logs) — per-request log + with server-side filtering. +- [Log Collection & Retention](/agent-network/usage-and-logs/log-collection) — + enable/disable logging, set retention, and control prompt capture. + +## Usage vs. Logs + +Token and cost **usage** is always collected, so dashboards and limits stay +accurate even if access-log collection is turned off. The full **access log** +(request detail and optional prompts) is retained according to your log +collection settings. \ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/log-collection.mdx b/src/pages/agent-network/usage-and-logs/log-collection.mdx new file mode 100644 index 00000000..820c457c --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/log-collection.mdx @@ -0,0 +1,36 @@ +import { Note } from '@/components/mdx' + +export const description = + 'Control whether Agent Network access logs are collected, how long they are retained, and whether prompts are captured.' + +# Log Collection & Retention + +Found under **Agent Network → Configuration → Log Collection**, these +account-level controls govern how much request detail is stored. + +

+ agent network log collection and retention configuration +

+ +## Enable Log Collection + +Persist a per-request [access log](/agent-network/usage-and-logs/access-logs) +for every agent-network request. On by default. + + + Token and cost usage is recorded regardless of this setting, so + [Usage Overview](/agent-network/usage-and-logs/usage-overview) and limits stay + accurate even when log collection is off. + + +## Retention Period + +Choose how long access logs are kept before they're automatically deleted +(7–90 days, or indefinite). A periodic sweep removes older entries. Usage +history is kept separately and isn't affected. + +## Enable Prompt Collection + +Capture prompt and completion bodies on logged requests. Prompt capture only +runs when this is on **and** a policy [guardrail](/agent-network/policies/guardrails) +also enables it. PII redaction can strip sensitive data before storage. \ No newline at end of file diff --git a/src/pages/agent-network/usage-and-logs/usage-overview.mdx b/src/pages/agent-network/usage-and-logs/usage-overview.mdx new file mode 100644 index 00000000..5e2562f5 --- /dev/null +++ b/src/pages/agent-network/usage-and-logs/usage-overview.mdx @@ -0,0 +1,34 @@ +export const description = + 'Token and cost usage for Agent Network aggregated over time, filterable by date, user, group, provider, and model.' + +# Usage Overview + +The Usage tab shows account consumption over time as a per-day chart with a +Tokens / Cost switch, plus a breakdown table. + +

+ agent network usage overview chart and table +

+ +## Filters + +Filter the view by: + +- **Date** — defaults to the last 14 days. +- **User** +- **Group** +- **Provider** +- **Model** + +Filters apply to both the chart and the table. + +## Tokens vs. Cost + +Switch between input/output token totals and estimated USD spend. Cost is +derived from the per-model pricing configured on each +[provider](/agent-network/providers). + +## Always Collected + +Usage is recorded on every request independently of access-log collection, so +this view stays complete even when logs are disabled. \ No newline at end of file