O senhor pode começar com AI agentes
Crie seu primeiro agente AI usando o Mosaic AI Agent Framework. Neste tutorial, o senhor aprenderá:
- Crie um agente usando o Agent Framework.
- Adicione uma ferramenta ao seu agente.
- O senhor implantou seu agente em um Databricks servindo o modelo endpoint.
Para obter uma introdução conceitual aos agentes e outros aplicativos gen AI, consulte O que são aplicativos gen AI?
Requisitos
O site workspace deve ter os seguintes recursos ativados:
- Unity Catalog
- Estrutura do Mosaic AI Agent
- Modelos de fundação (pay-per-tokens, provisionamento, taxa de transferência ou modelos externos). Ver recurso com disponibilidade regional limitada
Exemplo de notebook
Este Notebook contém todo o código de que o senhor precisa para criar e implantar seu primeiro agente AI. Importe o Notebook para o site Databricks workspace para executá-lo.
Mosaic AI demonstração do agente
Defina o agente
Um agente AI consiste no seguinte:
- Um modelo de linguagem grande (LLM) que pode raciocinar e tomar decisões
- Ferramentas que o LLM pode usar para fazer mais do que apenas gerar texto, como executar código Python ou buscar dados
Execute o código a seguir em um Notebook Databricks para definir um agente de chamada de ferramenta simples:
-
Instale o pacote Python necessário:
Python%pip install -U -qqqq mlflow databricks-openai databricks-agents"
dbutils.library.restartPython()mlflow: Usado para desenvolvimento e rastreamento de agentes.databricks-openaiUtilizado para conectar-se ao LLM hospedado Databrickse acessar as ferramentas Unity Catalog .databricks-agents: Usado para embalar e implantar o agente.
-
Defina o agente. Esse trecho de código faz o seguinte:
- Conecta-se ao modelo Databricks servindo endpoint usando o cliente OpenAI.
- Habilita o rastreamento do MLflow usando
autolog(). Isso adiciona instrumentação para que você possa ver o que seu agente faz quando você envia uma consulta. - Adiciona a ferramenta
system.ai.python_execao seu agente. Essa função integrada Unity Catalog permite que seu agente execute o código Python. - Usa funções auxiliares MLflow (
output_to_responses_items_stream,create_function_call_output_item) para converter a saída do transmissão LLM em um formato compatível com a API de Respostas.
Pythonimport json
import mlflow
from databricks.sdk import WorkspaceClient
from databricks_openai import UCFunctionToolkit, DatabricksFunctionClient
# Import MLflow utilities for converting from chat completions to Responses API format
from mlflow.types.responses import output_to_responses_items_stream, create_function_call_output_item
# Enable automatic tracing for easier debugging
mlflow.openai.autolog()
# Get an OpenAI client configured to connect to Databricks model serving endpoints
openai_client = WorkspaceClient().serving_endpoints.get_open_ai_client()
# 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).value
raise ValueError(f"Unknown tool: {tool_name}")
def call_llm(prompt):
for chunk in openai_client.chat.completions.create(
model="databricks-claude-3-7-sonnet",
messages=[{"role": "user", "content": prompt}],
tools=builtin_tools,
stream=True
):
yield chunk.to_dict()
def run_agent(prompt):
"""
Send a user prompt to the LLM, and yield LLM + tool call responses
The LLM is allowed to call the code interpreter tool if needed, to respond to the user
"""
# Convert output into Responses API-compatible events
for chunk in output_to_responses_items_stream(call_llm(prompt)):
yield chunk.model_dump(exclude_none=True)
# If the model executed a tool, call it and yield the tool call output in Responses API format
if chunk.item.get('type') == 'function_call':
tool_name = chunk.item["name"]
tool_args = json.loads(chunk.item["arguments"])
tool_result = call_tool(tool_name, tool_args)
yield {"type": "response.output_item.done", "item": create_function_call_output_item(call_id=chunk.item["call_id"], output=tool_result)}
Teste o agente
Teste o agente consultando-o com um prompt que exige a execução do código Python:
for output_chunk in run_agent("What is the square root of 429?"):
print(output_chunk)
Além da saída do LLM, o senhor verá informações detalhadas de rastreamento diretamente no Notebook. Esses rastreamentos ajudam a depurar chamadas lentas ou falhadas do agente. Esses traços foram adicionados automaticamente usando mlflow.openai.autolog() .
implantado o agente
Agora que o senhor tem um agente, pode empacotá-lo e implantá-lo em um Databricks que serve endpoint. Começar a coletar feedback sobre um agente implantado, compartilhando-o com outras pessoas e conversando com ele usando uma UI de bate-papo integrada.
Prepare o código do agente para implantação
Para preparar o código do agente para implantação, envolva-o usando a interface ResponsesAgent do MLflow. A interface ResponsesAgent é a maneira recomendada de empacotar agentes para implantação em Databricks.
-
Para implementar a interface
ResponsesAgent, defina os métodospredict_stream()(para respostas de transmissão) epredict()(para solicitações de não transmissão). Como a lógica subjacente do agente já gera eventos compatíveis com a API de Respostas, a implementação é simples:Pythonfrom mlflow.pyfunc import ResponsesAgent
from mlflow.types.responses import ResponsesAgentRequest, ResponsesAgentResponse, ResponsesAgentStreamEvent
class QuickstartAgent(ResponsesAgent):
def predict_stream(self, request: ResponsesAgentRequest):
# Extract the user's prompt from the request
prompt = request.input[-1].content
# Stream response items from our agent
for chunk in run_agent(prompt):
yield ResponsesAgentStreamEvent(**chunk)
def predict(self, request: ResponsesAgentRequest) -> ResponsesAgentResponse:
outputs = [
event.item
for event in self.predict_stream(request)
if event.type == "response.output_item.done"
]
return ResponsesAgentResponse(output=outputs) -
Adicione o seguinte código ao Notebook para testar a classe
ResponsesAgent:Pythonfrom mlflow.types.responses import ResponsesAgentRequest
AGENT = QuickstartAgent()
# Create a ResponsesAgentRequest with input messages
request = ResponsesAgentRequest(
input=[
{
"role": "user",
"content": "What's the square root of 429?"
}
]
)
for event in AGENT.predict_stream(request):
print(event) -
Combine todo o código do agente em um único arquivo para que o senhor possa log e implantá-lo.
- Consolide todo o código do agente em uma célula do Notebook.
- Na parte superior da célula, adicione o comando mágico
%%writefile quickstart_agent.pypara salvar seu agente em um arquivo. - Na parte inferior da célula, chame
mlflow.models.set_model()com seu objeto agente. Isso informa ao MLflow qual objeto de agente deve ser usado ao fornecer previsões. Essa etapa configura efetivamente o ponto de entrada do nosso código de agente.
A célula do Notebook deve se parecer com o seguinte:
%%writefile quickstart_agent.py
import json
from databricks.sdk import WorkspaceClient
from databricks_openai import UCFunctionToolkit, DatabricksFunctionClient
import mlflow
from mlflow.pyfunc import ResponsesAgent
from mlflow.types.responses import (
ResponsesAgentRequest,
ResponsesAgentResponse,
ResponsesAgentStreamEvent,
output_to_responses_items_stream,
create_function_call_output_item
)
# Enable automatic tracing for deployed agent
mlflow.openai.autolog()
# Get an OpenAI client configured to talk to Databricks model serving endpoints
openai_client = WorkspaceClient().serving_endpoints.get_open_ai_client()
# 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).value
raise ValueError(f"Unknown tool: {tool_name}")
def call_llm(prompt):
for chunk in openai_client.chat.completions.create(
model="databricks-claude-3-7-sonnet",
messages=[{"role": "user", "content": prompt}],
tools=builtin_tools,
stream=True
):
yield chunk.to_dict()
def run_agent(prompt):
"""
Send a user prompt to the LLM, and yield LLM + tool call responses
The LLM is allowed to call the code interpreter tool if needed, to respond to the user
"""
# Convert output into Responses API-compatible events
for chunk in output_to_responses_items_stream(call_llm(prompt)):
yield chunk.model_dump(exclude_none=True)
# If the model executed a tool, call it and yield the tool call output in Responses API format
if chunk.item.get('type') == 'function_call':
tool_name = chunk.item["name"]
tool_args = json.loads(chunk.item["arguments"])
tool_result = call_tool(tool_name, tool_args)
yield {"type": "response.output_item.done", "item": create_function_call_output_item(call_id=chunk.item["call_id"], output=tool_result)}
class QuickstartAgent(ResponsesAgent):
def predict_stream(self, request: ResponsesAgentRequest):
# Extract the user's prompt from the request
prompt = request.input[-1].content
# Stream response items from our agent
for chunk in run_agent(prompt):
yield ResponsesAgentStreamEvent(**chunk)
def predict(self, request: ResponsesAgentRequest) -> ResponsesAgentResponse:
outputs = [
event.item
for event in self.predict_stream(request)
if event.type == "response.output_item.done"
]
return ResponsesAgentResponse(output=outputs)
AGENT = QuickstartAgent()
mlflow.models.set_model(AGENT)
registrar o agente
Faça o login do seu agente e registre-o em Unity Catalog. Isso agrupa o agente e suas dependências em um único artefato para implantação.
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
)
implantado o agente
implantar seu agente registrado em um site endpoint:
from databricks import agents
deployment_info = agents.deploy(
model_name=registered_model_name,
model_version=logged_agent_info.registered_model_version,
scale_to_zero=True
)
Depois que o agente endpoint começar, o senhor pode conversar com ele usando o AI Playground ou compartilhá-lo com as partes interessadas para obter feedback.
Próximas etapas
Escolha para onde ir a seguir com base em seus objetivos:
Avalie e melhore a qualidade do seu agente : consulte o guia de início rápido da Avaliação de Agentes.
Crie agentes mais avançados : crie um agente que execute RAG usando dados não estruturados, gerencie conversas de vários turnos e use a Avaliação de Agentes para medir a qualidade. Veja o tutorial: Criar, avaliar e implantar um agente de recuperação.
Aprenda a criar agentes utilizando outras estruturas : Aprenda a criar agentes utilizando bibliotecas populares como LangGraph, pure Python e OpenAI. Consulte os agentes de autorização AI no código.