Ověřování pro agenty AI

Agenti umělé inteligence se často potřebují ověřit v jiných prostředcích, aby mohli provádět úlohy. Nasazený agent může například potřebovat přístup k indexu vyhledávání AI, aby mohl dotazovat nestrukturovaná data, obsluhující koncový bod pro volání základního modelu nebo funkce katalogu Unity pro spuštění vlastní logiky.

Tato stránka popisuje metody ověřování pro agenty nasazené v Databricks Apps. Informace o agentech nasazených v koncových bodech obsluhy modelů najdete v tématu Ověřování agentů AI (obsluha modelů).

Databricks Apps poskytuje pro agenty dvě metody ověřování. Každá metoda obsluhuje různé případy použití:

Metoda Description Kdy ho použít
Autorizace aplikace Agent se autentizuje pomocí automaticky vytvořeného služebního principálu s konzistentními oprávněními. Dříve se nazývalo ověřování principálu služby. Nejběžnější případ použití Použijte, když by všichni uživatelé měli mít stejný přístup k prostředkům.
Autorizace uživatele Agent se ověřuje pomocí identity uživatele, který požadavek provádí. Bylo dříve nazýváno ověřování On-Behalf-Of (OBO). Použijte, když potřebujete oprávnění specifická pro uživatele, záznamy auditu nebo jemně odstupňované řízení přístupu pomocí katalogu Unity.

Obě metody můžete kombinovat v jednom agentu. Pomocí autorizace aplikace můžete například získat přístup ke sdílenému indexu vyhledávání AI při použití autorizace uživatele k dotazování tabulek specifických pro uživatele.

Konfigurace ověřování pomocí uživatelského rozhraní pracovního prostoru nebo deklarativních balíčků automatizace

Všechna nastavení ověřování můžete nakonfigurovat dvěma způsoby:

  • Uživatelské rozhraní pracovního prostoru: Upravte aplikaci a spravujte prostředky a obory v kroku Konfigurace . Je doporučeno, když iterujete s jednou aplikací v pracovním prostoru.
  • Deklarativní balíčky automatizace: Deklarujte prostředky, obory a proměnné prostředí v databricks.yml souboru a nasaďte pomocí databricks bundle deploynástroje . Doporučuje se, pokud chcete verzování založené na Gitu, CI/CD, nebo nasadit stejného agenta napříč pracovními prostory. Všechny šablony agentů jsou dodávány s databricks.yml.

Obě cesty vytvářejí stejnou konfiguraci modulu runtime. Zbytek této stránky zobrazuje jednotlivé instrukce v obou formulářích, takže můžete vybrat jednu a zůstat konzistentní v rámci projektu.

Pokud chcete do aplikace přidat prostředek prostřednictvím obou cest, musíte mít Can Manage oprávnění k prostředku i aplikaci.

Pro úplný odkaz na balík viz Prostředek aplikace a app.resources. Pro podrobný návod k komplexnímu balíčku najdete v tématu Správa aplikací Databricks pomocí deklarativních automatizačních balíčků.

Autorizace aplikace

Ve výchozím nastavení se aplikace Databricks ověřují pomocí autorizace aplikace. Databricks automaticky vytvoří instanční objekt při vytváření aplikace a funguje jako identita aplikace.

Všichni uživatelé, kteří používají aplikaci, sdílejí stejná oprávnění definovaná pro služební principal. Tento model funguje dobře, když chcete, aby všichni uživatelé viděli stejná data nebo když aplikace provádí sdílené operace, které nejsou svázané s uživatelskými ovládacími prvky přístupu.

Podrobné informace o autorizaci aplikací najdete v tématu Autorizace aplikací.

Udělení oprávnění experimentu MLflow

Váš agent potřebuje přístup k experimentu MLflow k zaznamenávání sledování a hodnocení výsledků. Udělte služebnímu principálu Can Edit oprávnění k experimentu.

Uživatelské rozhraní pracovního prostoru

  1. Na domovské stránce aplikace klikněte na Upravit .
  2. Přejděte ke kroku Konfigurace .
  3. V části Prostředky aplikace přidejte prostředek experimentu MLflow s oprávněním Can Edit .

Viz Přidání prostředku experimentu MLflow do aplikace Databricks.

Deklarativní balíčky automatizace

  1. Deklarujte experiment v seznamu vaší aplikace resources v souboru databricks.yml. Při nastavování proměnných prostředí se na prostředek přiřazený k name bude odkazováno později.

    resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

  2. Znovu nasaďte balíček:

    databricks bundle deploy
databricks bundle run my_agent

Viz app.resources.experiment pro všechna pole.

Udělení oprávnění dalším prostředkům Databricks

Pokud váš agent používá jiné prostředky Databricks, jako jsou agenti Genie, indexy AI Search nebo sklady SQL, udělte instančnímu objektu oprávnění u každého z nich.

Pokud chcete získat přístup k registru výzev, udělte oprávnění CREATE FUNCTION, EXECUTE, a MANAGE ke schématu katalogu Unity pro ukládání výzev.

Při udělování přístupu k prostředkům katalogu Unity musíte také udělit oprávnění všem podřízeným závislým prostředkům. Pokud například udělíte přístup k agentu Genie, musíte také udělit přístup k jeho podkladovým tabulkám, skladům SQL a funkcím katalogu Unity.

Uživatelské rozhraní pracovního prostoru

Když vytvoříte nebo upravíte aplikaci v pracovním prostoru Databricks, přidejte do aplikace prostředky prostřednictvím oddílu Prostředky aplikace .

  1. Na domovské stránce aplikace klikněte na Upravit .
  2. Přejděte ke kroku Konfigurace .
  3. V prostředcích aplikace klikněte na + Přidat prostředek pro každý prostředek, který agent používá, a nastavte oprávnění.

Úplný seznam podporovaných prostředků a snímků obrazovky najdete v tématu Přidání prostředků do aplikace Databricks .

Deklarativní balíčky automatizace

  1. Deklarujte každý prostředek, který agent používá v resources seznamu pod vaší aplikací v databricks.yml. Následující příklad ukazuje agenta, který používá experiment MLflow, obsluhující koncový bod, Agent Genie, SQL Warehouse, index AI Search, funkci Katalogu Unity a instanci Lakebase. Každý prostředek name je odkazován z config.env přes value_from takže agent obdrží vyřešený identifikátor za běhu.

    bundle:
  name: my_agent

resources:
  apps:
    my_agent:
      name: 'my-agent'
      description: 'Custom agent deployed on Databricks Apps'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
          - name: LAKEBASE_INSTANCE_NAME
            value_from: 'database'

      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

        - name: 'sales-genie'
          genie_space:
            space_id: '<genie-space-id>'
            permission: 'CAN_RUN'

        - name: 'warehouse'
          sql_warehouse:
            id: '<warehouse-id>'
            permission: 'CAN_USE'

        - name: 'docs-index'
          uc_securable:
            securable_full_name: 'main.docs.chunks_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'lookup-function'
          uc_securable:
            securable_full_name: 'main.tools.order_lookup'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

        - name: 'database'
          database:
            instance_name: '<lakebase-instance-name>'
            database_name: 'databricks_postgres'
            permission: 'CAN_CONNECT_AND_CREATE'

targets:
  dev:
    mode: development
    default: true

    Important

    Každá hodnota value_from v config.env musí odpovídat poli name v seznamu resources. Neshody způsobují, že se proměnná prostředí vyřeší na None v nasazené aplikaci.

  2. Nasazení a spuštění sady:

    databricks bundle validate
databricks bundle deploy
databricks bundle run my_agent

    bundle deploy nahraje zdroj a nakonfiguruje prostředky. bundle run spustí nebo restartuje aplikaci s nejnovějším zdrojem. bundle run Argumentem pro je klíč YAML pod resources.apps (tady my_agent), nikoli pole nasazené aplikace name.

Úplné schéma každého podtypu prostředků najdete v tématu app.resources.

Následující tabulka uvádí minimální oprávnění použitá v příkladech výše a ekvivalentní hodnotu deklarativních balíčků automation pro každý typ prostředku:

Typ zdroje Oprávnění UI pracovního prostoru Prostředek a oprávnění deklarativní služby Automation Bundles
Datový sklad SQL Can Use sql_warehouse s CAN_USE
Koncový bod pro obsluhu modelu Can Query serving_endpoint s CAN_QUERY
Funkce katalogu Unity Can Execute uc_securable s securable_type: FUNCTION a EXECUTE
Genie Agent Can Run genie_space s CAN_RUN
Index vyhledávání AI Can Select uc_securable s securable_type: TABLE a SELECT
Tabulka katalogu Unity SELECT uc_securable s securable_type: TABLE a SELECT
Připojení katalogu Unity Use Connection uc_securable s securable_type: CONNECTION a USE_CONNECTION
Svazek katalogu Unity Can Read nebo Can Read and Write uc_securable s securable_type: VOLUME a READ_VOLUME nebo WRITE_VOLUME
Lakebase (zřízeno) Can Connect and Create database s CAN_CONNECT_AND_CREATE
LakeBase (automatické škálování) Can Connect and Create postgres s CAN_CONNECT_AND_CREATE

Dodržujte princip nejnižší úrovně oprávnění. Udělte služebnímu principálu jenom oprávnění, která agent potřebuje, a použijte vyhrazený služební principál pro každou aplikaci. Úplný seznam najdete v tématu Osvědčené postupy zabezpečení.

Autorizace uživatele

Important

Autorizace uživatele je ve verzi Public Preview. Správce pracovního prostoru ho musí povolit, než budete moct používat autorizaci uživatelů.

Autorizace uživatele umožňuje agentu jednat s identitou uživatele, který žádost provádí. To poskytuje:

  • Přístup jednotlivých uživatelů k citlivým datům
  • Jemná kontrola dat vynucovaná katalogem Unity
  • Trasování auditu specifické pro uživatele
  • Automatické vynucování filtrů na úrovni řádků a mask sloupců

Autorizaci uživatele použijte, když váš agent potřebuje přístup k prostředkům pomocí identity žádajícího uživatele místo instančního objektu aplikace.

Jak funguje autorizace uživatelů

Při konfiguraci autorizace uživatele pro agenta:

  1. Přidejte do aplikace obory rozhraní API: Definujte, ke kterým rozhraním API Databricks může aplikace přistupovat jménem uživatelů. Viz Přidání oborů do aplikace.
  2. Přihlašovací údaje uživatele jsou omezené: Databricks používá přihlašovací údaje uživatele a omezuje je pouze na rozsahy rozhraní API, které jste definovali.
  3. Předávání tokenů: Token s omezeným rozsahem je zpřístupněn vaší aplikaci prostřednictvím hlavičky x-forwarded-access-token HTTP.
  4. Server agenta MLflow ukládá token: Server agenta tento token automaticky ukládá na žádost o pohodlný přístup v kódu agenta.

Nakonfigurujte autorizaci uživatelů přidáním oborů do uživatelského rozhraní Databricks Apps při vytváření nebo úpravách aplikace nebo programově pomocí rozhraní API. Podrobné pokyny najdete v tématu Přidání oborů do aplikace .

Agenti s autorizací uživatelů mají přístup k následujícím prostředkům Databricks:

  • Datový sklad SQL
  • Genie Agent
  • Soubory a adresáře
  • Koncový bod obsluhy modelu
  • Index vyhledávání AI
  • Připojení katalogu Unity
  • Tabulky katalogu Unity

Implementace autorizace uživatele

Pokud chcete implementovat autorizaci uživatelů, musíte do aplikace přidat obory autorizace. Obory omezují, co aplikace může jménem uživatele dělat. Seznam dostupných oborů a sémantiky oboru najdete v tématu Eskalace zabezpečení a oprávnění na základě oboru.

Uživatelské rozhraní pracovního prostoru

  1. V uživatelském rozhraní Databricks přejděte do nastavení autorizace vaší aplikace.
  2. V části Autorizace uživatele klikněte na + Přidat obor a vyberte obory, které aplikace potřebuje pro přístup k prostředkům jménem uživatele.
  3. Uložte změny a restartujte aplikaci.

Deklarativní balíčky automatizace

  1. Deklarujte obory v rámci user_api_scopes prostředku aplikace v databricks.yml:

    resources:
  apps:
    my_agent:
      name: 'my-agent'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'

  2. Znovu nasaďte sadu a restartujte aplikaci:

    databricks bundle deploy
databricks bundle run my_agent

    Note

    Po první autorizaci uživatele v pracovním prostoru je nutné restartovat existující aplikace, aby mohly používat rozsahy. Viz Přidání oborů do aplikace.

Pokud chcete nakonfigurovat autorizaci uživatele v kódu agenta, načtěte hlavičku pro tento požadavek z AgentServeru a vytvořte klienta pracovního prostoru s těmito přihlašovacími údaji.

  1. V kódu agenta naimportujte ověřovací nástroj:

    Pokud používáte některou z poskytnutých šablon z databricks/app-templates, naimportujte poskytnutý nástroj:

    from databricks_app.utils import get_user_workspace_client

    Jinak importujte z nástrojů agent serveru.

    from agent_server.utils import get_user_workspace_client

    Funkce get_user_workspace_client() používá server agenta k zachycení hlavičky x-forwarded-access-token a sestavení klienta pracovního prostoru s těmito přihlašovacími údaji uživatele, zpracování ověřování mezi uživatelem, aplikací a serverem agenta.

  2. Inicializujte klienta pracovního prostoru během vykonávání dotazu, ne při spuštění aplikace.

    Important

    Volání get_user_workspace_client() uvnitř invoke a stream obslužných rutin, ne při __init__ nebo spuštění aplikace. Přihlašovací údaje uživatele jsou k dispozici pouze v době dotazu, když uživatel odešle žádost. Inicializace během spuštění aplikace selže, protože ještě neexistuje žádný kontext uživatele.

    # In your agent code (inside invoke or stream handler)
user_client = get_user_workspace_client()


# Use user_client to access Databricks resources with user permissions
response = user_client.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Kompletní průvodce přidáním oborů a pochopením zabezpečení založeného na oboru najdete v tématu Eskalace zabezpečení a oprávnění na základě oboru. Vyžadovat pouze minimální rozsahy, které agent potřebuje, a protokolovat každou akci provedenou jménem uživatele; viz Osvědčené postupy pro autorizaci uživatelů.

Ověření autorizace uživatele

Po přidání rozsahů oprávnění a zavolání get_user_workspace_client() ověřte, že agent běží jménem volajícího, a ne jako instanční objekt služby aplikace. Pokud přeposlaný token chybí, get_user_workspace_client() přejde na služebního principála, aniž by vyvolal výjimku, takže agent může vrátit zdánlivě běžnou odpověď a přitom stále jedná jako aplikace. Chcete-li to ověřit, přidejte nástroj whoami a spusťte ho pod svým účtem. Pokud vrátí vaše uživatelské jméno, autorizace uživatele funguje.

current_user.me() se vztahuje na výchozí iam.current-user:read obor, takže pro tento test nemusíte přidávat žádné obory.

from agents import Agent, function_tool
from agent_server.utils import get_user_workspace_client

@function_tool
def whoami() -> str:
    """Returns the identity of the current user."""
    user_wc = get_user_workspace_client()
    return user_wc.current_user.me().user_name

agent = Agent(
    name="my-agent",
    instructions=(
        "When the user asks who they are, call the whoami tool "
        "and return the raw result."
    ),
    model="databricks-claude-sonnet-4-6",
    tools=[whoami],
)

Znovu nasaďte agenta. Viz Vytvoření agenta AI a jeho nasazení v Databricks Apps.

Uživatelské rozhraní pracovního prostoru

Test uživatelského rozhraní Workspace je nejrychlejší základní kontrola funkčnosti a nevyžaduje tokeny OAuth.

  1. Změny oboru se projeví okamžitě, ale aktualizace interních mezipamětí může trvat až 5 minut – počkejte dlouho před testováním (nevyžaduje se restartování aplikace). Vždy vymažte soubory cookie prohlížeče pro URL adresu aplikace (postup najdete v rozevírací nabídce níže), jinak relace znovu používá tokeny vydané před změnou rozsahu.
  2. Potvrďte, že máte CAN USE oprávnění k aplikaci. Viz Konfigurace oprávnění pro aplikaci Databricks.
  3. Otevřete adresu URL aplikace v prohlížeči. Při první návštěvě přijměte výzvu k vyjádření souhlasu pro požadované obory.
  4. V chatu požádejte Who am I? a potvrďte, že agent vrátí vaše uživatelské jméno (například you@your-company.com).
Vymazání souborů cookie v Chromu
  1. Otevřete DevTools: Stiskněte F12 nebo Cmd+Option+I v systému macOS nebo Ctrl+Shift+I na Windows nebo Linuxu.
  2. Otevřete kartu Aplikace .
  3. V částiSoubory cookie> vyberte adresu URL vaší aplikace.
  4. Klikněte pravým tlačítkem na každý soubor cookie a zvolte Odstranit.

Chrome DevTools zobrazující kartu Aplikace, soubory cookie adresy URL aplikace a nabídku Odstranit po kliknutí pravým tlačítkem myši

Python

K vyvolání agenta použijte profil rozhraní příkazového řádku nebo přihlašovací údaje instančního objektu. Informace o generování tokenů OAuth najdete v tématu Query agent nasazený na Azure Databricks a Pojení k aplikaci API Databricks pomocí ověřování tokenů.

  1. Změny oboru se projeví okamžitě, ale aktualizace interních mezipamětí může trvat až 5 minut, proto počkejte před testováním (nevyžaduje se restartování aplikace).

  2. Vyvolejte agenta jako sebe sama:

    from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

app_name = "<your-app-name>"
prompt = [{"role": "user", "content": "Call the whoami tool and return only the raw result."}]

w = WorkspaceClient(profile="<your-profile>")
client = DatabricksOpenAI(workspace_client=w)
response = client.responses.create(model=f"apps/{app_name}", input=prompt)
print(response.output_text)

    Výstup by měl být vaše uživatelské jméno , you@your-company.comnapříklad .

Pokud nástroj místo uživatelského jména vrátí UUID, x-forwarded-access-token hlavička se nedostaví k nástroji a agent se vrátí k instančnímu objektu aplikace (UUID je ID klienta instančního objektu aplikace). Pokud chcete diagnostikovat, potvrďte následující:

  1. V pracovním prostoru je povolená autorizace uživatele.
  2. Aplikace má nakonfigurované obory.
  3. get_user_workspace_client() je volána uvnitř @invoke nebo @stream obslužné rutiny, ne při spuštění aplikace.
  4. Kód používá get_user_workspace_client() a ne WorkspaceClient().

Několik věcí, které je potřeba sledovat:

  • whoami Odstraňte nástroj před nasazením do produkce. Je to jenom diagnostika a zveřejňuje identitu uživatele komukoli, kdo může vyvolat agenta.
  • Otestujte ho s druhým uživatelem. Kontrola jednoho uživatele potvrzuje, že se token přeposílal; Druhý volající potvrdí, že každý požadavek získá vlastní identitu místo sdíleného náhradního prostředku.
  • Přeposlaný token nikdy nezaznamenávejte do logu. Přečtěte si osvědčené postupy pro autorizaci uživatelů.
  • Pokud chcete ověřit konkrétní obor, nahraďte current_user.me() voláním, které tento obor vyžaduje. Například příkaz SELECT current_user() spuštěný nad skladem pokryje rozsah sql od začátku do konce.

Přihlásit se na servery MCP služby Databricks

Spravované servery MCP služby Databricks zpřístupňují indexy AI Search a funkce Katalogu Unity jako nástroje prostřednictvím adres URL formuláře https://<workspace>/api/2.0/mcp/ai-search/<catalog>/<schema> a https://<workspace>/api/2.0/mcp/functions/<catalog>/<schema>. Předpona starší verze /api/2.0/mcp/vector-search/ adresy URL nadále funguje kvůli zpětné kompatibilitě. Seznam dostupných serverů a vzory jejich adres URL naleznete v článku Spravované servery MCP ve službě Azure Databricks.

Pokud se chcete autentizovat, udělte instančnímu objektu agenta (nebo uživateli, při použití autorizace uživatele) přístup ke všem podřízeným prostředkům v těchto schématech.

Pokud například váš agent používá následující adresy URL serveru MCP:

  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/customer_support
  • https://<your-workspace>/api/2.0/mcp/ai-search/prod/billing
  • https://<your-workspace>/api/2.0/mcp/functions/prod/billing

Musíte udělit přístup ke každému indexu vyhledávání AI v prod.customer_support a prod.billing, a každé funkce Unity Catalog v prod.billing.

Uživatelské rozhraní pracovního prostoru

Přidejte každý index a funkci jako prostředek v části Prostředky aplikace. Postupujte stejně jako udělte oprávnění jiným prostředkům Databricks.

Deklarativní balíčky automatizace

  1. Přidejte jednu uc_securable položku na index a funkci do seznamu vaší aplikace resources :

    resources:
  apps:
    my_agent:
      resources:
        - name: 'support-index'
          uc_securable:
            securable_full_name: 'prod.customer_support.tickets_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'billing-index'
          uc_securable:
            securable_full_name: 'prod.billing.invoices_index'
            securable_type: 'TABLE'
            permission: 'SELECT'

        - name: 'refund-function'
          uc_securable:
            securable_full_name: 'prod.billing.process_refund'
            securable_type: 'FUNCTION'
            permission: 'EXECUTE'

  2. Znovu nasaďte balíček:

    databricks bundle deploy
databricks bundle run my_agent

Vlastní servery MCP hostované jako aplikace Databricks (názvy aplikací s předponou mcp-) nejsou zatím podporovány jako svazkové prostředky. Udělte instančnímu objektu Can Use agenta v aplikaci serveru MCP ručně pomocí databricks apps update-permissions. Podívejte se na vlastní dovednosti serveru mcp-server v úložišti šablon agentů.

Další kroky

  • Last updated on