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 visualizações do Azure Databricks.

Com a integração do agente de codificação Azure Databricks, você pode rotear o tráfego de agentes de codificação como Cursor, CLI do Gemini e CLI do Codex por meio de serviços de modelo no Gateway de IA do Unity. Isso fornece limitação de taxa, rastreamento de uso e tabelas de inferência — com todos os controles configurados no nível do serviço de modelo, do usuário ou do grupo.

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 por meio do Gateway de IA do Unity no nível de serviço de modelo, usuário ou grupo.

Requirements

A versão prévia do Gateway de Inteligência Artificial do Unity foi habilitada para a sua conta. Consulte Gerenciar visualizações 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 workspace. Consulte Habilitar um workspace para o Unity Catalog.

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 os servidores MCP do Azure Databricks (funções do Unity Catalog, AI Search, 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, clique em Controlar no canto superior direito da página gateway de IA do Unity e clique em Painel de Uso. O painel de uso interno inclui uma guia Agentes de Codificação com grafos para uso da ferramenta de codificação.

Painel do agente de codificação

Instalação manual

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

Cursor IDE
Codex CLI
GMINI CLI

Cursor IDE

Para configurar o Cursor para usar serviços de modelo no Gateway de IA 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 Substituir URL Base do OpenAI e insira o URL:
```
https://<workspace-url>/ai-gateway/cursor/v1
```
Substitua <workspace-url> pela URL do workspace Azure Databricks.
Cole o token de acesso pessoal do Azure Databricks no campo Chave de API OpenAI .

Etapa 2: Adicionar modelos personalizados

Clique em + Adicionar Modelo Personalizado nas Configurações do Cursor.
Adicione o nome do serviço do seu modelo (por exemplo, system.ai.databricks-claude-opus-4-6) e ative a opção.

Note

Atualmente, há suporte apenas para serviços de modelo fornecidos por 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

Note

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.

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

Use modelos de código aberto com agentes de codificação

O Azure Databricks suporta a integração de modelos código aberto (OSS), como glm-5-2, com agentes de codificação.

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

OpenCode

Configure ucode conforme descrito em Usar ucode (recomendado) e, em seguida, selecione system.ai.glm-5-2 como modelo.

Configuração manual

Alternativamente, você 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 workspace do Azure Databricks.
<databricks_pat_token> com seu token de acesso pessoal.
<código aberto model service name> com o serviço do modelo OSS de destino, por exemplo, system.ai.glm-5-2.

Então comece o OpenCode:

opencode

Codex

A Codex conecta-se a modelos Open Source por meio da API Open Responses que a Codex suporta.

Configure ucode conforme descrito em Use ucode (recomendado), então 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

Alternativamente, você pode instalar a CLI do Codex conforme descrito no Codex CLI, então 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 <código aberto model service name> pelo serviço de modelo OSS de destino, system.ai.glm-5-2por exemplo.

Então comece o Codex:

codex

Configurar a coleta de dados OpenTelemetry

O Azure Databricks oferece suporte à exportação de métricas e logs do OpenTelemetry de agentes de codificação para tabelas Delta gerenciadas pelo 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 habilitada na versão de prévia do Azure Databricks. Consulte Gerenciar visualizações 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-07-29

Integrar com agentes de codificação

Features

Requirements

Configuração

Usar ucode (recomendado)

Dashboard

Instalação manual

Cursor IDE

Codex CLI

GMINI CLI

Use modelos de código aberto com agentes de codificação

OpenCode

Codex

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