Menggunakan agen kustom

Sebelum memulai

Tutorial ini mengasumsikan bahwa Anda telah membaca dan mengikuti petunjuk di:

Mendapatkan instance agen

Untuk mengkueri agen, Anda harus memiliki instance agen terlebih dahulu. Anda dapat membuat instance baru atau mendapatkan instance yang ada dari agen.

Untuk mendapatkan agen yang sesuai dengan ID resource tertentu:

Agent Platform SDK

Jalankan kode berikut:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

agent = client.agent_engines.get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

print(agent)

di mana

permintaan

Jalankan kode berikut:

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
)

REST 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

Saat menggunakan Agent Platform SDK untuk Python, objek agent sesuai dengan class AgentEngine yang berisi hal berikut:

Bagian ini mengasumsikan bahwa Anda memiliki instance, yang diberi nama agent.

Mencantumkan operasi yang didukung

Saat mengembangkan agen secara lokal, Anda memiliki akses dan pengetahuan tentang operasi yang didukungnya. Untuk menggunakan agen yang di-deploy, Anda dapat menghitung operasi yang didukungnya:

Agent Platform SDK

Jalankan kode berikut:

print(agent.operation_schemas())

permintaan

Jalankan kode berikut:

import json

json.loads(response.content).get("spec").get("classMethods")

REST

Direpresentasikan dalam spec.class_methods dari respons terhadap permintaan curl.

Skema untuk setiap operasi adalah kamus yang mendokumentasikan informasi metode untuk agen yang dapat Anda panggil. Kumpulan operasi yang didukung bergantung pada framework yang Anda gunakan untuk mengembangkan agen:

Sebagai contoh, berikut adalah skema untuk operasi query dari LangchainAgent:

{'api_mode': '',
 'name': 'query',
 'description': """Queries the Agent with the given input and config.
    Args:
        input (Union[str, Mapping[str, Any]]):
            Required. The input to be passed to the Agent.
        config (langchain_core.runnables.RunnableConfig):
            Optional. The config (if any) to be used for invoking the Agent.
    Returns:
        The output of querying the Agent with the given input and config.
""",            '        ',
 'parameters': {'$defs': {'RunnableConfig': {'description': 'Configuration for a Runnable.',
                                             'properties': {'configurable': {...},
                                                            'run_id': {...},
                                                            'run_name': {...},
                                                            ...},
                                             'type': 'object'}},
                'properties': {'config': {'nullable': True},
                               'input': {'anyOf': [{'type': 'string'}, {'type': 'object'}]}},
                'required': ['input'],
                'type': 'object'}}

di mana

  • name adalah nama operasi (yaitu agent.query untuk operasi bernama query).
  • api_mode adalah mode API operasi ("" untuk sinkron, "stream" untuk streaming).
  • description adalah deskripsi operasi berdasarkan docstring metode.
  • parameters adalah skema argumen input dalam format skema OpenAPI.

Mengkueri agen menggunakan operasi yang didukung

Untuk agen kustom, Anda dapat menggunakan salah satu operasi kueri atau streaming berikut yang Anda tentukan saat mengembangkan agen:

Perhatikan bahwa framework tertentu hanya mendukung operasi kueri atau streaming tertentu:

Framework Operasi kueri yang didukung
Agent Development Kit async_stream_query
LangChain query, stream_query
LangGraph query, stream_query
AG2 query
LlamaIndex query

Mengkueri agen

Kueri agen menggunakan operasi query:

Agent Platform SDK 

agent.query(input="What is the exchange rate from US dollars to Swedish Krona today?")

permintaan 

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

requests.post(
    f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query",
    headers={
        "Content-Type": "application/json; charset=utf-8",
        "Authorization": f"Bearer {get_identity_token()}",
    },
    data=json.dumps({
        "class_method": "query",
        "input": {
            "input": "What is the exchange rate from US dollars to Swedish Krona today?"
        }
    })
)

REST 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:query -d '{
  "class_method": "query",
  "input": {
    "input": "What is the exchange rate from US dollars to Swedish Krona today?"
  }
}'

Respons kueri adalah string yang mirip dengan output pengujian aplikasi lokal:

{"input": "What is the exchange rate from US dollars to Swedish Krona today?",
 # ...
 "output": "For 1 US dollar you will get 10.7345 Swedish Krona."}

Men-streaming respons dari agen

Streaming respons dari agen menggunakan operasi stream_query:

Agent Platform SDK 

agent = agent_engines.get("projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

for response in agent.stream_query(
    input="What is the exchange rate from US dollars to Swedish Krona today?"
):
    print(response)

permintaan 

from google import auth as google_auth
from google.auth.transport import requests as google_requests
import requests

def get_identity_token():
    credentials, _ = google_auth.default()
    auth_request = google_requests.Request()
    credentials.refresh(auth_request)
    return credentials.token

requests.post(
    f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:streamQuery",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {get_identity_token()}",
    },
    data=json.dumps({
        "class_method": "stream_query",
        "input": {
            "input": "What is the exchange rate from US dollars to Swedish Krona today?"
        },
    }),
    stream=True,
)

REST 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:streamQuery?alt=sse -d '{
  "class_method": "stream_query",
  "input": {
    "input": "What is the exchange rate from US dollars to Swedish Krona today?"
  }
}'

Agent Platform men-streaming respons sebagai urutan objek yang dibuat secara berulang. Misalnya, kumpulan tiga respons mungkin terlihat seperti berikut:

{'actions': [{'tool': 'get_exchange_rate', ...}]}  # first response
{'steps': [{'action': {'tool': 'get_exchange_rate', ...}}]}  # second response
{'output': 'The exchange rate is 11.0117 SEK per USD as of 2024-12-03.'}  # final response

Mengkueri agen secara asinkron

Jika Anda menentukan operasi async_query saat membuat agen, ada dukungan untuk kueri asinkron sisi klien agen di Agent Platform SDK untuk Python:

Agent Platform SDK untuk Python 

agent = agent_engines.get("projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

response = await agent.async_query(
    input="What is the exchange rate from US dollars to Swedish Krona today?"
)
print(response)

Respons kueri adalah kamus yang sama dengan output pengujian lokal:

{"input": "What is the exchange rate from US dollars to Swedish Krona today?",
 # ...
 "output": "For 1 US dollar you will get 10.7345 Swedish Krona."}

Men-streaming respons dari agen secara asinkron

Jika Anda menentukan operasi async_stream_query saat membuat agen, Anda dapat men-streaming respons dari agen secara asinkron menggunakan salah satu operasinya (misalnya, async_stream_query):

Agent Platform SDK untuk Python 

agent = agent_engines.get("projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")

async for response in agent.async_stream_query(
    input="What is the exchange rate from US dollars to Swedish Krona today?"
):
    print(response)

Operasi async_stream_query memanggil endpoint streamQuery yang sama di balik layar dan men-streaming respons secara asinkron sebagai urutan objek yang dibuat secara berulang. Misalnya, kumpulan tiga respons mungkin terlihat seperti berikut:

{'actions': [{'tool': 'get_exchange_rate', ...}]}  # first response
{'steps': [{'action': {'tool': 'get_exchange_rate', ...}}]}  # second response
{'output': 'The exchange rate is 11.0117 SEK per USD as of 2024-12-03.'}  # final response

Respons harus sama dengan yang dihasilkan selama pengujian lokal.

Tugas kueri yang berjalan lama

Untuk kueri yang dapat memerlukan waktu lama untuk diselesaikan (hingga tujuh hari), Anda dapat menjalankannya sebagai tugas yang berjalan lama. Untuk mengetahui informasi selengkapnya, lihat Menggunakan agen ADK.

Memulai tugas kueri yang berjalan lama

Untuk memulai tugas kueri yang berjalan lama:

Agent Platform SDK untuk Python 

import vertexai

client = vertexai.Client(
    project="PROJECT_ID",
    location="LOCATION",
)

response = client.agent_engines.run_query_job(
    name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
    config={
        "query": '{ "input": {"product": "Google"} }',
        "output_gcs_uri": "gs://GCS_BUCKET_NAME/OUTPUT_FILE",
    },
)
print(response)

REST 

curl \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID:asyncQuery -d \
'{
  "input_gcs_uri": "gs://GCS_BUCKET_NAME/INPUT_FILE",
  "output_gcs_uri": "gs://GCS_BUCKET_NAME/OUTPUT_FILE"
}'

Memeriksa status tugas kueri yang berjalan lama

Untuk memeriksa status dan mengambil hasil tugas kueri yang berjalan lama:

Agent Platform SDK 

response = client.agent_engines.check_query_job(
    name="JOB_NAME",
    config={
        "retrieve_result": True,
    },
)
print(response)

Langkah berikutnya