Integración con agentes de codificación

Importante

Esta característica se encuentra en su versión beta. Los administradores de cuentas pueden controlar el acceso a esta característica desde la página Vista previa de la consola de la cuenta. Consulte Administrar versiones preliminares de Azure Databricks.

Con la integración del agente de codificación de Azure Databricks, puede enrutar el tráfico desde agentes de codificación como Cursor, Cli de Gemini y cli del Codex a través de servicios de modelo en Unity AI Gateway. Esto ofrece limitación de tasa, seguimiento del uso y tablas de inferencia, con todos los controles configurados a nivel de servicio de modelo, usuario o grupo.

Features

Acceso: acceso directo a varias herramientas y modelos de codificación, todos en una sola factura.
Observabilidad: un único panel unificado para realizar un seguimiento del uso, el gasto y las métricas en todas las herramientas de codificación.
Gobernanza unificada: los administradores pueden administrar los permisos del modelo y los límites de velocidad a través de Unity AI Gateway en el nivel de servicio, usuario o grupo del modelo.

Requirements

Versión preliminar de Unity AI Gateway habilitada para su cuenta. Consulte Administrar versiones preliminares de Azure Databricks.
Un área de trabajo de Azure Databricks en una región compatible con Unity AI Gateway.
Unity Catalog habilitado para su área de trabajo. Consulte Habilitar un área de trabajo para Unity Catalog.

Configuración

La forma más rápida de empezar es con ucode, una CLI de Azure Databricks que instala, autentica y configura los agentes de codificación admitidos con Unity AI Gateway en un comando.

Usar ucode (recomendado)

ucode (CLI de programación de Unity AI Gateway) es el punto de acceso único para ejecutar agentes de programación con Unity AI Gateway. Controla OAuth, escribe el archivo de configuración de cada agente y enruta el tráfico a través de cualquier servidor LLM o MCP que haya registrado. Agentes admitidos:

Paso 1: Instalar ucode

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

Requiere Python 3.12 o posterior y uv.

Paso 2: Abrir un agente de codificación

Ejecute el agente que desee. En el primer inicio, ucode solicita la dirección URL del área de trabajo de Azure Databricks, se autentica y escribe automáticamente el archivo de configuración del agente. Los lanzamientos posteriores van directamente al agente.

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

ucode pasa opciones después del nombre del agente a la herramienta subyacente, por ejemplo:

ucode codex --full-auto

Para configurar varios agentes de codificación al mismo tiempo, ejecute:

ucode configure

Para registrar los servidores MCP de Azure Databricks (funciones de Unity Catalog, AI Search, almacenes SQL y conexiones externas detectadas) en agentes compatibles con MCP:

ucode configure mcp

Para ver el resumen de uso de Unity AI Gateway durante los últimos 7 días:

ucode usage

Para obtener la referencia completa del comando, ejecute:

ucode --help

Dashboard

Después de realizar un seguimiento del uso del agente de codificación a través de Unity AI Gateway, puede ver y supervisar las métricas en el panel integrado.

Para abrir el panel, seleccione Ver panel en la página Puerta de enlace de AI. Esta acción crea un panel preconfigurado con gráficos para el uso de la herramienta de codificación.

Botón Ver el panel

Panel del agente de codificación

Instalación manual

Si prefiere configurar los agentes usted mismo, siga las instrucciones para:

Cursor IDE
Codex CLI
Gemini CLI

Cursor IDE

Para configurar Cursor para usar los servicios de modelos en Unity AI Gateway:

Paso 1: Configuración de la dirección URL base y la clave de API

Abra el cursor y navegue a Configuración>Configuración del Cursor>Modelos>Claves de API.
Habilite Sobrescribir la URL base de OpenAI y escriba la URL:
```
https://<workspace-url>/ai-gateway/cursor/v1
```
Reemplace <workspace-url> por la dirección URL del área de trabajo de Azure Databricks.
Pegue el token de acceso personal de Azure Databricks en el campo OpenAI API Key.

Paso 2: Agregar modelos personalizados

Haga clic en + Agregar modelo personalizado en Configuración del cursor.
Agrega el nombre del servicio de modelo (por ejemplo, system.ai.databricks-claude-opus-4-6) y activa el interruptor.

Nota:

Actualmente, solo se admiten los servicios de modelo proporcionados por Azure Databricks.

Paso 3: Probar la integración

Abra el modo Ask con Cmd+L (macOS) o Ctrl+L (Windows/Linux) y seleccione el modelo.
Enviar un mensaje. Todas las solicitudes ahora se enrutan a través de Azure Databricks.

Codex CLI

Paso 1: Instalación o actualización de la CLI de Codex

Instale o actualice a la CLI de Codex versión 0.118 o posterior:

npm install -g @openai/codex@latest

Paso 2: Crear o actualizar el archivo de configuración del Codex

Cree o edite el archivo de configuración del Codex en ~/.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

Reemplace <workspace-url> por la dirección URL del área de trabajo de Azure Databricks.

Paso 3: Autenticación en el área de trabajo

Nota:

Esto solo debe hacerse una vez. No es necesario volver a autenticarse cada vez que inicie El Codex.

En primer lugar, asegúrese de que tiene instalada la CLI de Azure Databricks. Consulte Instalación o actualización de la CLI de Databricks para obtener instrucciones.

A continuación, autentíquese:

databricks auth login --host <workspace-url>

Reemplace <workspace-url> por la dirección URL del área de trabajo de Azure Databricks.

Paso 4: Iniciar el Códice

codex

Para cambiar el modelo, use /model.

Gemini CLI

Paso 1: Instalación de la versión más reciente de la CLI de Gemini

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

Paso 2: Configurar variables de entorno

Cree un archivo ~/.gemini/.env y agregue la siguiente configuración. Consulte los documentos de autenticación de la CLI de Gemini para obtener más información.

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>

Reemplace <workspace-url> por la dirección URL del área de trabajo de Azure Databricks y <databricks_pat_token> por el token de acceso personal.

Configuración de la recopilación de datos de OpenTelemetry

Azure Databricks admite la exportación de métricas y registros de OpenTelemetry desde agentes de codificación a tablas delta administradas de Unity Catalog. Todas las métricas son datos de serie temporal exportados mediante el protocolo de métricas estándar openTelemetry y los registros se exportan mediante el protocolo de registros de OpenTelemetry.

Requirements

OpenTelemetry en Azure Databricks, habilitada la versión preliminar. Consulte Administrar versiones preliminares de Azure Databricks.

Paso 1: Crear tablas openTelemetry en el catálogo de Unity

Cree tablas administradas de Unity Catalog preconfiguradas con los esquemas de registros y métricas de OpenTelemetry.

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

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

Paso 2: Actualización de las var de env en el agente de codificación

En cualquier agente de codificación con la compatibilidad con métricas openTelemetry habilitadas, configure las siguientes variables de entorno.

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

Paso 3: Ejecutar el agente de codificación.

Los datos deben propagarse a las tablas del Catálogo de Unity en un plazo de 5 minutos.

Pasos siguientes

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-07-02

Integración con agentes de codificación

Features

Requirements

Configuración

Usar ucode (recomendado)

Dashboard

Instalación manual

Cursor IDE

Codex CLI

Gemini CLI

Configuración de la recopilación de datos de OpenTelemetry

Requirements

Paso 1: Crear tablas openTelemetry en el catálogo de Unity

Paso 2: Actualización de las var de env en el agente de codificación

Paso 3: Ejecutar el agente de codificación.

Pasos siguientes

Comentarios

Recursos adicionales