Dukungan agen Python TypeScript dukungan agen Praktik terbaik untuk LangGraph agen

Siapkan LangGraph telemetri untuk Evaluasi AgentCore

Halaman ini menjelaskan cara instrumen LangGraph agen, bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi. AgentCore Evaluasi mendukung LangGraph agen yang dibangun di Python dan TypeScript; halaman ini mencakup setiap bahasa secara terpisah, dalam dukungan agen Python dan dukungan TypeScript agen. Ini ditutup dengan praktik terbaik untuk menyusun LangGraph agen sehingga dapat dievaluasi dengan andal.

Topik

Dukungan agen Python
TypeScript dukungan agen
Praktik terbaik untuk LangGraph agen

Dukungan agen Python

LangGraph Agen Python memancarkan rentang di bawah nama cakupan opentelemetry.instrumentation.langchain (OpenTelemetry) atau openinference.instrumentation.langchain (OpenInference).

Instrumentasikan agen Anda

Anda dapat menginstrumenkan LangGraph agen dengan salah satu dari dua pustaka instrumentasi: OpenTelemetry (opentelemetry-instrumentation-langchain) atau OpenInference (openinference-instrumentation-langchain). Amazon Bedrock AgentCore Evaluations mendukung kedua perpustakaan. Pustaka memancarkan nama cakupan yang berbeda dan menggunakan atribut rentang yang berbeda. Layanan evaluasi mengekstrak nilai yang sama dari masing-masing.

Saat agen Anda berjalan dengan AWS Distro for OpenTelemetry (ADOT), seperti pada Amazon Bedrock AgentCore Runtime, Anda tidak perlu menambahkan kode instrumentasi eksplisit. Menambahkan pustaka instrumentasi ke dependensi proyek Anda sudah cukup. ADOT menemukannya saat startup dan mengaktifkannya secara otomatis.

Tambahkan pustaka instrumentasi untuk jalur yang Anda inginkan ke dependensi Anda. Contoh berikut menyematkan versi minimum; gunakan versi terbaru yang tersedia kecuali Anda memiliki alasan untuk menyematkan.

contoh

catatan

Instrumentasi adalah salah satu langkah dalam mengatur observabilitas. Untuk mengekspor telemetri untuk evaluasi, selesaikan penyiapan lengkap di Menyi apkan observ abilitas.

Bagaimana rentang diidentifikasi

Atribut yang digunakan untuk mengklasifikasikan rentang berbeda antara dua pustaka instrumentasi.

contoh

OpenTelemetry

P OpenTelemetry ustaka instrumentasi mengklasifikasikan rentang menggunakan traceloop.span.kind atribut, dan versi terbaru juga ditetapkan. gen_ai.operation.name

Jenis rentang	Mengidentifikasi atribut
Memanggil agen	`traceloop.span.kind`= `workflow` (juga `gen_ai.operation.name` =`invoke_agent`)
Jalankan alat	`traceloop.span.kind`= `tool` (juga `gen_ai.operation.name` =`execute_tool`)
Inferensi	`gen_ai.operation.name` = `chat`

OpenInference

Pust OpenInference aka instrumentasi mengklasifikasikan rentang menggunakan atribut. openinference.span.kind

Jenis rentang	Mengidentifikasi atribut
Memanggil agen	`openinference.span.kind`= `CHAIN` atau `AGENT`
Jalankan alat	`openinference.span.kind` = `TOOL`
Inferensi	`openinference.span.kind` = `LLM`

Bagaimana bidang evaluasi diekstraksi

Untuk rentang agen invoke, input dan output tidak berisi daftar per-pesan bersih. Sebaliknya, kontennya adalah status LangChain grafik serial: string JSON yang membungkus status penuh. Bentuk yang tepat dari status serial ini berbeda antara dua pustaka instrumentasi. Dalam kedua kasus, layanan menguraikannya untuk menemukan prompt pengguna (pesan manusia) dan respons agen (pesan AI).

LangGraph juga menyerialkan peran pesan dalam lebih dari satu bentuk. Peran dapat muncul sebagai nilai huruf kecil (human,ai,tool) atau sebagai nama kelas LangChain pesan (HumanMessage,AIMessage,ToolMessage). Layanan mengenali kedua bentuk.

Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut pengi traceloop.span.kind dentifikasi (atauopeninference.span.kind) berada pada rentang dalam kedua kasus. Untuk informasi selengkapnya, lihat Peng aturan dan pengiriman telemetri.

Dari catatan acara

Dengan telemetri terpisah, layanan membaca konten dari catatan peristiwa yang berkorelasi dengan setiap rentang:

Prompt pengguna dan respons agen: dari catatan peristiwa span agen pemanggilan, di body.input danbody.output.
Panggilan alat: nama alat dari rentang alat eksekusi. Argumen alat dan hasil berasal dari catatan peristiwa span itu, di body.input danbody.output.

Untuk informasi selengkapnya, lihat Contoh rentang dalam telem etri terpisah.

Dari atribut rentang

Dengan telemetri terpadu, konten yang sama tetap pada rentang sebagai atribut. Atribut tergantung pada pustaka instrumentasi:

OpenTelemetry:
- Prompt pengguna dan respons agen: dari gen_ai.task.input dan gen_ai.task.output pada rentang agen pemanggilan.
- Panggilan alat: nama alat darigen_ai.tool.name, dan argumen serta hasil dari gen_ai.tool.call.arguments dangen_ai.tool.call.result, pada rentang alat eksekusi.
OpenInference:
- Prompt pengguna dan respons agen: dari input.value dan output.value pada rentang agen pemanggilan.
- Panggilan alat: nama alat daritool.name, dan argumen serta hasil dari input.value danoutput.value, pada rentang alat eksekusi.

Untuk informasi selengkapnya, lihat Contoh rentang dalam telem etri terpadu.

Contoh rentang dalam telemetri terpisah

Dengan telemetri terpisah, rentang membawa atribut pengidentifikasi dan konten hidup dalam catatan peristiwa yang berkorelasi. Contoh berikut berasal dari agen LangGraph perencanaan perjalanan Python yang digunakan di Amazon Bed AgentCore rock Runtime. Agen yang sama ditampilkan di bawah setiap perpustakaan instrumentasi.

catatan

Contoh-contoh ini bukan rentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

OpenTelemetry

contoh

Invoke agent span

A traceloop.span.kind tribut (workflow) mengidentifikasi ini sebagai rentang agen pemanggilan; versi pustaka terbaru juga menetapkan 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"
  }
}

Catatan peristiwa yang berkorelasi membawa percakapan. Setiap pesan content adalah status LangChain grafik serial. Input membungkus status di bawah inputs kunci. Output membungkusnya di bawah outputs kunci, dengan setiap pesan sebagai objek LangChain konstruktor. Prompt pengguna adalah pesan manusia dan respons agen adalah pesan AI di dalam status serial itu.


{
  "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

A traceloop.span.kind tribut (tool) mengidentifikasi ini sebagai rentang alat eksekusi; gen_ai.tool.name memegang nama alat dan 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"
  }
}

Catatan peristiwa yang berkorelasi membawa input alat (argumen) dan output (hasil, diserialkan sebagai a 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

Dengan pust OpenInference aka, tipe rentang dibawa dalam openinference.span.kind atribut, dan input dan output agen diserialkan dalam catatan peristiwa yang berkorelasi.

contoh

Invoke agent span

A openinference.span.kind tribut (CHAIN, atau AGENT ketika grafik dikompilasi dengan nama) mengidentifikasi ini sebagai rentang agen pemanggilan.


{
  "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"
  }
}

Catatan peristiwa yang berkorelasi membawa percakapan. Prompt pengguna adalah pesan peran manusia dan respons agen adalah AI-role pesan dalam pesan serial.


{
  "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

A openinference.span.kind tribut (TOOL) mengidentifikasi ini sebagai rentang alat eksekusi; tool.name memegang nama alat.


{
  "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"
  }
}

Catatan peristiwa yang berkorelasi membawa input alat (argumen) dan output (hasil, diserialkan sebagai a 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"
        }
      ]
    }
  }
}

Contoh rentang dalam telemetri terpadu

Dengan telemetri terpadu, konten yang sama tetap pada atribut rentang dan tidak ada catatan peristiwa terpisah yang dihasilkan. Contoh berikut berasal dari agen LangGraph perencanaan perjalanan Python. Agen yang sama ditampilkan di bawah setiap perpustakaan instrumentasi.

catatan

Contoh-contoh ini bukan rentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

OpenTelemetry

contoh

Invoke agent span

A gen_ai.task.input tribut menyimpan prompt pengguna, dan gen_ai.task.output atribut memegang status serial dengan respons agen. Keduanya adalah status LangChain grafik serial.


{
  "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

A gen_ai.tool.call.arguments tribut menyimpan argumen alat, dan gen_ai.tool.call.result atribut menyimpan hasil alat, diserialkan sebagai 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

contoh

TypeScript dukungan agen

TypeScript LangGraph Agen memancarkan tipe rentang yang sama dengan agen Python, sehingga layanan evaluasi membacanya dengan cara yang sama. Ada tiga perpustakaan TypeScript instrumentasi, masing-masing dengan nama ruang lingkup dan konvensi klasifikasi span-nya sendiri.

Instrumentasikan agen Anda

Tambahkan pustaka instrumentasi untuk jalur yang Anda inginkan ke TypeScript dependensi Anda. Contoh berikut menyematkan versi minimum; gunakan versi terbaru yang tersedia kecuali Anda memiliki alasan untuk menyematkan.

contoh

catatan

Instrumentasi adalah salah satu langkah dalam mengatur observabilitas. Untuk mengekspor telemetri untuk evaluasi, selesaikan penyiapan lengkap di Menyi apkan observ abilitas.

Bagaimana rentang diidentifikasi

Identifikasi rentang tergantung pada perpustakaan instrumentasi:

ADOT (OpenTelemetry): paket autoinstrumentasi AWS Distro Node (@aws/aws-distro-opentelemetry-node-autoinstrumentation), yang memancarkan nama cakupan@aws/aws-distro-opentelemetry-instrumentation-langchain, set gen_ai.operation.name (,,chat) invoke_agentexecute_tool, sama dengan kerangka kerja lainnya. ADOT-native
Traceloop (OpenTelemetry): pustaka OpenTelemetry JS dari Traceloop (@traceloop/instrumentation-langchain) set traceloop.span.kind (workflowuntuk rentang agen invoke, untuk rentang alat), task cocok dengan pustaka Python. OpenTelemetry Lihat Bagaimana rentang diidentifikasi di bawah dukungan agen Python.
OpenInference: perpustakaan OpenInference JS (@arizeai/openinference-instrumentation-langchain) menetapkan openinference.span.kind (CHAINatau AGENTTOOL,,LLM), sama dengan pust OpenInference aka Python.

Bagaimana bidang evaluasi diekstraksi

Ekstraksi lapangan tergantung pada perpustakaan instrumentasi:

ADOT (OpenTelemetry): rentang agen invoke adalah wadah struktural, dan konten percakapan hidup pada rentang inferensi (chat), dalam format bagian dan atribut. gen_ai.input.messages gen_ai.output.messages
Traceloop (OpenTelemetry): dengan pustaka OpenTelemetry JS dari Traceloop, percakapan berada di traceloop.entity.output atribut traceloop.entity.input and, sebagai status serial. LangChain Ini cocok dengan pust OpenTelemetry aka Python; lihat Bagaimana bidang evaluasi diekstraksi di bawah dukungan agen Python.
OpenInference: dengan perpustakaan OpenInference JS, percakapan ada di output.value atribut input.value dan, dan pesan inferensi juga muncul pada atribut yang diindeksllm.input_messages.*. llm.output_messages.* Ini cocok dengan pust OpenInference aka Python.

Contoh rentang dari agen TypeScript

Contoh berikut berasal dari agen TypeScript LangGraph perencanaan perjalanan yang digunakan di Amazon Bedrock AgentCore Runtime dengan telemetri terpadu. Agen yang sama ditampilkan di bawah masing-masing dari tiga perpustakaan TypeScript instrumentasi.

catatan

Contoh-contoh ini bukan rentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

OpenTelemetry (ADOT asli)

Dengan pust ADOT-native aka (dari paket autoinstrumentasi AWS Distro Node@aws/aws-distro-opentelemetry-node-autoinstrumentation, memancarkan nama cakupan@aws/aws-distro-opentelemetry-instrumentation-langchain), rentang agen invoke adalah wadah struktural dan konten percakapan hidup pada rentang inferensi (chat), dalam format bagian dan atribut. gen_ai.input.messages gen_ai.output.messages

contoh

Invoke agent span

A gen_ai.operation.name tribut (invoke_agent) mengidentifikasi ini sebagai rentang agen invoke. Rentang membawa nama agen dan model tetapi tidak ada konten percakapan.


{
  "traceId": "6a6bd0a1c8d91ed1e70a3906b551618",
  "spanId": "ba1833fa7f097041",
  "name": "invoke_agent LangGraph",
  "kind": "INTERNAL",
  "scope": {
    "name": "@aws/aws-distro-opentelemetry-instrumentation-langchain",
    "version": "0.12.0"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "LangGraph",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

A gen_ai.operation.name tribut (execute_tool) mengidentifikasi ini sebagai rentang alat eksekusi; gen_ai.tool.name memegang nama alat. gen_ai.tool.call.resultAtribut gen_ai.tool.call.arguments dan menyimpan argumen alat dan hasil.


{
  "traceId": "6a6bd0a25c52f3d86a35038f35f5ba30",
  "spanId": "5b332f3cd15ace04",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "@aws/aws-distro-opentelemetry-instrumentation-langchain",
    "version": "0.12.0"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.type": "function",
    "gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

A gen_ai.operation.name tribut (chat) mengidentifikasi ini sebagai rentang inferensi. gen_ai.output.messagesAtribut gen_ai.input.messages and menahan percakapan dalam format bagian, dan gen_ai.system_instructions menahan prompt sistem.


{
  "traceId": "6a6bd0a1c8d91ed1e70a3906b551618",
  "spanId": "7c1f9a2b4d6e8a03",
  "name": "chat gpt-4o-mini",
  "kind": "INTERNAL",
  "scope": {
    "name": "@aws/aws-distro-opentelemetry-instrumentation-langchain",
    "version": "0.12.0"
  },
  "attributes": {
    "gen_ai.operation.name": "chat",
    "gen_ai.provider.name": "openai",
    "gen_ai.request.model": "gpt-4o-mini",
    "gen_ai.input.messages": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]",
    "gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trip ...\"}]}]",
    "gen_ai.system_instructions": "[{\"type\": \"text\", \"content\": \"You are a travel planning assistant ...\"}]",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

OpenTelemetry (Traceloop)

Dengan pust OpenTelemetry aka JS dari Traceloop (@traceloop/instrumentation-langchain), tipe span dibawa dalam traceloop.span.kind atribut (workflowuntuk rentang agen invoke, untuk rentang alat), task dan gen_ai.operation.name = workflow pada rentang agen invoke. Percakapan berada dalam traceloop.entity.output atribut traceloop.entity.input dan, sebagai LangChain status serial.

contoh

Invoke agent span

A traceloop.span.kind tribut (workflow) mengidentifikasi ini sebagai rentang agen invoke. traceloop.entity.outputAtribut traceloop.entity.input and memegang LangChain status serial, dari mana prompt pengguna (pesan manusia) dan respons agen (pesan AI) diurai.


{
  "traceId": "6a6bd0b1c8d91ed1e70a3906b551618",
  "spanId": "ba1833fa7f097041",
  "name": "workflow RunnableSequence",
  "kind": "INTERNAL",
  "scope": {
    "name": "@traceloop/instrumentation-langchain",
    "version": "0.27.0"
  },
  "attributes": {
    "traceloop.span.kind": "workflow",
    "gen_ai.operation.name": "workflow",
    "gen_ai.provider.name": "langchain",
    "traceloop.workflow.name": "RunnableSequence",
    "traceloop.entity.input": "{\"messages\": [{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain_core\", \"messages\", \"HumanMessage\"], \"kwargs\": {\"content\": \"Hey, how can you help me\"}}]}",
    "traceloop.entity.output": "{\"messages\": [{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain_core\", \"messages\", \"AIMessage\"], \"kwargs\": {\"content\": \"I can assist you with planning your trip ...\"}}]}",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

A traceloop.span.kind tribut (task) mengidentifikasi ini sebagai rentang alat eksekusi. traceloop.entity.outputAtribut traceloop.entity.input dan menyimpan argumen alat dan hasil.


{
  "traceId": "6a6bd0b25c52f3d86a35038f35f5ba30",
  "spanId": "5b332f3cd15ace04",
  "name": "task search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "@traceloop/instrumentation-langchain",
    "version": "0.27.0"
  },
  "attributes": {
    "traceloop.span.kind": "task",
    "traceloop.entity.name": "search_flights",
    "traceloop.entity.input": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "traceloop.entity.output": "{\"output\": {\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain_core\", \"messages\", \"ToolMessage\"], \"kwargs\": {\"status\": \"success\", \"content\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}}}",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

OpenInference

Dengan pustaka OpenInference JS (@arizeai/openinference-instrumentation-langchain), tipe span dibawa dalam openinference.span.kind atribut. Konten percakapan ada di output.value atribut input.value dan, dan pesan inferensi juga muncul di indeks llm.input_messages.* dan llm.output_messages.* atribut.

contoh

Invoke agent span

A openinference.span.kind tribut (CHAIN) mengidentifikasi ini sebagai rentang agen invoke. output.valueAtribut input.value and memegang LangChain status serial.


{
  "traceId": "6a6bd0c1c8d91ed1e70a3906b551618",
  "spanId": "0a7990d804132a9b",
  "name": "LangGraph",
  "kind": "INTERNAL",
  "scope": {
    "name": "@arizeai/openinference-instrumentation-langchain",
    "version": "4.0.14"
  },
  "attributes": {
    "openinference.span.kind": "CHAIN",
    "input.value": "{\"messages\": [{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain_core\", \"messages\", \"HumanMessage\"], \"kwargs\": {\"content\": \"Hey, how can you help me\"}}]}",
    "output.value": "{\"messages\": [{\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain_core\", \"messages\", \"AIMessage\"], \"kwargs\": {\"content\": \"I can assist you with planning your trip ...\"}}]}",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

Execute tool span

A openinference.span.kind tribut (TOOL) mengidentifikasi ini sebagai rentang alat eksekusi; tool.name memegang nama alat. output.valueAtribut input.value and menyimpan argumen alat dan hasil (diserialkan sebagai a LangChain ToolMessage).


{
  "traceId": "6a6bd0c25c52f3d86a35038f35f5ba30",
  "spanId": "ab105c12cc40048f",
  "name": "search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "@arizeai/openinference-instrumentation-langchain",
    "version": "4.0.14"
  },
  "attributes": {
    "openinference.span.kind": "TOOL",
    "tool.name": "search_flights",
    "input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
    "output.value": "{\"output\": {\"lc\": 1, \"type\": \"constructor\", \"id\": [\"langchain_core\", \"messages\", \"ToolMessage\"], \"kwargs\": {\"status\": \"success\", \"content\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}}}",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

Inference span

A openinference.span.kind tribut (LLM) mengidentifikasi ini sebagai rentang inferensi. A llm.input_messages.* tribut menahan prompt sistem dan prompt pengguna, dan llm.output_messages.* atribut menahan respons agen.


{
  "traceId": "6a6bd0c1c8d91ed1e70a3906b551618",
  "spanId": "1221a062c7f90a8e",
  "name": "ChatOpenAI",
  "kind": "INTERNAL",
  "scope": {
    "name": "@arizeai/openinference-instrumentation-langchain",
    "version": "4.0.14"
  },
  "attributes": {
    "openinference.span.kind": "LLM",
    "llm.model_name": "gpt-4o-mini",
    "llm.input_messages.0.message.role": "system",
    "llm.input_messages.0.message.content": "You are a travel planning assistant ...",
    "llm.input_messages.1.message.role": "user",
    "llm.input_messages.1.message.content": "Hey, how can you help me",
    "llm.output_messages.0.message.role": "assistant",
    "llm.output_messages.0.message.content": "I can assist you with planning your trip ...",
    "session.id": "sea-nyc-trip-2-turns"
  },
  "status": {
    "code": "OK"
  }
}

Praktik terbaik untuk LangGraph agen

Bagaimana Anda membangun dan memanggil LangGraph agen memengaruhi apa yang muncul dalam telemetri-nya, dan oleh karena itu seberapa andal agen dapat dievaluasi. Praktik berikut membantu memastikan prompt pengguna, respons agen, dan aktivitas alat dapat dipulihkan.

1. Pilih pola konstruksi agen

Ada dua cara umum untuk membangun LangGraph agen:

Prebuilt create_agent: cara tercepat untuk memulai. Ini menghasilkan rentang agen pemanggilan tunggal per giliran, dengan percakapan melewati loop eksekusi baw LangGraph aan. Gunakan ini jika Anda menginginkan agen tindakan alasan standar tanpa alur kontrol khusus.
```
from langchain.agents import create_agent

agent = create_agent(model=model, tools=[search_flights, book_flight])
```

Kustom StateGraph: memberi Anda kontrol penuh atas node, tepi, dan routing bersyarat. Setiap eksekusi node menjadi rentangnya sendiri, sehingga jejak lebih granular. Gunakan ini saat Anda membutuhkan orkestrasi khusus.


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()

Kedua pola dievaluasi dengan cara yang sama; perbedaannya adalah granularitas jejak.

2. Gunakan `pesan` di Status grafik Anda (disarankan)

Layanan evaluasi merekonstruksi percakapan dari pesan input dan output agen. Menggunakan messages bidang tidak wajib, tetapi memungkinkan ekstraksi yang paling andal. Untuk kebiasaanStateGraph, simpan percakapan di messages bidang di Negara Bagian Anda:

Sertakan messages di Negara Anda (disarankan). Anda dapat menambahkan bidang khusus lainnya (seperti user_id atau metadata). Ketika messages ada, ekstraksi standar menemukan prompt pengguna dan respons agen secara langsung. Jika tidak messages ada, layanan kembali merekonstruksi percakapan dari rentang inferensi individu, yang kurang dapat diandalkan.
Tambahkan, jangan ganti. Ikuti LangGraph konvensi menambahkan pesan baru ke daftar daripada menulisnya, sehingga riwayat percakapan lengkap dipertahankan.
Gunakan jenis LangChain pesan kanonik (HumanMessage,, AIMessageToolMessage,SystemMessage). Instrumentasi membuat serial ini dengan benar, dan layanan mengenali peran mereka.

3. Meneruskan pesan pengguna dalam format yang didukung

Saat Anda memanggil LangGraph agen, Anda menambahkan pesan pengguna ke status grafik. messages LangGraph menerima pesan dalam tiga format yang dapat dipertukarkan, dan AgentCore Evaluasi mendukung semuanya. Masing-masing menghasilkan rentang dan catatan peristiwa yang dapat dibaca layanan.

Tuple: (role, content) sepasang:


agent.invoke({"messages": [("user", user_message)]}, config=config)

LangChain objek pesan: a HumanMessage (atau kelas pesan lainnya):


from langchain_core.messages import HumanMessage

agent.invoke({"messages": [HumanMessage(content=user_message)]}, config=config)

Kamus: kam {"role", "content"} us:


agent.invoke({"messages": [{"role": "user", "content": user_message}]}, config=config)

Ketiga format menghasilkan status yang samamessages, sehingga prompt pengguna dan respons agen diekstraksi secara identik terlepas dari mana yang Anda pilih.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Agen Helai

Agen OpenAI

Siapkan LangGraph telemetri untuk Evaluasi AgentCore

Dukungan agen Python

Instrumentasikan agen Anda

contoh

catatan

Bagaimana rentang diidentifikasi

contoh

Bagaimana bidang evaluasi diekstraksi

Dari catatan acara

Dari atribut rentang

Contoh rentang dalam telemetri terpisah

catatan

OpenTelemetry

contoh

OpenInference

contoh

Contoh rentang dalam telemetri terpadu

catatan

OpenTelemetry

contoh

OpenInference

contoh

TypeScript dukungan agen

Instrumentasikan agen Anda

contoh

catatan

Bagaimana rentang diidentifikasi

Bagaimana bidang evaluasi diekstraksi

Contoh rentang dari agen TypeScript

catatan

OpenTelemetry (ADOT asli)

contoh

OpenTelemetry (Traceloop)

contoh

OpenInference

contoh

Praktik terbaik untuk LangGraph agen

1. Pilih pola konstruksi agen

2. Gunakan pesan di Status grafik Anda (disarankan)

3. Meneruskan pesan pengguna dalam format yang didukung

2. Gunakan `pesan` di Status grafik Anda (disarankan)