API Risposte OCI

Utilizzare l'API Risposte insieme AI seguenti componenti di creazione degli agenti in OCI Generative AI:

Se necessario, è possibile utilizzare gli elementi di base di basso livello con l'API Risposte.

Utilizzare l'API Risposte per effettuare le operazioni riportate di seguito.

• Chiama modelli ospitati supportati e modelli importati.
• Invia input di testo e immagine e ricevi output di testo.
• Genera testo o output strutturati.
• Eseguire prompt a passo singolo o flussi di lavoro a più fasi.
• Aggiungere gli strumenti supportati nella richiesta.
• Ripristinare le risposte al client.
• Utilizza lo stato di conversazione gestito da OCI tramite l'API Conversations.
• Riutilizza la cronologia delle conversazioni o gli output precedenti come contesto per le richieste successive.
• Connettere il modello a sistemi e dati esterni tramite chiamata di funzione e chiamata MCP.
• Combina le richieste del modello con file, vector store o container quando necessario.

Ciò ti consente di iniziare con un semplice prompt ed espanderti a flussi di lavoro più avanzati senza passare a un'API diversa.

Per la maggior parte delle nuove applicazioni, iniziare con l'API Risposte.

Utilizzarlo quando si desidera:

• Utilizza un'unica API per l'interazione del modello e le funzionalità agentic.
• Aggiungere strumenti supportati a una richiesta modello.
• Utilizzare la cronologia delle conversazioni gestita da OCI.
• Genera output strutturati.
• Crea flussi di lavoro che possono anche utilizzare file, archivi vettoriali o container quando necessario.

Sostituire ${region} con un'area OCI supportata come us-chicago-1.

Sebbene il formato della richiesta sia compatibile con OpenAI, l'autenticazione utilizza le credenziali OCI, le richieste vengono instradate tramite gli endpoint di inferenza OCI Generative AI e le risorse e l'esecuzione rimangono in OCI.

È possibile accedere agli endpoint compatibili con OCI OpenAI in due modi:

• Chiavi API OCI Generative AI
• Autenticazione basata su IAM OCI

Utilizza le API key per test e sviluppo precoce. Utilizza l'autenticazione basata su IAM per i carichi di lavoro di produzione e gli ambienti gestiti da OCI.

Prima di chiamare l'API delle risposte:

• Crea un progetto OCI Generative AI. Le chiamate API compatibili con OCI OpenAI richiedono un progetto.
• Impostare il client con l'URL di base compatibile con OCI OpenAI.
• Impostare l'autenticazione.
• Utilizzare un modello supportato in un'area supportata.

Per i passi di impostazione, vedere Avvio rapido, Autenticazione e Modelli e aree supportati.

Per chiamare l'API Risposte dal codice, si consiglia di utilizzare OpenAI SDK. Vedere QuickStart.

L'esempio riportato di seguito utilizza OpenAI SDK con l'endpoint compatibile con OCI OpenAI, una chiave API OCI Generative AI e un OCID progetto.

from openai import OpenAI

client = OpenAI(
    base_url="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/openai/v1",
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    project="ocid1.generativeaiproject.oc1.us-chicago-1.xxxxxxxx",
)

response = client.responses.create(
    model="<supported-model-id>",
    input="Write a one-sentence explanation of what a database is."
)

print(response.output_text)

In questo esempio:

• base_url punta all'endpoint OCI compatibile con OpenAI.
• client.responses.create(...) chiama l'API OCI Responses.
• project identifica il progetto OCI Generative AI per la richiesta.

Per consentire a OCI di gestire la cronologia delle conversazioni in più turni, creare prima una conversazione:

conversation = client.conversations.create()

Includere quindi l'ID conversazione nella richiesta API Risposte:

response = client.responses.create(
  model="<supported-model-id>",
  input=[
        {
            "role": "user",
            "content": "Recommend a restaurant based on the food I like."
        }
    ],
    conversation=conversation.id,
)

Utilizzare questo pattern quando si desidera che OCI gestisca lo stato della conversazione tra le richieste.

Per ulteriori informazioni sulle funzionalità di memoria, vedere Conversations API, Short-Term Memory, Long-Term Memory e Short-Term Memory Compaction.

L'API Responses supporta i workflow abilitati per gli strumenti tramite la proprietà tools. Per molti casi d'uso, puoi dichiarare gli strumenti nella richiesta e lasciare che OCI Generative AI coordini l'esecuzione del modello e l'uso degli strumenti.

Il supporto degli strumenti è disponibile solo tramite l'API.

L'esempio riportato di seguito definisce uno strumento MCP nella richiesta.

response = client.responses.create(
    model="openai.gpt-oss-120b",
    tools=[
        {
            "type": "mcp",
            "server_url": "https://example.com/mcp",
        }
    ],
    input="What events are scheduled for 2026-04-02?"
)

In questo esempio, l'API Responses richiama il modello e passa la definizione dello strumento MCP come parte della stessa richiesta. Non è necessaria un'API separata specifica per MCP.

È possibile utilizzare gli elementi di base dell'agente di basso livello con l'API Risposte quando il flusso di lavoro richiede il controllo diretto su file, vector store o container.

Gli esempi comuni includono:

• Caricamento dei file prima di inviare una richiesta modello
• Gestione diretta dei contenuti della memoria di vettore
• Riutilizzo di file o risorse in più richieste
• Utilizzo dei container sandbox come parte di un flusso di lavoro più ampio

La seguente API viene comunemente utilizzata con l'API Risposte:

file_response = client.files.create(
    file=open("example-document.pdf", "rb"),
    purpose="assistants"
)

file_id = file_response.id

response = client.responses.create(
    model="<model-id>",
    input=[
        {
            "role": "user",
            "content": [
                { "type": "input_file", "file_id": file_id },
                { "type": "input_text", "text": "List all the cities mentioned in this document." }
            ]
        }
    ]
)

È possibile utilizzare l'API Risposte OCI con OpenAI SDK. È inoltre possibile utilizzarlo con framework agente lato client compatibili.

OpenAI SDK supporta i seguenti linguaggi:

• Python
• Java
• TypeScript
• Esegui
• .NET

Più supporto linguistico è disponibile attraverso le biblioteche della comunità.

I framework degli agenti compatibili includono:

• SDK OpenAI Agents (consigliato)
• SDK Codex OpenAI
• Framework agente Microsoft
• LangChain
• Grafo lingua
• CrewAI
• Generazione automatica
• Indice Lama
• Pidantico

• API conversazioni
• Strumenti API risposte
  • Ricerca file
  • Interprete codice
  • Chiamata funzione
  • Chiamata MCP
• API File
• API Negozi vettoriali
• API container
• Autenticazione
  • Chiavi API OCI Generative AI
  • Autenticazione basata su IAM OCI
• Modelli e aree supportati
• Avvio rapido