Skip to main content

Connecting Agents

This guide is for developers who run AI agents and need the agents' outbound HTTP and HTTPS traffic to go through the HTTP Egress Proxy. It covers a local shell, Docker, Kubernetes, HTTPS interception, and diagnostics.

Connecting an agent takes two things:

  • Proxy environment variables that send the agent's traffic to the gateway. The proxy uses the standard HTTP_PROXY and HTTPS_PROXY convention, so most HTTP client libraries use it once the variables are set.
  • A proxy access token that the agent presents on every request.

Prerequisites​

What an agent needs to connect​

ItemDescription
HTTP_PROXY, HTTPS_PROXYSend the agent's outbound HTTP and HTTPS traffic to the gateway.
NO_PROXYHosts that bypass the proxy, for example localhost.
Proxy access tokenA short-lived, workflow-bound token the agent presents to the proxy. Mint it with asg proxy token create or the consent flow. The agent reads it from a token file.

asg proxy env, asg proxy container-config, and asg run generate these values, so you rarely set them by hand.

Connect an agent in a local shell​

You have two options for a local agent process.

Launch the agent with asg run​

asg run gets a workflow-bound token through browser consent, embeds the token in the proxy URL, and starts the agent as a child process with the proxy environment set. The agent's code does not need to handle the token. Use this option when a person starts the agent from their machine.

Export the proxy environment​

Mint a token with asg proxy token create, then export the proxy environment into the current shell:

eval "$(asg proxy env acme)"

The command exports HTTP_PROXY, HTTPS_PROXY, NO_PROXY, and AGENT_SECURITY_PROXY_TOKEN_FILE. AGENT_SECURITY_PROXY_TOKEN_FILE points to $HOME/.agent-security/tokens/<subdomain>.token. Write the token to that path, or set AGENT_SECURITY_PROXY_TOKEN_FILE to the path where you wrote it.

The exported variables do not authenticate requests. Your agent's HTTP client must read the token from $AGENT_SECURITY_PROXY_TOKEN_FILE and send it on every request in the Proxy-Authorization: Bearer <token> header. Without the header, the proxy returns 407.

To check the connection, send a test request as shown in Verify the allow-list. A host in your workflow returns the upstream's response. A host outside your workflow returns 403 from the proxy.

Connect an agent in Docker or Kubernetes​

Generate container configuration for your platform:

# Docker env file or Compose snippet.
asg proxy container-config acme --format docker-env
asg proxy container-config acme --format docker-compose

# Kubernetes ConfigMap.
asg proxy container-config acme --format k8s-configmap

Then configure the agent's container:

  1. Mount or reference the generated configuration so the proxy variables are set in the container's environment.
  2. Supply the proxy token through your platform's secret mechanism, for example a mounted Kubernetes Secret.
  3. Set AGENT_SECURITY_PROXY_TOKEN_FILE to the path of the mounted token file.

HTTPS interception​

By default, the proxy handles HTTPS in passthrough mode. The proxy authenticates the connection and authorizes it against the domain's tunnel rule, which is the rule with method class all and no path. See HTTPS needs a tunnel rule. The proxy then forwards the encrypted tunnel without reading it. In passthrough mode, the proxy cannot see the request path or body, inject a credential, or scrub the response.

To apply path-level rules, credential injection, and response scrubbing to HTTPS, switch the domain's tunnel rule to intercept mode:

  1. In the dashboard, go to CLIs / APIs → Workflows and open the workflow.
  2. Edit the domain's tunnel rule.
  3. Set TLS mode to Intercept (decrypt + inject credential).

The proxy reads TLS mode only from the tunnel rule. Setting TLS mode on a path-scoped or method-scoped rule has no effect.

In intercept mode, the proxy terminates the agent's TLS connection with a certificate authority (CA) issued for your host, and runs every check on the decrypted request. The agent must trust that CA certificate, or its TLS connections through the proxy fail. Manage the CA with the asg CLI:

# Inspect your host's interception CA.
asg proxy ca status acme

# Download the CA certificate to install in your agent's trust store.
asg proxy ca download acme --output ./agent-security-ca.pem

# Print a shell snippet that points common tools at the CA.
asg proxy ca trust-shell acme

# Rotate the CA, keeping the previous one valid during a grace window.
asg proxy ca rotate acme --grace-days 7
Choosing passthrough or intercept mode

Use passthrough when domain-level control is enough, and for very large uploads, downloads, and long-lived streaming connections. Use intercept when you need path-level rules, credential injection, or response scrubbing on HTTPS. The tunnel rule decides the mode, so for HTTPS the mode is set per domain. One workflow can use passthrough for some domains and intercept for others.

Diagnose with doctor​

When an agent's traffic does not reach the upstream, run the built-in diagnostic:

asg proxy doctor acme

asg proxy doctor checks:

  • Gateway reachability.
  • Whether proxy mode is enabled for the host.
  • The number of stored credentials.
  • Your local proxy environment variables.
  • The interception CA's status and expiry, and whether your environment trusts the CA.
  • The token file's permissions and the token's expiry.
  • When agent identity is enabled, whether the agent registered a session and whether the session is drift-blocked. A drift-blocked session fails the check and shows the re-approval link that clears the block.

Each check reports pass, warn, or fail. A check that does not pass includes a suggested fix.

asg proxy doctor exits with 0 when all checks pass, 1 for a failure you can fix, and 2 for a gateway fault. You can use the exit code to gate a CI pipeline.

Next steps​

Contents

Edit this page

Need help?