Tutorial Framework Agen

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Memulai di notebook

Mulai menggunakan Framework Agen menggunakan Agen "Hello World" di notebook.

Contoh Agen

Untuk mempelajari contoh kode agen contoh, download file .zip dari folder Google Drive ini ke lingkungan pengembangan lokal Anda.

Di direktori contoh terdapat agen demo. Instal dependensi dalam file requirements.txt untuk agen demo tertentu:

pip install  -r samples/anthropic_demo/requirements.txt

Jalankan perintah berikut:

af web samples

af run samples/hello_world

Tutorial

Halaman ini menyediakan tutorial langkah demi langkah untuk tugas umum saat menggunakan Agent Framework. Pilih tutorial untuk memulai.

Tutorial: Mengintegrasikan Data Anda Sendiri ke dalam Agen

Tutorial ini membahas berbagai metode untuk memberikan data, pengetahuan, atau dokumen Anda sendiri kepada agen. Pendekatan terbaik bergantung pada ukuran dan jenis data, serta keseimbangan yang diinginkan antara latensi dan akurasi.

Memberikan data Anda sendiri

Ada beberapa cara untuk memberikan data / pengetahuan / dokumen Anda sendiri ke agen, berdasarkan ukuran data, jenis data, dan kompromi latensi/akurasi yang diinginkan.

Panduan berikut akan berisi informasi selengkapnya tentang setiap pendekatan.

Menyematkan data dalam petunjuk

Cara mudah untuk memberikan dokumen dalam jumlah kecil kepada agen adalah dengan menyematkannya dalam petunjuk.

PDF atau file teks lainnya dapat dikonversi menjadi teks biasa dan disematkan dalam petunjuk.

Pertimbangan

• Konten file akan dikirim ke model, sehingga semakin besar file, semakin tinggi latensi dan biayanya.

• Konten akan dikirim ke model untuk semua permintaan, terlepas dari apakah kueri pengguna tidak ada hubungannya dengan konten.

• Anda dapat menggunakan teks biasa atau format teks apa pun yang dapat dibaca, misalnya markdown untuk file Anda.

Risiko Keamanan

• Menyematkan konten dengan cara ini memiliki beberapa risiko keamanan, karena server dapat memperlakukan konten dokumen tersemat sebagai instruksinya sendiri.

• Risiko keamanan ini dapat dimitigasi hingga tingkat tertentu dengan menandai awal dan akhir konten tersemat secara jelas, seperti yang ditunjukkan dalam contoh di bawah.

• Karena risiko ini, jangan menyematkan konten yang tidak Anda percayai, misalnya konten buatan pengguna.

Contoh

Agar petunjuk dapat dibaca, pendekatan umum adalah memuat file dan menyisipkannya ke petunjuk menggunakan sintaksis f-string Python.

Perhatikan bahwa file ini menggunakan tag XML untuk memisahkan konten file dari instruksi lainnya. Anda juga dapat menggunakan cara lain untuk memisahkan selama hal tersebut jelas bagi model. Misalnya, tag seperti BEGIN_USER_GUIDE / END_USER_GUIDE.

def read_file(filename):
  file_path = os.path.join(os.path.dirname(__file__), filename)
  with open(file_path, 'r') as f:
    return f.read()

agent_framework_bot = Agent(
    # ...
    instruction=f"""You are an agent that answers user's questions about the Agent Framework.

You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)

Menggunakan RAG

Pembuatan yang dilengkapi dengan pengambilan adalah pola umum untuk melengkapi respons model dengan data Anda sendiri. Hal ini sangat berguna untuk data dalam jumlah besar, karena berfungsi dengan mengindeks data, dan hanya mengambil sebagian kecil data yang relevan dengan kueri.

Framework Agen menyediakan beberapa cara untuk berintegrasi dengan berbagai sistem RAG.

FilesRetrieval

FilesRetrieval akan mem-build penyimpanan vektor dalam memori saat Agen Anda dimulai, yang akan menambah latensi dan dibatasi pada memori dan performa lingkungan hosting API. Oleh karena itu, opsi ini hanya cocok untuk demo / prototipe, atau produksi dengan jumlah dokumen yang sangat kecil.

FilesRetrieval dibuat berdasarkan LlamaIndex. Anda perlu menyiapkannya dengan mengikuti Dokumentasi LlamaIndex.

Setelah disiapkan, Anda dapat menempatkan dokumen dalam folder dan membuat alat pengambilan seperti ini:

company_policies_retrieval = FilesRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)

root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

VertexRagRetrieval

Vertex RAG Engine adalah layanan terkelola sepenuhnya yang menangani penyerapan, transformasi, penyematan, pengindeksan, dan pengambilan data.

Untuk menggunakannya, ikuti Panduan Mulai Cepat untuk menyiapkan korpus dan menyerap dokumen. Kemudian, tambahkan alat tersebut ke agen Anda.

company_policies_retrieval = VertexRagRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

Menggunakan Google Penelusuran

Dengan menggunakan Google Penelusuran, agen Anda akan dapat mengakses pengetahuan dunia nyata secara real time, dan menggunakan Google Penelusuran untuk meneliti pertanyaan.

Catatan

• Perujukan (Grounding) dengan Google Penelusuran dapat dikenai biaya tambahan.
• Untuk Gemini 1.5:
  • Saat menambahkan alat Google Penelusuran ke agen, Anda tidak dapat memiliki alat lain untuk agen tersebut.
  • Alat Google Penelusuran selalu dijalankan, terlepas dari apakah kueri memerlukan Google Penelusuran atau tidak.
• Untuk Gemini 2.0 dan yang lebih baru:
  • Anda dapat memiliki alat lain saat menggunakan alat Google Penelusuran.
  • Alat Google Penelusuran hanya dijalankan jika model menganggapnya perlu.
• Model pihak ketiga tidak mendukung alat Google Penelusuran.
• Untuk menggunakan alat Google Penelusuran, Anda harus mengikuti panduan di Menggunakan Saran Google Penelusuran, termasuk selalu menampilkan banner untuk menampilkan kueri Google Penelusuran terkait. UI Developer kami juga mengikuti aturan ini.

Contoh

Mengaktifkan alat Google Penelusuran sangat mudah, cukup tambahkan google_search ke daftar alat Anda.

from agents.tools import google_search

root_agent = Agent(
    # ...
    tools=[google_search],
)

Tutorial: Mengevaluasi Performa Agen

Mengevaluasi agen Anda sangatlah penting untuk memastikan agen tersebut berperforma seperti yang diharapkan dan memenuhi standar kualitas Anda. Framework Agen menyediakan beberapa cara untuk mengevaluasi performa agen menggunakan file pengujian dan kriteria evaluasi.

Cara Kerja Evaluasi

Setiap file pengujian berisi daftar kueri, lintasan alat yang diharapkan, dan respons referensi. File pengujian dapat diatur ke dalam folder. Secara opsional, folder dapat menyertakan file test_config.json yang menentukan kriteria evaluasi.

Contoh File Pengujian

File pengujian berisi sesi dengan kueri, penggunaan alat yang diharapkan, dan respons referensi. Berikut ini contohnya:

[
  {
    "query": "hi",
    "expected_tool_use": [],
    "reference": "Hello! What can I do for you?\n"
  },
  {
    "query": "roll a die for me",
    "expected_tool_use": [
      {
        "tool_name": "roll_die",
        "tool_input": {
          "sides": 6
        }
      }
    ]
  },
  {
    "query": "what's the time now?",
    "expected_tool_use": [],
    "reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
  }
]

Kriteria Evaluasi

Kriteria evaluasi di test_config.json menentukan cara performa agen akan diukur:

• tool_trajectory_avg_score: Mengevaluasi lintasan alat.
• response_match_score: Mengevaluasi respons.

Jika tidak ada kriteria evaluasi yang diberikan, konfigurasi default akan diterapkan.

Contoh Kriteria Evaluasi (test_config.json)

Berikut adalah contoh file test_config.json yang menentukan kriteria penilaian kustom:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}

• tool_trajectory_avg_score: Tetapkan ke 1,0, yang berarti penggunaan lintasan alat yang sempurna diharapkan.
• response_match_score: Tetapkan ke 0,8, yang memungkinkan margin error kecil dalam respons agen.

Cara Menjalankan Evaluasi

1. af web - Menjalankan Evaluasi melalui UI Web

Anda dapat mengevaluasi agen secara interaktif menggunakan UI berbasis web kami.

Langkah-langkah:

1. Mulai server web dengan menjalankan: bash af web
2. Di antarmuka web:
   • Pilih agen.
   • Klik "Simpan sesi sebagai file pengujian" untuk menyimpan sesi sebagai file pengujian.
   • Klik "Jalankan file pengujian" untuk menampilkan pop-up dengan file pengujian di folder agen.

File Pengujian:

File pengujian disimpan di folder yang sama dengan agen. Anda dapat memperbarui atau menambahkan file pengujian secara manual sesuai kebutuhan.

2. af test - Menjalankan Pengujian melalui Command Line

Anda dapat menjalankan semua file pengujian di folder yang ditentukan menggunakan perintah af test. Folder harus berisi definisi agen dan file pengujian.

Contoh:

af test samples/agent_folder

Perintah ini akan menemukan dan menjalankan semua file pengujian (*.test.json) di folder yang ditentukan.

3. pytest - Menjalankan Pengujian Secara Terprogram

Anda juga dapat menggunakan pytest untuk menjalankan file pengujian sebagai bagian dari pengujian integrasi.

Contoh Perintah:

pytest tests/integrations/

Contoh Kode Pengujian:

Berikut adalah contoh kasus pengujian pytest yang menjalankan satu file pengujian:

def test_with_single_test_file():
    """Test the agent's basic ability via a session file."""
    AgentEvaluator.evaluate(
        "tests.integration.fixture.home_automation_agent",
        "tests/integration/fixture/home_automation_agent/simple_test.test.json",
    )

Pendekatan ini memungkinkan Anda mengintegrasikan evaluasi agen ke dalam pipeline CI/CD atau rangkaian pengujian yang lebih besar.