Deploy Agent Builder on self-hosted LangSmith when using additional Dataplanes

Last updated: March 4, 2026

This article describes how to deploy the Agent Builder and connect it to your self-hosted LangSmith instance when you use additional data planes.

When is this needed?

Self-hosted LangSmith can run in different configurations. The full platform includes a control plane (UI and APIs for managing deployments) and one or more data planes (the runtime where Agent Servers and agent workloads run). You can add additional data planes in a different Kubernetes cluster or in a different namespace in the same cluster—for example, to isolate workloads or scale across regions.

IMPORTANT

This guide is only necessary when additional data planes are configured for your self-hosted LangSmith install. If you use only the default data plane that ships with your self-hosted deployment, the Agent Builder is typically available without following these steps. Use this guide when you have set up extra data planes and need to deploy and wire the Agent Builder to your LangSmith frontend and backend.

Prerequisites

A Kubernetes cluster with access to pull the Agent Builder image
Helm and kubectl configured for your cluster
Your LangSmith Helm values and any existing secrets (e.g., encryption key, JWT secret)

Step 1: Create the Agent Builder deployment

Create a new deployment using the Agent Builder image in the LangSmith Deployments UI:

Image: docker.io/langchain/agent-builder-deep-agent:0.13.18 (check for the latest image tag)

Ensure your cluster can pull this image (image pull secrets if required).

Configure the following environment variables for the deployment:

AGENT_BUILDER_ENCRYPTION_KEY — Must match the Fernet encryptionKey used in the agentBuilder section of your Helm values (may be in a Kubernetes secret).
X_SERVICE_AUTH_JWT_SECRET — Must match the jwtSecret in your Helm values (may be in a Kubernetes secret).
SMITH_BACKEND_ENDPOINT — Your LangSmith URL (include https://).
GO_ENDPOINT — {SMITH_BACKEND_ENDPOINT}/api/v1
HOST_BACKEND_ENDPOINT — {SMITH_BACKEND_ENDPOINT}/api-host
LANGSMITH_LICENSE_REQUIRED_CLAIMS — agent_builder_enabled
MCP_SERVER_URL — {SMITH_BACKEND_ENDPOINT}/mcp

Submit the deployment and confirm the pods start successfully.
Note the public URL of the Agent Builder deployment (e.g., the URL of the service/ingress you use to reach it). You will need this in Step 2.

Step 2: Configure LangSmith Helm values

Add the following to your LangSmith Helm values, replacing placeholders with your actual URLs:

"agent-builder-deployment-url" — The public URL of the Agent Builder deployment from Step 1. (e.g., https://<langsmith-url>/lgp/agent-builder-9be55f395e9d5ff6af65205cfe3637c0)
"langsmith-url" — Your LangSmith instance URL (e.g., https://your-langsmith-host.example.com).

commonEnv:
  - name: "LANGGRAPH_API_URL_PUBLIC"
    value: "<agent-builder-deployment-url>"
frontend:
  deployment:
    extraEnv:
    - name: "VITE_AGENT_BUILDER_DEPLOYMENT_URL_PUBLIC"
      value: "<agent-builder-deployment-url>"
    - name: "VITE_AGENT_BUILDER_GENERATOR_DEPLOYMENT_URL_PUBLIC"
      value: "<agent-builder-deployment-url>"
    - name: "VITE_AGENT_BUILDER_MCP_SERVER_URL"
      value: "<langsmith-url>/mcp"
    - name: "VITE_AGENT_BUILDER_TRIGGERS_API_URL"
      value: "<langsmith-url>"
config:
  agentBuilder:
    enabled: true
    encryptionKey: "<fernet-encryption-key>"

Step 3: Apply the release

Perform a new Helm release with the updated values.
After the release completes, the Agent Builder option should appear in the LangSmith UI (e.g., in the expected menu or dropdown).

Troubleshooting

Deployment not starting — Check image pull access, resource limits, and that all required environment variables are set.
Agent Builder not visible in UI — Confirm config.agentBuilder.enabled is true and that the frontend env vars point to the correct URLs.
Encryption or auth errors — Ensure AGENT_BUILDER_ENCRYPTION_KEY and X_SERVICE_AUTH_JWT_SECRET match the values used by the rest of your LangSmith deployment (Helm values or secrets).