Agent Gateway Quick Start

Prerequisites

A WireGuard Interface on a Network, as in the WireGuard Interface Quick Start. This page uses the interface c788eb40-a4c0-4bf5-8f84-976027960f8e.
An Edge Compute function and the telnyx-edge CLI, as in the Edge Compute Quick Start.

An Agent Gateway instance sits on the user’s Network. This page creates one, issues a key, and connects an agent to it.

New instances currently cannot finish provisioning: they move from pending to failed at their database migration (AIPLAT-1702), so a newly created instance does not reach ready. The steps on this page ran on instances that provisioned before this regression.

Create the Agent Gateway

Send POST /v2/agent_gateways with the WireGuard Interface’s id:

{
  "name": "support-gw",
  "wireguard_interface_id": "c788eb40-a4c0-4bf5-8f84-976027960f8e"
}

The response returns the instance pending, with no gateway_url yet. network_id is the WireGuard Interface’s Network.

{
  "data": {
    "id": "32ce035d-3165-4031-b1a7-a7c0c259590a",
    "name": "support-gw",
    "status": "pending",
    "gateway_url": null,
    "wireguard_interface_id": "c788eb40-a4c0-4bf5-8f84-976027960f8e",
    "network_id": "7ade8c3c-95a7-447b-92f2-c829f760159c",
    ...
  }
}

Wait for the Gateway

Poll GET /v2/agent_gateways/{id} until status is ready. The instance joins the WireGuard Interface as a peer named agw-32ce035d-3165-4031-b1a7-a7c0c259590a, which puts the interface in provisioning again. The instance is ready once the interface is provisioned and the instance answers through the tunnel. Here that took 172 seconds. gateway_url is its address on the interface:

{
  "data": {
    "id": "32ce035d-3165-4031-b1a7-a7c0c259590a",
    "status": "ready",
    "gateway_url": "http://172.27.0.4:4000",
    ...
  }
}

Issue a Key

The instance refuses a request without a key. Send POST /v2/agent_gateways/{id}/keys with a name for the agent that holds it:

{
  "name": "support-agent"
}

The response carries the key’s value in key, and no later response returns it:

{
  "data": {
    "id": "9b1f1703ade70a9e35be9ac96d439ce3bc8e68ca7fd0ae5fa4d847977d23f7bc",
    "key": "sk-EXAMPLE-KEY-VALUE",
    "name": "support-agent",
    "models": [],
    "blocked": false,
    ...
  }
}

Connect an Agent

An agent on Edge Compute reaches the instance through a network binding to the instance’s WireGuard Interface. In the function’s func.toml, bind the interface and set the instance’s gateway_url:

func.toml

[network.PRIVATE_NET]
id = "c788eb40-a4c0-4bf5-8f84-976027960f8e"

[env_vars]
GATEWAY_URL = "http://172.27.0.4:4000"

Store the key from Issue a Key as a secret:

Workstation

telnyx-edge secrets add AGENT_GATEWAY_KEY "$AGENT_GATEWAY_KEY"

The function sends a chat completion to gateway_url through the binding, with the key:

index.ts

import * as http from "node:http";
import { env } from "@telnyx/edge-runtime";

const { GATEWAY_URL, AGENT_GATEWAY_KEY } = process.env;

const server = http.createServer(async (req, res) => {
  if (req.url === "/health" || req.url?.startsWith("/health/")) {
    res.writeHead(200); res.end(); return;
  }
  const response = await env.PRIVATE_NET.fetch(`${GATEWAY_URL}/v1/chat/completions`, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${AGENT_GATEWAY_KEY}` },
    body: JSON.stringify({
      model: "GLM-5.3-Flash",
      messages: [{ role: "user", content: "Say hello in five words." }],
    }),
  });
  const completion = await response.json();
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ answer: completion.choices[0].message.content }));
});

server.listen(process.env.PORT || 8080);

Generate the binding’s types, and ship the function:

Workstation

telnyx-edge types
telnyx-edge ship

Send the function a request:

Workstation

curl https://acme-agent-6a01e98a-b.telnyxcompute.com

Output

{"answer":"Hello, nice to meet you!"}

The instance’s spend logs list the request under the key support-agent.

Delete the Agent Gateway

DELETE /v2/agent_gateways/{id} returns the instance deleting. The gateway stops answering at once, and seconds later GET /v2/agent_gateways/{id} returns 404.

{
  "data": {
    "id": "32ce035d-3165-4031-b1a7-a7c0c259590a",
    "status": "deleting",
    ...
  }
}

Get Started

Targets

Virtual Private Cloud

Outbound Authentication

Inbound Authentication

Authorization and Policy

Traffic Control

Audit and Observability

API Reference

For AI Agents

Agent Gateway Quick Start

Prerequisites

Create the Agent Gateway

Wait for the Gateway

Issue a Key

Connect an Agent

Delete the Agent Gateway

​Prerequisites

​Create the Agent Gateway

​Wait for the Gateway

​Issue a Key

​Connect an Agent

​Delete the Agent Gateway

Prerequisites

Create the Agent Gateway

Wait for the Gateway

Issue a Key

Connect an Agent

Delete the Agent Gateway