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:

• Codex CLI
• Gemini CLI
• OpenCode
• GitHub Copilot CLI
• Pi
• e muito mais

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, clique em Governar no canto superior direito da página do Unity AI Gateway e depois clique em Painel de Utilização. O painel de utilização incorporado inclui um separador de Agentes de Codificação com gráficos para utilização de ferramentas de programaçã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

1. Abra o Cursor e navegue até Definições>Definições do Cursor>Modelos>Chaves API.

2. 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.

3. Cole o seu token de acesso pessoal Azure Databricks no campo OpenAI API Key .

Passo 2: Adicionar modelos personalizados

1. Clique + Adicionar Modelo Personalizado nas Definições do cursor.
2. 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

1. Abre o modo Ask com Cmd+L (macOS) ou Ctrl+L (Windows/Linux) e seleciona o teu modelo.
2. 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.

Utilizar modelos Open Source com agentes de codificação

O Azure Databricks suporta a integração de modelos open source (OSS), como glm-5-2, com agentes de programação.

Para além dos requisitos acima, o seu espaço de trabalho deve também ter acesso ao modelo OSS alvo.

OpenCode

Configura ucode conforme descrito em Use ucode (recomendado) e depois selecione system.ai.glm-5-2 como modelo.

Configuração manual

Alternativamente, pode instalar o OpenCode conforme descrito na documentação do OpenCode, depois criar ou editar ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "databricks-oss/<open source model service name>",
  "provider": {
    "databricks-oss": {
      "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "<workspace-url>/ai-gateway/mlflow/v1",
        "apiKey": "<databricks_pat_token>"
      },
      "models": {
        "<open source model service name>": {}
      }
    }
  }
}

Substitua o seguinte:

• <workspace-url> com a URL do seu espaço de trabalho Azure Databricks.
• <databricks_pat_token> com o seu token de acesso pessoal.
• <open source model service name> com o serviço OSS do modelo de destino, por exemplo system.ai.glm-5-2.

Depois começa o OpenCode:

opencode

Codex

A Codex liga-se a modelos Open Source através da API Open Responses que a Codex suporta.

Configure ucode conforme descrito em Use ucode (recomendado), depois execute:

ucode codex --model <open source model service name>

Por exemplo, para usar o GLM 5.2 com o Codex, execute:

ucode codex --model system.ai.glm-5-2

Configuração manual

Em alternativa, pode instalar a CLI do Codex conforme descrito no Codex CLI, depois criar ou editar ~/.codex/config.toml:

model = "<open source model service name>"
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'"]
# Re-run the token command periodically so long sessions don't fail when the
# short-lived Databricks token expires.
timeout_ms = 5000
refresh_interval_ms = 1800000

Substitua <workspace-url> pelo URL do seu workspace do Azure Databricks e <open source model service name> pelo serviço de modelo OSS de destino, system.ai.glm-5-2por exemplo.

Depois, inicie o Codex:

codex

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

• Serviços modelo
• Criar e gerir serviços modelo
• Serviços de modelo de consulta
• Descubra e regule o acesso a serviços modelo