Blok konten hasil pencarian saat ini dalam versi beta. Gunakan header beta search-results-2025-06-09 beta header untuk mengaktifkan fitur ini.

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

​
Manfaat utama

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

​
Cara kerjanya

Hasil pencarian dapat disediakan dalam dua cara:

  1. Dari panggilan tool - Tool 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 sebelumnya 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",  // Wajib: URL sumber atau identifier
  "title": "Judul Artikel",                  // Wajib: Judul hasil
  "content": [ // Wajib: Array blok teks
    {
      "type": "text",
      "text": "Konten aktual dari hasil pencarian..."
    }
  ],
  "citations": {                             // Opsional: Konfigurasi kutipan
    "enabled": true                          // Aktifkan/nonaktifkan kutipan untuk hasil ini
  }
}

​
Field wajib

FieldTypeDeskripsi
typestringHarus "search_result"
sourcestringURL sumber atau identifier untuk konten
titlestringJudul deskriptif untuk hasil pencarian
contentarrayArray blok teks yang berisi konten aktual

​
Field opsional

FieldTypeDeskripsi
citationsobjectKonfigurasi kutipan dengan field boolean enabled
cache_controlobjectPengaturan kontrol cache (misalnya, {"type": "ephemeral"})

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 tool

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

​
Contoh: Tool basis pengetahuan

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam,
    BetaToolResultBlockParam
)

client = Anthropic()

# Definisikan tool 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": "Query pencarian"
            }
        },
        "required": ["query"]
    }
}

# Fungsi untuk menangani panggilan tool
def search_knowledge_base(query):
    # Logika pencarian Anda di sini
    # Mengembalikan hasil pencarian dalam format yang benar
    return [
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/product-guide",
            title="Panduan Konfigurasi Produk",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Untuk mengkonfigurasi produk, navigasi ke Settings > Configuration. Timeout default adalah 30 detik, tetapi dapat disesuaikan antara 10-120 detik berdasarkan kebutuhan Anda."
                )
            ],
            citations={"enabled": True}
        ),
        BetaSearchResultBlockParam(
            type="search_result",
            source="https://docs.company.com/troubleshooting",
            title="Panduan Troubleshooting",
            content=[
                BetaTextBlockParam(
                    type="text",
                    text="Jika Anda mengalami error timeout, pertama periksa pengaturan konfigurasi. Penyebab umum termasuk latensi jaringan dan nilai timeout yang salah."
                )
            ],
            citations={"enabled": True}
        )
    ]

# Buat pesan dengan tool
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    tools=[knowledge_base_tool],
    messages=[
        BetaMessageParam(
            role="user",
            content="Bagaimana cara mengkonfigurasi pengaturan timeout?"
        )
    ]
)

# Ketika Claude memanggil tool, berikan hasil pencarian
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])
    
    # Kirim hasil tool kembali
    final_response = client.beta.messages.create(
        model="claude-opus-4-20250514",
        max_tokens=1024,
        betas=["search-results-2025-06-09"],
        messages=[
            BetaMessageParam(role="user", content="Bagaimana cara mengkonfigurasi pengaturan timeout?"),
            BetaMessageParam(role="assistant", content=response.content),
            BetaMessageParam(
                role="user",
                content=[
                    BetaToolResultBlockParam(
                        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 sebelumnya dari infrastruktur pencarian Anda
  • Hasil pencarian yang di-cache dari query sebelumnya
  • Konten dari layanan pencarian eksternal
  • Testing dan development

​
Contoh: Hasil pencarian langsung

from anthropic import Anthropic
from anthropic.types.beta import (
    BetaMessageParam,
    BetaTextBlockParam,
    BetaSearchResultBlockParam
)

client = Anthropic()

# Berikan hasil pencarian langsung dalam pesan pengguna
response = client.beta.messages.create(
    model="claude-opus-4-20250514",
    max_tokens=1024,
    betas=["search-results-2025-06-09"],
    messages=[
        BetaMessageParam(
            role="user",
            content=[
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/api-reference",
                    title="Referensi API - Autentikasi",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Semua permintaan API harus menyertakan kunci API dalam header Authorization. Kunci dapat dibuat dari dashboard. Batas rate: 1000 permintaan per jam untuk tier standar, 10000 untuk premium."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaSearchResultBlockParam(
                    type="search_result",
                    source="https://docs.company.com/quickstart",
                    title="Panduan Memulai",
                    content=[
                        BetaTextBlockParam(
                            type="text",
                            text="Untuk memulai: 1) Daftar akun, 2) Buat kunci API dari dashboard, 3) Install SDK kami menggunakan pip install company-sdk, 4) Inisialisasi client dengan kunci API Anda."
                        )
                    ],
                    citations={"enabled": True}
                ),
                BetaTextBlockParam(
                    type="text",
                    text="Berdasarkan hasil pencarian ini, bagaimana cara mengautentikasi permintaan API dan apa batas rate-nya?"
                )
            ]
        )
    ]
)

print(response.model_dump_json(indent=2))

​
Respons Claude dengan kutipan

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

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Untuk mengautentikasi permintaan API, Anda perlu menyertakan kunci API dalam header Authorization",
      "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 dalam header Authorization",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Anda dapat membuat kunci API dari dashboard Anda",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referensi API - Autentikasi",
          "cited_text": "Kunci dapat dibuat dari dashboard",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    },
    {
      "type": "text",
      "text": ". Batas rate adalah 1.000 permintaan per jam untuk tier standar dan 10.000 permintaan per jam untuk tier premium.",
      "citations": [
        {
          "type": "search_result_location",
          "source": "https://docs.company.com/api-reference",
          "title": "Referensi API - Autentikasi",
          "cited_text": "Batas rate: 1000 permintaan per jam untuk tier standar, 10000 untuk premium",
          "search_result_index": 0,
          "start_block_index": 0,
          "end_block_index": 0
        }
      ]
    }
  ]
}

​
Field kutipan

Setiap kutipan mencakup:

FieldTypeDeskripsi
typestringSelalu "search_result_location" untuk kutipan hasil pencarian
sourcestringSumber dari hasil pencarian asli
titlestring atau nullJudul dari hasil pencarian asli
cited_textstringTeks persis yang dikutip
search_result_indexintegerIndeks hasil pencarian (berbasis 0)
start_block_indexintegerPosisi awal dalam array konten
end_block_indexintegerPosisi akhir dalam array konten

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

​
Beberapa blok konten

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 Rate: API memungkinkan 1000 permintaan per jam per kunci."
    },
    {
      "type": "text",
      "text": "Penanganan Error: API mengembalikan kode status HTTP standar."
    }
  ]
}

Claude dapat mengutip blok spesifik menggunakan field start_block_index dan end_block_index.

​
Penggunaan lanjutan

​
Menggabungkan kedua metode

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

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

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

​
Menggabungkan dengan jenis konten lain

Kedua metode mendukung pencampuran hasil pencarian dengan konten lain:

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

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

​
Kontrol cache

Tambahkan kontrol cache untuk performa 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 mengatur 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 ketika menggunakan informasi dari hasil pencarian. Ini memungkinkan:

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

Jika field citations dihilangkan, kutipan dinonaktifkan secara default.

Kutipan bersifat semua-atau-tidak-sama-sekali: baik semua hasil pencarian dalam permintaan harus memiliki kutipan yang diaktifkan, atau semua harus dinonaktifkan. Mencampur hasil pencarian dengan pengaturan kutipan yang berbeda akan menghasilkan error. Jika Anda perlu menonaktifkan kutipan untuk beberapa sumber, Anda harus menonaktifkannya untuk semua hasil pencarian dalam permintaan tersebut.

​
Praktik terbaik

​
Untuk pencarian berbasis tool (Metode 1)

  • Konten dinamis: Gunakan untuk pencarian real-time dan aplikasi RAG dinamis
  • Penanganan error: 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 sebelumnya: Gunakan ketika Anda sudah memiliki hasil pencarian
  • Pemrosesan batch: Ideal untuk memproses beberapa hasil pencarian sekaligus
  • Testing: 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 yang deskriptif
    • Pecah konten panjang menjadi blok teks yang logis

  2. Pertahankan konsistensi

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

  3. Tangani error dengan baik

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

​
Keterbatasan

  • Blok konten hasil pencarian hanya tersedia dengan header beta
  • Hanya konten teks yang didukung dalam hasil pencarian (tidak ada gambar atau media lain)
  • Array content harus berisi setidaknya satu blok teks