Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

# Memecahkan masalah Connect AI agent
<a name="ts-ai-agents-self-service"></a>

Gunakan topik ini untuk membantu mendiagnosis dan menyelesaikan masalah umum dengan agen Connect AI.

**Topics**
+ [Pencatatan dan penelusuran untuk agen Connect AI](viewing-logs-for-connect-ai-agents-self-service.md)
+ [Memecahkan masalah layanan mandiri agen](ts-agentic-self-service.md)
+ [Masalah umum](ts-common-self-service-issues.md)
+ [(Legacy) Masalah layanan mandiri](ts-non-agentic-self-service.md)

# Pencatatan dan penelusuran untuk agen Connect AI
<a name="viewing-logs-for-connect-ai-agents-self-service"></a>

Untuk memecahkan masalah agen Connect AI secara efektif, gunakan opsi pencatatan dan penelusuran berikut.
+ **ListSpans API (direkomendasikan untuk agen AI orkestrator)**: Gunakan [ListSpans](https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListSpans.html)API untuk mengambil jejak eksekusi agen AI untuk sesi. Ini adalah titik awal yang direkomendasikan untuk men-debug interaksi agen AI orkestrator, karena memberikan visibilitas granular ke dalam aliran orkestrasi agen, interaksi LLM, dan pemanggilan alat, memungkinkan Anda untuk melacak bagaimana agen AI beralasan melalui permintaan dan alat mana yang dipilih dan dijalankan.
+ **CloudWatch Log**: Aktifkan CloudWatch Logging untuk agen Connect AI Anda dengan mengikuti langkah-langkahnya[Monitor Connect agen AI](monitor-ai-agents.md).

  Interaksi swalayan lama menghasilkan entri log dengan jenis peristiwa `TRANSCRIPT_SELF_SERVICE_MESSAGE` dalam format berikut:

  ```
  {
      "assistant_id": "{UUID}",
      "event_timestamp": 1751414298692,
      "event_type": "TRANSCRIPT_SELF_SERVICE_MESSAGE",
      "session_id": "{UUID}",
      "utterance": "[CUSTOMER]...",
      "prompt": "{prompt used}",
      "prompt_type": "SELF_SERVICE_PRE_PROCESS|SELF_SERVICE_ANSWER_GENERATION",
      "completion": "{Response from model}",
      "model_id": "{model id e.g.: us.amazon.nova-pro-v1:0}",
      "session_message_id": "{UUID}",
      "parsed_response": "{model response}"
  }
  ```

  Interaksi layanan mandiri agen menghasilkan entri log dengan jenis peristiwa. `TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION` Entri ini mencakup konteks orkestrasi lengkap seperti prompt dengan konfigurasi alat, riwayat percakapan dengan panggilan dan hasil alat, penyelesaian model, dan konfigurasi agen AI. Contoh berikut menunjukkan bidang kunci:

  ```
  {
      "assistant_id": "{UUID}",
      "event_timestamp": 1772748470993,
      "event_type": "TRANSCRIPT_LARGE_LANGUAGE_MODEL_INVOCATION",
      "session_id": "{UUID}",
      "prompt": "{full prompt including system instructions, tool configs, and conversation history}",
      "prompt_type": "ORCHESTRATION",
      "completion": "{model response with message and tool use}",
      "model_id": "{model id e.g.: us.anthropic.claude-haiku-4-5-20251001-v1:0}",
      "parsed_response": "{parsed customer-facing message}",
      "generation_id": "{UUID}",
      "ai_agent_id": "{UUID}"
  }
  ```
+ **Pencatatan Amazon Lex (khusus layanan mandiri)**: Aktifkan pencatatan Amazon Lex dengan mengikuti langkah-langkah dalam [kesalahan Pencatatan dengan log kesalahan di Amazon Lex V2](https://docs.aws.amazon.com/lexv2/latest/dg/error-logs.html). 
+ **Pencatatan Amazon Connect**: Aktifkan pencatatan Amazon Connect dengan menambahkan blok [Mengatur perilaku logging](set-logging-behavior.md) aliran di alur Amazon Connect Anda.

# Memecahkan masalah layanan mandiri agen
<a name="ts-agentic-self-service"></a>

Masalah-masalah berikut khusus untuk [layanan mandiri agen](agentic-self-service.md).

## Agen AI tidak menanggapi pelanggan
<a name="ts-ai-agent-not-responding"></a>

Jika agen AI Anda memproses permintaan tetapi pelanggan tidak melihat tanggapan apa pun, prompt orkestrasi mungkin kehilangan instruksi pemformatan pesan yang diperlukan.

Agen AI orkestrator hanya menampilkan pesan kepada pelanggan saat respons model dibungkus dengan tag. `<message>` Jika prompt Anda tidak menginstruksikan model untuk menggunakan tag ini, tanggapan tidak akan diberikan kepada pelanggan.

**Solusi**: Pastikan prompt orkestrasi Anda menyertakan instruksi pemformatan yang mengharuskan model untuk membungkus respons dalam tag. `<message>` Untuk informasi selengkapnya, lihat [Penguraian pesan](use-orchestration-ai-agent.md#message-parsing).

## Kegagalan pemanggilan alat MCP
<a name="ts-mcp-tool-failures"></a>

Jika agen AI Anda gagal menjalankan alat MCP selama percakapan, periksa hal berikut:
+ **Izin profil keamanan** — Verifikasi bahwa profil keamanan agen AI memberikan akses ke alat MCP tertentu yang dibutuhkannya. Agen AI hanya dapat memanggil alat yang memiliki izin eksplisit untuk mengaksesnya.
+ **Konektivitas gateway** — Konfirmasikan bahwa Amazon Bedrock AgentCore Gateway telah dikonfigurasi dengan benar dan bahwa URL penemuan valid. Verifikasi bahwa audiens otentikasi masuk disetel ke ID gateway. Periksa status gateway di AgentCore konsol.
+ **Kesehatan titik akhir API** - Verifikasi bahwa fungsi backend API atau Lambda di belakang alat MCP berjalan dan merespons dengan benar. Periksa CloudWatch Log untuk kesalahan dalam layanan target.

## Izin IAM untuk alat MCP
<a name="ts-mcp-iam-permissions"></a>

Jika alat MCP memanggil kesalahan akses kembali ditolak, verifikasi bahwa peran IAM memiliki izin yang diperlukan:
+ Peran **Amazon Bedrock AgentCore Gateway — Peran** eksekusi gateway harus memiliki izin untuk menjalankan fungsi backend APIs atau Lambda yang terhubung dengan alat MCP Anda.
+ **Peran terkait layanan Amazon Connect — Peran terkait** layanan Amazon Connect harus memiliki izin untuk memanggil Amazon Bedrock Gateway. AgentCore 

# Masalah umum
<a name="ts-common-self-service-issues"></a>

## Bundel AWS SDK terbaru dengan fungsi Lambda Anda
<a name="ts-lambda-sdk-bundling"></a>

Jika Anda memanggil agen Connect AI APIs langsung dari fungsi Lambda, Anda harus mengemas dan menggabungkan versi terbaru AWS SDK bersama dengan kode fungsi Anda. Lingkungan runtime Lambda mungkin menyertakan versi SDK yang lebih lama yang tidak mendukung model dan fitur API Connect AI agent terbaru.

**Gejala**: Anda mungkin mengalami pengecualian validasi parameter atau meminta parameter input diabaikan secara diam-diam saat menggunakan versi SDK yang sudah ketinggalan zaman.

Untuk menghindari penyimpangan model API, sertakan AWS SDK terbaru sebagai dependensi dalam paket penerapan Anda atau sebagai lapisan Lambda daripada mengandalkan SDK yang disediakan oleh runtime Lambda. Langkah-langkah untuk menggabungkan SDK bervariasi menurut bahasa. Misalnya, untuk Node.js, lihat [Membuat paket penerapan dengan dependensi](https://docs.aws.amazon.com/lambda/latest/dg/nodejs-package.html#nodejs-package-create-dependencies). Untuk bahasa lain, lihat dokumentasi kemasan penyebaran Lambda yang sesuai. Untuk berbagi SDK di beberapa fungsi, lihat Lapisan [Lambda](https://docs.aws.amazon.com/lambda/latest/dg/chapter-layers.html).

# (Legacy) Masalah layanan mandiri
<a name="ts-non-agentic-self-service"></a>

Masalah-masalah berikut khusus untuk [layanan mandiri warisan](generative-ai-powered-self-service.md).

## Pelanggan tiba-tiba menerima “Eskalasi ke agen...”
<a name="customers-unexpectedly-receiving-escalating-to-agent"></a>

Eskalasi agen yang tidak terduga terjadi ketika ada kesalahan selama interaksi bot swalayan atau ketika model tidak menghasilkan `tool_use` respons yang valid untuk. `SELF_SERVICE_PRE_PROCESS`

### Langkah pemecahan masalah
<a name="escalation-ts-steps"></a>

1. **Periksa log agen Connect AI**: Periksa `completion` atribut di entri log terkait.

1. **Validasi alasan berhenti**: Konfirmasikan bahwa `stop_reason` ada`tool_use`.

1. **Verifikasi respons yang diuraikan**: Periksa apakah `parsed_response` bidang diisi, karena ini mewakili respons yang akan Anda terima dari model.

### Masalah yang diketahui dengan Claude 3 Haiku
<a name="known-issue-with-claude-3-haiku"></a>

Jika Anda menggunakan Claude 3 Haiku untuk pra-pemrosesan swalayan, ada masalah yang diketahui di mana ia menghasilkan `tool_use` JSON sebagai teks, menghasilkan teks dan bukan. `stop_reason` `end_turn` `tool_use`

**Solusi**: Perbarui prompt khusus Anda untuk membungkus string `tool_use` JSON di dalam `<tool>` tag dengan menambahkan instruksi ini:

```
You MUST enclose the tool_use JSON in the <tool> tag
```

## Obrolan swalayan atau panggilan suara tiba-tiba berakhir
<a name="self-service-unexpectedly-terminating"></a>

Masalah ini dapat terjadi karena batas waktu dari Amazon Lex atau konfigurasi Amazon Nova Pro yang salah. Masalah-masalah ini dijelaskan di bawah ini.

### Timeout dari Amazon Lex
<a name="timeouts-from-amazon-lex"></a>
+ **Gejala**: Log Amazon Connect menunjukkan “Kesalahan Server Internal” untuk [Dapatkan masukan pelanggan](get-customer-input.md) blok
+ **Penyebab**: Bot swalayan Anda habis waktu sambil memberikan hasil dalam batas 10 detik. Kesalahan batas waktu tidak akan muncul di log agen Connect AI.
+ **Solusi**: Sederhanakan prompt Anda dengan menghapus penalaran yang rumit untuk mengurangi waktu pemrosesan.

### Konfigurasi Amazon Nova Pro
<a name="amazon-nova-pro-configuration"></a>

[Jika Anda menggunakan Amazon Nova Pro untuk permintaan AI kustom Anda, pastikan bahwa contoh tool\$1use mengikuti format yang kompatibel dengan Python.](create-ai-prompts.md#nova-pro-aiprompt)