LangGraph
此頁面說明如何檢測 LangGraph 代理程式、如何識別範圍，以及如何擷取評估欄位。它會關閉並採用最佳實務來建構 LangGraph 代理程式，以便可靠地評估它。
主題
檢測您的代理程式
您可以使用兩種檢測程式庫之一來檢測 LangGraph 代理程式：OpenTelemetry (opentelemetry-instrumentation-langchain) 或 OpenInference ()openinference-instrumentation-langchain。Amazon Bedrock AgentCore Evaluations 支援這兩個程式庫。程式庫會發出不同的範圍名稱，並使用不同的跨度屬性。評估服務會從每個 中擷取相同的值。
當您的代理程式使用 AWS Distro for OpenTelemetry (ADOT) 執行時，例如在 Amazon Bedrock AgentCore 執行期，您不需要新增明確的檢測程式碼。將檢測程式庫新增至專案的相依性已足夠。ADOT 在啟動時發現它並自動啟用它。
為您想要的相依性路徑新增檢測程式庫。下列範例會鎖定最低版本；除非您有鎖定原因，否則請使用最新的可用版本。
範例
- OpenTelemetry
-
注意：使用 版本 0.55.0 或更新版本。0.55.0 版新增了對評估服務所依賴之較新 OpenTelemetry 生成式 AI 代理程式範圍慣例的支援。
將 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
-
將 openinference-instrumentation-langchain新增至您的相依性。發出的範圍名稱為 openinference.instrumentation.langchain。
requirements.txt:
openinference-instrumentation-langchain>=0.1.62
pyproject.toml:
[project]
dependencies = [
"openinference-instrumentation-langchain>=0.1.62",
]
如何識別跨度
用於分類範圍的屬性在兩個檢測程式庫之間不同。
範例
- OpenTelemetry
-
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 檢測程式庫會使用 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) 位於跨度。如需詳細資訊，請參閱跨度、事件記錄和遙測訊號。
分割遙測時，服務會從與每個範圍相關的事件記錄中讀取內容：
如需範例，請參閱範例跨越事件記錄。
未分割遙測時，相同內容會保留在範圍上做為屬性。屬性取決於檢測程式庫：
-
OpenTelemetry：
-
OpenInference：
如需範例，請參閱沒有事件記錄的範例跨度。
範例跨越事件記錄
分割遙測時，範圍會攜帶識別屬性，而內容會存在於相關事件記錄中。下列範例來自部署在 Amazon Bedrock AgentCore 執行期上的 LangGraph 行程規劃代理程式。相同的代理程式會顯示在每個檢測程式庫下方。
這些範例不是完整的跨度。它們會顯示來自實際客服人員互動的代表性資料，省略一些欄位，並截斷長值以保證可讀性。
OpenTelemetry
範例
- Invoke agent span
-
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"
}
]
}
}
}
- Execute tool span
-
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 屬性中承載，而代理程式輸入和輸出會在相關事件記錄中序列化。
範例
- Invoke agent span
-
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"
}
]
}
}
}
- Execute tool span
-
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
範例
- Invoke agent span
-
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"
}
}
- Execute tool span
-
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
範例
- Invoke agent span
-
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"
}
}
- Execute tool span
-
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狀態，因此無論您選擇哪個格式，都會以相同的方式擷取使用者提示和客服人員回應。
