Strumenti OpenAPI e Integration Connectors

Puoi utilizzare le funzionalità di Agent Assist insieme ad API e origini dati esterne. Google Cloud fornisce strumenti OpenAPI e Integration Connectors per facilitare le integrazioni di Agent Assist.

Strumenti OpenAPI

OpenAPIOpenAPI consentono la connessione tra le funzionalità di Agent Assist e le API esterne. Questa connessione consente alle funzionalità di Assistente agente di leggere e scrivere informazioni da più origini. Per creare uno strumento OpenAPI, devi fornire uno schema OpenAPI che descriva le API esterne a cui vuoi connetterti.

Strumento Integration Connectors

Utilizza Integration Connectors per connetterti Google Cloud a una serie di origini dati. Gli strumenti del connettore consentono alle funzionalità di Agent Assist di utilizzare Integration Connectors per leggere e scrivere queste origini dati.

Prima di iniziare

Per configurare l'ambiente per creare strumenti OpenAPI e Integration Connectors, inserisci l'ID progetto e la regione, quindi esegui il seguente codice.

CLOUDSDK_CORE_PROJECT=YOUR_PROJECT_ID
REGION=YOUR_REGION
API_VERSION=v2beta1
API_ENDPOINT=https://${REGION}-dialogflow.googleapis.com/${API_VERSION}

function gcurl () {
        curl -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "X-Goog-User-Project: ${CLOUDSDK_CORE_PROJECT}" -H "Content-Type: application/json; charset=utf-8" "$@"
}

Crea uno strumento OpenAPI

Per utilizzare uno strumento OpenAPI, devi prima richiedere la sua creazione e salvare il nome della risorsa dello strumento.

Passaggio 1: richiedi la creazione dello strumento

Segui questi passaggi per richiedere la creazione di uno strumento OpenAPI.

Personalizza il codice come segue:
1. All'interno di un singolo progetto, utilizza un valore tool_key univoco tra tutti i tuoi strumenti.
2. Inserisci il tuo schema OpenAPI nel campo open_api_spec.text_schema.

Esegui il seguente codice personalizzato.

$ cat > create-tool-request.json << EOF
{
  "tool_key": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "display_name": "TOOL_DISPLAY_NAME",
  "open_api_spec": {
    "text_schema": "Your-Schema"
  }
}
EOF

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-tool-request.json | tee create-tool-response.json

In caso di esito positivo, l'API restituisce lo strumento appena creato, che contiene il nome della risorsa, come mostrato nell'esempio seguente.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "UNIQUE_KEY",
  "description": "TOOL_DESCRIPTION",
  "createTime": "2025-06-02T18:11:38.999174724Z",
  "updateTime": "2025-06-02T18:11:38.999174724Z",
  "displayName": "TOOL_DISPLAY_NAME",
  "openApiSpec": {
    "textSchema": "Your-Schema"
  }
}

Passaggio 2: salva il nome della risorsa dello strumento

Salva il nome della risorsa dello strumento in una variabile di ambiente per un utilizzo futuro. Di seguito è riportato un modello di esempio per la variabile di ambiente della risorsa dello strumento.

TOOL_RESOURCE=$(cat create-tool-response.json | jq .name | tr -d '"')

AI coach con uno strumento OpenAPI

Puoi utilizzare uno strumento OpenAPI con la funzionalità AI coach per accedere a informazioni aggiuntive dall'esterno di Google Cloud. Queste informazioni esterne possono essere utilizzate per generare suggerimenti che aiutano gli agenti del contact center.

Passaggio 1: crea un generatore

L'esempio seguente crea un generatore con la variabile di ambiente della risorsa dello strumento.

$ cat > create-generator-request.json << _EOF_
{"agent_coaching_context":{"instructions":[{"agent_action":"help customer by using the tool to find information from library of congress","condition":"The customer asks about library of congress","description":"agent coaching test","display_name":"Search for information"}],"overarching_guidance":"Help customer with questions"},"description":"prober-generate-suggestions-with-agent-coaching-generator","inference_parameter":{"max_output_tokens":256,"temperature":0},"tools":["${TOOL_RESOURCE}"],"trigger_event":"CUSTOMER_MESSAGE"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/generators -d @create-generator-request.json | tee create-generator-response.json

Dovresti ricevere una risposta simile al seguente esempio di generatore AI coach.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID",
  "description": "example-generator",
  "inferenceParameter": {
    "maxOutputTokens": 256,
    "temperature": 0
  },
  "triggerEvent": "CUSTOMER_MESSAGE",
  "createTime": "2025-06-02T18:30:51.021461728Z",
  "updateTime": "2025-06-02T18:30:51.021461728Z",
  "agentCoachingContext": {
    "instructions": [
      {
        "displayName": "Search for information",
        "condition": "The customer asks about library of congress",
        "agentAction": "help customer by using the tool to find information from library of congress"
      }
    ],
    "version": "1.5",
    "overarchingGuidance": "Help customer with questions"
  },
  "tools": [
    "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID"
  ]
}

Salva il nome della risorsa del generatore

Salvalo come variabile di ambiente per un utilizzo futuro, come nell'esempio seguente.

GENERATOR_RESOURCE=$(cat create-generator-response.json | jq .name | tr -d '"')

Passaggio 2: crea un profilo di conversazione

Esegui il seguente codice per creare un profilo di conversazione.

$ cat > create-conversation-profile-request.json << _EOF_
{"displayName":"prober-generate-suggestions-with-agent-coaching-generator","humanAgentAssistantConfig":{"humanAgentSuggestionConfig":{"generators":["${GENERATOR_RESOURCE}"]}}}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversationProfiles -d @create-conversation-profile-request.json | tee create-conversation-profile-response.json

Dovresti ricevere una risposta simile alla seguente.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
  "humanAgentAssistantConfig": {
    "humanAgentSuggestionConfig": {
      "generators": [
        "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
      ]
    }
  },
  "languageCode": "en-US",
  "createTime": "2025-06-02T18:40:39.940318Z",
  "updateTime": "2025-06-02T18:40:39.940318Z",
  "projectNumber": "${project_number}"
}

Salva il nome della risorsa del profilo di conversazione

Salva questo nome come variabile di ambiente, come nell'esempio seguente.

CONVERSATION_PROFILE_RESOURCE=$(cat create-conversation-profile-response.json | jq .name | tr -d '"')

Passaggio 3: crea una conversazione

Esegui il seguente codice per creare una conversazione.

$ cat > create-conversation-request.json << _EOF_
{"conversationProfile":"${CONVERSATION_PROFILE_RESOURCE}"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/conversations -d @create-conversation-request.json | tee create-conversation-response.json

Dovresti ricevere una risposta simile alla seguente.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID",
  "lifecycleState": "IN_PROGRESS",
  "conversationProfile": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
  "startTime": "2025-06-02T18:43:40.818123Z",
  "conversationStage": "HUMAN_ASSIST_STAGE",
  "source": "ONE_PLATFORM_API",
  "initialConversationProfile": {
    "name": "projects/Your-Project-ID/locations/Your-Region/conversationProfiles/Conversation-Profile-ID",
    "displayName": "prober-generate-suggestions-with-agent-coaching-generator",
    "humanAgentAssistantConfig": {
      "humanAgentSuggestionConfig": {
        "generators": [
          "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID"
        ]
      }
    },
    "languageCode": "en-US"
  },
  "projectNumber": "${project_number}",
  "initialGeneratorContexts": {
    "projects/Your-Project-ID/locations/Your-Region/generators/Generator-ID": {
      "generatorType": "AGENT_COACHING",
      "generatorVersion": "1.5"
    }
  }
}

Salva il nome della risorsa della conversazione

Salva questo nome come variabile di ambiente per un utilizzo futuro. La variabile deve avere il seguente formato.

CONVERSATION_RESOURCE=$(cat create-conversation-response.json | jq .name | tr -d '"')

Passaggio 4: crea un utente finale

Esegui il seguente codice per creare un utente finale.

$ cat > create-end-user-request.json << _EOF_
{"role":"END_USER"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-end-user-request.json | tee create-end-user-response.json

Dovresti ricevere una risposta simile alla seguente.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-ID/participants/End-User-Participant-ID",
  "role": "END_USER"
}

Salva il nome della risorsa dell'utente finale

Salva il nome della risorsa dell'utente finale come variabile di ambiente, come nell'esempio seguente.

END_USER_RESOURCE=$(cat create-end-user-response.json | jq .name | tr -d '"')

Passaggio 5: crea un agente umano

Esegui il seguente codice per creare un agente umano.

$ cat > create-human-agent-request.json << _EOF_
{"role":"HUMAN_AGENT"}
_EOF_

$ gcurl -X POST ${API_ENDPOINT}/${CONVERSATION_RESOURCE}/participants -d @create-human-agent-request.json | tee create-human-agent-response.json

Dovresti ricevere una risposta simile alla seguente.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/conversations/Conversation-IDHuman-Agent-Participant-ID",
  "role": "HUMAN_AGENT"
}

Salva il nome della risorsa dell'agente umano

Salva il nome della risorsa dell'agente umano come variabile di ambiente, come nell'esempio seguente.

HUMAN_AGENT_RESOURCE=$(cat create-human-agent-response.json | jq .name | tr -d '"')

Passaggio 6: invia testo all'AI coach

Esegui il seguente codice per inviare testo all'AI coach con il metodo AnalyzeContent.

cat > analyze-content-1-request.json << _EOF_
{"text_input":{"languageCode":"en-US","text":"Can you search library of congress for the latest trends"}}
_EOF_

gcurl -X POST "${API_ENDPOINT}/${END_USER_RESOURCE}:analyzeContent" -d @analyze-content-1-request.json | tee analyze-content-1-response.json

Passaggio 7: verifica la chiamata dello strumento

Esegui il seguente codice per verificare la chiamata dello strumento.

cat analyze-content-1-response.json| jq ".humanAgentSuggestionResults[0].generateSuggestionsResponse.generatorSuggestionAnswers[0].generatorSuggestion.toolCallInfo"

Dovresti ricevere una risposta simile alla seguente.

[
  {
    "toolCall": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
      "action": "search",
      "inputParameters": {
        "q": "latest trends",
        "fo": "json",
        "tool_description": "A generic search endpoint that might be available across various LoC APIs. The structure of the results will vary.\n",
        "at": "trending_content"
      },
      "createTime": "2025-06-02T18:56:53.882479179Z"
    },
    "toolCallResult": {
      "tool": "projects/Your-Project-ID/locations/Your-Region/tools/MjM0NTU3NDk2MTM5NTAwNzQ4OQ",
      "action": "search",
      "content": ""}]}",
      "createTime": "2025-06-02T18:56:54.289367086Z"
    }
  }
]

Passaggio 8: (facoltativo) elimina le risorse

Per eliminare le risorse create nei passaggi precedenti, esegui il seguente codice.

Profilo di conversazione

gcurl -X DELETE ${API_ENDPOINT}/${CONVERSATION_PROFILE_RESOURCE}

Generatore

gcurl -X DELETE ${API_ENDPOINT}/${GENERATOR_RESOURCE}

Strumento OpenAPI

gcurl -X DELETE ${API_ENDPOINT}/${TOOL_RESOURCE}

Crea uno strumento Integration Connectors

Puoi configurare Integration Connectors utilizzando la Google Cloud console. Segui questi passaggi per creare uno strumento Integration Connectors di Assistente agente basato su un connettore BigQuery.

Passaggio 1: crea uno strumento del connettore BigQuery

Prima di creare uno strumento Integration Connectors, vai alla Google Cloud console e crea un connettore BigQuery Integration Connectors.

Passaggio 2: richiedi la creazione dello strumento Integration Connectors

Esegui il seguente codice per richiedere la creazione di uno strumento. Per il campo connector_spec.name, utilizza il nome della risorsa del connettore BigQuery.

cat > create-connector-tool-request.json << _EOF_
{
  "tool_key": "order_tool",
  "description": "order bigquery connector tool",
  "display_name": "order bigquery connector tool",
  "connector_spec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/Your-Connector-ID",
    "actions": [
                             {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "LIST"
                               }
                             }, {
                               "entityOperation": {
                                 "entityId": "Orders",
                                 "operation": "GET"
                               }
                             }
                           ]
  }
}
_EOF_


gcurl -X POST ${API_ENDPOINT}/projects/${CLOUDSDK_CORE_PROJECT}/locations/${REGION}/tools -d @create-connector-tool-request.json | tee create-connector-tool-response.json

Dovresti ricevere una risposta simile alla seguente.

{
  "name": "projects/Your-Project-ID/locations/Your-Region/tools/Tool-ID",
  "toolKey": "order_tool",
  "description": "order bigquery connector tool",
  "createTime": "2025-06-03T19:29:55.896178942Z",
  "updateTime": "2025-06-03T19:29:55.896178942Z",
  "connectorSpec": {
    "name": "projects/Your-Project-ID/locations/Your-Region/connections/order-bigquery-connector",
    "actions": [
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "LIST"
        }
      },
      {
        "entityOperation": {
          "entityId": "Orders",
          "operation": "GET"
        }
      }
    ]
  },
  "displayName": "order bigquery connector tool"
}

Passaggi successivi

Per un elenco completo degli strumenti Integration Connectors supportati da Agent Assist, consulta l'elenco degli strumenti del connettore Dialogflow.

Strumenti OpenAPI e Integration Connectors Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.