mirror of
https://github.com/netbirdio/docs.git
synced 2026-09-17 04:19:04 +02:00
Document agentgateway Agent Network integration (#949)
* docs: add agentgateway Agent Network integration Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io> * docs: remove agentgateway release note Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io> * docs: remove agentgateway example link Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io> * docs: link agentgateway routing guides Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io> * docs: add agentgateway analytics next steps Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io> --------- Signed-off-by: Daneyon Hansen <daneyon.hansen@solo.io>
This commit is contained in:
Daneyon Hansen
@@ -551,6 +551,10 @@ export const docsNavigation = [
|
||||
},
|
||||
{ title: 'Codex', href: '/agent-network/integrations/codex' },
|
||||
{ title: 'LiteLLM', href: '/agent-network/integrations/litellm' },
|
||||
{
|
||||
title: 'agentgateway',
|
||||
href: '/agent-network/integrations/agentgateway',
|
||||
},
|
||||
{ title: 'vLLM', href: '/agent-network/integrations/vllm' },
|
||||
{
|
||||
title: 'Google Vertex AI',
|
||||
|
||||
@@ -37,7 +37,8 @@ upstream API or gateway. The proxy can also inject the calling agent's identity
|
||||
request, so the gateway itself can attribute usage and enforce its own limits based on the
|
||||
agent's group membership. For example, with a LiteLLM gateway it writes the agent's IdP groups
|
||||
into `metadata.tags` and its identity into the `x-litellm-end-user-id` header, so LiteLLM
|
||||
can apply tag budgets and per-user attribution.
|
||||
can apply tag budgets and per-user attribution. With agentgateway, NetBird uses the trusted
|
||||
`x-netbird-user-id` and `x-netbird-groups` headers for request attribution.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/agent-network/how-it-works/agent-network-diagram-llm-apis.png" alt="agent network LLM request path through the NetBird proxy" className="imagewrapper-big" />
|
||||
@@ -104,10 +105,11 @@ upstream:
|
||||
the request is denied here. See [Policies, Limits, and
|
||||
Guardrails](#policies-limits-and-guardrails).
|
||||
5. **Stamp identity for the gateway.** Add the caller's identity to the upstream request
|
||||
(for example into `metadata.tags` and `x-litellm-end-user-id`) for gateways that key
|
||||
their own budgets and attribution off it, or into a provider's own cost-allocation
|
||||
metadata such as AWS Bedrock's `X-Amzn-Bedrock-Request-Metadata`. This is on by default
|
||||
and can be turned off per provider. See [Identity
|
||||
(for example into `metadata.tags` and `x-litellm-end-user-id`, or agentgateway's
|
||||
`x-netbird-user-id` and `x-netbird-groups` headers) for gateways that key their own
|
||||
budgets and attribution off it, or into a provider's own cost-allocation metadata such
|
||||
as AWS Bedrock's `X-Amzn-Bedrock-Request-Metadata`. This is on by default and can be
|
||||
turned off per provider. See [Identity
|
||||
Metadata](/agent-network/providers#identity-metadata).
|
||||
6. **Apply guardrails.** Enforce the model allowlist and the prompt-capture rules.
|
||||
|
||||
|
||||
@@ -0,0 +1,155 @@
|
||||
import { Warning } from '@/components/mdx'
|
||||
|
||||
export const description =
|
||||
'Connect a private agentgateway listener to NetBird Agent Network with strict virtual-key authentication and trusted caller identity headers.'
|
||||
|
||||
# agentgateway
|
||||
|
||||
[agentgateway](https://agentgateway.dev/) is an AI-native data plane that routes requests
|
||||
to multiple model providers. Connecting it behind NetBird gives agents one keyless endpoint
|
||||
over the NetBird network while agentgateway continues to handle provider routing,
|
||||
authentication, and observability.
|
||||
|
||||
NetBird supports the OpenAI and Anthropic request shapes through one agentgateway provider.
|
||||
Configure agentgateway routes for the paths you intend to expose, such as
|
||||
`/v1/chat/completions`, `/v1/responses`, `/v1/embeddings`, and `/v1/messages`.
|
||||
See the agentgateway provider documentation for
|
||||
[Kubernetes](https://agentgateway.dev/docs/kubernetes/latest/llm/providers/) or
|
||||
[standalone](https://agentgateway.dev/docs/standalone/latest/llm/providers/) deployments
|
||||
for details on configuring routing.
|
||||
|
||||
## Prepare agentgateway
|
||||
|
||||
Before connecting the provider in NetBird, configure an agentgateway listener that:
|
||||
|
||||
- Is reachable from the NetBird Agent Network proxy.
|
||||
- Routes the OpenAI and Anthropic paths you want to support to the corresponding backends.
|
||||
- Uses strict API-key authentication with a dedicated virtual key for NetBird.
|
||||
- Is private and cannot be reached by clients through another network path.
|
||||
|
||||
Agentgateway stores a SHA-256 hash of the virtual key. Enter the corresponding raw key in
|
||||
NetBird. The NetBird proxy sends it to agentgateway as an
|
||||
`Authorization: Bearer <virtual-key>` header on every upstream request.
|
||||
|
||||
## Connect agentgateway as a Provider
|
||||
|
||||
1. Go to **Agent Network → Providers** and click **Connect Provider**.
|
||||
2. Select **agentgateway**.
|
||||
3. Set **Upstream URL** to the private agentgateway proxy listener that the NetBird proxy
|
||||
can reach.
|
||||
4. Paste the raw **Virtual API key** configured for strict API-key authentication in
|
||||
agentgateway.
|
||||
5. Leave the model list empty to make agentgateway a catch-all, or add the exact model IDs
|
||||
and pricing that NetBird should use for routing and cost reporting.
|
||||
6. Keep **Forward identity metadata** enabled and save the provider.
|
||||
|
||||
NetBird stores the virtual key server-side. Clients use the generated Agent Network
|
||||
endpoint without receiving this key or the upstream providers' credentials.
|
||||
|
||||
## Create a Policy
|
||||
|
||||
Agent Network denies requests until a policy authorizes them:
|
||||
|
||||
1. Go to **Agent Network → Policies** and add a policy.
|
||||
2. Select the source groups whose users or agents should reach agentgateway.
|
||||
3. Select the agentgateway provider as the destination.
|
||||
4. Optionally add [limits](/agent-network/policies/limits) and
|
||||
[guardrails](/agent-network/policies/guardrails), then save the policy.
|
||||
|
||||
See [Policies](/agent-network/policies) for the complete policy behavior.
|
||||
|
||||
## Trusted Identity Headers
|
||||
|
||||
For authorized requests, the NetBird proxy removes caller-supplied values and adds these
|
||||
headers from the authenticated NetBird identity:
|
||||
|
||||
| Header | Value |
|
||||
| --- | --- |
|
||||
| `x-netbird-user-id` | The user's email, the peer name when no user email is available, or the internal user ID as a final fallback. |
|
||||
| `x-netbird-groups` | A sorted CSV of the display names of groups that authorized this request. |
|
||||
|
||||
Agentgateway can map the headers into its standard request-log attributes:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
rawConfig:
|
||||
config:
|
||||
standardAttributes:
|
||||
user: 'request.headers["x-netbird-user-id"]'
|
||||
group: 'request.headers["x-netbird-groups"]'
|
||||
```
|
||||
|
||||
<Warning>
|
||||
The private agentgateway listener must remain reachable only through the NetBird proxy.
|
||||
The virtual key authenticates NetBird, but it does not make identity headers received
|
||||
through another network path trustworthy. Enforce this boundary with NetworkPolicy, a
|
||||
service mesh, a firewall, or an equivalent private-network control.
|
||||
</Warning>
|
||||
|
||||
`x-netbird-groups` contains display names for attribution. It is not a delimiter-safe set
|
||||
of stable group IDs and must not be used as an agentgateway authorization claim. Enforce
|
||||
user and group authorization with NetBird Agent Network policies.
|
||||
|
||||
## Verify the Integration
|
||||
|
||||
Run requests from a NetBird peer covered by the policy. Replace `<your-endpoint>` with the
|
||||
endpoint shown on **Agent Network → Providers** and choose models configured on your
|
||||
agentgateway backends.
|
||||
|
||||
An OpenAI request uses the normal OpenAI path and body:
|
||||
|
||||
```bash
|
||||
curl -fsS "https://<your-endpoint>/v1/chat/completions" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "<openai-model>",
|
||||
"messages": [{"role": "user", "content": "Reply with connected."}],
|
||||
"max_tokens": 16
|
||||
}'
|
||||
```
|
||||
|
||||
An Anthropic request uses the normal Anthropic path and body:
|
||||
|
||||
```bash
|
||||
curl -fsS "https://<your-endpoint>/v1/messages" \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{
|
||||
"model": "<anthropic-model>",
|
||||
"messages": [{"role": "user", "content": "Reply with connected."}],
|
||||
"max_tokens": 16
|
||||
}'
|
||||
```
|
||||
|
||||
Neither request includes a provider key or the agentgateway virtual key. NetBird identifies
|
||||
the caller from the peer connection, enforces the Agent Network policy, injects the virtual
|
||||
key and trusted identity headers, and forwards the request to agentgateway.
|
||||
|
||||
If a request fails, check both systems:
|
||||
|
||||
- A `403` from the Agent Network endpoint usually means the peer is not authorized by the
|
||||
selected NetBird policy.
|
||||
- A `401` from agentgateway usually means the raw virtual key stored in NetBird does not
|
||||
match the hash configured in agentgateway.
|
||||
- A model routed with zero cost usually needs an explicit model and pricing row in NetBird.
|
||||
|
||||
## Next Steps
|
||||
|
||||
The integration does not require agentgateway's request-log database, model catalog, or
|
||||
Admin UI. Add them if you also want agentgateway-side analytics:
|
||||
|
||||
- Follow the agentgateway cost-dashboard guide for
|
||||
[Kubernetes](https://agentgateway.dev/docs/kubernetes/latest/llm/cost-controls/dashboard/)
|
||||
or
|
||||
[standalone](https://agentgateway.dev/docs/standalone/latest/llm/cost-controls/dashboard/)
|
||||
deployments. The dashboard can group requests, tokens, and cost by the
|
||||
`agentgateway.user` and `agentgateway.group` attributes populated from NetBird's trusted
|
||||
identity headers. Without a model catalog, request and token usage is still available,
|
||||
but cost is reported as zero.
|
||||
- Review the agentgateway Admin UI guidance for
|
||||
[Kubernetes](https://agentgateway.dev/docs/kubernetes/latest/observability/ui/) or
|
||||
[standalone](https://agentgateway.dev/docs/standalone/latest/operations/ui/) before
|
||||
making the UI reachable outside its default private interface.
|
||||
|
||||
Because `x-netbird-groups` is a CSV string, agentgateway treats the complete sorted value
|
||||
as one group dimension. A request authorized by `Engineering,Platform` is attributed to
|
||||
that combined value rather than two separate groups.
|
||||
@@ -1,5 +1,5 @@
|
||||
export const description =
|
||||
'Connect specific agent tools and gateways to NetBird Agent Network: Claude Code, Codex, and LiteLLM.'
|
||||
'Connect specific agent tools and gateways to NetBird Agent Network: Claude Code, Codex, LiteLLM, and agentgateway.'
|
||||
|
||||
# Integrations
|
||||
|
||||
@@ -17,6 +17,8 @@ Replace `<your-endpoint>` in the snippets below with the endpoint shown on the
|
||||
- [Codex](/agent-network/integrations/codex): point the Codex CLI at the endpoint.
|
||||
- [LiteLLM](/agent-network/integrations/litellm): use a LiteLLM gateway with identity-based
|
||||
attribution and budgets.
|
||||
- [agentgateway](/agent-network/integrations/agentgateway): route OpenAI and Anthropic
|
||||
requests through a private listener with trusted NetBird identity headers.
|
||||
- [vLLM](/agent-network/integrations/vllm): connect a self-hosted, OpenAI-compatible vLLM
|
||||
server.
|
||||
- [Google Vertex AI](/agent-network/integrations/vertex-ai): connect Gemini and Claude on
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
export const description =
|
||||
'Connect AI providers and gateways (OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Mistral, Kimi (Moonshot AI), LiteLLM, Portkey, Bifrost, Cloudflare, Vercel, OpenRouter, or any OpenAI-compatible endpoint) to NetBird Agent Network and expose a single keyless endpoint.'
|
||||
'Connect AI providers and gateways (OpenAI, Anthropic, Azure OpenAI, AWS Bedrock, Google Vertex AI, Mistral, Kimi (Moonshot AI), LiteLLM, agentgateway, Portkey, Bifrost, Cloudflare, Vercel, OpenRouter, or any OpenAI-compatible endpoint) to NetBird Agent Network and expose a single keyless endpoint.'
|
||||
|
||||
# Providers
|
||||
|
||||
@@ -36,6 +36,7 @@ forward the calling agent's identity to these so the gateway can apply its own a
|
||||
and budgets (see [How It Works](/agent-network/how-it-works#llm-apis-and-ai-gateways)):
|
||||
|
||||
- LiteLLM Proxy
|
||||
- agentgateway
|
||||
- Portkey AI Gateway
|
||||
- Bifrost
|
||||
- Cloudflare AI Gateway
|
||||
@@ -159,4 +160,3 @@ first provider and reachable only over the NetBird overlay.
|
||||
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).
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user