Documentación de Oracle Cloud Infrastructure

Inicio rápido

Descripción general

Siga esta guía de dos pasos para aprovisionar, configurar y ejecutar un agente.

Paso 1: Aprovisionar un agente con un punto final en la consola de OCI

En este paso, en la consola de OCI, cree una instancia de agente y un punto final para el agente. No es necesario agregar ninguna herramienta a este agente. En este paso se trata de la configuración de la infraestructura y se utiliza la consola de OCI para hacerlo. También puede crear una instancia de agente y su punto final mediante el SDK de OCI o con Terraform.

Nota: Las instrucciones de configuración o las herramientas para la instancia de agente se tratan en el paso 2.

Paso 2: Configuración y ejecución del agente mediante el ADK

En este paso, utilice el ADK para configurar y ejecutar el agente. Para configurar su agente, puede iterar con sus instrucciones y herramientas localmente. Después de configurar el agente localmente, transfiera la información del agente a la instancia del agente remoto ejecutando el método agent.setup(). Para un agente en ejecución, ejecute el método agent.run() para cumplir las solicitudes, sin tener que escribir código para manejar las interacciones cliente-servidor de bajo nivel, como la gestión de sesiones, la búsqueda y llamada de funciones, etc.

Requisitos

Paso 1: Aprovisionamiento del punto final del agente

Siga esta guía para crear una instancia de agente y un punto final de agente mediante la consola de OCI con los siguientes detalles:

  • No agregue ninguna herramienta mediante la consola de OCI.

  • Mantenga la casilla de control Crear automáticamente un punto final para este agente seleccionada para obtener un punto final de agente.

  • Después de crear el agente, copie el ID (OCID) del punto final del agente y péguelo en un bloc de notas para el siguiente paso.

Para cada agente que esté desarrollando, solo tendrá que realizar este paso una vez.

Nota: En este paso, no agrega ninguna herramienta a través de la consola de OCI.

En su lugar, en el siguiente paso, utilice el ADK para configurar las herramientas localmente. A continuación, utilice el ADK para sincronizar automáticamente las herramientas locales con la instancia de agente remoto. El objetivo es que, mediante el ADK, pueda tener una única fuente de datos para las herramientas que incluye el esquema de función y el dispositivo de llamada real que maneja la llamada de función.

En este paso, está aprovisionando una instancia de agente y un punto final de agente en la nube. Piense en este punto final de agente como un punto final de API de LLM al que el ADK se conecta, pero que se mejora con comportamientos ágentes, sus herramientas registradas previamente y está dedicado a su aplicación. En el paso 2, conecte el objeto de agente de ADK a este punto final de agente.

Paso 2: Configuración y ejecución del agente

Python

Cree un proyecto con un entorno virtual:

# Create a project folder with name of your choice
mkdir <your-project-name>
cd <your-project-name>

# Create and activate a virtual environment under `<myenv>` subfolder
python -m venv <myenv>
source <myenv>/bin/activate

El ADK de Python requiere Python 3.10 o posterior. Asegúrese de que tiene instalada la versión correcta de Python en su entorno.

Instalación del ADK

Después de crear un proyecto y un entorno virtual, instale la última versión de ADK:

pip install "oci[adk]"

Consejo: ¿Se ha producido un error de timeout de la conexión a pypi.org?

Si obtiene el error anterior al ejecutar el comando pip install, es probable que se deba a un problema de red. Intente desconectarse de la VPN y vuelva a ejecutar el comando.

Java

Para incluir ADK en el proyecto de Java, agregue la siguiente dependencia de Maven a pom.xml:

    <dependency>
        <groupId>com.oracle.oci.sdk</groupId>
        <artifactId>oci-java-sdk-addons-adk</artifactId>
        <version>{latest-version}</version>
    </dependency>

Instalarlo en su repositorio de Maven local

mvn clean install

Autenticación de la aplicación ADK en OCI

El ADK proporciona una clase AgentClient para simplificar la gestión de la autenticación y la gestión de recursos de agente. Se admiten cuatro tipos de autenticación:

Python

Autenticación de clave de API (por defecto)

La autenticación de clave de API es el método por defecto y más común para autenticarse con servicios de OCI.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="api_key",
    profile="DEFAULT",
    region="<your-region>"  # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Para configurar la autenticación de claves de API, siga la guía de configuración de claves de API de OCI.

Autenticación de token de seguridad

La autenticación de token de seguridad crea un token de sesión temporal que se puede utilizar para autenticar ADK para utilizar los servicios de OCI. Este método se utiliza comúnmente en pruebas locales.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="security_token",
    profile="DEFAULT",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Para autenticar una sesión de la CLI, ejecute el siguiente comando en su terminal. Sustituya el nombre de perfil y la región por los valores.

oci session authenticate --auth security_token --profile-name DEFAULT --region <your-region>

Si la autenticación se realiza correctamente, la aplicación ADK que se ejecuta desde el mismo terminal también se autentica.

Autenticación de principal de instancia

Se recomienda la autenticación del principal de instancia para las instancias informáticas de OCI.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="instance_principal",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Autenticación de entidad de recurso

La autenticación de entidad de recurso se recomienda para recursos de OCI como Functions.

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="resource_principal",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

Java

Autenticación de clave de API (por defecto)

La autenticación de clave de API es el método por defecto y más común para autenticarse con servicios de OCI.

import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.ConfigFileAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new ConfigFileAuthenticationDetailsProvider(
                ConfigFileReader.parse("~/.oci/config", "DEFAULT"));

AgentClient agentClient = AgentClient.builder()
    .authProvider(authProvider)
    .region("us-chicago-1")
    .build();

Para configurar la autenticación de claves de API, siga la guía de configuración de claves de API de OCI.

Autenticación de token de seguridad

La autenticación de token de seguridad crea un token de sesión temporal que se puede utilizar para autenticar ADK para utilizar los servicios de OCI. Este enfoque se utiliza comúnmente en las pruebas locales.

import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new SessionTokenAuthenticationDetailsProvider(
                ConfigFileReader.parse("~/.oci/config", "DEFAULT"));

AgentClient agentClient = AgentClient.builder()
    .authProvider(authProvider)
    .region("us-chicago-1")
    .build();

Para autenticar una sesión de la CLI, ejecute esta operación en su terminal. Sustituya el nombre de perfil y la región por los valores.

oci session authenticate --auth security_token --profile-name DEFAULT --region us-chicago-1

Después de la autenticación correcta, la aplicación ADK que se ejecuta desde el mismo terminal se debe autenticar.

Autenticación de principal de instancia

Se recomienda la autenticación del principal de instancia para las instancias informáticas de OCI.

import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.InstancePrincipalsAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new InstancePrincipalsAuthenticationDetailsProvider();

AgentClient agentClient = AgentClient.builder()
    .authProvider(authProvider)
    .region("us-chicago-1")
    .build();

Autenticación de entidad de recurso

La autenticación de entidad de recurso se recomienda para recursos de OCI como Functions.

import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.ResourcePrincipalAuthenticationDetailsProvider;
import com.oracle.bmc.adk.client.AgentClient;

BasicAuthenticationDetailsProvider authProvider =
        new ResourcePrincipalAuthenticationDetailsProvider();

AgentClient agentClient = AgentClient.builder()
    .authProvider(authProvider)
    .region("us-chicago-1")
    .build();

Nota: Asegúrese de que el usuario que se está autenticando tiene permisos para utilizar el servicio OCI Generative AI Agents.

Configuración y Ejecución de un Agente

Después de que el punto final del agente esté activo, puede configurar y ejecutar el siguiente ejemplo de agente meteorológico simple mediante el ADK.

Python

Cree un archivo denominado quickstart.py en la raíz del proyecto y copie el siguiente código en el archivo:

quickstart.py

from typing import Dict
from oci.addons.adk import Agent, AgentClient, tool

# Use @tool to signal that this Python function is a function tool.
# Apply standard docstring to provide function and parameter descriptions.
@tool
def get_weather(location: str) -> Dict[str, str]:
    """
    Get the weather for a given location.

    Args:
      location(str): The location for which weather is queried
    """
    return {"location": location, "temperature": 72, "unit": "F"}


def main():
    # Create an agent client with your authentication and region details
    # Replace the auth_type with your desired authentication method.
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="us-chicago-1",
    )

    # Create a local agent object with the client, instructions, and tools.
    # You also need the agent endpoint id. To obtain the OCID, follow Step 1.
    agent = Agent(
        client=client,
        agent_endpoint_id="<your-agent-endpoint-OCID>",
        instructions="You perform weather queries using tools.",
        tools=[get_weather]
    )

    # Sync local instructions and tools to the remote agent resource
    # You only need to invoke setup() when you change instructions and tools
    agent.setup()

    # Run the agent. You can embed this method in your webapp, slack bot, etc.
    # You invoke the run() when you need to handle your user's request.
    input = "Is it cold in Seattle?"
    response = agent.run(input)

    # Print the response
    response.pretty_print()

if __name__ == "__main__":
    main()

Ejecutar el script

A continuación, ejecute el script quickstart.py y debería ver la salida de la siguiente forma:

Java

Cree un archivo denominado QuickStart.java en la raíz del proyecto y copie el siguiente código en él.

QuickStart.java

package demos;
import com.oracle.bmc.ConfigFileReader;
import com.oracle.bmc.adk.agent.Agent;
import com.oracle.bmc.adk.client.AgentClient;
import com.oracle.bmc.adk.tools.FunctionTool;
import com.oracle.bmc.adk.tools.Param;
import com.oracle.bmc.adk.tools.Tool;
import com.oracle.bmc.adk.run.RunResponse;
import com.oracle.bmc.auth.BasicAuthenticationDetailsProvider;
import com.oracle.bmc.auth.SessionTokenAuthenticationDetailsProvider;

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;

public class QuickStart {
    @Tool(name = "getWeather", description = "Get weather of a given location")
    public static Map<String, String> getWeather(
            @Param(description = "The location") String location) {
        Map<String, String> weather = new HashMap<>();
        weather.put("location", location);
        weather.put("temperature", "72");
        weather.put("unit", "F");
        return weather;
    }

    public static void main(String[] args) throws Exception {
        final String configLocation = "~/.oci/config";
        final String configProfile = "DEFAULT";
        BasicAuthenticationDetailsProvider authProvider =
                new SessionTokenAuthenticationDetailsProvider(
                        ConfigFileReader.parse(configLocation, configProfile));

        AgentClient agentClient = AgentClient.builder()
            .authProvider(authProvider)
            .region("us-chicago-1")
            .build();

        FunctionTool getWeatherTool =
                FunctionTool.fromMethod(QuickStart.class, "getWeather", String.class);

        Agent agent = Agent.builder()
                .client(agentClient)
                .agentEndpointId("YOUR_AGENT_ENDPOINT_ID")
                .instructions("Perform weather queries using the given tools.")
                .tools(Arrays.asList(getWeatherTool))
                .build();

        agent.setup();

        String input = "Is it cold in Seattle";
        RunResponse response = agent.run(input);
        response.prettyPrint();
    }
}

IntelliJ IDEA

Si utiliza IntelliJ, seleccione la configuración de ejecución denominada QuickStart y, a continuación, haga clic en Run ▶️ o pulse Shift + F10 para iniciar el programa.

Terminal

Si está utilizando el terminal:

mvn compile exec:java \
  -Dexec.mainClass="demos.QuickStart" \
  -Dexec.workingdir=java/examples

Asegúrese de que está ejecutando esto desde la raíz del proyecto (donde se encuentra pom.xml).

Debería ver una salida como esta:

Resumen

Ahora tiene un agente meteorológico simple que utiliza ADK que se ejecuta localmente, con conexión saliente al punto final del agente en OCI.

Nota: ¿Por qué necesita un punto final de agente? ¿Puede utilizar ADK localmente sin un punto final de agente remoto?

ADK requiere que un punto final de agente funcione de forma muy parecida a como un marco de agente del cliente necesita un punto final de LLM. Piense en el punto final del agente como un punto final de LLM mejorado, que ofrece funciones avanzadas de autenticación, como peticiones de datos de razonamiento optimizadas y herramientas del lado del servidor de OCI. ADK no soporta conexiones directas a puntos finales de LLM raw.

Este agente está equipado con una herramienta de función personalizada local get_weather que ha implementado. El agente está listo para manejar la solicitud de su usuario expresada en lenguaje natural.

En segundo plano, el ADK maneja la orquestación cliente-servidor de bajo nivel, mientras que el punto final del agente maneja la ejecución del bucle del agente principal, la comunicación con un LLM y la posible llamada a otras herramientas alojadas, como una herramienta RAG (no implementada en este inicio rápido).

Cómo Funciona

Normalmente, su código ADK está embebido en una aplicación más grande y se despliega en su entorno. Tu aplicación más grande puede ser una aplicación web, un Slackbot, un servicio o un script.

A través de las herramientas de funciones de ADK, puede integrar un agente con su base de código local, sus bases de datos remotas, microservicios remotos, etc., mediante la autenticación nativa de su entorno.

El ADK llama al punto final del agente, expuesto por el servicio OCI Generative AI Agents, que ejecuta el bucle del agente de forma remota en su entorno.

Cuando el bucle de agente decide llamar a una herramienta alojada (como una herramienta RAG), las llamadas se realizan sin volver a ADK.

Cuando el bucle de agente decide llamar a las herramientas de función local, el control se devuelve al ADK. El ADK llama a las herramientas de función locales y envía la salida de la herramienta de función de nuevo a los agentes de IA generativa, que luego continúa la siguiente iteración del bucle de agente.

Siguientes Pasos