Usar um agente

O código para consultar um agente é o mesmo, independentemente de ele estar sendo executado localmente ou implantado remotamente. Portanto, nesta página, o termo agent se refere a local_agent ou remote_agent de forma intercambiável. Como o conjunto de operações com suporte varia de acordo com o framework, fornecemos instruções de uso para modelos específicos de framework:

Framework Descrição
LangChain (link em inglês) É mais fácil de usar para casos de uso básicos devido às configurações e abstrações predefinidas.
LangGraph (em inglês) Abordagem baseada em gráfico para definir fluxos de trabalho, com recursos avançados de human-in-the-loop e de repetição/reprodução.
AG2 (anteriormente AutoGen) O AG2 oferece um framework de conversa entre vários agentes como uma abstração de alto nível para criar fluxos de trabalho de LLM.

Para agentes personalizados que não são baseados em um dos modelos específicos da estrutura, siga estas etapas:

  1. Autenticação do usuário.
  2. Receba uma instância do agente.
  3. Procure as operações compatíveis.
  4. Consultar o agente.
  5. (Se aplicável) Transmitir respostas do agente.

Etapa 1: autenticação do usuário

Siga as mesmas instruções para configurar seu ambiente.

Etapa 2: acessar uma instância de um agente

Para consultar um agente, primeiro você precisa de uma instância dele. É possível criar uma nova instância ou acessar uma instância atual de um agente.

Para encontrar o agente correspondente a um ID de recurso específico:

SDK da Vertex AI para Python

Execute o seguinte código:

from vertexai import agent_engines

agent = agent_engines.get(RESOURCE_ID)

Como alternativa, forneça o nome completo do recurso do agente:

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

solicitações

Execute o seguinte código:

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/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

O restante desta seção pressupõe que você tenha uma instância chamada agent.

Etapa 3: operações com suporte

Ao desenvolver o agente localmente, você tem acesso e conhecimento das operações compatíveis. Para usar um agente implantado, enumere as operações compatíveis:

SDK da Vertex AI para Python

Execute o seguinte código:

agent.operation_schemas()

solicitações

Execute o seguinte código:

import json

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

REST

Representado em spec.class_methods da resposta à solicitação do curl.

O esquema de cada operação é um dicionário que documenta as informações de um método do agente que você pode chamar. Confira a seguir um exemplo do esquema de operação para uma operação síncrona:

O comando a seguir fornece uma lista de esquemas no formato JSON que correspondem às operações do objeto remote_app:

agent.operation_schemas()

Como exemplo, confira abaixo o esquema da operação query de um 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'}}

em que

  • name é o nome da operação (por exemplo, agent.query para uma operação chamada query).
  • api_mode é o modo de API da operação ("" para síncrono, "stream" para streaming).
  • description é uma descrição da operação com base no docstring do método.
  • parameters é o esquema dos argumentos de entrada no formato de esquema da OpenAPI.

Etapa 4: consultar o agente

Para consultar o agente usando uma das operações com suporte (por exemplo, query):

SDK da Vertex AI para Python 

agent.query(input={"messages": [
    ("user", "What is the exchange rate from US dollars to Swedish currency?")
]})

solicitações 

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({"input": {
        "input": {"messages": [
            ("user", "What is the exchange rate from US dollars to Swedish currency?")
        ]},
    }})
)

REST 

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

A resposta da consulta é uma string semelhante à saída de um teste de aplicativo local:

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

Etapa 5: transmitir respostas do agente

Se aplicável, você pode transmitir uma resposta do agente usando uma das operações dele (por exemplo, stream_query):

SDK da Vertex AI para Python 

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

agent.stream_query(input={"messages": [
    ("user", "What is the exchange rate from US dollars to Swedish currency?")
]})

solicitações 

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({"input": {
        "input": {"messages": [
            ("user", "What is the exchange rate from US dollars to Swedish currency?")
        ]},
    }}),
    stream=True,
)

REST 

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

O mecanismo do agente transmite respostas como uma sequência de objetos gerados de forma iterativa. Por exemplo, um conjunto de três respostas pode ser parecido com este:

{'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

A seguir