Non-agentic HTTP traffic

Route HTTP traffic to a non-agentic backend such as httpbin with the agentgateway binary.

Verified

Use the agentgateway binary to route HTTP traffic to a simple backend (httpbin) running locally.

    flowchart LR
    A[client] -->|localhost:3000| B[agentgateway]
    B --> C[httpbin]

The client sends requests to agentgateway on port 3000.
Agentgateway forwards the requests to the httpbin backend based on the route and backend configuration.
Httpbin responds, and agentgateway returns the response back to the client.

Before you begin

Install the agentgateway binary.
Download and install the agentgateway binary. Alternatively, you can manually download the binary from the agentgateway releases page.
To install the latest release:
curl -sL https://agentgateway.dev/install | bash
Example output:
% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 8878 100 8878 0 0 68998 0 --:--:-- --:--:-- --:--:-- 69359 Downloading https://github.com/agentgateway/agentgateway/releases/download/v1.5.0/agentgateway-darwin-arm64 Verifying checksum... Done. Preparing to install agentgateway into /usr/local/bin Password: agentgateway installed into /usr/local/bin/agentgateway
To install a specific version, pass the --version flag. Use any release tag from the agentgateway releases page, such as v1.5.0. The version must start with v (the script adds the v if you omit it).
curl -sL https://agentgateway.dev/install | bash -s -- --version v1.5.0
A nightly build has no release tag and is not listed on the releases page. Instead, each nightly build is a run of the nightly GitHub Actions workflow, and you download the binary from that run’s artifacts.
1. Go to the nightly builds in GitHub Actions and click the run that you want to install from.
2. Copy the run ID from the end of that run’s URL, such as 24873456345 in https://github.com/agentgateway/agentgateway/actions/runs/24873456345.
3. Using the gh CLI, download the binary artifact for your OS. The following example uses macOS. For other operating systems, replace release-binary-mac with release-binary-linux, release-binary-linux-arm, or release-binary-windows.
  gh run download 24873456345 -R agentgateway/agentgateway -n release-binary-mac
4. Make the binary file executable and move it to your binary location, such as in the following example.
  chmod +x agentgateway sudo mv agentgateway /usr/local/bin/agentgateway
5. Verify that you have the nightly build. The version string of a nightly build is 0.0.0-alpha.<commit>, not a release tag.
  agentgateway --version
  Example output:
  { "version": "0.0.0-alpha.813d7d0", "git_revision": "813d7d0ab4757db7c8ed5a639bc63c0bb20ac116", "rust_version": "1.95.0", "build_profile": "release", "build_target": "aarch64-apple-darwin" }

Install Docker to run httpbin.

Steps

Step 1: Start httpbin in Docker

Run the httpbin image so it listens on port 80 inside the container. Map it to a host port such as 8000 so that agentgateway can reach it.

docker run --rm -d -p 8000:80 --name httpbin kennethreitz/httpbin

Verify that httpbin responds.

curl -s http://localhost:8000/headers | head -20 || true

Example output:

{
  "headers": {
    "Accept": "*/*",
    "Host": "localhost:8000",
    "User-Agent": "curl/8.7.1"
  }
}

Step 2: Configure agentgateway to route to httpbin

You add the gateway and route from the UI, so you can start agentgateway without a config file. When you run agentgateway without specifying a config, it bootstraps a basic config at ~/.config/agentgateway/config.yaml and uses it automatically.

In a separate terminal, start agentgateway.
```
agentgateway
```
Open the agentgateway UI.
- On the first run of the UI, the welcome wizard already enables the API row, because the bootstrap config includes a gateway. Click Continue.
- If you already opened the UI, the Gateway Overview home page shows the Traffic row enabled.
Add a gateway.
1. In the Traffic section of the navigation menu, click Gateways.
2. Click Add gateway, enter httpbin for the Name and 3000 for the Port, and click Save gateway.
  The bootstrap config already created a gateway named default on port 4000. The name default is reserved for it, so give the new gateway a different name.
Add a route to httpbin.
1. Click Routes, and then click Add route.
2. For the Gateway, select the httpbin gateway you created.
3. For the Name, enter httpbin. Save route stays disabled until the route has a name.
4. Under Backends, click Add backend, keep the Host target type, and enter 127.0.0.1:8000 for the host.
5. Click Save route.

Step 3: Send a request through agentgateway

Send a request to agentgateway on port 3000. Agentgateway forwards it to httpbin; the response is returned to you.

curl -i http://localhost:3000/headers

Example response (status and headers):

HTTP/1.1 200 OK
content-type: application/json
...

Example JSON body:

{
  "headers": {
    "Accept": "*/*",
    "Host": "localhost:3000",
    "User-Agent": "curl/8.7.1"
  }
}

You can try other httpbin endpoints through agentgateway, such as the following.

curl -s http://localhost:3000/get
curl -s http://localhost:3000/post -X POST -H "Content-Type: application/json" -d '{"key":"value"}'

Step 4 (Optional): Stop httpbin

When you are done, stop and remove the httpbin container.

docker stop httpbin

Next steps

Check out more guides for managing your APIs with agentgateway.

Traffic managementControl traffic with matching, redirects, body buffering, rewrites, and transformations. ResiliencyConfigure retries, timeouts, rate limits, and mirroring for fault tolerance. SecuritySecure backends and routes with different types of security, authentication, authorization, and rate limiting policies.

MCP servers

Was this page helpful?