18 Informazioni sugli strumenti agente

Oracle AI Data Platform Workbench supporta modelli di strumenti che possono essere configurati per accedere ai dati e adattarsi ai casi d'uso.

Gli agenti supportano configurazioni costituite da un singolo agente che può interfacciarsi con uno o più strumenti. AI Data Platform Workbench offre tre modelli di strumenti che possono essere configurati per l'uso tramite flussi visivi o codice:

• Codice personalizzato: lo strumento Codice personalizzato consente agli sviluppatori AI di implementare il proprio strumento utilizzando Python. Gli sviluppatori raggruppano il proprio strumento in un file ZIP, lo caricano nell'area di lavoro e lo configurano come nodo nell'agente. Gli strumenti di codice personalizzato sono destinati ai casi in cui gli strumenti integrati non forniscono l'integrazione di cui hanno bisogno.
• Richiesta HTTP: gli strumenti di richiesta HTTP consentono agli sviluppatori di utilizzare le chiamate API REST supportate nei propri agenti, utilizzando le API del workbench AI Data Platform e le funzioni che forniscono. Gli agenti possono utilizzare le API REST per creare oggetti dell'area di lavoro, controllare i dettagli, estrarre elenchi o modificare oggetti esistenti. Per un elenco completo delle API disponibili, vedere API REST per Oracle AI Data Platform Workbench.
• Prompt: lo strumento prompt consente allo sviluppatore AI di definire un prompt parametrizzato che può essere emesso a un LLM a propria scelta. I casi d'uso comuni per uno strumento di prompt includono le attività di redazione delle e-mail, le attività di traduzione, la conversione dello stile, il messaggio di commit git e le spiegazioni del codice.
• RAG: lo strumento RAG consente agli agenti di estrarre informazioni esterne rilevanti prima di generare una risposta. In AI Data Platform Workbench, lo strumento RAG esegue una query su una knowledge base (26ai Vector Search) e recupera chunk di documenti semanticamente pertinenti. Questi chunk vengono quindi passati all'agente per la generazione della risposta.
• SQL: lo strumento SQL consente agli agenti di eseguire query SQL su origini dati strutturate registrate tramite cataloghi esterni, come Oracle Autonomous AI Lakehouse, Oracle Autonomous AI Transaction Processing o Oracle Autonomous AI Database. Lo strumento è destinato agli scenari in cui le query SQL sono predefinite e possono essere parametrizzate. L'obiettivo è consentire a un agente di assegnare valori ai parametri. Questo strumento non è uno strumento NL2SQL che genera una query SQL basata su un prompt del linguaggio naturale.

  Nota

  Lo strumento SQL esegue solo query sui dati in un catalogo esterno. Non supporta i dati memorizzati in un catalogo standard.

Strumenti flusso agente tramite flusso visivo

Quando si aggiungono strumenti agli agenti tramite il flusso visivo, è possibile trovare strumenti in Modelli di strumenti nell'agente. Per aggiungere uno strumento all'agente, trascinarlo e rilasciarlo nello sfondo del flusso visivo. Dopo aver trascinato il nodo dello strumento sullo sfondo, il nodo si connette automaticamente all'agente.

Ogni strumento può essere configurato nella scheda Parametri ed essere testato indipendentemente dall'agente facendo clic sulla scheda Test.

Nota

È necessario collegare una computazione AI al proprio agente prima di poter eseguire il test di uno strumento di sistema. Se non è collegata alcuna computazione, la scheda Test viene disabilitata.

Strumenti agente tramite codice LangGraph

È possibile aggiungere strumenti agli agenti codificati LangGraph tramite un'istanza della classe AIDPToolConf().

from aidputils.agents.toolkit.configs import AIDPToolConf
aidp_tool =  AIDPToolConf(name, description, tool_class, conf, params)

I parametri rispecchiano l'esperienza del flusso visivo degli strumenti. Per ogni strumento, è necessario fornire:

• Nome: un nome descrittivo per aiutare gli utenti e l'LLM a comprendere lo scopo dello strumento.
• Descrizione: un riepilogo completo che fornisce informazioni sufficienti per gli utenti e gli LLM per capire cosa fa lo strumento.
• tool_class: tipo di strumento supportato, PromptTool, SQLTool, RAGTool, HTTPTool e MCPTool.
• conf: configurazione dello strumento. Queste informazioni sono nascoste al LLM.
• param: i parametri esposti all'LLM.

Strumento personalizzato

Lo strumento Codice personalizzato consente agli sviluppatori di agenti di estendere AI Data Platform con il proprio codice Python.

L'implementazione dello strumento viene impacchettata come file ZIP, caricata nell'area di lavoro e configurata come nodo dello strumento Codice personalizzato nell'agente. L'agente chiama il codice come strumento, con i parametri forniti dall'LLM in fase di esecuzione.

Lo strumento Codice personalizzato è destinato ai casi in cui gli strumenti incorporati (HTTP, SQL, RAG, MCP) non coprono l'integrazione di cui hai bisogno, ad esempio quando devi eseguire il calcolo locale, analizzare un formato specifico del dominio o comporre più passaggi che dovrebbero apparire all'agente come una singola chiamata di strumento.

AI Data Platform Workbench ha i seguenti limiti quando si carica un file ZIP con codice Python per lo strumento di codice personalizzato:

Vincolo	Limite
Dimensione massima ZIP	10 MB
Dimensione massima del file all'interno dello ZIP	10 MB per file
Dimensione massima totale non compressa	500 MB
Attraversamento percorso	Bloccato (../ rifiutato)

Nota

Gli strumenti di codice personalizzato vengono eseguiti sulla computazione AI collegata al tuo agente. Il codice ha accesso all'ambiente di calcolo e all'accesso di rete in uscita in base alla configurazione di rete dell'area di lavoro. Carica codice solo da fonti attendibili.

Parametri strumento codice personalizzato

Nella scheda Parametri è possibile configurare le impostazioni statiche per ogni classe di strumenti nel pacchetto. L'elenco a discesa Classe strumento consente di passare dagli strumenti trovati nel pacchetto.

La scheda Parametri strumento codice personalizzato include le sezioni riportate di seguito.

• Classe strumento: selezionare la classe strumento da configurare. L'elenco a discesa viene popolato dalle classi registrate in tool_implementation.py.
• Descrizione: una descrizione chiara e concisa delle operazioni eseguite dallo strumento. La descrizione viene fornita all'agente e aiuta l'LLM a decidere quando chiamare lo strumento. La descrizione predefinita viene letta da tool_config.json e può essere sostituita qui.
• Configurazione: le impostazioni statiche necessarie per lo strumento in fase di esecuzione. Queste sono le chiavi definite nell'oggetto conf di tool_config.json. Gli esempi includono timeout, base_dir, max_output_lines e riferimenti alle credenziali. I valori di configurazione supportano i riferimenti ai parametri di runtime {{variable}}. Le variabili di sessione non vengono attualmente sostituite nella configurazione dello strumento personalizzato; se è necessario un valore di sessione, passarlo come parametro di runtime dall'agente.
• Definizione dello strumento AI: lo schema esposto all'agente, inclusi il nome dello strumento, la descrizione e i parametri di runtime che l'agente può passare. Lo schema viene visualizzato automaticamente dall'array di schemi in tool_config.json.

Creazione strumenti codice personalizzato

Un pacchetto di strumenti Codice personalizzato è un file ZIP con la seguente struttura:

my_tool.zip 
├── tool_implementation.py    # Required. Contains the tool class(es). 
├── tool_config.json          # Required. Tool metadata and schema. 
├── requirements.txt          # Optional. Python dependencies. 
├── utils/                    # Optional. Helper modules. 
│   ├── __init__.py 
│   └── helpers.py 
├── config/                   # Optional. Static configuration files. 
│   └── settings.yaml 
└── wheels/                   # Optional. Bundled wheel files for offline install. 
    └── humanize-4.15.0-py3-none-any.whl 

tool_implementazione.py

Ogni classe di strumenti estende CustomToolBase ed è decorata con @BaseTool.register. La classe deve implementare il metodo di classe _execute_tool, che riceve la configurazione dello strumento, i parametri di runtime dall'agente e le variabili di contesto del sistema, e restituisce un valore, come dett, str o list.

Di seguito è riportato un modello di esempio vuoto di tool_implementation.py.

"""Custom Code tool implementation.""" 
from aidputils.agents.tools.custom_tools.base import CustomToolBase 
 
 
@BaseTool.register 
class MyTool(CustomToolBase): 
    """Brief description of what the tool does.""" 
 
    @classmethod 
    def _validate_config(cls, conf, runtime_params, **context_vars): 
        """Optional. Validate configuration before execution. 
        Raise ValueError to abort the call. 
        """ 
        # Example: require an api_key in the tool configuration 
        if not conf.get("conf", {}).get("api_key"): 
            raise ValueError("api_key is required") 
 
    @classmethod 
    def _execute_tool(cls, conf, runtime_params, **context_vars): 
        """Required. Implement the tool logic. 
 
        Args: 
            conf: the AIDPToolConf dict. User configuration values 
                live under conf["conf"] when the tool is invoked from 
                a deployed agent. During a Test run the tool may 
                receive a flat conf dict; the Developer Toolkit example 
                below uses a small _get_cfg helper that tolerates both 
                shapes. 
            runtime_params: the runtime parameters passed by the 
                agent at invocation time. 
            context_vars: system context (such as datalake_id). 
 
        Returns: 
            Any value (dict, str, list, ...). It will be wrapped into 
            the MCP response by the framework. 
 
            To signal a failure, raise an exception: 
              - ValueError -> INVALID_CONFIG 
              - any other exception -> TOOL_EXECUTION_ERROR 
            Do NOT return {"error": "..."}; the framework wraps a 
            successful return in {"response": ..., "success": True}, 
            so a returned error dict is treated as a normal payload 
            and the agent will not see it as a failure. 
        """ 
        tool_conf = conf.get("conf", conf) 
        param_value = runtime_params.get("my_param", "") 
        # Tool logic here 
        return {"output": f"Processed: {param_value}"} 
 
    @classmethod 
    def _transform_response(cls, response): 
        """Optional. Transform the response before MCP formatting.""" 
        return response

tool_config.json

Il file tool_config.json descrive gli strumenti del package, ovvero il nome visualizzato, la descrizione, la versione, lo schema dei parametri di runtime e i valori di configurazione predefiniti. Ogni strumento registrato in tool_implementation.py deve avere una voce corrispondente nell'array tools.

Di seguito è riportato un modello di esempio vuoto di tool_config.json.

{
   "displayName": "My Tool Package",
   "description": "Brief description of the tool package.",
   "tools": [
     {
       "toolClassName": "MyTool",
       "displayName": "My Tool",
       "description": "Clear description of when the agent should call this tool.",
       "version": "1.0.0",
       "schema": [
         {
           "name": "my_param",
           "type": "string",
           "description": "What this parameter is for."
         }
       ],
       "conf": {
         "timeout": 30
       }
     }
   ]
 }

Tipi di campo schema

La scheda Parametri nel visual builder accetta stringhe, numeri e valori booleani. Il runtime accetta un set più ampio durante la creazione manuale di tool_config.json: int, integer, float, double, number, numeric, bytes, list, array, sequence, dett, map, mapping, set, tuple, none, null, plus generic forms like list[int]. Questi tipi più ampi sono utilizzabili da JSON, ma non sono esposti nell'elenco a discesa dell'interfaccia utente.

requisiti.txt

Il file requirements.txt elenca le dipendenze Python necessarie per lo strumento. È supportata la sintassi pip standard, inclusi gli identificatori di versione e i commenti. Il file è opzionale: se lo strumento utilizza solo la libreria standard Python o i pacchetti preinstallati, non è necessario disporre di un file requirements.txt.

Di seguito è riportato un esempio vuoto di requirements.txt:

# List third-party dependencies one per line. 
# Examples: 
# humanize>=4.0 
# python-dateutil>=2.8,<3.0 
# beautifulsoup4==4.12.3 

AI Data Platform Workbench filtra le dipendenze in requirements.txt prima di installarle nella computazione AI, per evitare conflitti di runtime con la piattaforma stessa. Di seguito sono riportate le regole di filtro.

Categoria	Esempio	Azione
Pacchetti piattaforma	langgraph, langchain-core, langchain-oci, langchain_mcp_adapters, pyyaml	Eliminato (interruzione del runtime dell'agente).
Pacchetti preinstallati	oci, richieste, request-toolbelt, websockets, crittografia, certificfi, pyopenssl, urllib3, pydantic, pydantic-core, pydantic-settings, numpy, oracledb, sqlalchemy, aiohttp, httpx, httpx-sse, anyio, jsonschema, orjson	Saltato (già disponibile, non è necessario dichiararlo).
Installazioni URL o VCS	git+https://..., -e ./local_pkg	Bloccato (sicurezza).
Tutto il altro	umanizzare, beautifulsoup4, jmespath	Installato.

Nota

Le dipendenze dichiarate in requirements.txt vengono installate durante la distribuzione completa dell'agente. Le dipendenze non vengono installate durante una singola esecuzione di test dal pannello di configurazione. Se il tuo strumento dipende da pacchetti di terze parti, distribuisci prima l'agente e poi esercita lo strumento dal Playground.

Per gli strumenti che hanno bisogno di dipendenze che non sono preinstallate e dove l'installazione deterministica e offline è importante, è possibile raggruppare file .whl all'interno di una directory di ruote / alla radice dello ZIP. La piattaforma si installa prima dalla directory delle ruote locali e torna all'indice del pacchetto solo se necessario. Questo è l'approccio consigliato per gli strumenti di produzione.

Ruote per installazione offline

pip download \
  --dest wheels/ \
  --platform manylinux_2_28_x86_64 \
  --python-version 3.11 \
  --only-binary=:all: \
  -r requirements.txt

Ganci ciclo di vita strumento

Gli strumenti di codice personalizzato supportano tre metodi del ciclo di vita. È necessario solo _execute_tool.

Metodo	Quando chiamato	Scopo
_convalida_config	Prima di _execute_tool	Convalida la configurazione. Genera ValueError per interrompere la chiamata prima che venga eseguita.
_strumento esecuzione	Su ogni richiamo strumento	Obbligatoria. Implementa il comportamento dello strumento. Restituisce qualsiasi valore (dict, str, list) e genera un'eccezione per segnalare un errore (ValueError → INVALID_CONFIG, qualsiasi altra eccezione → TOOL_EXECUTION_ERROR). Non utilizzare un {"error" restituito: "..."} dittatura in quanto viene considerato come un normale payload.
_transform_response	Dopo _execute_tool	Trasformare la risposta prima che venga sottoposta a wrapping in formato MCP e restituita all'agente.
temp_prompt	stringa	Modello prompt utilizzato dal LLM, con variabili in formato {{variable}} per l'inserimento dinamico

Valori di configurazione e parametri runtime

Gli strumenti di codice personalizzato hanno due fonti di input distinte che sono facili da confondere. I valori di configurazione provengono dalla sezione Configurazione della scheda Parametri e vengono incorporati nello strumento quando l'agente viene distribuito. I parametri di runtime provengono dall'agente al momento del richiamo e sono diversi a ogni chiamata.

• I valori di configurazione sono accessibili tramite conf.get("conf", conf). Utilizzali per gli elementi che non cambiano tra le chiamate: URL di base, riferimenti alle credenziali, timeout, limiti di output.
• I parametri di runtime sono accessibili tramite runtime_params.get("nome"). Utilizzarli per i valori che l'agente decide effettivamente in fase di chiamata, ovvero la query, il percorso del file e il corpo della richiesta.

Nota

I valori di configurazione possono passare attraverso la sostituzione del modello e possono arrivare come stringhe anche quando sono stati definiti come numeri. Costringere sempre i valori di configurazione numerici in modo difensivo, ad esempio int(tool_conf.get("timeout", 30)).

Strumenti multipli per pacchetto

Un singolo ZIP può contenere più classi di strumenti. Ogni classe registrata con @CustomToolBase.register diventa uno strumento separato nell'agente. Il pannello Strumenti della scheda Pacchetto elenca tutti gli strumenti trovati e consente di abilitarli in modo indipendente. Ogni strumento viene configurato separatamente nella scheda Parametri tramite l'elenco a discesa Classe strumento.

Strumento di codice tramite codice LangGraph

Dal generatore di codice, uno strumento Codice personalizzato viene registrato attraverso la libreria helppUtils Python facendo riferimento al pacchetto caricato e selezionando una delle sue classi di strumenti.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
 from aidputils.agents.toolkit.configs import AIDPToolConf
 
hello_tool_conf = AIDPToolConf(
     name="hello_tool",
     description="Returns a hello world greeting.",
     tool_class="HelloTool",  # the class registered with @BaseTool.register
     conf={},                  # values from tool_config.json "conf"; supports {{variable}} substitution
     params=[
         {"name": "name", "type": "string",
          "description": "Name to greet."}
     ],
 )
 
hello_tool = create_langgraph_tool(hello_tool_conf.model_dump())

tool_class deve essere il nome esatto della classe registrato tramite @BaseTool.register in tool_implementation.py. Il framework ricerca la classe in BaseTool.tool_class_registry[tool_class]. conf rispecchia l'oggetto conf della voce corrispondente in tool_config.json.

Nota

Non inserire package_path o tool_class_name all'interno di conf perché non vengono utilizzati.

Strumenti codice personalizzato agente test

La scheda Test consente di eseguire lo strumento senza eseguire l'agente completo. Fornire i valori per i parametri di runtime e le variabili di sessione a cui viene fatto riferimento nella configurazione, quindi fare clic su Esegui per richiamare lo strumento e visualizzare la risposta.

Nota

Se lo strumento dipende da pacchetti di terze parti dichiarati in requirements.txt, le dipendenze vengono installate durante la distribuzione completa dell'agente, non durante una singola esecuzione di test. Per eseguire il test del codice che dipende da pacchetti aggiuntivi, distribuire prima l'agente e quindi richiamare lo strumento da Playground.

Aggiungere uno strumento personalizzato a un agente

Puoi aggiungere uno strumento personalizzato AI tuoi agenti per consentire di utilizzare il tuo codice Python per estendere AI Data Platform.

Nota

Prima di aggiungere uno strumento di codice personalizzato, è necessario collegare un'elaborazione AI al tuo agente. La computazione AI è necessaria per installare le dipendenze ed eseguire lo strumento.

1. Passare all'agente.
2. Dai modelli di strumento, trascinare e rilasciare uno strumento personalizzato sullo sfondo.
3. Nella scheda Pacchetto fare clic per selezionare il file ZIP con il codice personalizzato oppure trascinarlo e rilasciarlo sullo schermo. Attendere il completamento del caricamento.
   
   

   

   
   
4. Rivedere l'elenco degli strumenti trovati nella sezione Strumenti della scheda Package. Ogni classe di strumenti presente in tool_implementation.py è elencata con il nome, la descrizione e la versione della classe.
   
   

   

   
   
5. Selezionare gli strumenti da abilitare. Gli strumenti disabilitati non sono esposti all'agente.
6. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento server MCP remoto

Gli sviluppatori del flusso agente possono connettere i propri flussi agente ai server MCP (Remote Model Context Protocol) utilizzando lo strumento Server MCP remoto.

Lo strumento MCP è disponibile sia nel visual builder che nelle esperienze di code builder. Nell'esperienza del generatore di codice, la connessione MCP può essere configurata tramite la libreria Python helppUtils. In questa sezione, ti guidiamo attraverso sia le esperienze di visual builder che di code builder.

Nota

Questa funzione supporta i server MCP con trasporti HTTP-streamable (server remoti). I server MCP locali di tipo stdio-transport non sono supportati.

Credenziali MCP nell'area di memorizzazione delle credenziali del workbench di Oracle AI Data Platform

Durante la configurazione del server MCP, è necessario selezionare se il server MCP remoto richiede Nessuna autenticazione o un token Bearer. Se il server MCP richiede un token di autenticazione, tale token deve essere aggiunto all'area di memorizzazione delle credenziali prima che possa essere utilizzato come riferimento dal server MCP.

Quando si crea una credenziale del server MCP, selezionare l'opzione Token segreto per Tipo di credenziale, quindi fornire la chiave identificativo, ad esempio una chiave API e il valore del token. Per ulteriori informazioni, vedere Crea credenziali (anteprima).

Nota

Una singola credenziale può contenere più chiavi.

I server MCP pubblicamente disponibili non richiedono un'autenticazione aggiuntiva. Ad esempio, la connessione a https://mcp.deepwiki.com/mcp potrebbe essere simile alla seguente:

Come esporre gli strumenti MCP all'agente

Una volta stabilita una connessione al server MCP remoto, è possibile avviare la configurazione degli strumenti ospitati sul server che si desidera esporre all'agente. Il pannello di configurazione del server MCP è mostrato di seguito nel caso del server MCP DeepWiki.

A sinistra, nella scheda Strumenti viene visualizzato un elenco di strumenti disponibili nel server MCP. È necessario aggiungere strumenti per esporli all'agente. È possibile eseguire questa operazione facendo clic sull'opzione Aggiungi tutto per esporre tutti gli strumenti contemporaneamente oppure facendo clic sull'opzione Aggiungi di ogni strumento singolarmente per selezionare un subset degli strumenti.

Nell'esempio seguente, abbiamo aggiunto due strumenti (read_wiki_structure, read_wiki_structure). Se è necessario rimuovere gli strumenti, fare clic su Rimuovi.

Il pannello destro della scheda Strumenti fornisce la documentazione su ogni strumento, incluso il nome dello strumento, la descrizione dello strumento e i parametri dello strumento. Nello screenshot seguente, mostro un esempio per lo strumento del server MCP GitHub add_comment_to_pending_review.

Oracle AI Data Platform Workbench fornisce un paio di controlli aggiuntivi su ogni strumento. È possibile nascondere i parametri all'agente e assegnarli a tali parametri. Ad esempio, in GitHub puoi scegliere per il tuo agente di commentare solo un repository predeterminato, ad esempio oracle-aidp-samples. A tale scopo, disabilitare il parametro repo e assegnare un valore predefinito nella casella di testo.

Nel campo Istruzioni strumento è inoltre possibile sostituire la descrizione dello strumento e fornire una descrizione alternativa con istruzioni aggiuntive. Per la maggior parte dei casi d'uso, si consiglia di adottare la descrizione fornita dal server MCP.

Strumento server MCP remoto tramite codice LangGraph

La libreria Python aidpUtils offre agli sviluppatori la possibilità di selezionare un server MCP remoto ed esporre un sottoinsieme dei suoi strumenti a un agente creato con LangGraph. Per il riferimento all'API helpputils, vedere API Aidp-utils per Oracle AI Data Platform Workbench.

È possibile creare una raccolta di strumenti consentiti creando un'istanza di build_structured_tools_from_allowed_mcp_tools:

from aidputils.agents.toolkit.tool_helper import build_structured_tools_from_allowed_mcp_tools

TOOLS = build_structured_tools_from_allowed_mcp_tools(
allowed_tools=<ALLOWED_MCP_TOOLS>, 
	server_name=<MCP_SERVER_NAME>, 
	endpoint=<MCP_ENDPOINT>, 
	transport="streamable_http", 
	auth=<MCP_AUTH>, 
	headers={} 
)

dove:

• <MCP_SERVER_NAME> è un nome visualizzato che si desidera assegnare al server MCP. Questa operazione viene utilizzata a scopo di documentazione e non è esposta all'agente.
• <MCP_ENDPOINT> è l'endpoint del server MCP (ad esempio, https://api.githubcopilot.com/mcp/)
• <MCP_AUTH> è un dizionario con chiave "authType". Questa chiave può assumere due valori: NO_AUTH o BEARER_TOKEN. Nel caso di BEARER_TOKEN, è prevista un'altra chiave: "token" con il valore del token bearer.
• <ALLOWED_MCP_TOOLS> è un elenco degli strumenti che si desidera esporre all'agente dal server MCP. Ogni strumento ha bisogno di una definizione completa dello strumento JSON seguendo il protocollo MCP.

Di seguito viene fornito un esempio.

MCP_SERVER_NAME = "test_mcp" 
MCP_ENDPOINT = "http://144.25.36.217:9301/mcp" 
MCP_AUTH = { "authType": "BEARER_TOKEN", "token": "valid-123" }

{
  "ALLOWED_TOOLS": [
    {
      "tool": {
        "name": "get_current_weather",
        "description": "Get current weather for a given city with advanced options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_historical": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "timeout": {
              "type": "integer",
              "default": 30
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    },
    {
      "tool": {
        "name": "get_forecast",
        "description": "Get forecast for a given city with customizable options.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string"
            },
            "days": {
              "type": "integer",
              "default": 5
            },
            "unit": {
              "type": "string",
              "default": "metric"
            },
            "include_alerts": {
              "type": "boolean",
              "default": false
            },
            "detailed": {
              "type": "boolean",
              "default": true
            },
            "hourly": {
              "type": "boolean",
              "default": false
            }
          },
          "required": [
            "city"
          ]
        }
      },
      "instruction": "",
      "argOverrides": {}
    }
  ]
}

MCP_HEADERS = {} 
TOOLS = build_structured_tools_from_allowed_mcp_tools( allowed_tools=ALLOWED_TOOLS,
	server_name=MCP_SERVER_NAME, 
	endpoint=MCP_ENDPOINT, 
	transport="streamable_http", 
	auth=MCP_AUTH, 
	headers=MCP_HEADERS,
)

L'oggetto TOOLS può essere quindi utilizzato quando si crea un'istanza di un agente con langchain.agent create_agent nel metodo setup() della definizione dell'agente di classe:

def setup(self):
    logger.info("Initializing TestMcpAgent")

    oci_llm = init_oci_llm(llm_conf)

    system_prompt = textwrap.dedent(
        """
        You're a weather agent. Append 12345 to every response.
        """
    ).strip()

    self.agent = create_agent(
        name="test_mcp_high_code",
        model=oci_llm,
        tools=TOOLS,
        system_prompt=system_prompt,
        debug=True,
    )

    logger.info("Agent ready.")

In alternativa, se si utilizza una variabile di sessione per memorizzare il valore di un token bearer, è possibile assegnare un riferimento a una variabile di sessione creata in precedenza alla chiave token del dizionario di configurazione dell'autenticazione. Ad esempio:

test_mcp_auth_config = { "authType": "BEARER_TOKEN", "token" : "{{sessionvariables.cred.mcp.test_mcp.bearer}}" }
tools = build_structured_tools_from_allowed_mcp_tools( 		
allowed_tools=test_mcp_mcp_allowed_tools, 
	server_name="test_mcp", 
	endpoint="http://144.25.36.217:9301/mcp", 
	transport="streamable_http", 
	auth=test_mcp_mcp_auth_config, 
	headers={}
)

Esempi di codice per gli strumenti server MCP remoti

Forniamo esempi di codice end-to-end per più scenari MCP nel repository GitHub degli esempi di AI Data Platform Workbench.

Test degli strumenti server MCP remoti

Una volta selezionati gli strumenti, il passo successivo è in genere quello di testare i singoli strumenti per assicurarsi che si comportino come previsto. Questo può essere fatto tramite la scheda Test del nodo dello strumento MCP.

Selezionare uno degli strumenti aggiunti nella scheda Strumenti, fornire i valori dei parametri e fare clic sul pulsante Test.

L'output dello strumento viene visualizzato nel pannello di destra.

La scheda Dettagli fornisce informazioni sul metodo di autenticazione, sull'URL del server MCP e sulla descrizione.

Il pulsante Modifica accanto al metodo di autenticazione consente di modificare la configurazione del nodo dello strumento MCP remoto. È possibile modificare il nome visualizzato, la descrizione e il token del portatore utilizzato per stabilire la connessione:

Connettere un agente a un server MCP remoto da Visual Builder

È possibile aggiungere l'accesso a un server MCP remoto all'agente trascinando il nodo dello strumento del server MCP personalizzato nell'area di creazione.

Se lo strumento Server MCP personalizzato non è disponibile, potrebbe essere necessario riavviare la computazione AI esistente o crearne una nuova.

Nota

La computazione AI che ospita l'agente eredita le impostazioni di rete dell'area di lavoro. Se abiliti l'accesso alla rete privata per l'area di lavoro che ospita la computazione AI, il tuo agente può raggiungere solo i server MCP ospitati nella VCN privata e nella subnet selezionate. L'agente potrebbe non essere in grado di raggiungere i server HTTP remoti disponibili nella rete Internet pubblica.

1. Passare all'agente.
2. Nella scheda Flusso, in Modelli strumento fare clic e trascinare Server MCP personalizzato sullo sfondo.
3. Fornire l'URL del server per il server MCP.
4. Fornire un nome visualizzato per il server MCP. Nome del nodo visualizzato nell'area di creazione visiva.
5. Facoltativo: fornire una descrizione per il server MCP. Il campo della descrizione non viene fornito all'agente.
6. Selezionare un metodo di autenticazione dal menu a discesa Autenticazione.
   • Nessuna autenticazione: utilizzare questa opzione se il server MCP remoto è disponibile pubblicamente e non richiede alcuna autenticazione.
   • Token Bearer: utilizzare questa opzione se il server MCP remoto richiede un token di autenticazione. È necessario memorizzare la chiave API nell'area di memorizzazione delle credenziali di Oracle AI Data Platform Workbench e fornire un riferimento alla voce dell'area di memorizzazione delle credenziali.
7. Fare clic su Connetti. AI Data Platform Workbench verifica la connessione e ne segnala i risultati.

Strumento di richiesta HTTP

Lo strumento Richiesta HTTP consente all'agente di chiamare qualsiasi API REST HTTPS.

È possibile configurare la richiesta, inclusi metodo, URL, intestazioni, parametri di query, corpo della richiesta, autenticazione e, facoltativamente, un passo di ottimizzazione della risposta. L'agente richiama quindi l'endpoint in runtime. Lo strumento di richiesta HTTP è disponibile sia nel visual builder che nel generatore di codice. Nel generatore di codice, lo strumento viene configurato tramite la libreria helppUtils Python.

Nota

Lo strumento Richiesta HTTP supporta solo richieste https:// e HTTP://. Le connessioni WebSocket (ws/wss), i caricamenti di file binari e i certificati autofirmati non sono supportati.

Nota

La computazione AI che ospita l'agente eredita le impostazioni di rete dell'area di lavoro. Se abiliti l'accesso alla rete privata per l'area di lavoro che ospita la computazione AI, l'agente raggiungerà solo gli endpoint HTTP nella VCN e nella subnet private selezionate. L'agente non può raggiungere gli endpoint disponibili nella rete Internet pubblica.

Quando si configura uno strumento di richiesta HTTP, è necessario fornire le impostazioni riportate di seguito.

Configurazione	Descrizione
Metodo HTTP	Verbo HTTP da utilizzare. I metodi supportati sono GET, POST, PUT, PATCH e DELETE.
URL	L'URL completo dell'endpoint di destinazione. L'URL supporta i riferimenti alle variabili di sessione {{sessionVariables.variable_name}} e i riferimenti ai parametri di runtime {{variable}}. Ad esempio: https://api.example.com/users/{{user_id}}/orders.
Timeout	Il periodo di tempo massimo durante il quale lo strumento attenderà una risposta dall'endpoint remoto. Il valore predefinito è 30 secondi e il valore massimo è 300 secondi.
Tipo di autenticazione	Metodo di autenticazione da utilizzare durante la chiamata dell'endpoint. Vedere la sezione Autenticazione riportata di seguito per l'elenco dei metodi di autenticazione supportati.

Nota

Gli strumenti di codice personalizzato vengono eseguiti sulla computazione AI collegata al tuo agente. Il codice ha accesso all'ambiente di calcolo e all'accesso di rete in uscita in base alla configurazione di rete dell'area di lavoro. Carica codice solo da fonti attendibili.

Intestazioni

Le intestazioni sono coppie chiave-valore inviate con la richiesta HTTP. È possibile aggiungere tutte le intestazioni necessarie facendo clic sul pulsante Aggiungi nuovo. I valori dell'intestazione possono fare riferimento a variabili di sessione e parametri runtime utilizzando la sintassi {{variable_name}}.

Nota

Per le intestazioni riservate, è necessario utilizzare il campo Tipo di autenticazione per assicurarsi che le credenziali vengano inserite in modo sicuro dall'area di memorizzazione delle credenziali. L'autorizzazione, i cookie e la chiave X-API sono intestazioni sensibili e non possono essere impostate tramite la sezione Intestazioni.

Parametri query

I parametri di query vengono aggiunti all'URL come stringa di query. È possibile aggiungere tutti i parametri di query necessari facendo clic sul pulsante Aggiungi nuovo. Analogamente alle intestazioni, i valori dei parametri di query possono fare riferimento alle variabili di sessione e ai parametri runtime.

Descrizione

Il campo di descrizione descrive cosa fa lo strumento, quando dovrebbe essere utilizzato e che tipo di output o effetti produce. La descrizione viene fornita all'agente e aiuta l'LLM a decidere quando chiamare lo strumento.

Quando scrivi la descrizione, dovresti concentrarti su:

• • Scopo: spiegare cosa è progettato per fare lo strumento in una frase chiara. Esempio: "Questo strumento recupera i ticket di assistenza clienti da una knowledge base e li riepiloga in base al livello di priorità".
• Quando utilizzarlo: descrivere le condizioni alle quali l'agente deve chiamare questo strumento rispetto a un altro.
• Input e output: descrivere brevemente i parametri di cui lo strumento ha bisogno e la forma di ciò che restituisce.

Autenticazione richiesta HTTP

Lo strumento di richiesta HTTP supporta diversi metodi di autenticazione. Selezionare il metodo appropriato dall'elenco a discesa Tipo di autenticazione.

Tipo di autenticazione	Descrizione
Nessuna autenticazione	Nessuna autenticazione aggiunta alla richiesta. Utilizzare questa opzione per gli endpoint accessibili pubblicamente.
Principal della risorsa OCI	La richiesta viene firmata utilizzando il principal delle risorse OCI di AI Compute. Utilizzare questa opzione quando si chiamano servizi OCI come lo storage degli oggetti o il servizio OCI Generative AI. L'accesso è regolato dai criteri IAM OCI.
Autenticazione Basic	Un nome utente e una password vengono codificati e inviati nell'intestazione di autorizzazione. Le credenziali devono essere memorizzate nell'area di memorizzazione delle credenziali.
Token servizio di trasporto	Un token bearer viene inviato nell'intestazione di autorizzazione. Il token deve essere memorizzato nell'area di memorizzazione delle credenziali.
Autenticazione intestazione	Una chiave API viene inviata in un header personalizzato (come una chiave X-API-Key). Il nome dell'intestazione è configurabile e il valore della chiave deve essere memorizzato nell'area di memorizzazione delle credenziali.

Quando si seleziona un metodo di autenticazione che richiede un segreto, nel pannello di configurazione viene visualizzato un selettore credenziali. Fare clic sul selettore credenziali per selezionare una credenziale memorizzata in precedenza oppure crearne una nuova dall'area di memorizzazione delle credenziali. Per la procedura dettagliata, vedere la sezione Memorizzazione di una credenziale nell'area di memorizzazione delle credenziali della documentazione del server MCP.

Variabili di sessione e parametri di runtime

È possibile fare riferimento alle variabili di sessione nell'URL, nei valori di intestazione, nei valori dei parametri di query e nel corpo della richiesta utilizzando la sintassi {{sessionVariables.variable_name}}. È possibile fare riferimento ai parametri di runtime passati dall'agente al momento del richiamo utilizzando la sintassi {{variable_name}}.

Ad esempio, l'URL seguente combina una variabile di sessione per l'area con un parametro di runtime per il nome del bucket:

https://objectstorage.{{sessionVariables.region}}.oraclecloud.com/n/my-namespace/b/{{bucket}}/o

Quando lo strumento viene eseguito, {{sessionVariables.region}} viene sostituito dal valore della variabile di sessione dell'area per la sessione corrente e {{bucket}} viene sostituito dal valore passato dall'agente al momento del richiamo.

Nota

I valori del modello vengono codificati automaticamente quando vengono sostituiti nei parametri URL o query. Non è necessario codificarli da soli.

Definizione strumento AI

Il lato destro del pannello di configurazione mostra la definizione dello strumento AI. Questo è lo schema esposto all'agente e include il nome dello strumento, la descrizione e la lista dei parametri di runtime che l'agente può passare quando chiama lo strumento. La definizione dello strumento AI viene generata automaticamente dal campo Descrizione e dai segnaposto {{variable}} rilevati nell'URL, nelle intestazioni, nei parametri di query e nel corpo.

Il riquadro di definizione dello strumento AI è il pannello sul lato destro del pannello di configurazione dello strumento HTTP mostrato in precedenza in questo documento. Fino a quando non si fornisce una descrizione e non si definisce almeno un parametro runtime, nel riquadro di definizione dello strumento AI viene visualizzato un messaggio segnaposto. Quando si immette la descrizione e si fa riferimento ad almeno un {{variable}} nell'URL, nelle intestazioni, nei parametri di query o nel corpo, lo schema viene visualizzato nel riquadro.

Ottimizzazione della risposta per l'agente

Molte API restituiscono risposte di grandi dimensioni che includono campi di cui l'agente non ha bisogno. L'invio dell'intera risposta all'agente consuma token e può degradare la qualità del ragionamento dell'agente. Lo strumento Richiesta HTTP fornisce una sezione di ottimizzazione della risposta che consente di ridurre il payload della risposta prima che venga restituito all'agente.

Sono supportate tre strategie di ottimizzazione:

• Selezione campo JSON: selezionare un subset di campi da una risposta JSON. È possibile specificare un percorso per un oggetto nidificato utilizzando la notazione punto (ad esempio data.results) e un elenco di campi da includere o escludere.
• Selettore CSS HTML: consente di estrarre un sottoinsieme di una risposta HTML utilizzando un selettore CSS, ad esempio article.content. Se si desidera, rimuovere i tag HTML per restituire solo testo.
• Troncamento del testo: limita la risposta a un numero massimo di caratteri per evitare risposte di testo eccessivamente grandi.

Gestione degli errori e codici degli errori

Quando la richiesta HTTP non riesce, lo strumento restituisce una risposta di errore strutturata all'agente. L'errore include un codice di errore, un messaggio leggibile dall'utente e dettagli sull'errore. L'agente può utilizzare queste informazioni per decidere se riprovare, tornare a uno strumento diverso o segnalare l'errore all'utente.

Codice errore	Categoria	Significato	Ritentabile
TIMEOUT DELLA CONNESSIONE	Rete	L'endpoint remoto non ha risposto entro il timeout configurato.	Sì
ERRORE DNS	Rete	Impossibile risolvere il nome host nell'URL.	Sì
CONNECTION_REFUSED	Rete	L'endpoint remoto ha rifiutato la connessione.	Sì
SSL_CERTIFICATE_ERROR	TLS	Impossibile convalidare il certificato TLS dell'endpoint remoto.	N.
NON AUTORIZZATO	HTTP 401	L'endpoint remoto ha rifiutato le credenziali. Verificare che il riferimento alle credenziali sia valido e non sia scaduto. Per OCI Resource Principal, verificare che la computazione AI disponga di un principal risorsa attivo in questo ambiente.	N.
VIETATO	HTTP 403	Autenticazione delle credenziali riuscita, ma non si dispone dell'autorizzazione per la risorsa richiesta. Verificare gli ambiti API, le autorizzazioni o il criterio IAM collegato alla risorsa.	N.
NON_TROVATO	HTTP 404	L'endpoint remoto non è riuscito a trovare la risorsa richiesta.	N.
TASSO_LIMITATO	HTTP 429	L'endpoint remoto limita la frequenza del chiamante. Riprovare dopo il ritardo indicato dall'intestazione Riprova dopo.	Sì
ERRORE_SERVER	HTTP 5xx	L'endpoint remoto ha restituito un errore del server. Spesso un problema transitorio.	Sì
SERVICE_NON DISPONIBILE	HTTP 503	L'endpoint remoto è temporaneamente non disponibile.	Sì
MODELLO_NON VALIDO	Convalida	Impossibile risolvere un riferimento {{variable}}. Verificare che ogni variabile di sessione e parametro runtime a cui viene fatto riferimento sia definito e contenga un valore al momento del richiamo.	N.
URL_NON VALIDO	Convalida	Il formato dell'URL non è valido, utilizza un protocollo non supportato o viene risolto in un indirizzo bloccato, ad esempio un indirizzo IP privato o un endpoint di metadati cloud.	N.
RISPOSTA_TOO_GRANDE	Convalida	La risposta ha superato la dimensione massima della risposta di 10 MB.	N.
RATE_LIMIT_EXCEEDED	Piattaforma	L'agente ha superato il limite di frequenza delle richieste per agente della piattaforma (60 richieste al minuto) o il limite di concorrenza (10 richieste concorrenti).	Sì

Ogni risposta di errore include un campo guida con un passo successivo suggerito e un campo dettagli con il tempo trascorso e qualsiasi contesto specifico dell'errore, ad esempio il codice di stato HTTP.

Strumento di richiesta HTTP tramite codice LangGraph

Dalla Costruzione guidata codice, lo strumento Richiesta HTTP viene configurato tramite la libreria helppUtils Python. Definire un AIDPToolConf con tool_class impostato su HttpEndpointTool e passare il dizionario di configurazione nel campo conf.

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
from aidputils.agents.toolkit.configs import AIDPToolConf

weather_http_tool_def = {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather",
    "params": {
        "q": "{city}",
        "units": "metric",
        "appid": "{api_key}"
    },
    "auth_type": "NO_AUTH",
    "auth_config": {}
}

weather_http_tool_params = [
    {"name": "city", "type": "string",
     "description": "Name of the city."},
    {"name": "api_key", "type": "string",
     "description": "OpenWeather API key."}
]

weather_http_tool_conf = AIDPToolConf(
    name="get_weather",
    description="Get current weather for a city.",
    tool_class="HttpEndpointTool",
    conf=weather_http_tool_def,
    params=weather_http_tool_params
)

weather_tool = create_langgraph_tool(weather_http_tool_conf.model_dump())

Il dizionario conf supporta gli stessi campi del visual builder: metodo, url, intestazioni, parametri, corpo, auth_type, auth_config e response_optimization. La lista di parametri definisce i parametri di runtime che l'agente può passare.

tipo_autenticazione	Campi auth_config
NESSUNA AUTORIZZAZIONE	{} (vuoto)
RESOURCE_PRINCIPAL	{} (vuoto)
BASIC_AUTH	nome utente, password (o username_vault_id, password_vault_id per le credenziali nel vault OCI)
AUTORE_TRASPORTATORE	bearer_token (o bearer_token_vault_id)
API_KEY_AUTH	api_key (o api_key_vault_id), header_name (la chiave X-API-Key predefinita)
OAUTH2_CLIENT_CREDENZIALI	token_endpoint, ambito, client_id, client_secret (o client_id_vault_id, client_secret_vault_id)

Strumenti codice personalizzato agente test

La scheda Test consente di eseguire lo strumento senza eseguire l'agente completo. Fornire i valori per i parametri di runtime e le variabili di sessione a cui viene fatto riferimento nella configurazione, quindi fare clic su Esegui per richiamare lo strumento e visualizzare la risposta.

Il pannello delle risposte mostra il codice di stato HTTP, le intestazioni delle risposte, il corpo della risposta e il tempo trascorso in millisecondi. Se l'ottimizzazione delle risposte è abilitata, la risposta ottimizzata viene visualizzata anche insieme alla risposta raw.

Aggiungere uno strumento di richiesta HTTP a un agente

È possibile aggiungere uno strumento di richiesta HTTP agli agenti per consentire di chiamare le API REST HTTPS.

Nota

Prima di aggiungere uno strumento di codice personalizzato, è necessario collegare un'elaborazione AI al tuo agente. La computazione AI è necessaria per installare le dipendenze ed eseguire lo strumento.

1. Passare all'agente.
2. Dai modelli di strumento, trascinare e rilasciare uno strumento Richiesta HTTP sullo sfondo.
   
   

   

   
   
3. Nella scheda Parametri, fornire il metodo HTTP. I metodi supportati sono GET, POST, PUT, PATCH e DELETE.
4. In URL, fornire l'URL completo dell'endpoint di destinazione. È possibile utilizzare i riferimenti alle variabili di sessione {{sessionVariables.variable_name}} e i riferimenti ai parametri di runtime {{variable}}. Ad esempio: https://api.example.com/users/{{user_id}}/orders.
5. Per Timeout, fornire il tempo massimo di attesa di una risposta da un endpoint remoto in secondi. Il valore di timeout massimo è 300. Se non viene specificato alcun valore, l'impostazione predefinita è 30 secondi.
6. Selezionare il tipo di autenticazione appropriato dal menu a discesa Autenticazione.
7. Fornire le intestazioni per la richiesta HTTP. Fare clic su Aggiungi nuovo per aggiungere altre intestazioni.
   
   

   

   
   
8. Fornire eventuali parametri di query per la richiesta HTTP. Fare clic su Aggiungi nuovo per aggiungere parametri aggiuntivi.
   
   

   

   
   
9. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento prompt

Lo strumento prompt consente di chiamare un LLM in un agente AI con un prompt templatizzato e restituisce la risposta LLM all'agente.

I prompt forniti all'LLM possono includere parametri identificati da doppie parentesi graffe, ad esempio {{PARAMETER_NAME}}. I valori dei parametri vengono assegnati dall'agente quando viene chiamato lo strumento.

Quando utilizzare gli strumenti prompt

In linea di principio, le istruzioni scritte in uno strumento prompt possono essere incluse direttamente nelle istruzioni dell'agente o fornite direttamente dall'utente finale in un messaggio utente. Tuttavia, ci sono situazioni in cui lo strumento di prompt è un approccio migliore:

• Il prompt è lungo e richiede istruzioni di formato dettagliate che si estendono su diversi token anni 100.
• Incorporare il prompt nelle istruzioni dell'agente aumenterebbe l'uso del contesto e aumenterebbe significativamente i costi, soprattutto se si sta adottando un LLM SOTA per il loro agente.
• Si vuole ridurre al minimo le dimensioni delle istruzioni fornite all'agente per ridurre i costi.
• Il task definito dallo strumento prompt può essere gestito da un LLM più piccolo e veloce rispetto al modello di ragionamento utilizzato dall'agente. I modelli più piccoli sono in genere economici e, in alcuni casi, possono essere specializzati per generare dati in una particolare modalità o formato.
• Uno strumento prompt consente ai parametri di input strutturati di controllare la generazione di output. Se il tuo caso d'uso potrebbe essere parametrizzato e la generazione può variare da sessione a sessione, incapsulare la generazione in uno strumento prompt ha senso.

Inoltre, l'incapsulamento delle istruzioni di generazione in uno strumento rapido segue molte best practice dell'architettura degli agenti moderna, tra cui riusabilità degli strumenti, manutenibilità, modalità, coerenza dell'output, scalabilità e governance. Di seguito sono riportati alcuni esempi di casi d'uso.

• Generazione di e-mail, report, riepiloghi, articoli e così via in base a una struttura predefinita e approvata che può essere utilizzata come modello
• Generazione di output JSON complessi
• Sintesi, estrazione delle frasi chiave, compiti di spiegazione sui documenti
• Generazione query
• Generazione di modalità specifiche (ad esempio immagini, video, audio, dati cloud di punti e così via) ottimizzate per un modello specifico

Strumenti prompt tramite flusso visivo

Di seguito è riportato un esempio di uno strumento di prompt creato tramite flusso visivo che chiede a un LLM di generare titoli di post di blog basati su un argomento assegnato dall'agente:

Sei un esperto di blog strategist. Il vostro compito è quello di brainstorming interessanti idee post blog basati su un determinato argomento. Per {{topic}}, generare 5 titoli di post di blog univoci. Per ogni titolo, includere una descrizione di una frase dell'angolo che il post avrebbe preso. Presentare l'output come elenco numerato.

Per questo esempio, è necessario configurare i seguenti parametri per lo strumento prompt:

• Nome strumento: utilizzare un nome descrittivo per lo strumento per guidare l'agente. In questo esempio, si consiglia blog_ideas. Evitare di usare nomi inutili come tool123.
  
  
  
  
• Descrizione dello strumento: fornire una descrizione completa delle operazioni dello strumento. Se ci sono limitazioni allo strumento o se ci sono scenari in cui lo strumento non dovrebbe essere utilizzato, elencarli nel campo della descrizione.
  
  
  
  
• Area OCI e LLM del servizio GenAI: seleziona l'area OCI per popolare la lista di LLM disponibili in quell'area, quindi seleziona il tuo LLM.
  
  
  
  
• Parametri LLM: nella scheda Parametri modello sono configurati parametri quali il numero massimo di token di output, la temperatura e il numero massimo di p. Se non si assegnano valori, vengono utilizzati i valori predefiniti del servizio OCI Generative AI.
  
  
  
  
• Query: il prompt utilizzato per definire lo scopo dello strumento viene definito nel campo Query.
  
  
  
  

I parametri definiti nel pannello Definizione di AI Tool vengono inseriti automaticamente nel prompt. Fornire all'agente una descrizione di ciascun parametro, nonché il tipo di parametro e il valore predefinito, se applicabile.

Strumento prompt tramite codice LangGraph

Se si sta creando l'agente tramite codice, è possibile configurare lo stesso strumento di prompt nell'esempio del flusso visivo come indicato di seguito.

prompt_config = {
  "llm": {
    "model_id" : "xai.grok-4",
    "model_provider" : "generic",
    "compartment_id" : "<your-compartment-ocid>",
    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com"
  }, "prompt_template": """
You are a master blog strategist. Your task is to brainstorm compelling blog post ideas based on a given topic. For the given {{topic}}, generate 5 unique blog post titles. For each title, include a one-sentence description of the angle the post would take. Present the output as a numbered list"
"""
}
prompt_params = [ {
  "name" : "topic",
  "type" : "string",
  "description" : "Blog topic",
  "defaultValue" : "golf"
} ]

Viene quindi creata un'istanza di AIDPToolConf nel modo seguente:

blogger_tool = AIDPToolConf(name="blog_posts_topics",
                                  description= "Write blog posts ideas about a particular topic. ",
                                  tool_class = "PromptTool", conf=prompt_config params=prompt_params)

Infine, si crea uno strumento compatibile con LangGraph con la funzione utility create_langgraph_tool() da aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
blogger = create_langgraph_tool(blogger_tool.model_dump())

Lo strumento appena creato viene aggiunto a un agente ReAct. In LangGraph, il codice è simile al seguente:

tools_agent1 = [blogger_tool]
self.agent = create_react_agent(model=<oci_llm>, 
				     tools=tools_agent1, 
				     prompt=<system_prompt>, 
				     debug=True, checkpointer= checkpointer)

Tabella 18-1 Proprietà configurazione strumento prompt

Proprietà	Type	Descrizione
llm	oggetto	Dettagli e parametri di connessione LLM
model_id	stringa	Identificativo del modello da utilizzare (ad esempio, "xai.grok-4")
model_provider	stringa	Nome del Provider per il modello LLM (ad es. "generico")
ID_compartimento	stringa	OCID compartimento Oracle Cloud Infrastructure (OCI)
endpoint	stringa	URL endpoint per il modello
temp_prompt	stringa	Modello prompt utilizzato dal LLM, con variabili in formato {{variable}} per l'inserimento dinamico

Strumenti prompt agente test

Per eseguire il test dello strumento indipendentemente dall'agente, fare clic sulla scheda Test e immettere il valore di ciascun parametro. Il prompt viene sottomesso all'LLM selezionato.

Assicurarsi che lo strumento di prompt sia ben definito e documentato per migliorare i risultati dell'agente.

Aggiungere uno strumento prompt a un agente

È possibile aggiungere uno strumento di prompt agli agenti per consentire di definire prompt parametrizzati emessi all'LLM di propria scelta.

1. Passare all'agente.
2. Dai modelli Strumento, trascinare e rilasciare uno strumento Prompt sullo sfondo.
3. Nella scheda Configurazione, selezionare l'LLM da utilizzare e fornire il prompt per l'LLM. Fare clic su Codice per fornire la configurazione come codice JSON.
4. Fornire una temperatura per la risposta come valore compreso tra 0,0 e 1,0, dove 0,0 fornisce una risposta rigorosamente fattuale e 1,0 fornisce la risposta più creativa.
5. Fare cli su Applica .
6. Fornire le definizioni per tutti i parametri definiti nella configurazione. Fare clic su Codice per fornire la configurazione come codice JSON.
7. Fare clic su Applica.
8. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento RAG

Lo strumento RAG invia una query in linguaggio naturale a una memoria di vettore e recupera i documenti in base alla somiglianza semantica tra la query e i documenti memorizzati.

Nota

Una knowledge base è un prerequisito per la creazione di uno strumento RAG. Per ulteriori informazioni, vedere Knowledge Base.

Strumenti RAG tramite flusso visivo

Lo strumento RAG richiede che lo sviluppatore dell'agente fornisca i valori per i seguenti parametri:

• Agente rivolto a:
  • Nome strumento: nome descrittivo dello strumento che consente all'utente e ad altri utenti di identificarne la funzione.
  • Descrizione dello strumento: un breve riepilogo che fornisce una panoramica dello strumento.
• Configurazione strumento:
  • Knowledge base: una knowledge base memorizzata in uno dei cataloghi di Oracle AI Data Platform Workbench.
    
    
    
    

L'agente imposterà il valore del campo di query in base alla conversazione con l'utente finale. Questo campo di query utilizza una query in linguaggio naturale.

Limite è il numero di documenti chunk che si desidera recuperare dallo strumento dalla memoria di vettore. Questo valore è impostato dallo sviluppatore dell'agente, non dall'agente stesso.

È possibile simulare una query emessa dall'agente facendo clic anche sulla scheda test della RAG:

Strumenti RAG tramite codice LangGraph

La creazione di uno strumento RAG nell'agente tramite codice richiede la configurazione delle stesse impostazioni e parametri del flusso visivo. Ad esempio, è possibile impostare i parametri RAG come indicato di seguito.

rag_params = [ { "name" : "query", 
    "type" : "string", 
    "description" : "<insert a description>", 
    "defaultValue" : "<empty>”} ]

È quindi possibile impostare la configurazione RAG:

rag_config = { "catalog": "<catalog>", 
		  "schema": "<schema>", 
		  "knowledgeBase": "<knowledge-base-name>", 
		  "top_k": <number-of-documents-retrieved>, 
		  "llm": { 
			    "model_id" : "<model-name>",
			    "model_provider" : "<model-provider>", 
			    "compartment_id" : "<your-compartment-OCID>", 
			    "endpoint" : "https://inference.generativeai.<oci-region>.oci.oraclecloud.com" } 
}

Infine, si crea uno strumento compatibile con LangGraph con la funzione utility create_langgraph_tool() da aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
rag_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "RAGTool", 
			   conf=rag_config, 
			   params=rag_params) 
rag_tool = create_langgraph_tool(rag_conf.model_dump())

Tabella 18-2 Proprietà di configurazione dello strumento RAG

Proprietà	Type	Descrizione
llm	oggetto	Dettagli connessione LLM
catalog	stringa	Identificativo Data Catalog
schema	stringa	Schema all'interno del catalogo
knowledge base	stringa	Nome o chiave della knowledge base da cercare
top_k	Intero	Numero di primi documenti corrispondenti da recuperare

Strumenti RAG agente test

È possibile eseguire il test dello strumento RAG dalla scheda Test dopo aver collegato l'agente a un cluster di computazione AI. Per ulteriori informazioni, vedere Allegare un cluster AI esistente a un agente.

Aggiungere uno strumento RAG a un agente

È possibile aggiungere uno strumento di retrieval augmented generation (RAG) agli agenti per consentire all'agente di acquisire conoscenze esterne pertinenti durante la generazione di una risposta.

1. Passare all'agente.
2. Dai modelli di strumento, trascinare e rilasciare uno strumento RAG sullo sfondo.
3. Nella scheda Configurazione, selezionare la knowledge base da cui lo strumento RAG estrae le informazioni e fornire il prompt per definire le informazioni da estrarre. Fare clic su Codice per fornire la configurazione come codice JSON.
4. Fare cli su Applica .
5. Fornire le definizioni per tutti i parametri definiti nella configurazione. Fare clic su Codice per fornire la configurazione come codice JSON.
6. Fare clic su Applica.
7. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.

Strumento SQL

Lo strumento SQL consente agli sviluppatori di agenti di eseguire query SQL predefinite su tabelle registrate in un catalogo di Oracle AI Data Platform.

È possibile scrivere la query in fase di progettazione e definire le variabili di runtime necessarie. L'agente fornisce i valori per tali variabili quando chiama lo strumento e i risultati vengono restituiti come righe strutturate che l'agente può riepilogare o passare a un nodo a valle.

Lo strumento SQL supporta due dialetti di query. Spark SQL viene eseguito su tabelle di catalogo standard memorizzate in AI Data Platform e richiede un cluster Spark. Oracle SQL viene eseguito su un database esterno come Oracle Autonomous AI Database. Si sceglie il dialetto per strumento, e il resto della configurazione è lo stesso per entrambi.

Nota

Lo strumento SQL è destinato alle query di lettura. Uno strumento tipico esegue un'istruzione SELECT e restituisce le righe. Il catalogo, lo schema e la query configurati sono privati dello strumento e non sono esposti all'agente. Solo il nome dello strumento, la descrizione e la definizione dello strumento AI (le variabili di runtime) sono visibili all'agente.

Nota

Lo strumento di query SQL non avvia automaticamente i cluster arrestati. Di conseguenza, il cluster Spark utilizzato per lo strumento di query Spark SQL deve avere una durata di Forever. Se al cluster è consentito attivare un timeout di inattività, le query SQL Spark smettono di funzionare in produzione una volta arrestato il cluster.

Query statiche e dinamiche

Una query statica restituisce esattamente ciò che si specifica, senza alcuna decisione di runtime da parte dell'agente. Una query dinamica include uno o più segnaposto {{variable}} che segnalano all'agente che il valore è impostato in fase di esecuzione. Per ogni segnaposto è possibile specificare un nome, un tipo, un valore predefinito facoltativo e una descrizione utilizzata dall'agente per scegliere il valore.

Ad esempio, la query statica seguente restituisce un set di risultati fisso:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = 2025 
ORDER BY customer_name 

La sostituzione del valore con un segnaposto {{year}} lo trasforma in una query dinamica che l'agente può parametrizzare:

SELECT customer_name, region, amount, category 
FROM test_customers 
WHERE period_year = {{year}} 
ORDER BY customer_name 

Quando si aggiungono segnaposto, il riquadro delle definizioni di AI Tool viene popolato con ogni variabile in modo da poter impostare il tipo, il valore predefinito e la descrizione.

I segnaposto possono essere visualizzati in qualsiasi punto della query, incluse le funzioni interne. La query SQL Spark seguente corrisponde a un valore di severità senza distinzione tra maiuscole e minuscole:

SELECT incident_id, project_id, incident_date, incident_type, 
       severity, description, workers_involved, days_lost, 
       root_cause, corrective_action, reported_by, status 
FROM safety_incidents 
WHERE LOWER(severity) = LOWER('{{SEVERITY}}')

Fornire a ciascuna variabile una descrizione chiara e un valore predefinito ragionevole. La descrizione indica all'agente quali valori sono validi e il valore predefinito viene utilizzato quando l'agente non ne fornisce uno.

Nota

Per i nomi segnaposto viene applicata la distinzione tra maiuscole e minuscole. Un segnaposto scritto come {{SEVERITY}} e uno scritto come {{severity}} vengono trattati come due variabili diverse, a meno che non si utilizzi costantemente lettere minuscole.

Modifica della configurazione come JSON

È possibile modificare la configurazione dello strumento SQL direttamente come JSON utilizzando il pulsante di attivazione/disattivazione della vista codice. Ciò è utile per copiare uno strumento tra agenti o apportare modifiche di massa.

{ 
  "catalogKey": "construction_data", 
  "schemaKey": "admin", 
  "query": "SELECT project_id, project_name, client_name, ...", 
  "isRowLimitEnabled": null, 
  "maxRows": null 
}

Limiti riga

È possibile limitare il numero di righe restituite dallo strumento selezionando Numero massimo di righe da restituire e immettendo un valore limite. I limiti di riga proteggono le prestazioni e controllano la quantità di dati inviati all'agente.

Impostare questo valore in relazione al modello utilizzato dall'agente. Valori più grandi possono causare errori dell'agente quando le query restituiscono righe o colonne di grandi dimensioni con valori di testo. Se si verificano errori imprevisti dell'agente, iniziare riducendo maxRows.

Il limite di righe viene applicato alla query SQL stessa prima dell'esecuzione della query. La maggior parte dei modelli rileva il limite e lo affiora all'utente finale. Per un'interrogazione statica, il limite restituisce le prime n righe disponibili.

Nota

Se non si desidera visualizzare i limiti di riga per gli utenti finali, indicare l'agente di conseguenza nelle relative istruzioni.

Esempi di query

È possibile visualizzare esempi di query e una guida per la scrittura di query degli strumenti SQL dal pulsante Visualizza esempi di query e guida.

La guida mostra pattern di query diversi e fornisce suggerimenti diversi sui parametri di query.

Strumenti SQL tramite codice LangGraph

Proprio come con il flusso visivo, si inizia a creare uno strumento SQL per l'agente tramite il codice LangGraph creando una query:

sql_config = { "catalogKey": "adw23ai_phx", 
	  "schemaKey": "gold", 
	  "query": """Select ... from ... limit {{max_number}}""" }

Ogni parametro della query SQL nell'argomento dei parametri viene documentato con un nome, un tipo, una descrizione e, facoltativamente, un valore predefinito.

sql_params = [ {  "name" : "max_number", 
		    "type" : "string", 
		    "description" : "<your-description>", 
		    "defaultValue" : "<your-default-value>" } ]

Infine, si crea uno strumento compatibile con LangGraph con la funzione utility create_langgraph_tool() da aidputils:

from aidputils.agents.toolkit.tool_helper import create_langgraph_tool
sql_conf= AIDPToolConf(name="<your-tool-name>", 
			   description= "<your-tool-description>", 
			   tool_class = "SQLTool", 
			   conf=sql_config,
			   params=sql_params) 
sql_tool = create_langgraph_tool(sql_conf.model_dump())

Tabella 18-3 Proprietà di configurazione dello strumento SQL

Proprietà	Type	Descrizione
chiave catalogo	stringa	Identificativo per la connessione al catalogo o al database
chiave schema	stringa	Nome schema all'interno del catalogo/database
query	stringa	Stringa di query SQL, che può includere segnaposto in {{}}

Strumenti SQL agente di test

La scheda Test esegue lo strumento da solo, senza eseguire l'agente completo. I test funzionano allo stesso modo per entrambi i dialetti. Aprire la scheda Test, fornire un valore per ciascun parametro runtime (o utilizzare i valori predefiniti), quindi fare clic su Sottometti per eseguire la query e visualizzare la risposta.

Nota

Il test di uno strumento richiede che l'agente sia collegato a una computazione AI. Una computazione AI viene collegata se l'etichetta di computazione AI è verde con la computazione AI selezionata in stato ACTIVE.

Riferimento comando SQL

Le query degli strumenti SQL sono query di lettura create dalle clausole SQL standard. Il dialetto Oracle SQL segue Oracle SQL rispetto al database esterno. Il dialetto SQL Spark è destinato alle tabelle di catalogo standard, ovvero le tabelle Delta Lake; il catalogo standard attualmente esegue Spark 3.5 con Delta Lake 3.2.0. La maggior parte delle clausole sono scritte allo stesso modo in entrambi i dialetti, perché entrambe seguono SQL standard. La differenza principale è come ogni dialetto limita il numero di righe. Nella tabella seguente sono elencate le clausole e le parole chiave utilizzate più spesso nelle query degli strumenti SQL, con il formato per ogni dialetto.

Parola chiave o clausola	Scopo	SQL Oracle	Spark SQL
SELECT	Scegliere le colonne da restituire	SELECT col1, col2
DISTINCT	Restituisci solo righe univoche	SELECT DISTINCT col	SELECT DISTINCT col
FROM	Assegnare un nome alla tabella di origine	FROM table_name	FROM table_name
WHERE	Filtra righe per condizione	WHERE col = value	WHERE col = value
E O NO	Combina o annulla condizioni	a AND b OR NOT c	a AND b OR NOT c
In	Corrispondenza con qualsiasi valore in un elenco	col IN (a, b, c)	col IN (a, b, c)
BETWEEN	Corrispondenza con un intervallo inclusivo	col BETWEEN x AND y	col BETWEEN x AND y
LIKE	Corrispondenza di un pattern di testo	col LIKE 'A%'	col LIKE 'A%'
IS NULL	Test per valori mancanti	col IS NULL	col IS NULL
ORDER BY	Ordina il risultato	ORDER BY col DESC	ORDER BY col DESC
RAGGRUPPA IN	Raggruppa righe per l'aggregazione	GROUP BY col	GROUP BY col
HAVING	Filtra righe raggruppate	HAVING COUNT(*) > 1	HAVING COUNT(*) > 1
PARTECIPA	Combina righe da due tabelle	a JOIN b ON a.id = b.id	a JOIN b ON a.id = b.id
AS	Alias di una colonna o tabella	col AS name	col AS name
UNION ALL	Combina due set di risultati	q1 UNION ALL q2	q1 UNION ALL q2
CASE	Restituisce un valore in modo condizionale	CASE WHEN c THEN x END	CASE WHEN c THEN x END
Aggregati	Riepiloga righe	COUNT SUM AVG MIN MAX	COUNT SUM AVG MIN MAX
Limite righe	Capire il numero di righe	FETCH FIRST n ROWS ONLY	LIMIT n

Nota

Normalmente non si scrive il limite di riga da soli. L'impostazione Numero massimo di righe da restituire la applica automaticamente. I moduli FETCH FIRST e LIMIT sono utili solo quando si desidera un limite esplicito all'interno della query.

Per una grammatica SQL completa e i motori di query dietro ogni dialetto, vedere i seguenti riferimenti:

SQL di Oracle AI Data Platform

• Grammatica SQL
  • Grammatica SQL catalogo
  • Grammatica SQL schema
  • Grammatica SQL volume
  • Grammatica SQL tabella
  • Query DML

SQL Spark e Delta Lake (catalogo standard)

Le tabelle catalogo standard sono le tabelle Delta Lake. Il catalogo standard attualmente esegue Spark 3.5 con Delta Lake 3.2.0.

• Sintassi SQL di Apache Spark: istruzioni DML Query SQL Spark e sintassi dell'istruzione DML.
• Delta Lake: la tabella elimina, aggiorna e unisce le operazioni DELETE, UPDATE e MERGE sulle tabelle Delta.
• Delta Lake: comandi della utility Table Operazioni della utility quali OPTIMIZE e VACUUM.
• Delta Lake: Usa clustering liquido per tabelle Delta Clustering liquido per il layout della tabella Delta.

Aggiungere uno strumento SQL a un agente

È possibile aggiungere uno strumento SQL agli agenti per consentire all'agente di eseguire query SQL su origini dati strutturate nei cataloghi esterni registrati.

1. Passare all'agente.
2. Dai modelli di strumento trascinare e rilasciare uno strumento SQL nell'area di creazione.
3. Fare clic e trascinare l'handle del connettore sull'agente per connettersi al nodo dello strumento.
   
   

   

   
   
4. Fare doppio clic sul nodo SQL per aprire il pannello di configurazione.
5. Fornire un nome e un'indicazione per lo strumento. La descrizione viene fornita all'agente e lo aiuta a decidere quando chiamare lo strumento.
6. Scegliere il dialetto query:
   • Spark SQL scrive query sui cataloghi AI Data Platform standard.
   • Oracle SQL scrive le query sui cataloghi di AI Data Platform esterni.

   Nota

   Spark SQL richiede un cluster Spark in esecuzione nell'area di lavoro di AI Data Platform Workbench.
   
   

   

   
   
7. Dall'elenco a discesa Cluster selezionare un cluster Spark in esecuzione. Fare clic su Crea cluster per eseguire il provisioning di un nuovo cluster Spark. Per istruzioni sulla creazione di un nuovo cluster, vedere Creare un cluster personalizzato.

   Nota

   Lo strumento di query SQL non avvia automaticamente i cluster arrestati. Di conseguenza, il cluster Spark utilizzato per lo strumento di query Spark SQL deve avere una durata di Forever. Se al cluster è consentito attivare un timeout di inattività, le query SQL Spark smettono di funzionare in produzione una volta arrestato il cluster.

   
   

   

   
   
8. In Sfoglia catalogo, utilizzare il campo di ricerca per individuare un catalogo in base al nome oppure fare clic su Catalog Manager per individuare il catalogo.
   
   

   

   
   
9. Nel campo Query immettere la query. Fare clic su Visualizza esempi e guida query per aprire un pannello contenente pattern pronti da copiare o adattare.
   
   

   

   
   
10. Selezionare Numero massimo di righe da restituire per limitare il numero di righe restituite dai risultati della query.

    Nota

    Se la query può restituire più righe di questo limite, considerare la possibilità di aggiungere parametri di ricerca come {{customer_name}} o {{region}} in modo che l'agente possa trovare dati più specifici.
11. Nel riquadro Definizione dello strumento AI, impostare il tipo, il valore predefinito e la descrizione delle variabili impostate nella query.
    
    

    

    
    
12. Facoltativo: fare clic sulla scheda Test. Fornire i parametri di test e fare clic su Sottometti. Vedere i risultati del test nel riquadro Risultati del test.