Integre com agentes de codificação
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
- 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 dashboard, clique em Governar no canto superior direito da página do Unity AI Gateway e, em seguida, clique em Painel de Uso . O painel de uso integrado inclui uma tab **Coding Agents** 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.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.
Usar modelos de código aberto com agentes de codificação
O Databricks oferece suporte à integração de modelos de código aberto (OSS), como glm-5-2, com agentes de codificação.
Além dos requisitos acima, seu workspace também deve ter acesso ao modelo OSS de destino.
OpenCode
Configure ucode conforme descrito em Usar ucode (recomendado), então selecione system.ai.glm-5-2 como seu modelo.
Configuração manual
Como alternativa, você pode instalar o OpenCode conforme descrito na documentação do OpenCode e, em seguida, 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 Databricks.<databricks_pat_token>com seu access token pessoal.<open source model service name>com o serviço de modelo OSS de destino, por exemplo,system.ai.glm-5-2.
Em seguida, comece o OpenCode:
opencode
Codex
O Codex conecta-se a modelos de código aberto por meio da Open Responses API que o Codex suporta.
Configure ucode conforme descrito em Usar ucode (recomendado), então execute a execução:
ucode codex --model <open source model service name>
Por exemplo, para usar o GLM 5.2 com o Codex, execução:
ucode codex --model system.ai.glm-5-2
Configuração manual
Alternativamente, você pode instalar a CLI do Codex conforme descrito em Codex CLI, então crie ou edite ~/.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> pela URL do seu workspace Databricks e <open source model service name> pelo serviço de modelo OSS de destino, por exemplo, system.ai.glm-5-2.
Em seguida, comece o Codex:
codex
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.