使用 Terraform 管理 LangSmith

使用官方 LangSmith Terraform provider 以代码方式管理工作区、访问控制、资源标签、评估器、run 规则和告警规则。

官方 LangSmith Terraform provider 让你以代码方式管理 LangSmith 组织和工作区资源：工作区、自定义角色、组织和工作区成员、资源标签、访问策略、评估器、run 规则和告警规则。它是使用 API 管理组织的基础设施即代码对应方案。

NOTE

管理资源标签和访问策略需要 LangSmith Terraform provider v0.0.6 或更高版本。

TIP

在深入之前，阅读以下内容可能会有所帮助：

• 组织与工作区概念指南
• 组织设置操作指南

安装与配置

将 provider 添加到你的 Terraform 配置并固定版本：

terraform {
  required_providers {
    langsmith = {
      source  = "langchain-ai/langsmith"
      version = "~> 0.0.6"
    }
  }
}

provider "langsmith" {
  # Cloud (US). Use https://eu.api.smith.langchain.com for the EU region,
  # or your self-hosted URL. Can also be set via LANGSMITH_ENDPOINT.
  api_url = "https://api.smith.langchain.com"

  # Optional: scope workspace-level resources to a specific workspace.
  workspace_id = "00000000-0000-0000-0000-000000000000"
}

然后运行 terraform init 下载该 provider。

身份认证

该 provider 解析凭证的方式与 LangSmith SDK 和 CLI 相同。优先使用环境变量或 profile，而不是硬编码 api_key：

• 环境——LANGSMITH_API_KEY、LANGSMITH_ENDPOINT（API URL）、LANGSMITH_WORKSPACE_ID。
• Profile——设置 profile（或 LANGSMITH_PROFILE）以使用 LangSmith CLI profile。
• Provider 参数——api_key、api_url、workspace_id、profile。

在 LangSmith 设置中创建 API key 或服务密钥。可用密钥类型请参阅身份验证方法。

WARNING

组织范围的操作（例如创建工作区、邀请组织成员和管理访问策略）需要具有 Organization Admin 权限的组织范围服务密钥。设置 workspace_id（或 LANGSMITH_WORKSPACE_ID）以定位工作区范围的资源，例如工作区成员关系、资源标签、评估器和 run 规则。

示例

创建工作区

resource "langsmith_workspace" "demo" {
  display_name  = "Demo Workspace"
  tenant_handle = "demo-workspace"
}

管理角色和成员

使用数据源查找内置角色，然后分配它们。以下示例邀请用户加入组织，并授予其工作区管理员权限：

data "langsmith_org_role" "user" {
  name = "ORGANIZATION_USER"
}

data "langsmith_workspace_role" "admin" {
  name = "WORKSPACE_ADMIN"
}

resource "langsmith_org_membership" "alice" {
  email   = "alice@example.com"
  role_id = data.langsmith_org_role.user.id
}

resource "langsmith_workspace_membership" "alice_demo" {
  workspace_id = langsmith_workspace.demo.id
  email        = langsmith_org_membership.alice.email
  role_id      = data.langsmith_workspace_role.admin.id
}

你还可以定义自定义工作区角色，例如通过克隆现有角色的权限：

resource "langsmith_workspace_role" "issues_agent" {
  display_name = "Issues Agent"
  description  = data.langsmith_workspace_role.admin.description
  permissions  = data.langsmith_workspace_role.admin.permissions
}

管理资源标签和访问策略

使用资源标签组织工作区资源，并应用基于属性的访问控制（ABAC）。便捷资源 langsmith_tag 拥有一个标签键和一个值。当键或值在多个配置之间共享时，请使用独立的 langsmith_tag_key 和 langsmith_tag_value 资源。

以下配置创建一个 Environment=production 标签，将其应用到某个追踪项目，并将某个工作区角色限制为生产项目：

resource "langsmith_tag" "production" {
  key               = "Environment"
  value             = "production"
  key_description   = "Deployment environment"
  value_description = "Production workloads"
}

resource "langsmith_tagging" "production_project" {
  tag_value_id  = langsmith_tag.production.tag_value_id
  resource_type = "project"
  resource_id   = "00000000-0000-0000-0000-000000000000" # tracing project ID
}

resource "langsmith_workspace_role" "production_reader" {
  display_name = "Production Reader"
  description  = "Can read production projects"
  permissions  = ["projects:read"]
}

resource "langsmith_access_policy" "production_readers" {
  name        = "Production readers"
  description = "Read access to production projects"
  effect      = "allow"

  condition_groups = [{
    permission    = "projects:read"
    resource_type = "project"
    conditions = [{
      attribute_name  = "resource_tag_key"
      attribute_key   = "Environment"
      operator        = "equals"
      attribute_value = "production"
    }]
  }]
}

resource "langsmith_access_policy_attachment" "production_reader" {
  role_id          = langsmith_workspace_role.production_reader.id
  access_policy_id = langsmith_access_policy.production_readers.id
}

自动化评估器、run 规则和告警

该 provider 管理的不只是账户。你可以将在线代码评估器、应用它们的 run 规则以及告警与工作区一起代码化：

resource "langsmith_evaluator" "tool_calls" {
  workspace_id = langsmith_workspace.demo.id
  name         = "tool call counts"
  type         = "code"

  code_evaluator = {
    language = "javascript"
    code     = file("${path.module}/evaluator.js")
  }
}

# A run rule applies the evaluator to matching runs in a tracing project.
# Run rules can also add runs to a dataset or annotation queue, or call webhooks.
resource "langsmith_run_rule" "score_root_runs" {
  workspace_id  = langsmith_workspace.demo.id
  display_name  = "score root runs"
  session_id    = "00000000-0000-0000-0000-000000000000" # tracing project ID
  sampling_rate = 1
  filter        = "eq(is_root, true)"

  evaluator_id = langsmith_evaluator.tool_calls.id
}

resource "langsmith_alert_rule" "error_rate" {
  session_id     = "00000000-0000-0000-0000-000000000000" # tracing project ID
  name           = "run error count high"
  type           = "threshold"
  attribute      = "error_count"
  aggregation    = "sum"
  window_minutes = 15
  operator       = "gte"
  threshold      = 10
  filter         = "eq(is_root, true)"

  actions = [{
    target  = "webhook"
    url_env = "LANGSMITH_ALERTS_WEBHOOK_URL"
    config_json = jsonencode({
      body = jsonencode({ text = "Error rate elevated" })
    })
  }]
}

资源参考

完整的资源和数据源列表（包含每个参数和属性）已发布在 Terraform Registry 上并保持同步：

•LangSmith provider on the Terraform Registry

浏览所有资源和数据源的完整参考。

---