Skip to content

Commit 69d0875

Browse files
artbergerartberger
authored
Merge pull request #795 from agentgateway/adb-gateways
Docs for binds to gateways draft
2 parents 524428c + 2120567 commit 69d0875

100 files changed

Lines changed: 4817 additions & 2828 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎assets/agw-docs/pages/agentgateway/integrations/llm-clients/claude-code-13x.md‎

Lines changed: 183 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,183 @@
1+
Configure [Claude Code](https://code.claude.com/docs), the AI coding CLI by Anthropic, to route LLM requests through your agentgateway proxy.
2+
3+
The primary use case is routing Claude Code to non-Anthropic LLM backends (such as vLLM, Ollama, or any OpenAI-compatible provider) for cost optimization and flexibility. You can also configure direct routing to Anthropic or use a Claude Teams account as alternative options.
4+
5+
## Before you begin
6+
7+
1. {{< reuse "agw-docs/snippets/prereq-agentgateway.md" >}}
8+
2. Install the [Claude Code CLI](https://code.claude.com/docs) (`npm install -g @anthropic-ai/claude-code`).
9+
10+
> [!NOTE]
11+
> The `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` environment variable disables Claude Code's experimental beta features. You typically **do not need** this variable when proxying to non-Anthropic backends or standard Anthropic routing.
12+
>
13+
> Only set this variable if you encounter errors like `Extra inputs are not permitted` when using advanced Anthropic features (such as experimental translation or extended thinking). If you use a non-Anthropic backend, this variable can be safely omitted.
14+
15+
## Configure agentgateway with OpenAI-compatible backend
16+
17+
Route Claude Code to any OpenAI-compatible LLM provider (such as vLLM, Ollama, or local language models). This is the recommended approach for cost-effective and flexible deployment.
18+
19+
1. Create a configuration file with an OpenAI-compatible provider. The wildcard `*` model name accepts any model. Claude Code sends the model in each request, so you do not need to pin a specific model.
20+
21+
```yaml {paths="claude-code-openai-validate"}
22+
cat > config.yaml << 'EOF'
23+
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
24+
llm:
25+
models:
26+
- name: "*"
27+
provider: openAI
28+
params:
29+
baseURL: "http://localhost:8000/v1" # vLLM or similar OpenAI-compatible endpoint
30+
apiKey: "mock-key" # Not used for local providers, but required by config
31+
EOF
32+
```
33+
34+
Replace `http://localhost:8000/v1` with your OpenAI-compatible provider's endpoint.
35+
36+
{{< doc-test paths="claude-code-openai-validate" >}}
37+
agentgateway -f config.yaml --validate-only
38+
{{< /doc-test >}}
39+
40+
2. Start agentgateway.
41+
42+
```bash
43+
agentgateway -f config.yaml
44+
```
45+
46+
3. Configure Claude Code to point to your agentgateway instance.
47+
48+
```bash
49+
export ANTHROPIC_BASE_URL="http://localhost:4000"
50+
```
51+
52+
4. Verify the connection.
53+
54+
```bash
55+
claude -p "Hello"
56+
```
57+
58+
## Configure agentgateway with Anthropic backend
59+
60+
Alternatively, route Claude Code directly to Anthropic's API through agentgateway. This is useful if you want to leverage Anthropic's latest models or features directly.
61+
62+
1. Get an Anthropic API key from the [Anthropic Console](https://platform.claude.com).
63+
64+
2. Export your Anthropic API key.
65+
66+
```bash
67+
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
68+
```
69+
70+
3. Create a configuration file with the Anthropic provider. The wildcard `*` model name accepts any model. Claude Code sends the model in each request, so you do not need to pin a specific model.
71+
72+
```yaml {paths="claude-code-anthropic-validate"}
73+
cat > config.yaml << 'EOF'
74+
# yaml-language-server: $schema=https://agentgateway.dev/schema/config
75+
llm:
76+
models:
77+
- name: "*"
78+
provider: anthropic
79+
params:
80+
apiKey: "$ANTHROPIC_API_KEY"
81+
EOF
82+
```
83+
84+
{{< doc-test paths="claude-code-anthropic-validate" >}}
85+
export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-test}"
86+
agentgateway -f config.yaml --validate-only
87+
{{< /doc-test >}}
88+
89+
4. Start agentgateway.
90+
91+
```bash
92+
agentgateway -f config.yaml
93+
```
94+
95+
5. Configure Claude Code.
96+
97+
```bash
98+
export ANTHROPIC_BASE_URL="http://localhost:4000"
99+
```
100+
101+
6. Verify the connection.
102+
103+
```bash
104+
claude -p "Hello"
105+
```
106+
107+
Example output:
108+
109+
```
110+
Hello! How can I help you today?
111+
```
112+
113+
If you see an error like `API Error: 400 context_management: Extra inputs are not permitted`, Claude Code is sending experimental beta parameters that agentgateway does not yet support. Disable experimental betas and retry the request.
114+
115+
```bash
116+
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
117+
claude -p "Hello"
118+
```
119+
120+
{{< callout type="info" >}}
121+
For pinned model configuration, extended thinking, and other options, see the [Anthropic provider page]({{< link-hextra path="/llm/providers/anthropic" >}}).
122+
{{< /callout >}}
123+
124+
## Claude Teams or Pro account
125+
126+
If you have a Claude Teams or Pro account, you can use agentgateway for request routing without an API key. Authentication is handled by your Claude subscription via OAuth.
127+
128+
1. Create a configuration file. Agentgateway listens on port `4001` and exposes Claude at the `/claude` path.
129+
130+
```yaml
131+
cat > config.yaml << 'EOF'
132+
binds:
133+
- port: 4001
134+
listeners:
135+
- name: default
136+
protocol: HTTP
137+
routes:
138+
- name: claude-agent
139+
matches:
140+
- path:
141+
pathPrefix: /claude
142+
policies:
143+
urlRewrite:
144+
path:
145+
prefix: /
146+
backends:
147+
- ai:
148+
name: claude-agent
149+
provider:
150+
anthropic: {}
151+
policies:
152+
ai:
153+
routes:
154+
/v1/messages: messages
155+
/v1/messages/count_tokens: anthropicTokenCount
156+
'*': passthrough
157+
EOF
158+
```
159+
160+
2. Start agentgateway.
161+
162+
```bash
163+
agentgateway -f config.yaml
164+
```
165+
166+
3. Set the `ANTHROPIC_BASE_URL` environment variable to point Claude Code at the `/claude` path.
167+
168+
```bash
169+
export ANTHROPIC_BASE_URL="http://localhost:4001/claude"
170+
```
171+
172+
4. Verify the connection.
173+
174+
```bash
175+
claude -p "Hello"
176+
```
177+
178+
## Next steps
179+
180+
{{< cards >}}
181+
{{< card path="/llm/providers/anthropic" title="Anthropic provider" subtitle="Complete Anthropic provider configuration" >}}
182+
{{< card path="/llm/prompt-guards/" title="Prompt guards" subtitle="Set up guardrails for LLM requests and responses" >}}
183+
{{< /cards >}}

‎assets/agw-docs/pages/agentgateway/integrations/llm-clients/claude-code.md‎

Lines changed: 22 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -128,31 +128,30 @@ If you have a Claude Teams or Pro account, you can use agentgateway for request
128128

129129
```yaml
130130
cat > config.yaml << 'EOF'
131-
binds:
132-
- port: 4001
133-
listeners:
134-
- name: default
131+
gateways:
132+
default:
133+
port: 4001
135134
protocol: HTTP
136-
routes:
137-
- name: claude-agent
138-
matches:
139-
- path:
140-
pathPrefix: /claude
135+
routes:
136+
- name: claude-agent
137+
matches:
138+
- path:
139+
pathPrefix: /claude
140+
policies:
141+
urlRewrite:
142+
path:
143+
prefix: /
144+
backends:
145+
- ai:
146+
name: claude-agent
147+
provider:
148+
anthropic: {}
141149
policies:
142-
urlRewrite:
143-
path:
144-
prefix: /
145-
backends:
146-
- ai:
147-
name: claude-agent
148-
provider:
149-
anthropic: {}
150-
policies:
151-
ai:
152-
routes:
153-
/v1/messages: messages
154-
/v1/messages/count_tokens: anthropicTokenCount
155-
'*': passthrough
150+
ai:
151+
routes:
152+
/v1/messages: messages
153+
/v1/messages/count_tokens: anthropicTokenCount
154+
'*': passthrough
156155
EOF
157156
```
158157

‎assets/agw-docs/pages/agentgateway/integrations/llm-clients/claude-desktop-13x.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
Configure [Claude Desktop](https://claude.com/download) to route requests through your agentgateway proxy using a Claude Teams or Pro account.
2+
3+
## Before you begin
4+
5+
1. {{< reuse "agw-docs/snippets/prereq-agentgateway.md" >}}
6+
2. Install [Claude Desktop](https://claude.com/download).
7+
3. Install the [Claude Code CLI](https://code.claude.com/docs) (`npm install -g @anthropic-ai/claude-code`). This is required to run `claude setup-token` and obtain your bearer token.
8+
4. Have a Claude Teams or Pro subscription.
9+
10+
## Configure agentgateway
11+
12+
Start agentgateway with the Teams configuration. Agentgateway listens on port `4001` and exposes Claude at the `/claude` path.
13+
14+
1. Create a configuration file.
15+
16+
```yaml
17+
cat > config.yaml << 'EOF'
18+
binds:
19+
- port: 4001
20+
listeners:
21+
- name: default
22+
protocol: HTTP
23+
routes:
24+
- name: claude-agent
25+
matches:
26+
- path:
27+
pathPrefix: /claude
28+
policies:
29+
urlRewrite:
30+
path:
31+
prefix: /
32+
backends:
33+
- ai:
34+
name: claude-agent
35+
provider:
36+
anthropic: {}
37+
policies:
38+
ai:
39+
routes:
40+
/v1/messages: messages
41+
/v1/messages/count_tokens: anthropicTokenCount
42+
'*': passthrough
43+
EOF
44+
```
45+
46+
2. Start agentgateway.
47+
48+
```bash
49+
agentgateway -f config.yaml
50+
```
51+
52+
{{< callout type="info" >}}
53+
Claude Code automatically sends the `anthropic-beta: oauth-2025-04-20` header required for OAuth-based authentication. Claude Desktop may require this header to be set as well depending on your client version. If requests fail with a 400 error, add the following to the `passthrough` route policy in your config:
54+
55+
```yaml
56+
policies:
57+
requestHeaderModifier:
58+
add:
59+
anthropic-beta: oauth-2025-04-20
60+
```
61+
{{< /callout >}}
62+
63+
## Configure Claude Desktop
64+
65+
1. Get a bearer token for your Claude account.
66+
67+
```bash
68+
claude setup-token
69+
```
70+
71+
Copy the token printed to the terminal.
72+
73+
2. Open Claude Desktop and enable developer mode: **Help → Troubleshooting → Enable Developer Mode**. Then fully quit and relaunch Claude Desktop. A new **Developer** menu appears in the menu bar.
74+
75+
3. In the menu bar, go to **Developer → Configure Third Party Inference → Gateway**.
76+
77+
4. Enter the gateway URL. Use `127.0.0.1` rather than `localhost`.
78+
79+
```
80+
http://127.0.0.1:4001/claude
81+
```
82+
83+
5. Enter the bearer token you copied in step 1.
84+
85+
6. Click **Save** and restart Claude Desktop.
86+
87+
## Verify the connection
88+
89+
Send a message in Claude Desktop. If the connection is successful, responses flow through your agentgateway proxy and appear in the terminal where agentgateway is already running.
90+
91+
Look for log entries like the following in your running agentgateway output:
92+
93+
```
94+
info request gateway=default/default listener=http route=claude-agent endpoint=api.anthropic.com:443 http.method=POST http.path=/v1/messages http.status=200 protocol=llm
95+
```
96+
97+
## Next steps
98+
99+
{{< cards >}}
100+
{{< card path="/llm/providers/anthropic" title="Anthropic provider" subtitle="Complete Anthropic provider configuration" >}}
101+
{{< card path="/llm/prompt-guards/" title="Prompt guards" subtitle="Set up guardrails for LLM requests and responses" >}}
102+
{{< /cards >}}

‎assets/agw-docs/pages/agentgateway/integrations/llm-clients/claude-desktop.md‎

Lines changed: 22 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -15,31 +15,30 @@ Start agentgateway with the Teams configuration. Agentgateway listens on port `4
1515

1616
```yaml
1717
cat > config.yaml << 'EOF'
18-
binds:
19-
- port: 4001
20-
listeners:
21-
- name: default
18+
gateways:
19+
default:
20+
port: 4001
2221
protocol: HTTP
23-
routes:
24-
- name: claude-agent
25-
matches:
26-
- path:
27-
pathPrefix: /claude
22+
routes:
23+
- name: claude-agent
24+
matches:
25+
- path:
26+
pathPrefix: /claude
27+
policies:
28+
urlRewrite:
29+
path:
30+
prefix: /
31+
backends:
32+
- ai:
33+
name: claude-agent
34+
provider:
35+
anthropic: {}
2836
policies:
29-
urlRewrite:
30-
path:
31-
prefix: /
32-
backends:
33-
- ai:
34-
name: claude-agent
35-
provider:
36-
anthropic: {}
37-
policies:
38-
ai:
39-
routes:
40-
/v1/messages: messages
41-
/v1/messages/count_tokens: anthropicTokenCount
42-
'*': passthrough
37+
ai:
38+
routes:
39+
/v1/messages: messages
40+
/v1/messages/count_tokens: anthropicTokenCount
41+
'*': passthrough
4342
EOF
4443
```
4544

0 commit comments

Comments
 (0)