OpenAI e Endpoints Compatíveis

O OpenAIEngine alimenta modelos que implementam o protocolo padrão /chat/completions da OpenAI. Além dos modelos oficiais da OpenAI (como GPT-4o e o3-mini), este motor universal conecta-se diretamente ao xAI Grok, DeepSeek, Groq, servidores de inferência locais (vLLM, LM Studio) e gateways corporativos internos de API.

Predefinições Integradas de ProvedoresCopy Anchor Link

Para minimizar configurações manuais de endpoints, o chatflow-agent inclui predefinições verificadas para os principais provedores compatíveis com OpenAI:

Configurando Modelos Oficiais da OpenAICopy Anchor Link

Para utilizar modelos da OpenAI, forneça sua chave de API via variável de ambiente OPENAI_API_KEY ou diretamente no construtor do agente ou do motor:

import os
from chatflow_agent import Agent, Runner
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine

# Opção 1: Resolução implícita do motor via prefixo do nome do modelo
analyst = Agent(
    name="Analyst",
    model="gpt-4o",
    instructions="Analyze structured operational data.",
)

# Opção 2: Atribuição explícita do provedor
writer = Agent(
    name="Writer",
    provider="openai",
    model="gpt-4o-mini",
    instructions="Draft concise summaries.",
)

# Opção 3: Instanciação explícita do motor com parâmetros customizados
custom_engine = OpenAIEngine(
    api_key=os.environ.get("OPENAI_API_KEY"),
    provider="openai",
    timeout=45.0,
)
senior_agent = Agent(
    name="SeniorAgent",
    model="gpt-4o",
    engine=custom_engine,
    instructions="Review critical business decisions.",
)

Provedores Terceirizados: Groq, DeepSeek e xAI GrokCopy Anchor Link

Conectar-se a provedores de inferência de ultra-baixa latência ou modelos especializados de raciocínio exige apenas especificar o atributo provider ou o prefixo padrão do modelo:

import os
from chatflow_agent import Agent
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine

# Exige a variável de ambiente GROQ_API_KEY
groq_engine = OpenAIEngine(
    provider="groq",
    api_key=os.environ.get("GROQ_API_KEY"),
)

speed_agent = Agent(
    name="SpeedAgent",
    model="llama-3.3-70b-versatile",
    engine=groq_engine,
    instructions="Provide real-time triage responses.",
)

Endpoints Customizados e Gateways PrivadosCopy Anchor Link

Ao conectar-se a instâncias privadas (vLLM, LM Studio, proxies do Azure OpenAI ou LiteLLM), defina um base_url customizado:

from chatflow_agent import Agent
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine

# Gateway de inferência corporativo customizado
gateway_engine = OpenAIEngine(
    base_url="https://ai-gateway.internal.corp/v1",
    api_key="internal-gateway-token",
    timeout=60.0,
)

internal_agent = Agent(
    name="InternalAssistant",
    model="custom-llama-3",
    engine=gateway_engine,
    instructions="Answer queries using internal compliance guidelines.",
)

Regra de Segurança: Prevenção de Vazamento de CredenciaisCopy Anchor Link

# [INCORRETO] Levanta ValueError para proteger sua OPENAI_API_KEY contra vazamento acidental:
# engine = OpenAIEngine(base_url="https://untrusted-proxy.example.com/v1")

# [CORRETO] Forneça credenciais explicitamente para hosts customizados:
engine = OpenAIEngine(
    base_url="https://proxy.example.com/v1",
    api_key="proxy-secret-token",
)

# [CORRETO] Servidor interno sem autenticação:
open_engine = OpenAIEngine(
    base_url="http://192.168.1.100:8000/v1",
    api_key="",
)

Restrições e Normalização de IDs de Chamadas de FerramentaCopy Anchor Link

A OpenAI impõe um limite máximo rigoroso de 40 caracteres para o tool_call_id em respostas de chamada de funções. Em ambientes multiagente onde sessões são transferidas entre diferentes provedores (por exemplo, ferramentas do Anthropic Claude gerando IDs com mais de 40 caracteres), o chatflow-agent garante total conformidade com o protocolo:

1. Truncamento e Hashing: Se uma mensagem histórica contiver um ID de chamada de ferramenta superior a 40 caracteres, o OpenAIEngine o substitui com segurança por um identificador determinístico derivado de SHA-256 (call_ + 24 caracteres hexadecimais).
2. Normalização de Tipos de Esquema: O motor normaliza automaticamente os tipos de parâmetros do JSON Schema (_lowercase_schema_types) mantendo esquemas de propriedades customizadas, garantindo compatibilidade entre diferentes versões dos modelos da OpenAI.

Resolução de ProblemasCopy Anchor Link