Integrar com agentes de codificação

Importante

Esse recurso está em Beta. Os administradores de conta podem controlar o acesso a esse recurso na página Visualizações do console da conta. Consulte Gerenciar prévias do Azure Databricks.

Com a integração do agente de codificação Azure Databricks, você pode gerenciar o acesso e o uso para agentes de codificação, como Cursor, CLI do Gemini e CLI do Codex. Criado no Gateway de IA do Unity, ele fornece limitação de velocidade, rastreamento de uso e tabelas de inferência para suas ferramentas de codificação.

Features

Acesso: acesso direto a várias ferramentas de codificação e modelos, tudo em uma fatura.
Observabilidade: um único painel unificado para acompanhar o uso, os gastos e as métricas em todas as ferramentas de codificação.
Governança unificada: os administradores podem gerenciar permissões de modelo e limites de taxa diretamente por meio do Gateway de IA do Unity.

Requirements

A versão prévia do Gateway de Inteligência Artificial do Unity foi habilitada para a sua conta. Consulte Gerenciar prévias do Azure Databricks.
Um workspace do Azure Databricks em uma região com suporte ao Gateway de IA Unity.
Catálogo do Unity habilitado para seu ambiente de trabalho. Consulte Habilitar um espaço de trabalho no Catálogo do Unity.

Configuração

A maneira mais rápida de começar é com ucode, uma CLI de Azure Databricks que instala, autentica e configura agentes de codificação com suporte com o Gateway de IA do Unity em um comando.

Usar ucode (recomendado)

ucode (A CLI de Codificação do Gateway de IA do Unity) é o único ponto de entrada para executar agentes de codificação no Gateway de IA do Unity. Ele manipula o OAuth, grava o arquivo de configuração de cada agente e roteia o tráfego por meio de qualquer servidor LLM ou MCP que você registrou. Agentes com suporte:

Etapa 1: instalar o ucode

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

Requer Python 3.12 ou superior e uv.

Etapa 2: Abrir um agente de codificação

Execute o agente desejado. Na primeira inicialização, ucode solicita a URL do workspace Azure Databricks, autentica e grava automaticamente o arquivo de configuração do agente. As inicializações 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 sinalizadores após o nome do agente para a ferramenta subjacente, por exemplo:

ucode codex --full-auto

Para configurar vários agentes de codificação ao mesmo tempo, execute:

ucode configure

Para registrar servidores MCP do Azure Databricks (funções do Unity Catalog, Pesquisa Vetorial, SQL warehouses e conexões externas descobertas) em agentes compatíveis com MCP:

ucode configure mcp

Para ver o resumo de uso do Gateway de IA do Unity nos últimos 7 dias:

ucode usage

Para a referência de comando completa, execute:

ucode --help

Dashboard

Depois que o uso do agente de codificação é acompanhado por meio do Gateway de IA do Unity, você pode exibir e monitorar suas métricas no painel interno.

Para abrir o painel, selecione Exibir painel na página Gateway de IA. Essa ação cria um painel pré-configurado com grafos para uso da ferramenta de codificação.

Botão Exibir painel de controle

Painel do agente de codificação

Configuração manual

Se você preferir configurar agentes por conta própria, siga as instruções para:

Cursor IDE
Codex CLI
Gemini CLI

Cursor IDE

Para configurar o Cursor para usar endpoints do AI Gateway do Unity:

Etapa 1: Configurar a URL base e a chave de API

Abra o Cursor e navegue até Configurações>Configurações de Cursor>Modelos>Chaves de API.
Ative a opção Substituir URL Base do OpenAI e insira a URL:
```
https://<workspace-url>/ai-gateway/cursor/v1
```
Substitua <workspace-url> pela URL do workspace Azure Databricks.
Cole seu token de acesso pessoal Azure Databricks no campo OpenAI API Key.

Etapa 2: Adicionar modelos personalizados

Clique em + Adicionar Modelo Personalizado nas Configurações do Cursor.
Adicione o nome do ponto de extremidade do Gateway de IA do Unity e ative o botão de alternância.

Observação

Atualmente, somente há suporte para pontos de extremidade de modelos fundamentais criados pelo Azure Databricks.

Etapa 3: Testar a integração

Abra o modo Ask com Cmd+L (macOS) ou Ctrl+L (Windows/Linux) e selecione seu modelo.
Envie uma mensagem. Todas as solicitações agora passam por Azure Databricks.

Codex CLI

Etapa 1: Instalar ou atualizar a CLI do Codex

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

npm install -g @openai/codex@latest

Etapa 2: Criar ou atualizar o arquivo de configuração codex

Crie ou edite o arquivo 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> pela URL do workspace Azure Databricks.

Etapa 3: Autenticar no espaço de trabalho

Observação

Isso só precisa ser feito uma vez. Você não precisa se autenticar novamente sempre que iniciar o Codex.

Primeiro, verifique se você tem a CLI do Azure Databricks instalada. Consulte Instalar ou atualizar a CLI do Databricks para obter instruções.

Em seguida, autentique:

databricks auth login --host <workspace-url>

Substitua <workspace-url> pela URL do workspace Azure Databricks.

Etapa 4: Iniciar Codex

codex

Para alterar o modelo, use /model.

Gemini CLI

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

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

Etapa 2: Configurar variáveis de ambiente

Crie um arquivo ~/.gemini/.env e adicione a configuração a seguir. Consulte os documentos de autenticação da CLI do Gemini para obter 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> pela URL do workspace Azure Databricks e <databricks_pat_token> pelo token de acesso pessoal.

Configurar a coleta de dados OpenTelemetry

Azure Databricks dá suporte à exportação de métricas e logs do OpenTelemetry de agentes de instrumentação para tabelas Delta gerenciadas no Unity Catalog. Todas as métricas são dados de série temporal exportados usando o protocolo de métricas padrão OpenTelemetry e os logs são exportados usando o protocolo de logs OpenTelemetry.

Requirements

OpenTelemetry no Azure Databricks com a versão prévia habilitada. Consulte Gerenciar prévias do Azure Databricks.

Etapa 1: Criar tabelas OpenTelemetry no Catálogo do Unity

Crie tabelas gerenciadas do 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 Registros

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'
)

Etapa 2: atualizar o env vars em seu agente de codificação

Em qualquer agente de codificação com suporte à métrica OpenTelemetry habilitado, configure as variáveis de ambiente a seguir.

{
  "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"
}

Etapa 3: executar o agente de codificação.

Seus dados devem se propagar para as tabelas do Catálogo do Unity dentro de 5 minutos.

Próximas etapas

Comentários

Esta página foi útil?

Last updated on 2026-06-01

Integrar com agentes de codificação

Features

Requirements

Configuração

Usar ucode (recomendado)

Dashboard

Configuração manual

Cursor IDE

Codex CLI

Gemini CLI

Configurar a coleta de dados OpenTelemetry

Requirements

Etapa 1: Criar tabelas OpenTelemetry no Catálogo do Unity

Etapa 2: atualizar o env vars em seu agente de codificação

Etapa 3: executar o agente de codificação.

Próximas etapas

Comentários

Recursos adicionais