Integracja z agentami kodowania

Dzięki integracji z agentami kodowania Azure Databricks możesz kierować ruch z agentów kodujących takich jak Claude Code, Codex CLI, Cursor i Gemini CLI przez usługi modelowe w Unity Gateway. Zapewnia to ograniczanie szybkości, śledzenie użycia i tabele wnioskowania — ze wszystkimi kontrolkami skonfigurowanymi na poziomie usługi modelu, użytkownika lub grupy.

Features

• Dostęp: bezpośredni dostęp do różnych narzędzi i modeli kodowania, a wszystko w ramach jednej faktury.
• Możliwość obserwowania: jeden ujednolicony pulpit nawigacyjny do śledzenia użycia, wydatków i metryk we wszystkich narzędziach do kodowania.
• Zunifikowane zarządzanie: Administratorzy mogą zarządzać uprawnieniami modelu i limitami prędkości za pośrednictwem Unity Gateway na poziomie usługi modelowej, użytkownika lub grupy.

Requirements

• Obszar roboczy usługi Azure Databricks w regionie obsługiwanym przez Unity Gateway.
• Katalog Unity włączony dla obszaru roboczego. Zobacz Umożliwienie obszaru roboczego dla Unity Catalog.

Konfiguracja

Najszybszym sposobem na start jest Unity Gateway CLI, który instaluje, uwierzytelnia i konfiguruje wspieranych agentów kodujących za pomocą Unity Gateway w jednym poleceniu.

Użyj CLI Unity Gateway (zalecane)

Unity Gateway CLI (ug) jest pojedynczym punktem wejścia do uruchamiania agentów kodujących przeciwko Unity Gateway. Obsługuje protokół OAuth, zapisuje plik konfiguracji każdego agenta i kieruje ruch przez dowolny zarejestrowany serwer LLM lub MCP. Obsługiwani agenci:

• Kod Claude'a
• Codex — Interfejs wiersza polecenia
• Gemini CLI
• OpenCode
• GitHub Copilot CLI
• Pi
• i wiele więcej

Aby zobaczyć wszystkich obsługiwanych agentów kodu, uruchom ug --help.

Krok 1: Zainstaluj CLI Unity Gateway

uv tool install git+https://github.com/databricks/unity-gateway

Wymaga Pythona 3.12 lub nowszego i uv. To instaluje polecenie ug.

Krok 2. Otwieranie agenta kodowania

Uruchom żądanego agenta. Przy pierwszym uruchomieniu narzędzie wiersza poleceń Unity Gateway prosi o podanie adresu URL obszaru roboczego Azure Databricks, przeprowadza uwierzytelnienie i automatycznie zapisuje plik konfiguracyjny agenta. Kolejne uruchomienia są kierowane bezpośrednio do agenta.

ug claude     # Claude Code
ug codex      # OpenAI Codex
ug gemini     # Gemini CLI
ug opencode   # OpenCode
ug copilot    # GitHub Copilot CLI
ug pi         # Pi

Unity Gateway CLI przekazuje flagi występujące po nazwie agenta do narzędzia bazowego, na przykład:

ug codex --full-auto

Aby skonfigurować wielu agentów kodowania w tym samym czasie, uruchom polecenie:

ug configure

Aby zarejestrować serwery MCP usługi Azure Databricks (funkcje Unity Catalog, AI Search, magazyny SQL oraz wykryte połączenia zewnętrzne) w agentach obsługujących MCP:

ug mcp add

Aby zobaczyć podsumowanie korzystania z Unity Gateway z ostatnich 7 dni:

ug usage

Aby wyświetlić pełny opis poleceń, uruchom:

ug --help

Dashboard

Gdy użycie agentów programistycznych jest śledzone za pośrednictwem Unity Gateway, możesz wyświetlać i monitorować swoje wskaźniki we wbudowanym pulpicie nawigacyjnym.

Aby otworzyć pulpit, kliknij Govern w prawym górnym rogu strony Unity Gateway, a następnie kliknij Usage Dashboard. Wbudowany panel użycia zawiera kartę Agenty kodujące z wykresami przedstawiającymi użycie narzędzi do kodowania.

Konfiguracja ręczna

Jeśli wolisz skonfigurować agentów samodzielnie, postępuj zgodnie z instrukcjami dotyczącymi:

• Kod Claude'a
• Codex — Interfejs wiersza polecenia
• IDE Cursor
• Gemini CLI

Kod Claude'a

Krok 1. Konfigurowanie klienta programu Claude Code

Dodaj następującą konfigurację do ~/.claude/settings.json. Aby uzyskać więcej informacji, zobacz dokumentację ustawień kodu Claude'a .

{
  "env": {
    "ANTHROPIC_MODEL": "system.ai.claude-fable-5",
    "ANTHROPIC_BASE_URL": "https://<workspace-url>/ai-gateway/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<databricks_pat_token>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-databricks-use-coding-agent-mode: true",
    "CLAUDE_CODE_USE_GATEWAY": "1",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "ENABLE_TOOL_SEARCH": "1"
  }
}

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks i <databricks_pat_token> osobistym tokenem dostępu. Aby ustawić inny model domyślny, zmień ANTHROPIC_MODEL model na dowolną usługę modelu Unity Gateway, na przykład system.ai.claude-opus-4-6.

Krok 2 (opcjonalnie): Konfigurowanie kolekcji metryk OpenTelemetry

Zobacz Konfigurowanie zbierania danych OpenTelemetry, aby uzyskać szczegółowe informacje na temat eksportowania metryk i dzienników z Claude Code do zarządzanych przez Unity Catalog tabel Delta.

Interfejs wiersza polecenia Codex

Krok 1. Instalowanie lub aktualizowanie interfejsu wiersza polecenia Codex

Zainstaluj lub zaktualizuj interfejs wiersza polecenia Codex w wersji 0.118 lub nowszej:

npm install -g @openai/codex@latest

Krok 2. Tworzenie lub aktualizowanie pliku konfiguracji Codex

Utwórz lub edytuj plik konfiguracji Codex pod adresem ~/.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

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks.

Krok 3. Uwierzytelnianie w obszarze roboczym

Najpierw upewnij się, że masz zainstalowany Azure Databricks CLI. Aby uzyskać instrukcje, zobacz Instalowanie lub aktualizowanie interfejsu wiersza polecenia usługi Databricks .

Następnie uwierzytelnij:

databricks auth login --host <workspace-url>

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks.

Krok 4. Uruchamianie kodu

codex

Aby zmienić model, użyj polecenia /model.

IDE Cursor

Aby skonfigurować kursor do korzystania z usług modeli w Unity Gateway:

Krok 1. Konfigurowanie podstawowego adresu URL i klucza interfejsu API

1. Otwórz kursor i przejdź do Ustawienia>Ustawienia kursora>Modele>Klucze API.

2. Włącz zastąpienie podstawowego adresu URL OpenAI i wprowadź adres URL:

   https://<workspace-url>/ai-gateway/cursor/v1
   

   Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks.

3. Wklej osobisty token dostępu Azure Databricks do pola OpenAI API Key.

Krok 2. Dodawanie modeli niestandardowych

1. Kliknij + Dodaj model niestandardowy w ustawieniach kursora.
2. Dodaj nazwę usługi modelowej (na przykład system.ai.claude-opus-4-6) i włącz przełącznik.

Krok 3. Testowanie integracji

1. Otwórz tryb zapytaj przy użyciu Cmd+L (macOS) lub Ctrl+L (Windows/Linux) i wybierz model.
2. Wyślij wiadomość. Wszystkie żądania są teraz kierowane przez usługę Azure Databricks.

Gemini CLI

Krok 1. Instalowanie najnowszej wersji interfejsu wiersza polecenia Gemini

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

Krok 2. Konfigurowanie zmiennych środowiskowych

Utwórz plik ~/.gemini/.env i dodaj następującą konfigurację. Aby uzyskać więcej informacji, zobacz dokumentację uwierzytelniania interfejsu wiersza polecenia Gemini .

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>

Zastąp <workspace-url> adresem URL obszaru roboczego Azure Databricks i <databricks_pat_token> osobistym tokenem dostępu.

Używaj modeli open source z agentami programistycznymi

Azure Databricks wspiera integrację modeli open source (OSS), takich jak glm-5-2, z agentami kodującymi.

Oprócz powyższych wymagań , twoja przestrzeń pracy musi mieć również dostęp do docelowego modelu OSS.

OpenCode

Ustaw CLI Unity Gateway zgodnie z opisem w Use the Unity Gateway CLI (zalecane), a następnie wybierz system.ai.glm-5-2 jako swój model.

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

opencode

Kodeks

Codex łączy się z modelami open source poprzez API Open Responses , które Codex obsługuje.

Skonfiguruj narzędzie CLI Unity Gateway zgodnie z opisem w sekcji Korzystanie z narzędzia CLI Unity Gateway (zalecane), a następnie uruchom:

ug codex --model <open source model service name>

Na przykład, aby użyć GLM 5.2 z Codexem, wykonaj:

ug codex --model system.ai.glm-5-2

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

codex

Konfigurowanie zbierania danych OpenTelemetry

Azure Databricks obsługuje eksportowanie metryk i logów OpenTelemetry z agentów kodowania do zarządzanych przez Unity Catalog tabel Delta. Wszystkie metryki to dane szeregów czasowych eksportowane przy użyciu standardowego protokołu metryk OpenTelemetry, a dzienniki są eksportowane przy użyciu protokołu dzienników OpenTelemetry.

Requirements

• Usługa OpenTelemetry w wersji zapoznawczej usługi Azure Databricks jest włączona. Zobacz Zarządzanie wersjami zapoznawczami usługi Azure Databricks.

Krok 1: Tworzenie tabel OpenTelemetry w Unity Catalog

Utwórz prekonfigurowane tabele zarządzane Unity Catalog za pomocą schematów metryk i dzienników OpenTelemetry.

Tabela metryk

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 dzienników

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

Krok 2. Aktualizowanie wariantów env w agencie kodowania

W przypadku dowolnego agenta kodowania z włączoną obsługą metryk OpenTelemetry skonfiguruj następujące zmienne środowiskowe.

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

Dla Claude Code dodaj te zmienne do bloku env w pliku ~/.claude/settings.json, wraz z "CLAUDE_CODE_ENABLE_TELEMETRY": "1", aby włączyć eksport telemetrii.

Krok 3. Uruchamianie agenta kodowania.

Dane powinny trafić do tabel katalogu Unity w ciągu 5 minut.

Następne kroki

• Usługi modelu
• Tworzenie usług modelu i zarządzanie nimi
• Usługi modelu zapytań
• Odkrywanie i zarządzanie dostępem do usług modelowych