# LangGraph
此頁面說明如何檢測 [LangGraph](https://langchain-ai.github.io/langgraph/) 代理程式、如何識別範圍，以及如何擷取評估欄位。它會關閉並[採用最佳實務](#langgraph-best-practices)來建構 LangGraph 代理程式，以便可靠地評估它。
**主題**
+ [檢測您的代理程式](#langgraph-instrument)
+ [如何識別跨度](#langgraph-span-identification)
+ [如何擷取評估欄位](#langgraph-extraction)
+ [從事件記錄](#langgraph-extraction-event-records)
+ [從跨度屬性](#langgraph-extraction-attributes)
+ [範例跨越事件記錄](#langgraph-examples-with)
+ [沒有事件記錄的範例範圍](#langgraph-examples-without)
+ [LangGraph 代理程式的最佳實務](#langgraph-best-practices)
## 檢測您的代理程式
您可以使用兩種檢測程式庫之一來檢測 LangGraph 代理程式：**OpenTelemetry** (`opentelemetry-instrumentation-langchain`) 或 **OpenInference** ()`openinference-instrumentation-langchain`。Amazon Bedrock AgentCore Evaluations 支援這兩個程式庫。程式庫會發出不同的範圍名稱，並使用不同的跨度屬性。評估服務會從每個 中擷取相同的值。
當您的代理程式使用 AWS Distro for OpenTelemetry (ADOT) 執行時，例如在 Amazon Bedrock AgentCore 執行期，您不需要新增明確的檢測程式碼。將檢測程式庫新增至專案的相依性已足夠。ADOT 在啟動時發現它並自動啟用它。
為您想要的相依性路徑新增檢測程式庫。下列範例會鎖定最低版本；除非您有鎖定原因，否則請使用最新的可用版本。
**Example**
注意：使用 版本 `0.55.0` 或更新版本。0.55.0 版新增了對評估服務所依賴之較新 OpenTelemetry [生成式 AI 代理程式範圍慣例](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md)的支援。
將 `opentelemetry-instrumentation-langchain`新增至您的相依性。發出的範圍名稱為 `opentelemetry.instrumentation.langchain`。
`requirements.txt`:
```
opentelemetry-instrumentation-langchain>=0.55.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"opentelemetry-instrumentation-langchain>=0.55.0",
]
```
將 `openinference-instrumentation-langchain`新增至您的相依性。發出的範圍名稱為 `openinference.instrumentation.langchain`。
`requirements.txt`:
```
openinference-instrumentation-langchain>=0.1.62
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-langchain>=0.1.62",
]
```
**注意**
檢測是設定可觀測性的一個步驟。若要匯出遙測資料進行評估，請完成設定[可觀測性中的完整設定](supported-frameworks.md#supported-frameworks-setup)。
## 如何識別跨度
用於分類範圍的屬性在兩個檢測程式庫之間不同。
**Example**
OpenTelemetry 檢測程式庫會使用 `traceloop.span.kind` 屬性來分類跨度，而最新版本也會設定 `gen_ai.operation.name`。
| 跨度類型 | 識別屬性 |
| --- | --- |
| 叫用代理程式 | `traceloop.span.kind` = `workflow`（也是 `gen_ai.operation.name` = `invoke_agent`) |
| 執行工具 | `traceloop.span.kind` = `tool`（也是 `gen_ai.operation.name` = `execute_tool`) |
| Inference | `gen_ai.operation.name` = `chat` |
OpenInference 檢測程式庫會使用 `openinference.span.kind` 屬性分類跨度。
| 跨度類型 | 識別屬性 |
| --- | --- |
| 叫用代理程式 | `openinference.span.kind` = `CHAIN`或 `AGENT` |
| 執行工具 | `openinference.span.kind` = `TOOL` |
| Inference | `openinference.span.kind` = `LLM` |
## 如何擷取評估欄位
對於調用代理程式範圍，輸入和輸出不包含乾淨的每則訊息清單。反之，內容是**序列化 LangChain 圖形狀態**：包裝完整狀態的 JSON 字串。此序列化狀態的確切形狀在兩個檢測程式庫之間有所不同。在這兩種情況下，服務都會剖析它，以尋找使用者提示 （人工訊息） 和客服人員回應 (AI 訊息）。
LangGraph 也會以多種形式序列化訊息角色。角色可以顯示為小寫值 (`human`、`ai`、`tool`) 或 LangChain 訊息類別名稱 (`HumanMessage`、`AIMessage`、)`ToolMessage`。服務會辨識這兩種形式。
此內容的位置取決於收集遙測的方式。在這兩種情況下，識別屬性 (`traceloop.span.kind` 或 `openinference.span.kind`) 位於跨度。如需詳細資訊，請參閱[跨度、事件記錄和遙測訊號](supported-frameworks-telemetry.md)。
### 從事件記錄
分割遙測時，服務會從與每個範圍相關的事件記錄中讀取內容：
+ **使用者提示**和**客服人員回應**：在 `body.input`和 中，從調用客服人員的事件記錄`body.output`。
+ **工具呼叫**：執行工具範圍中的工具名稱。工具引數和結果來自 `body.input`和 中的跨度事件記錄`body.output`。
如需範例，請參閱[範例跨越事件記錄](#langgraph-examples-with)。
### 從跨度屬性
未分割遙測時，相同內容會保留在範圍上做為屬性。屬性取決於檢測程式庫：
+ **OpenTelemetry**：
+ **使用者提示**和**客服人員回應**：調用客服人員範圍`gen_ai.task.output`上的 `gen_ai.task.input`和 。
+ **工具呼叫**：執行工具範圍`gen_ai.tool.call.result`上來自 的工具名稱`gen_ai.tool.name`，以及來自 和 的引數`gen_ai.tool.call.arguments`和結果。
+ **OpenInference**：
+ **使用者提示**和**客服人員回應**：調用客服人員範圍`output.value`上的 `input.value`和 。
+ **工具呼叫**：執行工具範圍`output.value`上來自 的工具名稱`tool.name`，以及來自 和 的引數`input.value`和結果。
如需範例，請參閱[沒有事件記錄的範例跨度](#langgraph-examples-without)。
## 範例跨越事件記錄
分割遙測時，範圍會攜帶識別屬性，而內容會存在於相關事件記錄中。下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 LangGraph 行程規劃代理程式。相同的代理程式會顯示在每個檢測程式庫下方。
**注意**
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
### OpenTelemetry
**Example**
`traceloop.span.kind` 屬性 (`workflow`) 將此識別為調用代理程式範圍；最近的程式庫版本也會設定 `gen_ai.operation.name` = `invoke_agent`。
```
{
"traceId": "6a01eef11066751d68f90def0da1f80a",
"spanId": "ba1833fa7f097041",
"parentSpanId": "836a5ccf9a2186cc",
"name": "travel_agent.workflow",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.langchain",
"version": "0.60.0"
},
"startTimeUnixNano": 1778511607308521744,
"endTimeUnixNano": 1778511610930280395,
"durationNano": 3621758651,
"attributes": {
"traceloop.span.kind": "workflow",
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "travel_agent",
"gen_ai.provider.name": "langgraph",
"traceloop.workflow.name": "travel_agent",
"session.id": "sea-nyc-trip-2-turns-adot_v17_opentelemetry_0_60_0"
},
"status": {
"code": "OK"
}
}
```
相關事件記錄會承載對話。每個訊息的 `content`都是序列化 LangChain 圖形狀態。輸入會在 `inputs`金鑰下包裝 狀態。輸出將其包裝在 `outputs`金鑰下，每個訊息都是 LangChain 建構函數物件。使用者提示是人工訊息，客服人員回應是該序列化狀態內的 AI 訊息。
```
{
"spanId": "ba1833fa7f097041",
"traceId": "6a01eef11066751d68f90def0da1f80a",
"scope": {
"name": "opentelemetry.instrumentation.langchain"
},
"body": {
"input": {
"messages": [
{
"content": "{\"inputs\": {\"messages\": [{\"role\": \"user\", \"content\": \"Hey, how can you help me\"}]}, \"tags\": [], \"metadata\": {\"ls_integration\": \"langchain_create_agent\", \"lc_agent_name\": \"travel_agent\", \"thread_id\": \"sea-nyc-trip-2-turns-adot_v17_opentelemetry_0_60_0\"}, \"kwargs\": {\"name\": \"travel_agent\"}}",
"role": "user"
}
]
},
"output": {
"messages": [
{
"content": "{\"outputs\": {\"messages\": [{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain\", \"schema\", \"messages\", \"HumanMessage\"], \"kwargs\": {\"content\": \"Hey, how can you help me\", \"type\": \"human\", \"id\": \"12345678-1234-1234-1234-123456789012\"}}, {\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain\", \"schema\", \"messages\", \"AIMessage\"], \"kwargs\": {\"content\": \"Hello! I'm your travel planning assistant ...\", \"type\": \"ai\"}}]}, \"kwargs\": {\"tags\": []}}",
"role": "assistant"
}
]
}
}
}
```
`traceloop.span.kind` 屬性 (`tool`) 將此識別為執行工具範圍； `gen_ai.tool.name`會保留工具名稱 並 `gen_ai.operation.name` = `execute_tool`。
```
{
"traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
"spanId": "5b332f3cd15ace04",
"parentSpanId": "922a21edc04eba29",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.langchain",
"version": "0.60.0"
},
"startTimeUnixNano": 1778511614892698232,
"endTimeUnixNano": 1778511614893399618,
"durationNano": 701386,
"attributes": {
"traceloop.span.kind": "tool",
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.type": "function",
"gen_ai.tool.description": "Search for available flights between cities.",
"gen_ai.provider.name": "langgraph",
"traceloop.workflow.name": "travel_agent",
"session.id": "sea-nyc-trip-2-turns-adot_v17_opentelemetry_0_60_0"
},
"status": {
"code": "OK"
}
}
```
相關事件記錄會攜帶工具輸入 （引數） 和輸出 （結果，序列化為 LangChain `ToolMessage`)。
```
{
"spanId": "5b332f3cd15ace04",
"traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
"scope": {
"name": "opentelemetry.instrumentation.langchain"
},
"body": {
"input": {
"messages": [
{ "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
]
},
"output": {
"messages": [
{
"role": "tool",
"name": "search_flights",
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}"
}
]
}
}
}
```
### OpenInference
使用 OpenInference 程式庫時，跨度類型會在 `openinference.span.kind` 屬性中承載，而代理程式輸入和輸出會在相關事件記錄中序列化。
**Example**
`openinference.span.kind` 屬性 ( `CHAIN`或使用名稱編譯圖形`AGENT`時） 會將此識別為叫用代理程式範圍。
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "0a7990d804132a9b",
"parentSpanId": "29ae22014173881c",
"name": "LangGraph",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.langchain",
"version": "0.1.66"
},
"startTimeUnixNano": 1782087405949310976,
"endTimeUnixNano": 1782087408945828864,
"durationNano": 2996517888,
"attributes": {
"openinference.span.kind": "CHAIN",
"input.mime_type": "application/json",
"output.mime_type": "application/json",
"llm.input_messages.0.message.role": "user",
"session.id": "sea-nyc-trip-2-turns-oi-0-1-66"
},
"status": {
"code": "OK"
}
}
```
相關事件記錄會承載對話。使用者提示是人力角色訊息，客服人員回應是序列化訊息中的 AI 角色訊息。
```
{
"spanId": "0a7990d804132a9b",
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"scope": {
"name": "openinference.instrumentation.langchain"
},
"body": {
"input": {
"messages": [
{
"role": "user",
"content": "{\"messages\": [{\"role\": \"user\", \"content\": \"Hey, how can you help me\"}]}"
}
]
},
"output": {
"messages": [
{
"content": "{\"messages\": [{\"type\": \"human\", \"data\": {\"content\": \"Hey, how can you help me\", ...}}, {\"type\": \"ai\", \"data\": {\"content\": \"Hello! I'm your travel planning assistant ...\", ...}}]}",
"role": "assistant"
}
]
}
}
}
```
`openinference.span.kind` 屬性 (`TOOL`) 將此識別為執行工具範圍； `tool.name`會保留工具名稱。
```
{
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"spanId": "ab105c12cc40048f",
"parentSpanId": "9b2d4e72760690b4",
"name": "search_flights",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.langchain",
"version": "0.1.66"
},
"startTimeUnixNano": 1782087411724620032,
"endTimeUnixNano": 1782087411725306880,
"durationNano": 686848,
"attributes": {
"openinference.span.kind": "TOOL",
"tool.name": "search_flights",
"tool.description": "Search for available flights between cities.",
"input.mime_type": "application/json",
"output.mime_type": "application/json",
"session.id": "sea-nyc-trip-2-turns-oi-0-1-66"
},
"status": {
"code": "OK"
}
}
```
相關事件記錄會攜帶工具輸入 （引數） 和輸出 （結果，序列化為 LangChain `ToolMessage`)。
```
{
"spanId": "ab105c12cc40048f",
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"scope": {
"name": "openinference.instrumentation.langchain"
},
"body": {
"input": {
"messages": [
{
"role": "user",
"content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}"
}
]
},
"output": {
"messages": [
{
"content": "{\"type\": \"tool\", \"data\": {\"content\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\", \"type\": \"tool\", \"name\": \"search_flights\", \"tool_call_id\": \"toolu_bdrk_01LzXXJCfpfuS7Bpf7e1qLMg\", \"status\": \"success\"}}",
"role": "assistant"
}
]
}
}
}
```
## 沒有事件記錄的範例範圍
未分割遙測時，相同的內容會保留在跨度屬性上，而且不會產生單獨的事件記錄。下列範例來自 LangGraph 行程規劃代理程式。相同的代理程式會顯示在每個檢測程式庫下方。
**注意**
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
### OpenTelemetry
**Example**
`gen_ai.task.input` 屬性會保留使用者提示，而`gen_ai.task.output`屬性會保留具有代理程式回應的序列化狀態。兩者都是序列化 LangChain 圖形狀態。
```
{
"traceId": "6a4de7b85e61747e6b568a1f4768e89d",
"spanId": "31ea3d5882dac680",
"name": "LangGraph.workflow",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.langchain",
"version": "0.62.1"
},
"attributes": {
"traceloop.span.kind": "workflow",
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "LangGraph",
"gen_ai.task.input": "{\"inputs\": {\"messages\": [{\"role\": \"user\", \"content\": \"Hey, how can you help me\"}]}, \"tags\": [], \"metadata\": { ... }, \"kwargs\": {\"name\": \"LangGraph\"}}",
"gen_ai.task.output": "{\"outputs\": {\"messages\": [{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain\", \"schema\", \"messages\", \"HumanMessage\"], \"kwargs\": {\"content\": \"Hey, how can you help me\", \"type\": \"human\"}}, {\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain\", \"schema\", \"messages\", \"AIMessage\"], \"kwargs\": {\"content\": \"Hello! I'm your travel planning assistant ...\", \"type\": \"ai\"}}]}, \"kwargs\": {\"tags\": []}}",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
`gen_ai.tool.call.arguments` 屬性會保留工具引數，而 `gen_ai.tool.call.result` 屬性會保留工具結果，序列化為 LangChain `ToolMessage`。
```
{
"traceId": "6a4de7c376913db82e6f0f336a16731d",
"spanId": "b64c37adefae74f0",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.langchain",
"version": "0.62.1"
},
"attributes": {
"traceloop.span.kind": "tool",
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.description": "Search for available flights between cities.",
"gen_ai.tool.call.arguments": "{\"input_str\": \"{'origin': 'SEA', 'destination': 'NYC', 'date': '2025-03-15'}\", \"inputs\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}, \"metadata\": { ... }}",
"gen_ai.tool.call.result": "{\"output\": {\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain\", \"schema\", \"messages\", \"ToolMessage\"], \"kwargs\": {\"content\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\", \"type\": \"tool\", \"name\": \"search_flights\", \"status\": \"success\"}}}",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
### OpenInference
**Example**
`input.value` 屬性會保留使用者提示，而`output.value`屬性會保留具有代理程式回應的序列化狀態。
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "b8c0b67876b78b91",
"name": "LangGraph",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.langchain",
"version": "0.1.66"
},
"attributes": {
"openinference.span.kind": "CHAIN",
"input.value": "{\"messages\": [{\"role\": \"user\", \"content\": \"Hey, how can you help me\"}]}",
"output.value": "{\"messages\": [{\"type\": \"human\", \"data\": {\"content\": \"Hey, how can you help me\"}}, {\"type\": \"ai\", \"data\": {\"content\": \"Hello! I'm your travel planning assistant ...\"}}]}",
"session.id": "sea-nyc-trip-2-turns-oi-0-1-66"
},
"status": {
"code": "OK"
}
}
```
`input.value` 屬性會保留工具引數，而 `output.value` 屬性會保留工具結果，序列化為 LangChain `ToolMessage`。
```
{
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"spanId": "58752612d9b22ae1",
"name": "search_flights",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.langchain",
"version": "0.1.66"
},
"attributes": {
"openinference.span.kind": "TOOL",
"tool.name": "search_flights",
"tool.description": "Search for available flights between cities.",
"input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"output.value": "{\"type\": \"tool\", \"data\": {\"content\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\", \"name\": \"search_flights\"}}",
"session.id": "sea-nyc-trip-2-turns-oi-0-1-66"
},
"status": {
"code": "OK"
}
}
```
## LangGraph 代理程式的最佳實務
建置和叫用 LangGraph 代理程式的方式會影響其遙測中出現的內容，因此評估代理程式的可靠性。下列實務有助於確保可復原使用者提示、客服人員回應和工具活動。
### 1. 選擇代理程式建構模式
有兩種常見的方法來建置 LangGraph 代理程式：
+ **預先建置 `create_agent` **：最快速的入門方式。它會產生每個回合的單一叫用代理程式範圍，並透過 LangGraph 的內建執行迴圈傳遞對話。當您想要不使用自訂控制流程的標準 reason-act 代理程式時，請使用此選項。
```
from langchain.agents import create_agent
agent = create_agent(model=model, tools=[search_flights, book_flight])
```
+ **自訂 `StateGraph` **：可讓您完全控制節點、邊緣和條件式路由。每個節點執行都會成為自己的跨度，因此追蹤更為精細。當您需要自訂協同運作時，請使用此選項。
```
from langgraph.graph import StateGraph, START, END
from typing_extensions import TypedDict
class State(TypedDict):
messages: list
graph = StateGraph(State)
graph.add_node("generate_response", generate_response)
graph.add_node("tools", run_tools)
graph.add_edge(START, "generate_response")
agent = graph.compile()
```
兩種模式的評估方式都相同；差異在於追蹤的精細程度。
### 2. 在圖形狀態`messages`中使用 （建議）
評估服務會從客服人員的輸入和輸出訊息重建對話。使用`messages`欄位不是強制性的，但可啟用最可靠的擷取。對於自訂 `StateGraph`，請將對話保留在 狀態的 `messages` 欄位中：
+ **在您的狀態`messages`中包含 （建議）。**您可以新增其他自訂欄位 （例如 `user_id`或 中繼資料）。當 `messages` 存在時，標準擷取會直接尋找使用者提示和客服人員回應。如果 `messages` 不存在，則服務會從個別推論範圍重建對話，這較不可靠。
+ **附加，請勿取代。**遵循 LangGraph 將新訊息附加至清單而非覆寫，因此會保留完整的對話歷史記錄。
+ **使用正式 LangChain 訊息類型** (`HumanMessage`、`AIMessage`、`ToolMessage`、`SystemMessage`)。檢測會正確序列化這些項目，而服務會辨識其角色。
### 3. 以支援的格式傳遞使用者訊息
當您叫用 LangGraph 代理程式時，您可以將使用者訊息新增至圖形`messages`的狀態。LangGraph 接受三種可互換格式的訊息，而 AgentCore Evaluations 支援所有訊息。每個 都會產生服務可讀取的跨度和事件記錄。
+ **雙組**：一`(role, content)`對：
```
agent.invoke({"messages": [("user", user_message)]}, config=config)
```
+ **LangChain 訊息物件**： `HumanMessage`（或其他訊息類別）：
```
from langchain_core.messages import HumanMessage
agent.invoke({"messages": [HumanMessage(content=user_message)]}, config=config)
```
+ **字典**：`{"role", "content"}`字典：
```
agent.invoke({"messages": [{"role": "user", "content": user_message}]}, config=config)
```
這三種格式都會產生相同的`messages`狀態，因此無論您選擇哪個格式，都會以相同的方式擷取使用者提示和客服人員回應。