This guide demonstrates how to implement a comprehensive CI/CD pipeline for AI agent applications deployed in LangSmith Deployment. In this example, you'll use the LangGraph 开源框架，用于编排和构建代理， LangSmith 用于可观察性和评估。此管道基于 cicd-pipeline-example 仓库.

概述

The CI/CD pipeline provides:

• 自动化测试：单元、集成和端到端测试。
• 离线评估：使用 AgentEvals, OpenEvals 和 LangSmith.
• 预览和生产部署：使用 Control Plane API 实现自动化预发布和质量门控的生产发布。
• 监控：持续评估和告警。

管道架构

The CI/CD pipeline consists of several key components that work together to ensure code quality and reliable deployments:

graph TD
    A1[Code or Graph Change] --> B1[Trigger CI Pipeline]
    A2[Prompt Commit in PromptHub] --> B1
    A3[Online Evaluation Alert] --> B1
    A4[PR Opened] --> B1

    subgraph "Testing"
        B1 --> C1[Run Unit Tests]
        B1 --> C2[Run Integration Tests]
        B1 --> C3[Run End to End Tests]
        B1 --> C4[Run Offline Evaluations]

        C4 --> D1[Evaluate with OpenEvals or AgentEvals]
        C4 --> D2[Assertions: Hard and Soft]

        C1 --> E1[Run LangGraph Dev Server Test]
        C2 --> E1
        C3 --> E1
        D1 --> E1
        D2 --> E1
    end

    E1 --> F1[Push to Staging Deployment - Deploy to LangSmith as Development Type]

    F1 --> G1[Run Online Evaluations on Live Data]
    G1 --> H1[Attach Scores to Traces]

    H1 --> I1[If Quality Below Threshold]
    I1 --> J1[Send to Annotation Queue]
    I1 --> J2[Trigger Alert via Webhook]
    I1 --> J3[Push Trace to Golden Dataset]

    F1 --> K1[Promote to Production if All Pass - Deploy to LangSmith Production]

    J2 --> L1[Slack or PagerDuty Notification]

    subgraph Manual Review
        J1 --> M1[Human Labeling]
        M1 --> J3
    end

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33
    classDef alert fill:#F8E8E6,stroke:#B27D75,stroke-width:2px,color:#634643
    classDef neutral fill:#F2FAFF,stroke:#40668D,stroke-width:2px,color:#2F4B68

    class A1,A2,A3,A4 trigger
    class B1,C1,C2,C3,C4,D1,D2,E1 process
    class H1,I1 decision
    class F1,G1,K1 output
    class J2,L1 alert
    class J1,J3,M1 neutral

触发源

有多种方式可以触发此管道，无论是在开发期间还是应用程序已上线时。可以通过以下方式触发管道：

• 代码变更: Pushes to main/development branches where you can modify the LangGraph architecture, try different models, update agent logic, or make any code improvements.
• PromptHub 更新：LangSmith PromptHub 中存储的提示模板变更 — 每当有新的提示提交时，系统会触发 webhook 来运行管道。
• 在线评估告警：来自生产部署的性能降级通知
• LangSmith 追踪 webhooks：基于追踪分析和性能指标的自动触发。
• 手动触发：用于测试或紧急部署的手动管道启动。

测试层

与传统软件相比，测试 AI 代理应用还需要评估响应质量，因此测试工作流的每个部分都很重要。该管道实现多层测试：

1. **单元测试**：单个节点和工具函数的测试。
2. **集成测试**：组件交互测试。
3. **端到端测试**：完整图执行的测试。
4. **离线评估**：使用真实场景进行性能评估，包括端到端评估、单步评估、代理轨迹分析和多轮模拟。
5. **LangGraph 开发服务器测试**：使用 langgraph-cli 工具（在 GitHub Action 内部）启动本地服务器来运行 LangGraph 代理。这会轮询 /ok 服务器 API 端点直到可用，超出30秒则抛出错误。

GitHub actions 工作流

The CI/CD pipeline uses GitHub Actions with the Control Plane API 和 LangSmith API to automate deployment. A helper script manages API interactions and deployments: https://github.com/langchain-ai/cicd-pipeline-example/blob/main/.github/scripts/langgraph_api.py.

工作流包括：

• 新代理部署：当新的 PR 打开且测试通过时，使用 Control Plane API在 LangSmith Deployment 中创建新的预览部署。这允许您在推广到生产环境之前在预发布环境中测试代理。
• 代理部署修订：当发现具有相同 ID 的现有部署时，或者当 PR 合并到 main 时，会发生修订。在合并到 main 的情况下，预览部署被删除并创建生产部署。这确保了对代理的任何更新都正确部署并集成到生产基础设施中。

!代理部署修订工作流程

• 测试和评估工作流程：除了更传统的测试阶段（单元测试、集成测试、端到端测试等）之外，管道还包括 离线评估 和 代理开发服务器测试 ，因为您想测试代理的质量。这些评估使用真实场景和数据对代理的性能进行全面评估。

!使用结果工作流程进行测试

请参阅 LangGraph 测试文档 了解具体的测试方法，以及 评估方法指南 ，了解离线评估的全面概述。

先决条件

Before setting up the CI/CD pipeline, ensure you have:

• - AI 代理应用程序（在本例中使用 LangGraph)
• - A LangSmith 账户
• - A LangSmith API 密钥 ，用于部署代理和检索实验结果
• - 在您的存储库密钥中配置的项目特定环境变量（例如 LLM 模型 API 密钥、向量存储凭证、数据库连接）

部署选项

LangSmith 支持多种部署方法，具体取决于您的 LangSmith 实例的托管方式:

• 云 LangSmith：直接 GitHub 集成。
• Self-Hosted/Hybrid：基于容器注册表的部署。

部署流程从修改代理实现开始。至少，您必须拥有 langgraph.json 和项目中的依赖项文件（requirements.txt or pyproject.toml）。使用 langgraph dev CLI 工具用于检查错误——修复所有错误；否则，当部署到 LangSmith Deployment 时将会成功。

graph TD
    A[Agent Implementation] --> B[langgraph.json + dependencies]
    B --> C[Test Locally with langgraph dev]
    C --> D{Errors?}
    D -->|Yes| E[Fix Issues]
    E --> C
    D -->|No| F[Choose LangSmith Instance]

    F --> G[Cloud LangSmith]
    F --> H[Self-Hosted/Hybrid LangSmith]

    subgraph "Cloud LangSmith"
        G --> I[Method 1: Connect GitHub Repo in UI]
        G --> J[Method 2: Control Plane API with GitHub Repo]
        I --> K[Deploy via LangSmith UI]
        J --> L[Deploy via Control Plane API]
    end

    subgraph "Self-Hosted/Hybrid LangSmith"
        H --> S[Build Docker Image langgraph build]
        S --> T[Push to Container Registry]
        T --> U{Deploy via?}
        U -->|UI| V[Specify Image URI in UI]
        U -->|API| W[Use Control Plane API]
        V --> X[Deploy via LangSmith UI]
        W --> Y[Deploy via Control Plane API]
    end

    K --> AA[Agent Ready for Use]
    L --> AA
    X --> AA
    Y --> AA

    AA --> BB{Connect via?}
    BB -->|LangGraph SDK| CC[Use LangGraph SDK]
    BB -->|RemoteGraph| DD[Use RemoteGraph]
    BB -->|REST API| EE[Use REST API]
    BB -->|LangGraph Studio UI| FF[Use LangGraph Studio UI]

    classDef trigger fill:#F6FFDB,stroke:#6E8900,stroke-width:2px,color:#2E3900
    classDef process fill:#E5F4FF,stroke:#006DDD,stroke-width:2px,color:#030710
    classDef decision fill:#FDF3FF,stroke:#7E65AE,stroke-width:2px,color:#504B5F
    classDef output fill:#EBD0F0,stroke:#885270,stroke-width:2px,color:#441E33

    class A trigger
    class B,C process
    class D,U,BB decision
    class E process
    class F decision
    class G,H process
    class I,J,S,T process
    class K,L,V,W process
    class X,Y,AA output
    class CC,DD,EE,FF output

手动部署的前提条件

在部署您的智能体之前，请确保您已具备：

1. **LangGraph 图**：您的智能体实现（例如， ./agents/simple_text2sql.py:agent). 2. **依赖项**：或者 requirements.txt or pyproject.toml 以及所有必需的包。 3. **配置**: langgraph.json 文件，指定： - 智能体图的路径 - 依赖项位置 - 环境变量 - Python 版本

示例 langgraph.json:

{
    "graphs": {
        "simple_text2sql": "./agents/simple_text2sql.py:agent"
    },
    "env": ".env",
    "python_version": "3.11",
    "dependencies": ["."],
    "image_distro": "wolfi"
}

本地开发和测试

!Studio CLI 界面

首先，使用以下方式在本地测试您的智能体 Studio:

# Start local development server with Studio
langgraph dev

这将： - 启动一个带 Studio 的本地服务器。 - 允许您可视化并与您的图进行交互。 - 验证您的智能体在部署前是否正常工作。

请参阅 LangGraph CLI 文档 了解更多详情。

方法 1：LangSmith 部署 UI

使用 LangSmith 部署界面部署您的智能体：

1. 前往您的 LangSmith 仪表板.
2. 导航至 **部署** section.
3. 点击 **+ 新建部署** 右上角的按钮。
4. 从下拉菜单中选择包含您的 LangGraph 智能体的 GitHub 仓库。

支持的部署： - **云端 LangSmith**：通过下拉菜单直接与 GitHub 集成 - **Self-Hosted/Hybrid LangSmith**：在镜像路径字段中指定您的镜像 URI（例如， docker.io/username/my-agent:latest)

方法 2：Control Plane API

使用 Control Plane API 进行部署，每种部署类型采用不同的方式：

对于云端 LangSmith： - 使用 Control Plane API 通过指向您的 GitHub 仓库来创建部署 - 云端部署无需构建 Docker 镜像

For Self-Hosted/Hybrid LangSmith:

# Build Docker image
langgraph build -t my-agent:latest

# Push to your container registry
docker push my-agent:latest

您可以推送到您的部署环境可访问的任何容器镜像仓库（Docker Hub、AWS ECR、Azure ACR、Google GCR 等）。

支持的部署方式： - **云端 LangSmith**：使用 Control Plane API 从您的 GitHub 仓库创建部署 - **Self-Hosted/Hybrid LangSmith**：使用 Control Plane API 从您的容器镜像仓库创建部署

请参阅 LangGraph CLI 构建文档 了解更多详情。

连接到已部署的 Agent

• - **LangGraph SDK**：使用 LangGraph SDK 进行程序化集成。
• - **RemoteGraph**：使用 RemoteGraph 进行远程图连接（用于在其他图中使用您的图）。
• - **REST API**：使用 HTTP 方式与已部署的 agent 进行交互。
• - **Studio**：访问可视化界面进行测试和调试。

环境配置

数据库和缓存配置

默认情况下，LangSmith Deployment 会为您创建 PostgreSQL 和 Redis 实例。如需使用外部服务，请在新的部署或修订版本中设置以下环境变量：

# Set environment variables for external services

请参阅 环境变量文档 了解更多详情。

故障排除

API 端点错误

如果您遇到连接问题，请确认您正在使用适合您 LangSmith 实例的正确端点格式。存在两个不同的 API，它们有不同的端点：

LangSmith API（追踪、数据摄取等）

对于 LangSmith API 操作（追踪、评估、数据集）：

对于自托管的 LangSmith 实例，请使用 http(s)://<langsmith-url>/api 其中 <langsmith-url> 是您的自托管实例 URL。

LangSmith Deployment API（部署）

对于 LangSmith Deployment 操作（部署、修订版本）：

对于自托管的 LangSmith 实例，请使用 http(s)://<langsmith-url>/api-host 其中 <langsmith-url> 是您的自托管实例 URL。