Integre com agentes de codificação
Beta
Este recurso está em Beta. Administradores de conta podem controlar o acesso a este recurso na página Prévias do console da conta. Consulte Gerenciar prévias do Databricks.
Com a integração de agentes de codificação do Databricks, você pode rotear o tráfego de agentes de codificação como Cursor, Gemini CLI e Codex CLI por meio de serviços de modelo no Unity AI Gateway. Isso oferece limitação de taxa, acompanhamento de uso e tabelas de inferência — com todos os controles configurados no nível do serviço de modelo, usuário ou grupo.
recurso
- Acesso : acesso direto a várias ferramentas de codificação e modelos, tudo em uma única fatura.
- **Observabilidade**: Um único dashboard unificado para rastrear uso, gastos e métricas em todas as suas ferramentas de codificação.
- **Governança unificada**: os administradores podem gerenciar as permissões do modelo e os limites de taxa por meio do Unity AI Gateway no nível de serviço de modelo, usuário ou grupo.
Requisitos
- Prévia do Unity AI Gateway ativada para sua account. Consulte Gerenciar prévias do Databricks.
- Um workspace do Databricks em uma região suportada pelo Unity AI Gateway.
- Unity Catalog habilitado para seu workspace. Consulte Ativar um workspace para o Unity Catalog.
Configuração
A maneira mais rápida de começar é com ucode, uma CLI da Databricks que instala, autentica e configura agentes de codificação suportados com o Unity AI Gateway em um comando.
Use o ucode (recomendado)
ucode (Unity AI Gateway Coding CLI) é o ponto de entrada único para executar agentes de codificação contra o Unity AI Gateway. Ele lida com OAuth, escreve o arquivo de configuração de cada agente e roteia o tráfego por meio de qualquer LLM ou servidor MCP que você tenha registrado. Agentes compatíveis:
Etapa 1: Instale o ucode
uv tool install git+https://github.com/databricks/ucode
Requer Python 3.12 ou posterior e uv.
O passo 2: Abrir um agente de codificação
Realize a execução do agente desejado. Na primeira execução, ucode solicita a URL do seu workspace do Databricks, autentica e grava o arquivo de configuração do agente automaticamente. Os lançamentos subsequentes vão direto 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, realize a execução:
ucode configure
Para realizar o registro de servidores MCP do Databricks (funções do Unity Catalog, pesquisa de AI, SQL warehouse e conexões externas descobertas) com agentes compatíveis com MCP:
ucode configure mcp
Para ver o resumo de uso do Unity AI Gateway nos últimos 7 dias:
ucode usage
Para a referência completa do comando, execute:
ucode --help
Painel
Após o uso do agente de codificação ser acompanhado pelo Unity AI Gateway, você pode view e monitorar suas métricas no dashboard integrada.
Para abrir o painel, selecione **view painel** na página do AI Gateway. Essa ação cria um painel pré-configurado com gráficos para o uso de ferramentas de codificação.
Configuração manual
Se preferir configurar agentes por conta própria, siga as instruções para:
Cursor IDE
Para configurar o Cursor para usar serviços de modelo no Unity AI Gateway:
O passo 1: Configure a URL base e a key API
-
Abra o Cursor e navegue até Configurações > Configurações do Cursor > Modelos > Chaves de API .
-
Habilite Substituir URL Base da OpenAI e insira a URL:
https://<workspace-url>/ai-gateway/cursor/v1Substitua
<workspace-url>pelo URL do seu workspace do Databricks. -
Cole seu access token pessoal do Databricks no campo key da API OpenAI .
O passo 2: Adicionar modelos personalizados
- Clique em + Adicionar Modelo Personalizado nas Configurações do Cursor.
- Adicione o nome do seu serviço de modelo (por exemplo,
system.ai.databricks-claude-opus-4-6) e ative o botão.
Atualmente, somente os serviços de modelo fornecidos pelo Databricks são suportados.
O passo 3: Testar a integração
- Abra o modo de Perguntar com
Cmd+L(macOS) ouCtrl+L(Windows/Linux) e selecione seu modelo. - Envie uma mensagem. Todas as solicitações agora são roteadas por meio do Databricks.
CLI do Codex
O passo 1: Instale ou atualize a CLI do Codex
Instale ou atualize para a versão 0.118 ou posterior da CLI do Codex:
npm install -g @openai/codex@latest
O passo 2: Criar ou atualizar o arquivo de configuração do 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> pelo URL do seu workspace do Databricks.
O passo 3: Autentique-se no seu workspace
Isso só precisa ser feito uma vez. Não é necessário autenticar-se novamente cada vez que começar o Codex.
Primeiro, certifique-se de ter a CLI do Databricks instalada. Consulte Instalar ou atualizar a CLI do Databricks para obter instruções.
Em seguida, autentique-se:
databricks auth login --host <workspace-url>
Substitua <workspace-url> pelo URL do seu workspace do Databricks.
O passo 4: Comece o Codex
codex
Para alterar o modelo, use /model.
Gemini CLI
O passo 1: Instale a versão mais recente do Gemini CLI
npm install -g @google/gemini-cli@nightly
O passo 2: Configurar variáveis de ambiente
Crie um arquivo ~/.gemini/.env e adicione a seguinte configuração. Consulte a documentação de autenticação do Gemini CLI 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> pelo URL do seu workspace do Databricks e <databricks_pat_token> pelo seu access token pessoal.
Configurar a coleta de dados do OpenTelemetry
A Databricks oferece suporte à exportação de métricas e log 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 log são exportados usando o protocolo de log OpenTelemetry.
Requisitos
- Prévia do OpenTelemetry no Databricks ativada. Consulte Gerenciar prévias do Databricks.
O passo 1: Crie tabelas OpenTelemetry no Unity Catalog
Crie tabelas gerenciados do Unity Catalog pré-configuradas com os esquemas de métricas e log 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 log
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'
)
O passo 2: Atualizar variáveis de ambiente em seu agente de codificação
Em qualquer agente de codificação com suporte a métricas OpenTelemetry habilitado, 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: realize a execução do seu agente de codificação.
Seus dados devem ser propagados para as tabelas do Unity Catalog em 5 minutos.