---
title: "Pydantic AI com base_url compatível com a OpenAI | BroadRouter"
description: "Rode agentes do Pydantic AI na BroadNet Inference com OpenAIChatModel e OpenAICompatibleProvider, com tool calls, saída estruturada e ajustes de perfil."
url: https://broadrouter.com/pt/guides/pydantic-ai-openai-compatible/
lang: pt-BR
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/guides/pydantic-ai-openai-compatible/) (atualizado em 2026-11-16).

# Usar o Pydantic AI com a BroadNet Inference (OpenAICompatibleProvider)

Atualizado em 2026-11-16

Instale pydantic-ai-slim\[openai\] e crie um OpenAIChatModel com um ID de modelo da BroadNet, como broadnet/glm-5.3, e um OpenAICompatibleProvider com base URL https://inference.broadnet.ai/v1 e a sua chave da BroadNet como chave de API. Passe o modelo para Agent. Use OpenAIChatModel, não o modelo Responses, porque a BroadNet serve chat completions. A documentação do Pydantic AI diz que OpenAIProvider com base\_url é para a própria OpenAI.

O Pydantic AI é um framework Python para agentes criado pelo time do Pydantic. Para um serviço sem provider nativo, a documentação dele manda usar `OpenAICompatibleProvider` com o `base_url` do serviço. A BroadNet Inference serve chat completions padrão em `https://inference.broadnet.ai/v1`, então esse é o caminho. O BroadRouter é o site da própria BroadNet; este guia segue a documentação do Pydantic AI na versão 2.68.

## Instalação

```bash
pip install "pydantic-ai-slim[openai]"
export BROADNET_API_KEY='your-broadnet-key'
```

## Conexão

```python
import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai_compatible import OpenAICompatibleProvider

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider(
        'broadnet',
        base_url='https://inference.broadnet.ai/v1',
        api_key=os.environ['BROADNET_API_KEY'],
    ),
)

agent = Agent(model)
result = agent.run_sync('Give me three names for a Go linting tool.')
print(result.output)
```

Rodar isso já é o teste: se aparecer uma resposta, chave, URL e ID do modelo estão certos.

-   **O primeiro argumento é o ID do modelo** enviado à BroadNet. Use-o exatamente assim, com o prefixo `broadnet/`.
-   **O nome do provider** (aqui, `'broadnet'`) fica registrado em cada resposta. A documentação do Pydantic AI diz para mantê-lo estável, porque ele decide quais dados de respostas anteriores são enviados de volta ao serviço.
-   **Fique no `OpenAIChatModel`.** A documentação do Pydantic AI diz para usar `OpenAIResponsesModel` só se o serviço implementar a Responses API. A BroadNet não a lista.

## Ferramentas e saída estruturada

```python
from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str

agent = Agent(model, output_type=City)
print(agent.run_sync('Which city hosts the Burj Khalifa?').output)
```

Use `broadnet/glm-5.3` ou `broadnet/qwen3.8-27b` para ferramentas e saída estruturada; a documentação da BroadNet lista os dois recursos só para esses dois modelos.

## Quando definir um perfil de modelo

O Pydantic AI escolhe um perfil de requisição a partir do nome do modelo. Se um recurso for ignorado ou rejeitado, a documentação dele manda passar o seu próprio `OpenAIModelProfile`. Duas configurações valem a pena conhecer para a BroadNet:

```python
from pydantic_ai.profiles.openai import OpenAIModelProfile

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider('broadnet', base_url='https://inference.broadnet.ai/v1', api_key=os.environ['BROADNET_API_KEY']),
    profile=OpenAIModelProfile(
        openai_chat_supports_max_completion_tokens=False,  # send max_tokens, the field BroadNet documents
        openai_supports_strict_tool_definition=False,      # only if strict tool schemas are rejected
    ),
)
```

Passe o limite de saída pelas configurações do modelo, por exemplo `agent.run_sync(prompt, model_settings={'max_tokens': 2000})`. No DeepSeek V4.1 Flash, no GLM 5.3 e no Qwen3.8 27B, o raciocínio conta nesse limite.

## Qual modelo escolher

| Agente | Modelo |
| --- | --- |
| Ferramentas, saída estruturada | `broadnet/glm-5.3` |
| Imagens ou texto em árabe, com ferramentas | `broadnet/qwen3.8-27b` |
| Documentos longos, plano de preço fixo | `broadnet/deepseek-v4.1-flash` |
| Crédito inicial gratuito | `broadnet/gemma-4-26b-a4b` (contexto de 32.768 tokens) |

[Preços de todos os modelos](https://broadrouter.com/pt/pricing/).

## Solução de problemas

-   **401.** A chave está errada, expirou ou ficou sem cota.
-   **404 ou modelo não encontrado.** O `base_url` precisa terminar em `/v1`. Confira o ID do modelo. Os modelos pagos exigem uma recarga; o crédito de $5 cobre só `broadnet/gemma-4-26b-a4b` e os dois modelos Transcribe.
-   **Saída vazia ou um loop de retry de validação.** O raciocínio gastou o orçamento de saída. Aumente `max_tokens`. [Por que as respostas voltam vazias](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/).
-   **400 nas definições de ferramentas.** Defina `openai_supports_strict_tool_definition=False` no perfil e use um modelo que a BroadNet lista com ferramentas.
-   **429 ao rodar agentes em paralelo.** Uma chave de pagamento por uso permite 30 requisições por minuto e 4 em andamento. Veja [erros e novas tentativas](https://broadrouter.com/pt/guides/errors-and-retries/).

## Termos neste guia

[Tool calling (chamada de ferramentas)](https://broadrouter.com/pt/glossary/tool-calling/)

Tool calling, também chamado de function calling ou chamada de ferramentas, é um recurso de APIs de LLM em que o modelo devolve um pedido estruturado para executar uma função definida pelo desenvolvedor, com argumentos JSON. A aplicação executa a função e devolve o resultado; o modelo nunca executa código sozinho.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

[Saída estruturada (structured output)](https://broadrouter.com/pt/glossary/structured-output/)

Saída estruturada é um recurso de APIs de LLM que restringe a resposta de um modelo a um formato definido pelo desenvolvedor, normalmente um JSON Schema, para que o código consiga interpretá-la de forma confiável. É mais rigorosa que o JSON mode, que garante um JSON válido, mas não uma estrutura específica.

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Chat Completions API](https://broadrouter.com/pt/glossary/chat-completions-api/)

A Chat Completions API é o endpoint HTTP da OpenAI, POST /v1/chat/completions, que recebe o nome de um modelo e uma lista de mensagens marcadas com papéis e devolve a próxima mensagem do modelo. O formato da requisição e da resposta virou o padrão comum que provedores e SDKs compatíveis com a OpenAI reutilizam.

[Crédito pré-pago (prepaid credit)](https://broadrouter.com/pt/glossary/prepaid-credit/)

Crédito pré-pago é dinheiro adicionado a uma conta de API antes do uso. Cada requisição desconta o próprio custo do saldo e, quando o saldo acaba, as requisições cobradas por uso param até você fazer uma recarga. Ele limita o gasto ao que você já pagou.

## Perguntas frequentes

### Para a BroadNet, uso OpenAIProvider ou OpenAICompatibleProvider?

OpenAICompatibleProvider. A documentação do Pydantic AI diz que o OpenAIProvider também aceita um base\_url, mas ele é para a própria OpenAI ou para um proxy transparente até ela, e presume os modelos e recursos da OpenAI.

### Por que usar OpenAIChatModel e não o modelo OpenAI padrão?

O modelo OpenAI padrão do Pydantic AI usa a Responses API. A BroadNet serve chat completions em /v1/chat/completions, que é o que o OpenAIChatModel chama.

### Ferramentas e saída estruturada funcionam?

Sim, nos modelos que a BroadNet lista com ferramentas e saída estruturada: GLM 5.3 e Qwen3.8 27B. A documentação da BroadNet não lista ferramentas para o DeepSeek V4.1 Flash, então teste antes nele os agentes que usam ferramentas.

### Como faço o Pydantic AI parar de enviar max\_completion\_tokens?

Passe profile=OpenAIModelProfile(openai\_chat\_supports\_max\_completion\_tokens=False) para o OpenAIChatModel. O Pydantic AI passa então a enviar o campo antigo max\_tokens, que é o descrito na referência da API da BroadNet.

## Guias relacionados

-   [Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)
-   [Como usar o LangChain com a BroadNet Inference](https://broadrouter.com/pt/guides/langchain-openai-base-url/)
-   [CrewAI com a BroadNet Inference como endpoint OpenAI personalizado](https://broadrouter.com/pt/guides/crewai-custom-openai-endpoint/)
-   [Por que um modelo de raciocínio devolve uma resposta vazia](https://broadrouter.com/pt/guides/reasoning-tokens-empty-response/)
-   [Todas as ferramentas que funcionam com a BroadNet Inference (em inglês)](https://broadrouter.com/integrations/): SDKs, agentes de programação, interfaces de chat e ferramentas de automação, com as configurações exatas de cada uma

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-pydantic-ai-openai-compatible&utm_content=page-cta) ·

**Fontes**

-   [Documentação do Pydantic AI, Other compatible APIs (Other endpoints, Model profile) (conferido em 2026-11-15)](https://pydantic.dev/docs/ai/models/compatible-apis/)
-   [Documentação do Pydantic AI, modelos da OpenAI (conferido em 2026-11-15)](https://pydantic.dev/docs/ai/models/openai/)
-   [PyPI, pydantic-ai 2.68.0, Python 3.11+ (conferido em 2026-11-15)](https://pypi.org/project/pydantic-ai/)
-   [Referência da API da BroadNet Inference (conferido em 2026-11-15) (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-pydantic-ai-openai-compatible&utm_content=sources)
