Hasil pencarian

Blok konten hasil pencarian memungkinkan kutipan alami dengan atribusi sumber yang tepat, membawa kutipan berkualitas pencarian web ke aplikasi kustom Anda. Fitur ini sangat kuat untuk aplikasi RAG (Retrieval-Augmented Generation) di mana Anda memerlukan Claude untuk mengutip sumber dengan akurat.

Fitur hasil pencarian tersedia di model berikut:

• Claude Opus 4.1 (claude-opus-4-1-20250805)
• Claude Opus 4 (claude-opus-4-20250514)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Sonnet 4 (claude-sonnet-4-20250514)
• Claude Sonnet 3.7 (deprecated) (claude-3-7-sonnet-20250219)
• Claude 3.5 Haiku (claude-3-5-haiku-20241022)

Manfaat utama

• Kutipan alami - Capai kualitas kutipan yang sama seperti pencarian web untuk konten apa pun
• Integrasi fleksibel - Gunakan dalam pengembalian alat untuk RAG dinamis atau sebagai konten tingkat atas untuk data yang sudah diambil
• Atribusi sumber yang tepat - Setiap hasil mencakup informasi sumber dan judul untuk atribusi yang jelas
• Tidak perlu solusi berbasis dokumen - Menghilangkan kebutuhan akan solusi berbasis dokumen
• Format kutipan yang konsisten - Cocok dengan kualitas dan format kutipan dari fungsi pencarian web Claude

Cara kerjanya

Hasil pencarian dapat disediakan dengan dua cara:

1. Dari panggilan alat - Alat kustom Anda mengembalikan hasil pencarian, memungkinkan aplikasi RAG dinamis
2. Sebagai konten tingkat atas - Anda menyediakan hasil pencarian langsung dalam pesan pengguna untuk konten yang sudah diambil atau di-cache

Dalam kedua kasus, Claude dapat secara otomatis mengutip informasi dari hasil pencarian dengan atribusi sumber yang tepat.

Skema hasil pencarian

Hasil pencarian menggunakan struktur berikut:

{
  "type": "search_result",
  "source": "https://example.com/article",  // Diperlukan: URL sumber atau pengenal
  "title": "Article Title",                  // Diperlukan: Judul hasil
  "content": [ // Diperlukan: Array blok teks
    {
      "type": "text",
      "text": "Konten aktual dari hasil pencarian..."
    }
  ],
  "citations": {                             // Opsional: Konfigurasi kutipan
    "enabled": true                          // Aktifkan/nonaktifkan kutipan untuk hasil ini
  }
}

Bidang yang diperlukan

Bidang opsional

Setiap item dalam array content harus berupa blok teks dengan:

• type: Harus "text"
• text: Konten teks aktual (string tidak kosong)

Metode 1: Hasil pencarian dari panggilan alat

Kasus penggunaan paling kuat adalah mengembalikan hasil pencarian dari alat kustom Anda. Ini memungkinkan aplikasi RAG dinamis di mana alat mengambil dan mengembalikan konten yang relevan dengan kutipan otomatis.

Contoh: Alat basis pengetahuan

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam,
    ToolResultBlockParam
)

client = Anthropic()

# Tentukan alat pencarian basis pengetahuan
knowledge_base_tool = {
    "name": "search_knowledge_base",
    "description": "Cari basis pengetahuan perusahaan untuk informasi",
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Kueri pencarian"
            }
        },
        "required": ["query"]
    }
}

# Fungsi untuk menangani panggilan alat
def search_knowledge_base(query):
    # Logika pencarian Anda di sini
    # Mengembalikan hasil pencarian dalam format yang benar
    return [
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Panduan Konfigurasi Produk",
            content=[
                TextBlockParam(
                    type="text",
                    text="Untuk mengonfigurasi produk, navigasikan ke Pengaturan > Konfigurasi. Waktu tunggu default adalah 30 detik, tetapi dapat disesuaikan antara 10-120 detik berdasarkan kebutuhan Anda."
                )
            ],
            citations={"enabled": True}
        ),
        SearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Panduan Pemecahan Masalah",
            content=[
                TextBlockParam(
                    type="text",
                    text="Jika Anda mengalami kesalahan waktu tunggu, pertama-tama periksa pengaturan konfigurasi. Penyebab umum termasuk latensi jaringan dan nilai waktu tunggu yang tidak benar."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Buat pesan dengan alat
response = client.messages.create(
    model="claude-sonnet-4-5",  # Bekerja dengan semua model yang didukung
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(
            role="user",
            content="Bagaimana cara mengonfigurasi pengaturan waktu tunggu?"
        )
    ]
)

# Ketika Claude memanggil alat, berikan hasil pencarian
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Kirim hasil alat kembali
    final_response = client.messages.create(
        model="claude-sonnet-4-5",  # Bekerja dengan semua model yang didukung
        max_tokens=1024,
        messages=[
            MessageParam(role="user", content="Bagaimana cara mengonfigurasi pengaturan waktu tunggu?"),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result  # Hasil pencarian masuk di sini
                    )
                ]
            )
        ]
    )

Metode 2: Hasil pencarian sebagai konten tingkat atas

Anda juga dapat menyediakan hasil pencarian langsung dalam pesan pengguna. Ini berguna untuk:

• Konten yang sudah diambil dari infrastruktur pencarian Anda
• Hasil pencarian yang di-cache dari kueri sebelumnya
• Konten dari layanan pencarian eksternal
• Pengujian dan pengembangan

Contoh: Hasil pencarian langsung

from anthropic import Anthropic
from anthropic.types import (
    MessageParam,
    TextBlockParam,
    SearchResultBlockParam
)

client = Anthropic()

# Sediakan hasil pencarian langsung dalam pesan pengguna
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[
        MessageParam(
            role="user",
            content=[
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Referensi API - Autentikasi",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Semua permintaan API harus menyertakan kunci API di header Otorisasi. Kunci dapat dihasilkan dari dasbor. Batas laju: 1000 permintaan per jam untuk tingkat standar, 10000 untuk premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                SearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Panduan Memulai",
                    content=[
                        TextBlockParam(
                            type="text",
                            text="Untuk memulai: 1) Daftar akun, 2) Hasilkan kunci API dari dasbor, 3) Instal SDK kami menggunakan pip install company-sdk, 4) Inisialisasi klien dengan kunci API Anda."
                        )
                    ],
                    citations={"enabled": True}
                ),
                TextBlockParam(
                    type="text",
                    text="Berdasarkan hasil pencarian ini, bagaimana cara mengautentikasi permintaan API dan berapa batas lajunya?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

Respons Claude dengan kutipan

Terlepas dari bagaimana hasil pencarian disediakan, Claude secara otomatis menyertakan kutipan saat menggunakan informasi dari mereka:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Untuk mengautentikasi permintaan API, Anda perlu menyertakan kunci API di header Otorisasi",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referensi API - Autentikasi",
          "cited_text": "Semua permintaan API harus menyertakan kunci API di header Otorisasi",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Anda dapat membuat kunci API dari dasbor Anda",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referensi API - Autentikasi",
          "cited_text": "Kunci dapat dihasilkan dari dasbor",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Batas lajunya adalah 1.000 permintaan per jam untuk tingkat standar dan 10.000 permintaan per jam untuk tingkat premium.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referensi API - Autentikasi",
          "cited_text": "Batas laju: 1000 permintaan per jam untuk tingkat standar, 10000 untuk premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

Bidang kutipan

Setiap kutipan mencakup:

Catatan: search_result_index mengacu pada indeks blok konten hasil pencarian (berbasis 0), terlepas dari bagaimana hasil pencarian disediakan (panggilan alat atau konten tingkat atas).

Blok konten berganda

Hasil pencarian dapat berisi beberapa blok teks dalam array content:

{
  "type": "search_result",
  "source": "https://docs.company.com/api-guide",
  "title": "Dokumentasi API",
  "content": [
    {
      "type": "text",
      "text": "Autentikasi: Semua permintaan API memerlukan kunci API."
    },
    {
      "type": "text",
      "text": "Batas Laju: API memungkinkan 1000 permintaan per jam per kunci."
    },
    {
      "type": "text",
      "text": "Penanganan Kesalahan: API mengembalikan kode status HTTP standar."
    }
  ]
}

Claude dapat mengutip blok tertentu menggunakan bidang start_block_index dan end_block_index.

Penggunaan lanjutan

Menggabungkan kedua metode

Anda dapat menggunakan hasil pencarian berbasis alat dan tingkat atas dalam percakapan yang sama:

# Pesan pertama dengan hasil pencarian tingkat atas
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Ikhtisar Produk",
                content=[
                    TextBlockParam(type="text", text="Produk kami membantu tim berkolaborasi...")
                ],
                citations={"enabled": True}
            ),
            TextBlockParam(
                type="text",
                text="Ceritakan tentang produk ini dan cari informasi harga"
            )
        ]
    )
]

# Claude mungkin merespons dan memanggil alat untuk mencari harga
# Kemudian Anda memberikan hasil alat dengan lebih banyak hasil pencarian

Menggabungkan dengan tipe konten lain

Kedua metode mendukung pencampuran hasil pencarian dengan konten lain:

# Dalam hasil alat
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="Panduan Pengguna",
        content=[TextBlockParam(type="text", text="Detail konfigurasi...")],
        citations={"enabled": True}
    ),
    TextBlockParam(
        type="text",
        text="Konteks tambahan: Ini berlaku untuk versi 2.0 dan yang lebih baru."
    )
]

# Dalam konten tingkat atas
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Makalah Penelitian",
        content=[TextBlockParam(type="text", text="Temuan kunci...")],
        citations={"enabled": True}
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"}
    },
    TextBlockParam(
        type="text",
        text="Bagaimana hubungan bagan dengan temuan penelitian?"
    )
]

Kontrol cache

Tambahkan kontrol cache untuk kinerja yang lebih baik:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Panduan Pengguna",
  "content": [{"type": "text", "text": "..."}],
  "cache_control": {
    "type": "ephemeral"
  }
}

Kontrol kutipan

Secara default, kutipan dinonaktifkan untuk hasil pencarian. Anda dapat mengaktifkan kutipan dengan secara eksplisit menetapkan konfigurasi citations:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "Panduan Pengguna",
  "content": [{"type": "text", "text": "Dokumentasi penting..."}],
  "citations": {
    "enabled": true  // Aktifkan kutipan untuk hasil ini
  }
}

Ketika citations.enabled diatur ke true, Claude akan menyertakan referensi kutipan saat menggunakan informasi dari hasil pencarian. Ini memungkinkan:

• Kutipan alami untuk aplikasi RAG kustom Anda
• Atribusi sumber saat berinteraksi dengan basis pengetahuan proprietary
• Kutipan berkualitas pencarian web untuk alat kustom apa pun yang mengembalikan hasil pencarian

Jika bidang citations dihilangkan, kutipan dinonaktifkan secara default.

Praktik terbaik

Untuk pencarian berbasis alat (Metode 1)

• Konten dinamis: Gunakan untuk pencarian real-time dan aplikasi RAG dinamis
• Penanganan kesalahan: Kembalikan pesan yang sesuai ketika pencarian gagal
• Batas hasil: Kembalikan hanya hasil yang paling relevan untuk menghindari overflow konteks

Untuk pencarian tingkat atas (Metode 2)

• Konten yang sudah diambil: Gunakan ketika Anda sudah memiliki hasil pencarian
• Pemrosesan batch: Ideal untuk memproses beberapa hasil pencarian sekaligus
• Pengujian: Bagus untuk menguji perilaku kutipan dengan konten yang diketahui

Praktik terbaik umum

1. Struktur hasil secara efektif

   • Gunakan URL sumber yang jelas dan permanen
   • Berikan judul deskriptif
   • Pisahkan konten panjang menjadi blok teks logis

2. Pertahankan konsistensi

   • Gunakan format sumber yang konsisten di seluruh aplikasi Anda
   • Pastikan judul secara akurat mencerminkan konten
   • Pertahankan pemformatan yang konsisten

3. Tangani kesalahan dengan baik

   def search_with_fallback(query):
       try:
           results = perform_search(query)
           if not results:
               return {"type": "text", "text": "Tidak ada hasil yang ditemukan."}
           return format_as_search_results(results)
       except Exception as e:
           return {"type": "text", "text": f"Kesalahan pencarian: {str(e)}"}

Keterbatasan

• Blok konten hasil pencarian tersedia di Claude API dan Vertex AI Google Cloud
• Hanya konten teks yang didukung dalam hasil pencarian (tidak ada gambar atau media lainnya)
• Array content harus berisi setidaknya satu blok teks