Documentazione dell'infrastruttura Oracle Cloud

Chiamata funzione

Utilizzare Chiamata funzione per consentire al modello di richiedere dati o azioni dall'applicazione durante un flusso di lavoro API Risposte. Ciò è utile quando il modello richiede informazioni o operazioni non disponibili nel prompt stesso, ad esempio dati di calendario, stato dell'applicazione interna o risultato di un'operazione personalizzata.

Con questo modello, il modello non esegue direttamente la funzione. Invece, restituisce il nome e gli argomenti della funzione, l'applicazione esegue la funzione e quindi l'applicazione invia l'output della funzione in modo che il modello possa continuare e produrre la risposta rivolta all'utente.

Cosa questo permette

La funzione Chiamata è utile quando l'applicazione deve mantenere il controllo dell'esecuzione, pur consentendo al modello di decidere quando sono necessarie informazioni esterne.

Casi d'uso di esempio:

  • Ricerca degli eventi del calendario
  • Recupero dei dati dell'applicazione
  • Chiamata API interna o esterna
  • Esecuzione di business logic o calcoli

Nella funzione è possibile chiamare un servizio esterno, un database, una delle API della libreria, un'interfaccia CLI o un server MCP locale.

Questo approccio ti offre flessibilità mantenendo il percorso di esecuzione all'interno dell'applicazione.

Flusso di esecuzione

Una tipica funzione chiamata interazione funziona las segue:

  1. Il client invia una richiesta che include una o più definizioni di strumento di funzione.
  2. Il modello decide se uno di questi strumenti è necessario.
  3. Se è necessario uno strumento, il modello restituisce il nome e gli argomenti della funzione.
  4. L'applicazione esegue la funzione e prepara il risultato.
  5. L'applicazione invia il risultato in una richiesta di follow-up.
  6. Il modello utilizza tale risultato per completare la risposta.

Opzioni gestione stato

Esistono due modi comuni per gestire lo stato nelle seguenti richieste:

  • Stato gestito dal servizio

    Consigliato per la maggior parte dei casi d'uso. La richiesta di follow-up include previous_response_id e il servizio tiene traccia dello scambio precedente.

  • Stato gestito dal client

    L'applicazione mantiene la cronologia completa delle interazioni e invia il contesto accumulato ad ogni richiesta.

Suggerimento

Mantieni precise le definizioni degli strumenti. Nomi chiari, descrizioni ben scritte e parametri ben definiti aiutano il modello a selezionare lo strumento giusto e generare argomenti utilizzabili.

Definizione di uno strumento funzionale

Per definire uno strumento di funzione, aggiungere una voce nella proprietà tools con "type": "function".

Nell'esempio seguente viene definito uno strumento che recupera gli eventi di calendario per una data specificata.

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

Includere questo array tools nella richiesta client.responses.create().

Esempio: stato gestito dal servizio

In questo modello, la prima richiesta consente al modello di decidere se lo strumento è necessario. La seconda richiesta restituisce il risultato dello strumento e fa riferimento alla risposta precedente.

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

# Initial request
response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input="Show the calendar events for 2026-04-02.",
)

# Execute the requested function
tool_outputs = []
for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        tool_outputs.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

# Follow-up request
final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=tool_outputs,
    previous_response_id=response.id,
)

print(final.output_text)

Esempio: stato gestito dal client

In questo modello, l'applicazione mantiene lo scambio completo e lo risottomette con la richiesta di follow-up.

import json

tools = [
    {
        "type": "function",
        "name": "get_calendar_events",
        "description": "Return calendar events scheduled for a specific date.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {
                    "type": "string",
                    "description": "Date to query, for example 2026-04-02"
                }
            },
            "required": ["date"],
        },
    },
]

def get_calendar_events(date):
    # Replace this with actual calendar logic or an API call
    return [
        {"time": "09:00", "title": "Team standup"},
        {"time": "13:00", "title": "Design review"},
        {"time": "16:00", "title": "Project check-in"},
    ]

conversation = [
    {"role": "user", "content": "Show the calendar events for 2026-04-02."}
]

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=tools,
    input=conversation,
)

conversation += response.output

for item in response.output:
    if item.type == "function_call" and item.name == "get_calendar_events":
        args = json.loads(item.arguments)
        events = get_calendar_events(**args)
        conversation.append({
            "type": "function_call_output",
            "call_id": item.call_id,
            "output": json.dumps({"events": events}),
        })

final = client.responses.create(
    model="openai.gpt-oss-120b",
    instructions="Summarize the schedule clearly for the user.",
    tools=tools,
    input=conversation,
)

print(final.output_text)

La chiamata alle funzioni è un'opzione valida quando l'applicazione deve rimanere responsabile dell'esecuzione, del controllo dell'accesso e della logica di integrazione, consentendo al contempo al modello di richiedere le informazioni necessarie.