Mulai menggunakan agen AI

2025-05-14

Bangun agen AI pertama Anda menggunakan Mosaic AI Agent Framework. Dalam tutorial ini, Anda akan:

Menulis agen menggunakan Agent Framework.
Tambahkan alat ke agen Anda.
Sebarkan agen Anda ke model Databricks yang melayani titik akhir.

Untuk pengenalan konseptual agen dan aplikasi AI gen lainnya, lihat Apa itu aplikasi AI gen?

Persyaratan

Ruang kerja Anda harus mengaktifkan fitur berikut:

Katalog Unity
Kerangka Kerja Agen AI Mosaik
Model dasar (bayar per token, throughput yang disediakan, atau model eksternal). Lihat Fitur dengan ketersediaan regional terbatas

Contoh buku catatan

Buku catatan ini berisi semua kode yang Anda butuhkan untuk menulis dan menyebarkan agen AI pertama Anda. Impor buku catatan ke ruang kerja Azure Databricks Anda untuk menjalankannya.

Demo agen AI Mosaik

Dapatkan buku catatan

Tentukan agen

Agen AI terdiri dari yang berikut ini:

Model bahasa besar (LLM) yang dapat beralasan dan membuat keputusan
Alat yang dapat digunakan LLM untuk melakukan lebih dari sekadar menghasilkan teks, seperti menjalankan kode Python atau mengambil data

Jalankan kode berikut di buku catatan Databricks untuk menentukan agen panggilan alat sederhana:

Instal paket Python yang diperlukan:
```
%pip install -U -qqqq mlflow databricks-openai databricks-agents
dbutils.library.restartPython()
```
- mlflow: Digunakan untuk pengembangan agen dan pelacakan agen.
- databricks-openai: Digunakan untuk menyambungkan ke LLM yang dihosting Databricks.
- databricks-agent: Digunakan untuk mengemas dan menyebarkan agen.

Tentukan agen. Cuplikan kode ini melakukan hal berikut:

Menghubungkan ke titik akhir penyajian model Databricks menggunakan klien OpenAI.
Mengaktifkan pelacakan MLflow menggunakan autolog(). Ini menambahkan instrumentasi sehingga Anda dapat melihat apa yang dilakukan agen Anda saat mengirimkan kueri.
Menambahkan alat system.ai.python_exec ke agen Anda. Fungsi Katalog Unity bawaan ini memungkinkan agen Anda menjalankan kode Python.
Menentukan fungsi yang mengkueri LLM dengan perintah dan menangani respons.

import mlflow
import json
from databricks.sdk import WorkspaceClient
from databricks_openai import UCFunctionToolkit, DatabricksFunctionClient

# Get an OpenAI client configured to connect to Databricks model serving endpoints
# Use this client to query the LLM
openai_client = WorkspaceClient().serving_endpoints.get_open_ai_client()

# Enable automatic tracing for easier debugging
mlflow.openai.autolog()

# Load Databricks built-in tools (Python code interpreter)
client = DatabricksFunctionClient()
builtin_tools = UCFunctionToolkit(function_names=["system.ai.python_exec"], client=client).tools
for tool in builtin_tools:
  del tool["function"]["strict"]


def call_tool(tool_name, parameters):
  if tool_name == "system__ai__python_exec":
    return DatabricksFunctionClient().execute_function("system.ai.python_exec", parameters=parameters)
  raise ValueError(f"Unknown tool: {tool_name}")

def run_agent(prompt):
  """
  Send a user prompt to the LLM and return a list of LLM response messages
  The LLM is allowed to call the code interpreter tool, if needed, to respond to the user
  """
  result_msgs = []
  response = openai_client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": prompt}],
    tools=builtin_tools,
  )
  msg = response.choices[0].message
  result_msgs.append(msg.to_dict())

  # If the model executed a tool, call it
  if msg.tool_calls:
    call = msg.tool_calls[0]
    tool_result = call_tool(call.function.name, json.loads(call.function.arguments))
    result_msgs.append({"role": "tool", "content": tool_result.value, "name": call.function.name, "tool_call_id": call.id})
  return result_msgs

Menguji agen

Uji agen dengan mengkuerinya dengan perintah yang memerlukan menjalankan kode Python:

answer = run_agent("What is the 100th fibonacci number?")
for message in answer:
  print(f'{message["role"]}: {message["content"]}')

Selain output LLM, Anda akan melihat informasi pelacakan terperinci langsung di buku catatan Anda. Jejak ini membantu Anda men-debug panggilan agen yang lambat atau gagal. Jejak ini secara otomatis ditambahkan menggunakan mlflow.openai.autolog() .

Mengaktifkan agen

Sekarang setelah Anda memiliki agen, Anda dapat mengemas dan menerapkannya ke titik akhir layanan Databricks. Mulai kumpulkan umpan balik pada agen yang disebarkan dengan membagikannya dengan orang lain dan mengobrol dengannya menggunakan UI obrolan bawaan.

Menyiapkan kode agen untuk penyebaran

Untuk menyiapkan kode agen Anda untuk deployment, gunakan antarmuka MLflow ChatAgent untuk membungkusnya. Antarmuka ChatAgent adalah cara yang direkomendasikan untuk mengemas agen untuk penyebaran di Azure Databricks.

Untuk mengimplementasikan ChatAgent antarmuka, Anda harus menentukan predict() fungsi yang mengirim pesan pengguna ke agen, mengumpulkan respons agen, dan mengembalikannya dalam ChatAgentResponses format .

import uuid
from typing import Any, Optional

from mlflow.pyfunc import ChatAgent
from mlflow.types.agent import ChatAgentMessage, ChatAgentResponse, ChatContext

class QuickstartAgent(ChatAgent):
  def predict(
    self,
    messages: list[ChatAgentMessage],
    context: Optional[ChatContext] = None,
    custom_inputs: Optional[dict[str, Any]] = None,
  ) -> ChatAgentResponse:
    # 1. Extract the last user prompt from the input messages
    prompt = messages[-1].content

    # 2. Call run_agent to get back a list of response messages
    raw_msgs = run_agent(prompt)

    # 3. Map each response message into a ChatAgentMessage and return
    # the response
    out = []
    for m in raw_msgs:
      out.append(ChatAgentMessage(
        id=uuid.uuid4().hex,
        **m
      ))

    return ChatAgentResponse(messages=out)

Tambahkan kode berikut ke buku catatan Anda untuk menguji kelas Anda ChatAgent :

AGENT = QuickstartAgent()
for response_message in AGENT.predict({"messages": [{"role": "user", "content": "What's the 100th fibonacci number?"}]}).messages:
  print(f"role: {response_message.role}, content: {response_message.content}")

Gabungkan semua kode agen Anda ke dalam satu file sehingga Anda dapat mencatat dan menyebarkannya.

Konsolidasikan semua kode agen Anda ke dalam satu sel buku catatan.
Di bagian atas sel, tambahkan perintah "magic command" %%writefile quickstart_agent.py untuk menyimpan agen Anda ke dalam file.
Di bagian bawah sel, panggil mlflow.models.set_model() dengan objek agen Anda. Ini memberi tahu MLflow objek agen mana yang akan digunakan saat melayani prediksi. Langkah ini secara efektif mengonfigurasi titik masuk ke kode agen kami.

Sel buku catatan Anda akan terlihat seperti berikut ini:

%%writefile quickstart_agent.py

import json
import uuid
from databricks.sdk import WorkspaceClient
from databricks_openai import UCFunctionToolkit, DatabricksFunctionClient
from typing import Any, Optional

import mlflow
from mlflow.pyfunc import ChatAgent
from mlflow.types.agent import ChatAgentMessage, ChatAgentResponse, ChatContext

# Add an mlflow.openai.autolog() call to capture traces in the serving endpoint

# Get an OpenAI client configured to talk to Databricks model serving endpoints
# We'll use this to query an LLM in our agent
openai_client = WorkspaceClient().serving_endpoints.get_open_ai_client()

# Load Databricks built-in tools (a stateless Python code interpreter tool)
client = DatabricksFunctionClient()
builtin_tools = UCFunctionToolkit(function_names=["system.ai.python_exec"], client=client).tools
for tool in builtin_tools:
  del tool["function"]["strict"]


def call_tool(tool_name, parameters):
  if tool_name == "system__ai__python_exec":
    return DatabricksFunctionClient().execute_function("system.ai.python_exec", parameters=parameters)
  raise ValueError(f"Unknown tool: {tool_name}")

def run_agent(prompt):
  """
  Send a user prompt to the LLM, and return a list of LLM response messages
  The LLM is allowed to call the code interpreter tool if needed, to respond to the user
  """
  result_msgs = []
  response = openai_client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": prompt}],
    tools=builtin_tools,
  )
  msg = response.choices[0].message
  result_msgs.append(msg.to_dict())

  # If the model executed a tool, call it
  if msg.tool_calls:
    call = msg.tool_calls[0]
    tool_result = call_tool(call.function.name, json.loads(call.function.arguments))
    result_msgs.append({"role": "tool", "content": tool_result.value, "name": call.function.name, "tool_call_id": call.id})
  return result_msgs

class QuickstartAgent(ChatAgent):
  def predict(
    self,
    messages: list[ChatAgentMessage],
    context: Optional[ChatContext] = None,
    custom_inputs: Optional[dict[str, Any]] = None,
  ) -> ChatAgentResponse:
    prompt = messages[-1].content
    raw_msgs = run_agent(prompt)
    out = []
    for m in raw_msgs:
      out.append(ChatAgentMessage(
        id=uuid.uuid4().hex,
        **m
      ))

    return ChatAgentResponse(messages=out)

AGENT = QuickstartAgent()
mlflow.models.set_model(AGENT)

Catat agen

Masukkan agen Anda dan daftarkan ke dalam Katalog Unity. Ini mengemas agen Anda dan dependensinya ke dalam satu artefak untuk implementasi.

import mlflow
from mlflow.models.resources import DatabricksFunction, DatabricksServingEndpoint
from pkg_resources import get_distribution

# Change the catalog name ("main") and schema name ("default") to register the agent to a different location
registered_model_name = "main.default.quickstart_agent"

# Specify Databricks resources that the agent needs to access.
# This step lets Databricks automatically configure authentication
# so the agent can access these resources when it's deployed.
resources = [
  DatabricksServingEndpoint(endpoint_name="databricks-claude-3-7-sonnet"),
  DatabricksFunction(function_name="system.ai.python_exec"),
]

mlflow.set_registry_uri("databricks-uc")
logged_agent_info = mlflow.pyfunc.log_model(
  artifact_path="agent",
  python_model="quickstart_agent.py",
  extra_pip_requirements=[f"databricks-connect=={get_distribution('databricks-connect').version}"],
  resources=resources,
  registered_model_name=registered_model_name
)

Mengaktifkan agen

Sebarkan agen terdaftar Anda ke titik akhir penyajian:

from databricks import agents

deployment_info = agents.deploy(
  model_name=registered_model_name, model_version=logged_agent_info.registered_model_version
)

Setelah endpoint agen dimulai, Anda dapat berkomunikasi dengannya menggunakan AI Playground atau membagikannya kepada pemangku kepentingan untuk mendapatkan umpan balik.

Langkah selanjutnya

Pilih tempat berikutnya berdasarkan tujuan Anda:

Mengukur dan meningkatkan kualitas agen Anda: Lihat Panduan Cepat Evaluasi Agen.

Membangun agen yang lebih canggih: Membuat agen yang melakukan RAG menggunakan data yang tidak terstruktur, menangani percakapan multi-giliran, dan menggunakan Evaluasi Agen untuk mengukur kualitas. Lihat Tutorial: Membangun, mengevaluasi, dan menyebarkan agen pengambilan data.

Pelajari cara membuat agen menggunakan kerangka kerja lain: Pelajari cara membuat agen menggunakan pustaka populer seperti LangGraph, Python murni, dan OpenAI. Lihat Gunakan ChatAgent untuk membuat agen

Bagikan melalui

Mulai menggunakan agen AI

Persyaratan

Contoh buku catatan

Demo agen AI Mosaik

Tentukan agen

Menguji agen

Mengaktifkan agen

Menyiapkan kode agen untuk penyebaran

Catat agen

Mengaktifkan agen

Langkah selanjutnya

Saran dan Komentar

Sumber Daya Tambahan: