Vytvoření vlastního agenta pomocí rozhraní SUPERVISOR API (beta verze)

Important

Tato funkce je v beta verzi. Správci účtu můžou řídit přístup k této funkci ze stránky Previews . Viz Manage Azure Databricks preview.

Můžete vytvořit agenta Azure Databricks Apps, který používá rozhraní API Supervisor (beta verze) pro orchestraci místo správy smyčky agenta ve vašem vlastním kódu. Výsledek je stejný jako vytvoření vlastního agenta: nasazená aplikace s uživatelským rozhraním chatu, /invocations koncovým bodem a ověřováním. Rozdíl je v tom, že Azure Databricks automaticky spustí cyklus agenta za vás. Vaše agent.py provede jedno volání rozhraní API a Azure Databricks zpracovává výběr, spouštění a syntézu odpovědí.

Rozhraní API pro správce funguje s některým z podporovaných základních modelů. Změňte pole model k přepnutí zprostředkovatelů, aniž byste museli zasahovat do definic svých nástrojů nebo logiky obslužných rutin.

Kdy použít rozhraní API pro správce

Rozhraní API pro správce funguje dobře, když váš agent používá pouze nástroje hostované Azure Databricks a nepotřebuje vlastní logiku mezi voláními nástrojů. Místo toho použijte smyčku vlastního agenta, pokud váš agent vyžaduje některou z následujících:

  • Nástroje funkcí na straně klienta (rozhraní API správce nemůže kombinovat hostované nástroje a nástroje na straně klienta v jednom požadavku)
  • Koncové body agenta jiné než jsou koncové body agenta Bricks Knowledge Assistant
  • Vlastní načítáče, vlastní vstupy/výstupy nebo jemně odstupňované řízení streamování
  • Vlastní Python logika při volání nástrojů, jako je podmíněné větvení nebo správa stavu
  • Kontrola nad parametry odvození, jako je například temperature

Úplné referenční informace k rozhraní API a podporované parametry najdete v tématu Supervisor API (beta verze).

Požadavky

Vytvoření vlastního agenta pomocí rozhraní API supervisoru

Doporučeným výchozím bodem je vytvoření nové aplikace z nejnovější šablony aplikace Databricks. Nejnovější šablony zahrnují integrovanou use-supervisor-api dovednost pro pomocníky s kódováním AI a add-tools také dovednosti pro přidávání hostovaných nástrojů.

Pokud chcete vytvořit novou aplikaci ze šablony, přečtěte si téma Vytvoření agenta AI a jeho nasazení v Databricks Apps.

Po nastavení aplikace z nejnovější šablony otevřete projekt v pomocníkovi pro kódování AI a spusťte:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

Dovednost aktualizuje vaše agent_server/agent.py k volání DatabricksOpenAI().responses.create() s hostovanými nástroji, čímž nahrazuje smyčku ručního agenta. Přidá také databricks-openai závislost a zaznamená omezení beta verze.

Výsledkem je stejná nasazená aplikace s uživatelským rozhraním chatu, ověřováním /invocations a koncovým bodem, ale s jednodušším kódem agenta. Úplný pracovní postup nasazení (nasazení do aplikací, přidání nástrojů, vyhodnocení) najdete v tématu Vytvoření agenta AI a jeho nasazení v Databricks Apps.

Podporované nástroje a parametry

Úplný seznam podporovaných typů nástrojů, parametrů požadavků a příkladů kódu najdete v tématu Rozhraní SUPERVISOR API (beta verze).

Pro každý nástroj, který přidáte, také udělte odpovídající oprávnění k prostředku v databricks.yml. Příklady najdete v add-tools dovednostech.claude/skills/.

Autorizace pro hostované nástroje

Když rozhraní API správce spustí smyčku agenta, spustí hostované nástroje s použitím identity aplikace nebo požadované identity uživatele. Zvolte na základě toho, jestli by všichni uživatelé aplikace měli sdílet stejný přístup k vašim nástrojům, nebo každý uživatel by měl přistupovat jenom k tomu, co vlastní oprávnění povolují.

  • Autorizace aplikace (výchozí): Nástroje se spouští jako instanční objekt aplikace. Udělte instančnímu objektu služby oprávnění pro každý nástroj, který agent používá. Viz Autorizace aplikace.
  • Autorizace uživatele: Nástroje se spouští jako uživatel, který odeslal požadavek, takže oprávnění katalogu Unity, filtry řádků a masky sloupců platí pro uživatele. Podívejte se na následující část.

Spuštění nástrojů jako žádajícího uživatele

Important

Autorizace uživatele je ve verzi Public Preview. Správce pracovního prostoru ho musí povolit, abyste mohli do aplikace přidat obory. Viz Přidání oborů do aplikace.

Pokud chcete spustit hostované nástroje jménem žádajícího uživatele, předejte token DatabricksOpenAI uživatele klientovi a přidejte obory autorizace uživatele, které vaše nástroje potřebují.

  1. Přidejte obory autorizace uživatelů, které vaše aplikace potřebuje. ai-gateway vyžaduje se pro veškerý přístup k rozhraní API správce. Přidejte obor jednotlivých nástrojů pro každý typ nástroje, který agent používá:

    Typ nástroje Požadovaný obor
    Všechny nástroje ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    Typ app nástroje není podporován s autorizací uživatele. Pokud chcete volat koncový bod aplikace jako nástroj, použijte místo toho autorizaci aplikace. Informace o tom, jak přidat obory prostřednictvím uživatelského rozhraní pracovního prostoru nebo deklarativních sad automatizace, najdete v tématu Autorizace uživatele.

  2. Ve vaší obslužné rutině agent.py předejte klienta pracovního prostoru uživatele do DatabricksOpenAI. Toto je jediné zapojení specifické pro správce: místo volání prostředku přímo s uživatelským klientem ho předáte klientovi, který spouští smyčku agenta.

    from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

    get_user_workspace_client() přečte předávaný token uživatele z hlaviček požadavku, které se vyplní pouze v době dotazu. Volejte ho v obslužných rutinách invoke a stream, nikdy v __init__ ani při spuštění aplikace. Pokud přeposlaný token chybí, výsledný klient se neověří jako žádající uživatel. Jak ověřit, že agent běží pod identitou volajícího, a ne pod instančním objektem služby aplikace, najdete v tématu Autorizace uživatele.

  3. U každého nástroje udělte každému uživateli, který agenta spouští, požadované oprávnění, například CAN_RUN u agenta Genie nebo CAN_QUERY u koncového bodu asistenta znalostí.

Další zdroje informací

  • Last updated on