Menggunakan agen kustom

Sebelum memulai

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

Mendapatkan instance agen

Untuk mengkueri agen, Anda memerlukan 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:

Vertex AI SDK untuk Python

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)

dengan

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 Vertex AI SDK untuk Python, objek agent sesuai dengan class AgentEngine yang berisi hal berikut:

  • agent.api_resource dengan informasi tentang agen yang di-deploy. Anda juga dapat memanggil agent.operation_schemas() untuk menampilkan daftar operasi yang didukung agen. Lihat Operasi yang didukung untuk mengetahui detailnya.
  • agent.api_client yang memungkinkan interaksi layanan sinkron
  • agent.async_api_client yang memungkinkan interaksi layanan asinkron

Bagian selanjutnya 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:

Vertex AI SDK untuk Python

Jalankan kode berikut:

print(agent.operation_schemas())

permintaan

Jalankan kode berikut:

import json

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

REST

Ditampilkan di 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'}}

dengan

  • 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.

Membuat kueri ke 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

Mengirim kueri ke agen

Buat kueri ke agen menggunakan operasi query:

Vertex AI SDK untuk Python 

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:

Vertex AI SDK untuk Python 

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?"
  }
}'

Vertex AI Agent Engine melakukan streaming respons sebagai urutan objek yang dibuat secara iteratif. 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 mengembangkan agen, ada dukungan untuk kueri asinkron sisi klien agen di Vertex AI SDK untuk Python:

Vertex AI 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 mengembangkan agen, Anda dapat melakukan streaming respons dari agen secara asinkron menggunakan salah satu operasinya (misalnya, async_stream_query):

Vertex AI 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 melakukan streaming respons secara asinkron sebagai urutan objek yang dihasilkan secara iteratif. Misalnya, serangkaian 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

Responsnya harus sama dengan yang dihasilkan selama pengujian lokal.

Langkah berikutnya