Integrar com agentes de codificação

Importante

Este recurso está em versão Beta. Os administradores de conta podem controlar o acesso a esta funcionalidade a partir da página de Pré-visualizações da consola da conta. Ver Gerir as pré-visualizações de Azure Databricks.

Com a integração do agente de codificação do Azure Databricks, pode encaminhar o tráfego de agentes de codificação como Cursor, Gemini CLI e Codex CLI através de serviços de modelo no Unity AI Gateway. Isto fornece tabelas de limitação de taxa, rastreamento de utilização e inferência—com todos os controlos configurados ao nível do serviço-modelo, utilizador ou grupo.

Features

Acesso: Acesso direto a várias ferramentas e modelos de codificação, tudo sob uma única fatura.
Observabilidade: Um painel unificado único para acompanhar o uso, os gastos e as métricas em todas as suas ferramentas de programação.
Governação unificada: Os administradores podem gerir permissões de modelo e limites de taxa através do Unity AI Gateway ao nível do serviço, utilizador ou grupo.

Requirements

Pré-visualização do Unity AI Gateway ativada para a sua conta. Ver Gerir as pré-visualizações de Azure Databricks.
Um espaço de trabalho Azure Databricks numa região suportada por Unity AI Gateway.
Unity Catalog ativado para o seu espaço de trabalho. Consulte Habilitar um espaço de trabalho para o Unity Catalog.

Configuração

A forma mais rápida de começar é com ucode, uma CLI da Azure Databricks que instala, autentica e configura agentes de codificação suportados com o Unity AI Gateway num só comando.

Utilize o ucode (recomendado)

ucode (Unity AI Gateway Coding CLI) é o único ponto de entrada para executar agentes de codificação contra o Unity AI Gateway. Trata do OAuth, escreve o ficheiro de configuração de cada agente e encaminha o tráfego através de qualquer servidor LLM ou MCP que tenha registado. Agentes apoiados:

Passo 1: Instalar o ucode

uv tool install git+https://github.com/databricks/ucode

Requer o Python 3.12 ou superior e uv.

Passo 2: Abrir um agente de codificação

Procura o agente que quiseres. No primeiro lançamento, o ucode solicita o URL do seu Azure Databricks workspace, autentica e escreve automaticamente o ficheiro de configuração do agente. Os lançamentos subsequentes vão diretamente para o agente.

ucode codex      # OpenAI Codex
ucode gemini     # Gemini CLI
ucode opencode   # OpenCode
ucode copilot    # GitHub Copilot CLI
ucode pi         # Pi

ucode Passa flags após o nome do agente para a ferramenta subjacente, por exemplo:

ucode codex --full-auto

Para configurar múltiplos agentes de codificação ao mesmo tempo, execute:

ucode configure

Para registar servidores Azure Databricks MCP (funções do Unity Catalog, AI Search, SQL warehouses e conexões externas descobertas) com agentes compatíveis com MCP:

ucode configure mcp

Para ver o resumo de utilização do seu Unity AI Gateway nos últimos 7 dias:

ucode usage

Para a referência completa do comando, execute:

ucode --help

Dashboard

Depois de o uso do agente de codificação ser acompanhado através do Unity AI Gateway, pode visualizar e monitorizar as suas métricas no painel de controlo incorporado.

Para abrir o painel, selecione Ver painel na página do AI Gateway. Esta ação cria um painel pré-configurado com gráficos para utilização de ferramentas de programação.

Ver botão do painel de instrumentos

Painel de agentes de codificação

Configuração manual

Se preferir configurar os agentes por si próprio, siga as instruções para:

Cursor IDE
Codex CLI
Gemini CLI

Cursor IDE

Para configurar o Cursor para usar serviços de modelo no Unity AI Gateway:

Passo 1: Configurar URL base e chave API

Abra o Cursor e navegue até Definições>Definições do Cursor>Modelos>Chaves API.
Ative Override OpenAI Base URL e introduza o URL:
```
https://<workspace-url>/ai-gateway/cursor/v1
```
Substitua <workspace-url> pelo URL do seu Azure Databricks espaço de trabalho.
Cole o seu token de acesso pessoal Azure Databricks no campo OpenAI API Key .

Passo 2: Adicionar modelos personalizados

Clique + Adicionar Modelo Personalizado nas Definições do cursor.
Adiciona o nome do teu serviço de modelo (por exemplo, system.ai.databricks-claude-opus-4-6) e ativa a opção de alternar.

Note

Atualmente, apenas os serviços de modelo fornecidos pelo Azure Databricks são suportados.

Passo 3: Testar a integração

Abre o modo Ask com Cmd+L (macOS) ou Ctrl+L (Windows/Linux) e seleciona o teu modelo.
Envia uma mensagem. Todos os pedidos agora são encaminhados através do Azure Databricks.

Codex CLI

Passo 1: Instalar ou atualizar a CLI do Codex

Instalar ou atualizar para a versão 0.118 da CLI Codex ou posterior:

npm install -g @openai/codex@latest

Passo 2: Criar ou atualizar o ficheiro de configuração do Codex

Criar ou editar o ficheiro de configuração do Codex em ~/.codex/config.toml:

profile = "default"

[profiles.default]
model_provider = "Databricks"

[model_providers.Databricks]
name = "Databricks :re[ai-gateway]"
base_url = "<workspace-url>/ai-gateway/codex/v1"
wire_api = "responses"

[model_providers.Databricks.auth]
command = "sh"
args = ["-c", "databricks auth token --host <workspace-url> --output json | jq -r '.access_token'"]
timeout_ms = 5000
refresh_interval_ms = 1800000

Substitua <workspace-url> pelo URL do seu Azure Databricks espaço de trabalho.

Passo 3: Autenticar-se no seu espaço de trabalho

Note

Só precisa de fazer isto uma vez. Não precisas de autenticar novamente sempre que inicias o Codex.

Primeiro, certifique-se de que tem a CLI do Azure Databricks instalada. Consulte Instalar ou atualizar a CLI do Databricks para obter instruções.

Depois autentica:

databricks auth login --host <workspace-url>

Substitua <workspace-url> pelo URL do seu Azure Databricks espaço de trabalho.

Passo 4: Iniciar o Codex

codex

Para mudar o modelo, use /model.

Gemini CLI

Passo 1: Instalar a versão mais recente da Gemini CLI

npm install -g @google/gemini-cli@nightly

Passo 2: Configurar variáveis de ambiente

Crie um ficheiro ~/.gemini/.env e adicione a seguinte configuração. Consulte a documentação de autenticação da CLI Gemini para mais detalhes.

GEMINI_MODEL=databricks-gemini-2-5-flash
GOOGLE_GEMINI_BASE_URL=https://<workspace-url>/ai-gateway/gemini
GEMINI_API_KEY_AUTH_MECHANISM="bearer"
GEMINI_API_KEY=<databricks_pat_token>

Substitua <workspace-url> pelo URL do seu Azure Databricks workspace e <databricks_pat_token> pelo seu token de acesso pessoal.

Configurar a recolha de dados OpenTelemetry

O Azure Databricks suporta a exportação de métricas e logs do OpenTelemetry de agentes de codificação para tabelas Delta geridas pelo Unity Catalog. Todas as métricas são dados de séries temporais exportadas usando o protocolo padrão de métricas OpenTelemetry, e os registos são exportados usando o protocolo de registos OpenTelemetry.

Requirements

O OpenTelemetry na pré-visualização do Azure Databricks está ativado. Ver Gerir as pré-visualizações de Azure Databricks.

Passo 1: Criar tabelas OpenTelemetry no Catálogo Unity

Crie tabelas geridas no Unity Catalog pré-configuradas com os esquemas de métricas e logs do OpenTelemetry.

Tabela de métricas

CREATE TABLE <catalog>.<schema>.<table_prefix>_otel_metrics (
  name STRING,
  description STRING,
  unit STRING,
  metric_type STRING,
  gauge STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT
  >,
  sum STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    value: DOUBLE,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT,
    aggregation_temporality: STRING,
    is_monotonic: BOOLEAN
  >,
  histogram STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    bucket_counts: ARRAY<LONG>,
    explicit_bounds: ARRAY<DOUBLE>,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT,
    min: DOUBLE,
    max: DOUBLE,
    aggregation_temporality: STRING
  >,
  exponential_histogram STRUCT<
    attributes: MAP<STRING, STRING>,
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    scale: INT,
    zero_count: LONG,
    positive_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    negative_bucket: STRUCT<
      offset: INT,
      bucket_counts: ARRAY<LONG>
    >,
    flags: INT,
    exemplars: ARRAY<STRUCT<
      time_unix_nano: LONG,
      value: DOUBLE,
      span_id: STRING,
      trace_id: STRING,
      filtered_attributes: MAP<STRING, STRING>
    >>,
    min: DOUBLE,
    max: DOUBLE,
    zero_threshold: DOUBLE,
    aggregation_temporality: STRING
  >,
  summary STRUCT<
    start_time_unix_nano: LONG,
    time_unix_nano: LONG,
    count: LONG,
    sum: DOUBLE,
    quantile_values: ARRAY<STRUCT<
      quantile: DOUBLE,
      value: DOUBLE
    >>,
    attributes: MAP<STRING, STRING>,
    flags: INT
  >,
  metadata MAP<STRING, STRING>,
  resource STRUCT<
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  metric_schema_url STRING
) USING DELTA
TBLPROPERTIES (
  'otel.schemaVersion' = 'v1'
)

Tabela de registos

CREATE TABLE <catalog>.<schema>.<table_prefix>_otel_logs (
  event_name STRING,
  trace_id STRING,
  span_id STRING,
  time_unix_nano LONG,
  observed_time_unix_nano LONG,
  severity_number STRING,
  severity_text STRING,
  body STRING,
  attributes MAP<STRING, STRING>,
  dropped_attributes_count INT,
  flags INT,
  resource STRUCT<
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  resource_schema_url STRING,
  instrumentation_scope STRUCT<
    name: STRING,
    version: STRING,
    attributes: MAP<STRING, STRING>,
    dropped_attributes_count: INT
  >,
  log_schema_url STRING
) USING DELTA
TBLPROPERTIES (
  'otel.schemaVersion' = 'v1'
)

Passo 2: Atualize as variações ambientais no seu agente de codificação

Em qualquer agente de codificação com suporte para métricas OpenTelemetry ativado, configure as seguintes variáveis de ambiente.

{
  "OTEL_METRICS_EXPORTER": "otlp",
  "OTEL_EXPORTER_OTLP_METRICS_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_METRICS_ENDPOINT": "https://<workspace-url>/api/2.0/otel/v1/metrics",
  "OTEL_EXPORTER_OTLP_METRICS_HEADERS": "content-type=application/x-protobuf,Authorization=Bearer <databricks_pat_token>,X-Databricks-UC-Table-Name=<catalog>.<schema>.<table_prefix>_otel_metrics",
  "OTEL_METRIC_EXPORT_INTERVAL": "10000",
  "OTEL_LOGS_EXPORTER": "otlp",
  "OTEL_EXPORTER_OTLP_LOGS_PROTOCOL": "http/protobuf",
  "OTEL_EXPORTER_OTLP_LOGS_ENDPOINT": "https://<workspace-url>/api/2.0/otel/v1/logs",
  "OTEL_EXPORTER_OTLP_LOGS_HEADERS": "content-type=application/x-protobuf,Authorization=Bearer <databricks_pat_token>,X-Databricks-UC-Table-Name=<catalog>.<schema>.<table_prefix>_otel_logs",
  "OTEL_LOGS_EXPORT_INTERVAL": "5000"
}

Passo 3: Executa o teu agente de programação.

Os seus dados devem propagar-se para as tabelas do Catálogo Unity em 5 minutos.

Passos seguintes

Comentários

Esta página foi útil?

Last updated on 2026-07-02

Integrar com agentes de codificação

Features

Requirements

Configuração

Utilize o ucode (recomendado)

Dashboard

Configuração manual

Cursor IDE

Codex CLI

Gemini CLI

Configurar a recolha de dados OpenTelemetry

Requirements

Passo 1: Criar tabelas OpenTelemetry no Catálogo Unity

Passo 2: Atualize as variações ambientais no seu agente de codificação

Passo 3: Executa o teu agente de programação.

Passos seguintes

Comentários

Recursos adicionais