Integre com agentes de codificação
Beta
Este recurso está em versão Beta. Os administradores da conta podem controlar o acesso a este recurso na página de pré-visualizações do console account . Veja as prévias do Gerenciador Databricks.
Com a integração de agente de codificação Databricks, você pode rotear o tráfego de agentes de codificação como Cursor, Gemini CLI e Codex CLI por meio de endpoints do 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 endpoint, usuário ou grupo.
recurso
- Acesso : Acesso direto a diversas ferramentas e modelos de codificação, tudo em uma única fatura.
- Observabilidade : Um painel único e unificado para monitorar o uso, os gastos e as métricas em todas as suas ferramentas de programação.
- Governança unificada: administradores podem gerenciar permissões de modelos e limites de taxa por meio do Unity AI Gateway no nível de endpoint, usuário ou grupo.
Requisitos
- A pré-visualização do Unity AI Gateway foi ativada para sua account. Veja as prévias do Gerenciador Databricks.
- Um workspace Databricks em uma região compatível com o Unity AI Gateway.
- Unity Catalog está habilitado para seu workspace. Consulte Ativar um workspace para Unity Catalog.
Configurar
A maneira mais rápida de começar é com ucode, uma CLI da Databricks que instala, autentica e configura agentes de codificação compatíveis com o Unity AI Gateway em um único comando.
Usar ucode (recomendado)
ucode (Unity AI Gateway Coding CLI) é o ponto de entrada único para executar agentes de codificação no Unity AI Gateway. Ele gerencia o OAuth, grava o arquivo de configuração de cada agente e encaminha o tráfego por meio de qualquer servidor LLM ou MCP que você tenha registrado. Agentes suportados:
o passo 1: Instalar ucode
uv tool install git+https://github.com/databricks/ucode
Requer Python 3.12 ou posterior e uv.
o passo 2: Abra um agente de codificação
execução do agente que você deseja. Na primeira execução, ucode solicita o URL do seu workspace Databricks , autentica e grava automaticamente o arquivo de configuração do agente. Os lançamentos subsequentes são enviados diretamente ao 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 simultaneamente, execute o seguinte comando:
ucode configure
Para registro servidores MCP do Databricks (funções do Unity Catalog, Pesquisa de AI, SQL warehouses e conexões externas descobertas) com agentes compatíveis com MCP:
ucode configure mcp
Para ver o resumo de utilização do Unity AI Gateway nos últimos 7 dias:
ucode usage
Para a referência completa do comando, execução:
ucode --help
Painel
Após o uso do agente de codificação ser rastreado pelo Unity AI Gateway, você pode view e monitorar suas métricas no painel integrado.
Para abrir o painel de controle, selecione " Exibir painel de controle" na página do AI Gateway. Esta ação cria um painel pré-configurado com elementos gráficos para uso de ferramentas de codificação.
Configuração manual
Se preferir configurar os agentes você mesmo, siga as instruções para:
IDE do Cursor
Para configurar o Cursor para usar o endpoint do Unity AI Gateway:
Passo 1: Configurar URL base e key API
-
Abra o Cursor e navegue até Configurações > Configurações do Cursor > Modelos > ChaveAPI .
-
Ative a opção "Substituir URL base do OpenAI" e insira o URL:
https://<workspace-url>/ai-gateway/cursor/v1Substitua
<workspace-url>pela URL do seu workspace Databricks . -
Cole seu access token pessoal Databricks no campo da chave API OpenAI .
o passo 2: Adicionar modelos personalizados
- Clique em + Adicionar modelo personalizado nas configurações do cursor.
- Adicione o nome do endpoint do seu Unity AI Gateway e ative a opção.
Atualmente, apenas os endpoints do modelo de base criados Databrickssão suportados.
o passo 3: Teste a integração
- Abra o modo Ask com
Cmd+L(macOS) ouCtrl+L(Windows/Linux) e selecione seu modelo. - Enviar uma mensagem. Todas as solicitações agora são encaminhadas pelo Databricks.
Codex CLI
Passo 1: Instale ou atualize CLIdo Codex
Instale ou atualize para a versão 0.118 ou posterior do Codex CLI:
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> pela URL do seu workspace Databricks .
o passo 3: Autentique-se no seu workspace
Isso só precisa ser feito uma vez. Você não precisa se autenticar novamente toda vez que iniciar o Codex.
Primeiro, certifique-se de ter o Databricks CLI instalado. Consulte a seção Instalar ou atualizar a CLI do Databricks para obter instruções.
Em seguida, autentique-se:
databricks auth login --host <workspace-url>
Substitua <workspace-url> pela URL do seu workspace Databricks .
o passo 4: começar Codex
codex
Para alterar o modelo, use /model.
Gemini CLI
Passo 1: Instale a versão mais recente do Gemini CLI
npm install -g @google/gemini-cli@nightly
o passo 2: Configurar variável de ambiente
Crie um arquivo ~/.gemini/.env e adicione a seguinte configuração. Consulte a documentação 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> pelo URL do seu workspace Databricks e <databricks_pat_token> pelo seu access token pessoal.
Configurar a coleta de dados do OpenTelemetry
Databricks suporta a exportação de métricas e logs do OpenTelemetry de agentes de codificação para tabelas Delta Unity Catalog . Todos os métricas são dados de séries temporais exportados usando o protocolo métricas padrão do OpenTelemetry, e logs são exportados usando o protocolo logs do OpenTelemetry.
Requisitos
- Ativada a pré-visualização do OpenTelemetry no Databricks. Veja as prévias do Gerenciador Databricks.
o passo 1: Criar tabelas OpenTelemetry no Unity Catalog
Crie tabelas de gerenciamento de 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 logs
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 variáveis de ambiente no seu agente de codificação
Em qualquer agente de codificação com suporte a métricas OpenTelemetry ativado, configure a seguinte variável 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"
}
o passo 3: execute seu agente de codificação.
Seus dados devem ser propagados para as tabelas Unity Catalog em até 5 minutos.