API de Respostas do OCI

Use a API de Respostas com os seguintes componentes de criação de agente no OCI Generative AI:

Se necessário, você pode usar os blocos de construção básicos de baixo nível com a API de Respostas.

Use a API de Respostas para:

• Chamar modelos hospedados suportados e modelos importados.
• Envie entradas de texto e imagem e receba saídas de texto.
• Gerar texto ou saídas estruturadas.
• Execute prompts de uma única etapa ou fluxos de trabalho de várias etapas.
• Adicione as ferramentas suportadas na solicitação.
• Transmita respostas de volta para o cliente.
• Usar o estado de conversa gerenciado pelo OCI por meio da API de Conversas.
• Reutilize o histórico de conversas ou as saídas anteriores como contexto para solicitações posteriores.
• Conecte o modelo a sistemas e dados externos por meio de Chamada de Função e Chamada MCP.
• Combine solicitações de modelo com arquivos, armazenamentos de vetores ou contêineres quando necessário.

Isso permite que você comece com um prompt simples e expanda para fluxos de trabalho mais avançados sem alternar para uma API diferente.

Para a maioria dos novos aplicativos, comece com a API de Respostas.

Use-o quando quiser:

• Use uma API para interação de modelo e recursos agentic.
• Adicionar ferramentas suportadas a uma solicitação de modelo.
• Usar histórico de conversas gerenciado pelo OCI.
• Gerar saídas estruturadas.
• Crie fluxos de trabalho que também possam usar arquivos, armazenamentos de vetores ou contêineres quando necessário.

Substitua ${region} por uma região suportada, como us-chicago-1.

Embora o formato de solicitação seja compatível com OpenAI, a autenticação usa credenciais da OCI, as solicitações são roteadas por meio de pontos finais de inferência da OCI Generative AI e os recursos e a execução permanecem na OCI.

Você pode acessar os pontos finais compatíveis com o OCI OpenAI de duas maneiras:

• Chaves de API do OCI Generative AI
• Autenticação baseada no OCI IAM

Use chaves de API para teste e desenvolvimento antecipado. Usar autenticação baseada em IAM para cargas de trabalho de produção e ambientes gerenciados pela OCI.

Antes de chamar a API de Respostas:

• Crie um projeto do OCI Generative AI. As chamadas de API compatíveis com o OCI OpenAI exigem um projeto.
• Configure o cliente com o URL base compatível com o OCI OpenAI.
• Configure a autenticação.
• Use um modelo suportado em uma região suportada.

Para obter as etapas de configuração, consulte Início Rápido, Autenticação e Modelos e Regiões Suportados.

Para chamar a API de Respostas pelo código, recomendamos usar o OpenAI SDK. Consulte o QuickStart.

O exemplo a seguir usa o OpenAI SDK com o ponto final compatível com o OCI OpenAI, uma chave de API do OCI Generative AI e um OCID de projeto:

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)

Neste exemplo:

• base_url aponta para o ponto final compatível com o OCI OpenAI.
• O client.responses.create(...) chama a API de Respostas do OCI.
• O project identifica o projeto do OCI Generative AI para a solicitação.

Para permitir que a OCI gerencie o histórico de conversas em várias turnos, primeiro crie uma conversa:

conversation = client.conversations.create()

Em seguida, inclua o ID da conversa na solicitação da API de Respostas:

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

Use esse padrão quando quiser que o OCI gerencie o estado da conversa entre as solicitações.

Para obter mais informações sobre recursos de memória, consulte API de Conversas, Memória de Curto Prazo, Memória de Longo Prazo e Compação de Memória de Curto Prazo.

A API Respostas suporta workflows ativados por ferramenta por meio da propriedade tools. Para muitos casos de uso, você pode declarar as ferramentas na solicitação e permitir que a OCI Generative AI coordene a execução do modelo e o uso da ferramenta.

O suporte à ferramenta está disponível somente por meio da API.

O exemplo a seguir define uma ferramenta MCP na solicitação:

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?"
)

Neste exemplo, a API de Respostas chama o modelo e passa a definição da ferramenta MCP como parte da mesma solicitação. Você não precisa de uma API específica de MCP separada.

Você pode usar os blocos de construção do agente básico de baixo nível com a API Respostas quando seu workflow precisar de controle direto sobre arquivos, armazenamentos de vetores ou contêineres.

Exemplos comuns incluem:

• Fazendo upload de arquivos antes de enviar uma solicitação de modelo
• Gerenciando o conteúdo do armazenamento de vetores diretamente
• Reutilização de arquivos ou recursos em várias solicitações
• Trabalhando com contêineres sandbox como parte de um fluxo de trabalho mais amplo

A API a seguir é comumente usada com a API de Respostas:

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." }
            ]
        }
    ]
)

Você pode usar a API de Respostas do OCI com o OpenAI SDK. Você também pode usá-lo com estruturas de agente compatíveis do lado do cliente.

O OpenAI SDK suporta estes idiomas:

• Python
• Java
• TypeScript
• Go
• .NET

Mais suporte a idiomas está disponível através de bibliotecas comunitárias.

As estruturas de agentes compatíveis incluem:

• SDK de Agentes OpenAI (recomendado)
• OpenAI Codex SDK
• Estrutura do Microsoft Agent
• LangChain
• LangGraph
• IA da Equipe
• Geração Automática
• LamaÍndice
• Pydantic

• API de Conversas
• Ferramentas da API de Respostas
  • Pesquisa de Arquivo
  • Interpretador de códigos
  • Função de chamada
  • Chamada MCP
• API de Arquivos
• API de Lojas de Vetores
• API de Contêineres
• Autenticação
  • Chaves de API do OCI Generative AI
  • Autenticação baseada no OCI IAM
• Modelos e Regiões Suportados
• Início Rápido