Skip to content

Conversation

Copy link

Copilot AI commented Dec 6, 2025

Implements cross-language (C# → Python) integration with LangGraph/LangServe for stateful graph-based agent orchestration. Key capability: BotSharp ConversationId maps 1:1 to LangGraph thread_id, enabling LangGraph's checkpointer to act as external state persistence.

Implementation

Plugin Structure (BotSharp.Plugin.LangGraph)

  • LangServeClient: HTTP client supporting /invoke (sync), /stream (SSE), and interrupt detection
  • LangGraphStateMapper: State bridge between BotSharp conversation state and LangGraph thread state
  • Models: Request/response DTOs with interrupt metadata support

State Mapping

// ConversationId automatically maps to thread_id in config.configurable
{
  "input": { "messages": [...] },
  "config": {
    "configurable": {
      "thread_id": "botsharp_conversation_{conversationId}"
    }
  }
}

Human-in-the-Loop

  • Detects interrupted status or __interrupt__ field in responses
  • Persists interrupt state in BotSharp conversation state
  • ResumeAsync continues execution with same thread_id (LangGraph handles state restoration)

Streaming

  • SSE parsing with proper null/EOF handling
  • Yields content chunks as they arrive
  • [EnumeratorCancellation] attribute for proper async enumerable cancellation

Documentation

  • QUICKSTART.md: Integration architecture, sequence diagrams, protocol specification
  • Plugin README.md: Configuration, usage examples, troubleshooting

Configuration

{
  "LangGraph": {
    "BaseUrl": "http://localhost:8000",
    "ApiKey": "optional-key",
    "Timeout": 300,
    "EnableTracing": true
  }
}
Original prompt

On QUICKSTART.md, BotSharp 与 LangGraph 的集成跨越了语言边界(C# 到 Python)。LangGraph 的核心价值在于其状态管理和循环推理,因此集成的关键在于 状态映射(State Mapping) 和 持久化(Persistence)。
5.1 通信协议规范:LangServe REST API
LangServe 提供了一套标准化的 REST API 14。
API 端点:
/invoke: 同步调用,等待结果。
/stream: 流式返回,适合长文本生成。
/batch: 批量处理。
输入 Schema: LangServe 会根据定义的 Python Runnables 自动生成 OpenAPI 文档 14。通常输入格式为 {"input": {"messages": [...]}}。
状态控制 (State Control): 这是集成的核心。LangGraph 使用 thread_id 来隔离不同用户的会话状态 13。
5.2 状态管理策略:会话 ID 映射
BotSharp 拥有自己的 ConversationId。为了让 LangGraph 能够“记住”之前的交互,BotSharp 必须将自身的 ConversationId 传递给 LangGraph。
映射逻辑:
BotSharp 在调用 LangServe 时,必须在请求体的 config 字段中注入 configurable 字典。
请求 Payload 示例 (BotSharp -> LangServe):

JSON

{
"input": {
"messages": [
{ "type": "human", "content": "分析这份财务报表的数据趋势" }
]
},
"config": {
"configurable": {
"thread_id": "botsharp_conversation_Guid_Value"
}
}
}

深度洞察:通过这种 1:1 的 ID 映射,LangGraph 的 checkpointer(如 Postgres 或 Redis)实际上成为了 BotSharp 的“外挂海马体”。即使用户在 BotSharp 中切换了 Agent,只要再次切回 LangGraph Agent 并带上相同的 ID,LangGraph 就能无缝恢复之前的推理上下文。
5.3 序列图:BotSharp 调用 LangGraph(含状态持久化)

代码段

sequenceDiagram
participant Router as BotSharp Router
participant Plugin as LangGraph Plugin
participant LangServe as LangServe API (Python)
participant Graph as LangGraph Runtime
participant DB as Postgres (Checkpointer)

Router->>Plugin: 调用 "ResearchAgent" (Input: "分析市场趋势")

Note right of Plugin: 提取 ConversationId

Plugin->>LangServe: POST /research-agent/stream
Note right of Plugin: Header: Traceparent (OpenTelemetry)
Note right of Plugin: Body: { "input": {...}, "config": { "configurable": { "thread_id": "conv_abc123" } } }

LangServe->>Graph: 初始化图执行
Graph->>DB: 根据 thread_id 加载 Checkpoint
DB-->>Graph: 返回历史状态 (State Snapshot)

Graph->>Graph: 执行节点 (Nodes & Edges)
Note over Graph: 循环推理...

Graph->>DB: 保存新状态 Checkpoint
Graph->>LangServe: 产生输出块 (Chunks)

LangServe-->>Plugin: SSE Stream (Server-Sent Events)
Plugin-->>Router: 实时推送 / 聚合完整文本

5.4 处理“人机回环”(Human-in-the-loop)
LangGraph 支持 interrupt(中断)机制,用于请求人类确认 20。
检测中断:如果 LangServe 返回的状态为 interrupted 或包含 interrupt 字段,BotSharp 插件必须捕获此状态。
挂起会话:BotSharp 暂停当前流,向用户发送请求确认的消息(例如:“LangGraph需要您批准执行下一步操作,是否继续?”)。
恢复执行:当用户回复“是”时,BotSharp 再次向 LangServe 发送请求,这次使用 Command 模式或更新状态来恢复(Resume)执行,依然携带相同的 thread_id。


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI and others added 3 commits December 6, 2025 09:03
Co-authored-by: geffzhang <439390+geffzhang@users.noreply.github.com>
Co-authored-by: geffzhang <439390+geffzhang@users.noreply.github.com>
Co-authored-by: geffzhang <439390+geffzhang@users.noreply.github.com>
Copilot AI changed the title [WIP] Add integration between BotSharp and LangGraph Add LangGraph integration with state persistence and human-in-the-loop support Dec 6, 2025
Copilot AI requested a review from geffzhang December 6, 2025 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants