diff --git a/generative-ai-agent-adk/adk-installation/adk_install.md b/generative-ai-agent-adk/adk-installation/adk_install.md index 1d7272d76..4733850b7 100644 --- a/generative-ai-agent-adk/adk-installation/adk_install.md +++ b/generative-ai-agent-adk/adk-installation/adk_install.md @@ -2,7 +2,7 @@ ## Introduction -This lab will take you through the steps needed to install ADK using python installer .We recommend to use *OCI DATA Science* based notebook to run the operation as it comes with all the necessary software in place,however we have added an optional steps to follow local machine for ADK client setup. +This lab will take you through the steps needed to install ADK using the Python installer. We recommend using an OCI Data Science-based notebook to run the operation, as it comes with all the necessary software in place. However, we have added optional steps to follow on a local machine for the ADK client setup. Estimated Time: 30 minutes @@ -10,42 +10,45 @@ Estimated Time: 30 minutes ## Task 1: Setup OCI Data Science notebook for **ADK** usage. -1. From OCI Console > *AI & Analytics* > *Data science* +1. From OCI Console > AI & Analytics > Data Science ![Data science view](images/datascience_view.png) -1. Select *Create project*.Provide name and description. + +2. Select Create project. Provide a name and description. ![Data science project](images/create_ds_project.png) -1. With in the project,click *Create notebook session*. +3. Within the project, click Create notebook session. ![Create notebook](images/create_nb.png) -1. Provide a name and retain all the other default settings and click *Create*. +4. Provide a name, retain all the other default settings, and click Create. ![Create notebook completed](images/create_nb_final.png) -1. Wait for the resource to become active. +5. Wait for the resource to become active. ![Active notebook](images/nb_active.png) -1. Open the notebook detail page and click *Open*. +6. Open the notebook detail page and click Open. ![NB details](images/nb_detail_page.png) -1. Provide credentials and multi factor auth when prompted.Wait for the notebook to be opened. +7. Provide credentials and multi-factor authentication when prompted. Wait for the notebook to open. ![NB Opened](images/nb_open_view.png) -1. Click *extend* and extend the notebook timeout. +8. Click Extend and extend the notebook timeout. + -**You can skip the next section and follow to Task 3** +**You can skip the next section and proceed to Task 3** ## Task 2: (Optional) Setup a local machine for **ADK** usage. 1. Python ADK requires Python 3.10 or later. Ensure you have the correct version of Python installed in your environment. -1. Follow below and installed *OCI* with *ADK* + +2. Follow the steps below and install OCI with ADK: ``` @@ -57,7 +60,8 @@ Estimated Time: 30 minutes source /bin/activate ``` -1. After you create a project and a virtual environment, install the latest version of ADK: + +3. After you create a project and a virtual environment, install the latest version of ADK: ``` @@ -65,21 +69,21 @@ Estimated Time: 30 minutes pip install oci-cli ``` -1. Create an *API Signing Key* and store for further usage. Refer [here](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#two) for detailed steps. +4. Create an *API Signing Key* and store for it further usage. Refer [here](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#two) for detailed steps. ## Task 3: Validate ADK installation using OCI Data science. -1. Follow below steps if you are using a data science notebook.If not move to Task 4. +1. Follow the steps below if you are using a Data Science notebook. If not, move to Task 4 -* Click File > New >Notebook. + * Click File > New >Notebook. ![New Notebook](images/new_notbook.png) -1. Right click on Untitled notebook and rename the same. +2. Right-click on the untitled notebook and rename it. ![Rename the NB](images/rename_nb.png) -1. Run below and validate it returns the correct name reference. +3. Run the following and validate that it returns the correct name reference. ``` @@ -87,11 +91,12 @@ Estimated Time: 30 minutes adk.__name__ ``` - ![ADK Validation](images/adk_validate.png) -## Task 3: Validate ADK installation for local setup. + + +## Task 4: Validate ADK installation for local setup -1. Follow below steps for local machine +1. Follow the steps below for a local machine: ``` @@ -99,7 +104,8 @@ Estimated Time: 30 minutes adk.__name__ ``` -1. Validate the name reference. + +2. Validate the name reference. **Proceed to the next lab.** diff --git a/generative-ai-agent-adk/agent-config/agentconfig.md b/generative-ai-agent-adk/agent-config/agentconfig.md index 1110a6d1d..4ea074045 100644 --- a/generative-ai-agent-adk/agent-config/agentconfig.md +++ b/generative-ai-agent-adk/agent-config/agentconfig.md @@ -2,10 +2,10 @@ ## Introduction -This lab will take details the steps to configure Agent using the tools that created.It will also provide the steps to add additional client side tools such as Custom tools using function as well as integration with *Model Context Protocol- MCP*. +This lab details the steps to configure an Agent using the tools that were created. It also provides steps to add additional client-side tools, such as custom tools using functions, as well as integration with Model Context Protocol - MCP. ## Task 1: Import ADK modules. -The tasks imports various ADK python modules as well as some of the optional libraries for our usage.All these instructions works for python script as well as OCI Data science notebooks. +This task imports various ADK Python modules as well as some optional libraries for our usage. All these instructions work for Python scripts as well as OCI Data Science notebooks. 1. Add below to the notebook cell. @@ -23,7 +23,8 @@ The tasks imports various ADK python modules as well as some of the optional lib from mcp.client.session_group import StreamableHttpParameters ``` -1. Add below snippet for enabling async run for notbook. + +2. Add the below snippet to enable async run for the notebook. ``` @@ -33,12 +34,13 @@ The tasks imports various ADK python modules as well as some of the optional lib ``` ![](images/module_import.png) -1. For notebook,you may use the *Play* button and run these commands.For python script ,you may use your editor or run using *python scrip.py* format. + +3. For notebooks, you may use the Play button and run these commands. For Python scripts, you may use your editor or run using the python script.py format. ## Task 2: Define variables. -1. Define variables for agent endpoint and RAG knowledge based IDs. +1. Define variables for the agent endpoint and RAG knowledge base IDs. ``` @@ -46,7 +48,8 @@ The tasks imports various ADK python modules as well as some of the optional lib knowledge_id="knowledgeBase OCID" ``` -1. Define instructions for agents. + +2. Define instructions for agents. ``` @@ -63,7 +66,7 @@ The tasks imports various ADK python modules as well as some of the optional lib ## Task 3: Define a custom tool based on function. -1. Use below code to set a simple custom function based tool,which will return the season based on a location. +1. Use the below code to set a simple custom function-based tool, which will return the season based on a location. ``` @@ -92,13 +95,13 @@ The tasks imports various ADK python modules as well as some of the optional lib ![Custom function](images/custom_function.png) -## Task 4: Define mcp call using stdIO mode. +## Task 4: Define MCP call using stdIO mode. -* We are using an open source mcp library to fetch information from public internet. +* We are using an open-source MCP library to fetch information from the public internet. * The library details and credit goes to https://github.com/openbnb-org/mcp-server-airbnb. -* If you are using local client execution ,ensure nodejs and npx is available for run. +* If you are using local client execution, ensure Node.js and npx are available to run. -1. Copy the below to notebook or local script to define the MCP. +1. Copy the below to a notebook or local script to define the MCP. ``` @@ -114,9 +117,9 @@ The tasks imports various ADK python modules as well as some of the optional lib ![MCP Definition](images/mcp.png) -## Task 5: Connect Knowledge base to the RAG too. +## Task 5: Connect Knowledge Base to the RAG tool. -1. Connect knowledge base id and RAG tool with the agent.To do so copy below snippet and pase to the notebook or python script. + 1. Connect the knowledge base ID and RAG tool with the agent. To do so, copy the below snippet and paste it into the notebook or Python script. ``` @@ -133,7 +136,7 @@ The tasks imports various ADK python modules as well as some of the optional lib ## Task 6: Define an agent and connect with the tools. -1. Use below snippet to define an agent along with the tools.You need to update the placeholders accordingly. + 1. Use the below snippet to define an agent along with the tools. You need to update the placeholders accordingly. ``` @@ -167,11 +170,11 @@ The tasks imports various ADK python modules as well as some of the optional lib -## Task 7: Initialize and setup the agent. -During the process the ADK will check the tools defined and associate with the Agent. -The process may take several minutes depends on the tools and their configuration. +## Task 7: Initialize and set up the agent. +During the process, the ADK will check the tools defined and associate them with the Agent. +The process may take several minutes depending on the tools and their configuration. -1. Run below to setup and run a sample query.A setup process is only needed for the first time or for any configuration changes that needs to push from local or notebook to agents.You may update your query as well. +1. Run the below to set up and run a sample query. The setup process is only needed for the first time or for any configuration changes that need to be pushed from the local environment or notebook to agents. You may update your query as well. ``` @@ -183,7 +186,7 @@ The process may take several minutes depends on the tools and their configuratio ![Tool sync](images/tool_sync.png) -1. Wait for the execution to complete and validate the result.A result would look like as below. +2. Wait for the execution to complete and validate the result. A result would look like the one below. ![Result](images/mcp_results.png) diff --git a/generative-ai-agent-adk/agent-run/agentrun.md b/generative-ai-agent-adk/agent-run/agentrun.md index 4b504ffdc..676307c9a 100644 --- a/generative-ai-agent-adk/agent-run/agentrun.md +++ b/generative-ai-agent-adk/agent-run/agentrun.md @@ -2,11 +2,12 @@ ## Introduction -This lab will take provide various run modes with the *Agent* we have configured. +This lab will provide various run modes with the Agent we have configured. + ## Task 1: Run a query using RAG tool. -1. Run below query to fetch answers from OCI Agent RAG tool based on the knowledge base attached. +1. Run the query below to fetch answers from the OCI Agent RAG tool based on the attached knowledge base. ``` @@ -15,14 +16,14 @@ This lab will take provide various run modes with the *Agent* we have configured response.pretty_print() ``` -* The agent will run and share the information based on the RAG too. + The agent will run and share the information based on the RAG tool. ![Rag run](images/rag-run.png) ## Task 2: Validate SQL tool execution. -1. Run below query to fetch information via agent ,which will fetch and report the information from OCI Autonomous Data Base. +1. Run the query below to fetch information via the agent, which will retrieve and report the data from the Autonomous AI Database. ``` @@ -31,13 +32,13 @@ This lab will take provide various run modes with the *Agent* we have configured response.pretty_print() ``` -* Here the query about secondary category will translate to product subcategory based on the column description that we defined during SQL Tool setup. +* Here, the query about the secondary category will be translated to the product subcategory based on the column description defined during SQL tool setup. ![SQL Run](images/sql-run.png) -## Task 3: Validate function exeuction. +## Task 3: Validate function execution. -1. Run below to understand how agent reacts based on the function tool we defined. +1. Run the command below to see how the agent reacts based on the function tool we defined. ``` @@ -49,8 +50,10 @@ This lab will take provide various run modes with the *Agent* we have configured ![Custom tool run](images/custom_tool_run.png) ## Task 4 : Sample agent run using OCI SDK. -Here we are using OCI python SDK to run the agent endpoint and fetch results. -1. Use below snippet to fetch results using OCI SDK.You may comment/uncomment the Auth section/Region and endpoint details accordingly. + +Here we are using the OCI Python SDK to run the agent endpoint and fetch results. + +1. Use the snippet below to fetch results using the OCI SDK. You may comment/uncomment the Auth section, region, and endpoint details accordingly. ``` @@ -114,13 +117,14 @@ Here we are using OCI python SDK to run the agent endpoint and fetch results. ``` ![SDK Run](images/sdk-run.png) -1. A sample execution result will be as follows.Its for demo purpose only and the same can be achieved using ADK .As you may refer the SDK goes at a lower API level while ADK remains at the upper layer. +2. A sample execution result will be as follows. It is for demo purposes only, and the same can be achieved using ADK. As you may observe, the SDK operates at a lower API level, while ADK remains at a higher abstraction layer. ![SDK run output](images/sdk-output.png) -## Task 5 : Additional samples. -* You may refer [here](https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/adk/api-reference/examples.htm) for additional samples and can run against the setup. +## Task 5 : Additional samples + +* You may refer [here](https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/adk/api-reference/examples.htm) for additional samples and run them against your setup. **Proceed to the next lab.** diff --git a/generative-ai-agent-adk/agent-setup/setup.md b/generative-ai-agent-adk/agent-setup/setup.md index 5a1976772..c2fa22640 100644 --- a/generative-ai-agent-adk/agent-setup/setup.md +++ b/generative-ai-agent-adk/agent-setup/setup.md @@ -2,12 +2,12 @@ ## Introduction -This lab will take you through the steps needed to provision Oracle Infrastructure resources such as +This lab will take you through the steps needed to provision Oracle Infrastructure resources such as: * OCI IAM resources. * OCI Virtual Cloud Network resources. * OCI Object Storage bucket. -* OCI Autonomous Database. +* Autonomous AI Database. Estimated Time: 30 minutes @@ -21,14 +21,17 @@ This task will help you ensure that the Dynamic Group and Policy are correctly d ![Domain Navigation](images/locate_domain.png) -1. Click on your desired domain name -1. Click on Dynamic Groups, and then your Dynamic Group name +2. Click on your desired domain name. + +3. Click on Dynamic Groups, and then your Dynamic Group name. ![Dynamic group](images/domain_dg.png) -1. Click create dynamic group.Provide a name and a description.Select option Match any rules defined below. + +4. Click Create dynamic group. Provide a name and a description. Select the option Match any rules defined below. ![Create Dynamic group](images/create_dg.png) -1. Add below rules to the dynamic group. + +5. Add the below rules to the dynamic group: ``` @@ -36,31 +39,35 @@ This task will help you ensure that the Dynamic Group and Policy are correctly d ALL {resource.type='genaiagent',resource.compartment.id='OCID of the Compartment'} ``` -1. Create the dynamic group. + +6. Create the dynamic group. ![Created group](images/created_dg.png) -1. Make a note of *dynamic group's OCID* for further usage. +7. Make a note of the Dynamic Group's OCID for further usage. ![DG OCID](images/dg_ocid.png) -## Task 2: Create policies. +## Task 2: Create Policies -The tasks will help you to associate necessary policies with the dynamic group +This task will help you associate necessary policies with the dynamic group. -1. Select policies from section Identity & Security. +1. Select Policies from the Identity & Security section. ![Select policy](images/create_policies.png) -1. Ensure the compartment selected as the desired one. -1. Click *Create policy*. -1. Provide a name and description. +2. Ensure the selected compartment is the desired one. + +3. Click Create Policy. + +4. Provide a name and description. ![create policy](images/create_policy.png) -1. Click *Show manual editor* option. -1. Add below policy statements,ensure to update OCI accordingly. +5. Click the Show manual editor option. + +6. Add the policy statements below, ensuring to update the OCIDs accordingly: ``` @@ -74,170 +81,185 @@ The tasks will help you to associate necessary policies with the dynamic group allow dynamic-group to manage all-resources in compartment id ``` -1. Click create and validate. + +7. Click Create and validate. ![Validate policy](images/validate_policies.png) -## Task 3: Create virtual cloud network and subnet. +## Task 3: Create Virtual Cloud Network and Subnet -The tasks allows your to create our VCN that we will use for various transactions. +This task allows you to create the VCN that we will use for various transactions. -1. From OCI console ,select Network > *Virtual Cloud Networks* +1. From OCI Console, select Networking > Virtual Cloud Networks ![VCN View] (images/vcn_view.png) -1. Click *Actions* > *Start VCN Wizard*. +2. Click Actions > Start VCN Wizard. ![Create VCN](images/create_vcn.png) -1. Select option *Create VCN with Internet Connectivity*. +3. Select the option Create VCN with Internet Connectivity. ![VCN options](images/vcn_options.png) -1. Provide name ,description and use default information and create the VCN. -1. Wait for the vcn state to be *Active*. +4. Provide a name and description. Use the default information and create the VCN. + +5. Wait for the VCN state to become Active. ![VCN State](images/vcn_active.png) -## Task 4: Create Autonomous Database(ADB). +## Task 4: Create Autonomous AI Database (ADB). -The task help to create ADB that we will use for Nl2SQL tool usage. +This task helps to create an ADB that we will use for NL2SQL tool usage. -1. From *OCI Console* > *Oracle Database* > *Autonomous Databases*. +1. From OCI Console > Oracle AI Database > Autonomous AI Databases ![ADB View](images/create_adb.png) -1. Click create autonomous database. -1. Provide a friendly name for display and table name. +2. Click create Autonomous AI Database. + +3. Provide a friendly name for display and a database name. ![Create DB](images/create_db_basic.png) -1. Select version as *23ai*.Select other default configuration values. +4. Select version 26ai. Select other default configuration values. ![ADB config](images/adb_base_config.png) -1. Provide a complex password for the database. +5. Provide a complex password for the database. ![Admin credentials](images/db_admin_password.png) -1. As this for lab purpose select the option *Secure access from everywhere*. -1. Provide a contact mail id and click *Create*. -1. It will take several minutes to have the resource in Available status. +6. As this is for lab purposes, select the option Secure access from everywhere. + +7. Provide a contact email ID and click Create. + +8. It will take several minutes for the resource to reach Available status. ![ADB finale view](images/adb_final_view.png) -1. Make a note of Admin password for further usage. -## Task 5: Create a vault. +9. Make a note of the admin password for further usage. + +## Task 5: Create a Vault -The task helps to setup the OCI Vault. +This task helps to set up the OCI Vault. -1. From OCI console > *Identity & Security* > *Key Management & Secret Management* > *Vault* +1. From OCI Console > Identity & Security > Key Management & Secret Management > Vault ![Create vault](images/create_vault.png) -1. Click *Create vault*.Provide a name and click *Create Vault*. +2. Click Create Vault. Provide a name and click Create Vault. ![Create vault](images/vault_master.png) -1. Click *Create Master Key*.Provide a name and use default options.Click *Create Key*. +3. Click Create Master Key. Provide a name and use the default options. Click Create Key. + ![Create master key](images/create_vault_key.png) -1. Wait till the resources are in active state before moving to next section. +4. Wait until the resources are in Active state before moving to the next section. -## Task 6: Create database connection. +## Task 6: Create Database Connection -The task allow to create a DB connection for agent usage. +This task allows you to create a DB connection for agent usage. -1. From OCI console > *Developer Services* > *Connections*. +1. From OCI Console > Developer Services > Connections ![DB connections](images/db_connection.png) -1. Click *Create connection*.Provide name for the connection.Always ensure you are selected the desired compartment. +2. Click Create Connection. Provide a name for the connection. Always ensure the desired compartment is selected. ![DB connection create](images/connection_basics.png) -1. Use *Select Database* option. -1. Select option as *Oracle Autonomous Database*. -1. Select the compartment and the database created earlier. +3. Use the Select Database option. + +4. Select the option Oracle Autonomous AI Database. + +5. Select the compartment and the database created earlier. ![Select db](images/select_db.png) -1. Click *Create password secret*. -1. Provide name and description. -1. Select the vault and master key created. -1. Use the same password that used during ADB creation. -1. Click *Create*. + +6. Click Create password secret. + +7. Provide a name and description. + +8. Select the vault and master key created earlier. + +9. Use the same password that was used during ADB creation. + +10. Click Create ![Admin password creation](images/connection_admin_password.png) -1. Click *Create wallet content secret*. +11. Click Create wallet content secret. ![Wallet secrets](images/create_wallet_password.png) -1. Provide *Name*, *Description*,Select *Vault* and *Key*. -1. Use option *Retrieve regional wallet from Autonomous Database*. +12. Provide Name, Description, and select the Vault and Key. + +13. Use the option Retrieve regional wallet from Autonomous Database. ![Wallet secret creation](images/create_secrets_wallet.png) -1. Click create.Wait for the resource to become active. +14. Click Create. Wait for the resource to become active. ![Validate connection](images/validate_connection.png) -1. Provide confirmation. Wait for the validation.If there is an error fix accordingly. +15. Provide confirmation and wait for the validation. If there is an error, fix it accordingly. ![Connection validation](images/connect_validation.png) -1. Click *Close*. +16. Click Close. -## Task 7: Create OCI Object storage. +## Task 7: Create OCI Object Storage -The task help to create a object storage bucket to store artifacts for RAG usages. +This task helps to create an Object Storage bucket to store artifacts for RAG usage. -1. From OCI Console > *Object Storage & Archive Storage* > *Buckets*. +1. From OCI Console > Object Storage & Archive Storage > Buckets ![buckets](images/bucket_view.png) -1. Click *Create bucket*. -1. Provide name and use with default options. +2. Click Create Bucket. + +3. Provide a name and use the default options. ![Bucket created](images/bucket_created.png) -1. Make a note of *Name space name* and *Bucket name*. +4. Make a note of the Namespace name and Bucket name. -## Task 8: Create OCI Generative AI agents. +## Task 8: Create OCI Generative AI Agents -The task help to create a basic agent to which we will add further tools later. +This task helps to create a basic agent, to which we will add tools later. -1. From OCI console > *Analytics&AI* > *Generative AI Agents*. +1. From OCI Console > Analytics & AI > Generative AI Agents ![Create agent](images/create_agent.png) -1. Click *Agents* > *Create Agent*.Provide basic information and click *Next*. +2. Click Agents > Create Agent. Provide basic information and click Next. ![Agent basic](images/agent_basic_input.png) -1. Skip the tools page and click *Next*. -1. With in page *Setup agent endpoint* , check option *Automatically create an endpoint for this agent -*. +3. Skip the tools page and click Next. -1. Enable option *Enable human in the loop*. +4. Within the Setup agent endpoint page, check the option Automatically create an endpoint for this agent. + +5. Enable the option Enable human in the loop. ![Enable HIL](images/enable_hil.png) -1. Select option *Inform* for all the option of Guardrails. +6. Select the option Inform for all the Guardrail settings. ![Guardrails](images/guardrails.png) -1. Click *Next* and click *Create agent* +7. Click Next and then Create Agent. ![Create agent](images/create_agent_final.png) -1. Wait for the agent and endpoint to become active,once completed make a note of the *OCID of the Agent endpoint*. +8. Wait for the agent and endpoint to become active. Once completed, make a note of the OCID of the Agent Endpoint. ![Agent endpoint ocid](images/agent_endpoint.png) - **Proceed to the next lab.** ## Acknowledgements diff --git a/generative-ai-agent-adk/introduction/introduction.md b/generative-ai-agent-adk/introduction/introduction.md index 4c0aeeca5..0c12a8387 100644 --- a/generative-ai-agent-adk/introduction/introduction.md +++ b/generative-ai-agent-adk/introduction/introduction.md @@ -2,11 +2,11 @@ ## About this Workshop -This workshop will help to configure,deploy and run a chat powered by OCI Generative AI Agents using OCI Agent Development Kit (`adk`).During the flow the learner will +This workshop will help you configure, deploy, and run a chat powered by OCI Generative AI Agents using the OCI Agent Development Kit (adk). During the flow, the learner will: -- Create and configure OCI Generative AI agents. -- Configure tools such as Retrieval Augmented Generation(RAG),Nl2SQL,Custom tools including Model Context Protocol(MCP) based tools. -- Use `adk` for all the above tasks. +- Create and configure OCI Generative AI Agents. +- Configure tools such as Retrieval Augmented Generation (RAG), NL2SQL, and custom tools including Model Context Protocol (MCP)-based tools. +- Use adk for all the above tasks. ![User View](images/user_flow.jpg) @@ -14,28 +14,25 @@ Estimated Workshop Time: 2 hours ### Objectives -Objective of this workshop is to configure ,build ,deploy and run OCI Generative AI Agents using Agent Development Kit (**ADK**).The following services and features will be covered during the lab - - - -* OCI Generative AI Agent build and deploy. -* Configure and use inbuilt Retrieval Augmented Generation (**RAG**)tool. -* Configure and use inbuilt Natural Language 2 to SQL tool (**NL2SQL**). -* Usage of Model Context Protocol(**MCP**) with OCI Generative AI Agent. -* Configure and use Customer tools with OCI Generative AI Agents. +The objective of this workshop is to configure, build, deploy, and run OCI Generative AI Agents using the Agent Development Kit (ADK). The following services and features will be covered during the lab: +- OCI Generative AI Agent build and deploy +- Configure and use the inbuilt Retrieval Augmented Generation (RAG) tool +- Configure and use the inbuilt Natural Language to SQL tool (NL2SQL) +- Use Model Context Protocol (MCP) with OCI Generative AI Agents +- Configure and use custom tools with OCI Generative AI Agents ### Prerequisites This lab assumes you have: -* An Oracle Cloud Account (Non Free Tier) -* Access to OCI Generative AI Agents -* Access to a Region where the Agent service is available. - * Refer [here for more.](https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/overview.htm#regions) -* An OCI compartment on which we will allocate all the necessary resources. -* Must have an Administrator Account or Permissions to manage several OCI Services: Generative AI Agents, Autonomous Databases, Data Science, Object Storage, Network, Dynamic Groups, Policies, IDCS/Identity. -* Familiarity with Oracle Cloud Infrastructure (OCI) is helpful +- An Oracle Cloud Account (non-Free Tier) +- Access to OCI Generative AI Agents +- Access to a region where the Agent service is available + - Refer [here for more.](https://docs.oracle.com/en-us/iaas/Content/generative-ai-agents/overview.htm#regions) +- An OCI compartment where we will allocate all the necessary resources +- An Administrator account or permissions to manage several OCI services: Generative AI Agents, Autonomous Databases, Data Science, Object Storage, Network, Dynamic Groups, Policies, IDCS/Identity +- Familiarity with Oracle Cloud Infrastructure (OCI) is helpful ## Learn More @@ -52,5 +49,3 @@ This lab assumes you have: * **Rahul MR**, Principal Solutions Architect - OCI * **Contributors** * **Sanjeeva Kalva**, Principal Data Scientist - OCI -* **Last Updated By/Date** - * **TBD**, TBD \ No newline at end of file diff --git a/generative-ai-agent-adk/rag-tools/ragtools.md b/generative-ai-agent-adk/rag-tools/ragtools.md index 80ae79fa0..2be88849b 100644 --- a/generative-ai-agent-adk/rag-tools/ragtools.md +++ b/generative-ai-agent-adk/rag-tools/ragtools.md @@ -2,32 +2,30 @@ ## Introduction -This lab will take you through the steps needed to install setup knowledge ,data source and connect with OCI Agents.The lab covers all the following elements of OCI generative AI agents concepts. +This lab will take you through the steps needed to install, set up a knowledge base, configure a data source, and connect it with OCI Agents. The lab covers the following elements of OCI Generative AI Agents concepts: -* *RAG Tool* - A RAG tool in Generative AI Agents retrieves information from one or more knowledge bases and aims to respond with relevant and context-aware information in natural language. -* *Knowledge Bases* - A knowledge base is the base for all the data sources that an agent can use to retrieve information for its chat answers. You can create a knowledge base in advance and then add it to an agent's RAG tool. -* *Data source* - A data source points to the source of data. After you add a data source to a knowledge base, you must ingest the data source's data, so agents using the knowledge base can reach that data.* - +- RAG Tool – A RAG tool in Generative AI Agents retrieves information from one or more knowledge bases and aims to respond with relevant and context-aware information in natural language. +- Knowledge Bases – A knowledge base is the foundation for all the data sources that an agent can use to retrieve information for its chat answers. You can create a knowledge base in advance and then add it to an agent's RAG tool. +- Data Source – A data source points to the location of the data. After you add a data source to a knowledge base, you must ingest the data so agents using the knowledge base can access that information. Estimated Time: 30 minutes - - ## Task 1: Download PDFs for the RAG usage. -1. Run below command for data science notebook,else move to next step for adk running on local machine. +1. Run the command below if using a Data Science notebook. Otherwise, move to the next step for ADK running on a local machine. - ``` - - !mkdir pdfs - !wget https://docs.oracle.com/en/database/oracle/sql-developer-command-line/19.2/sqcug/oracle-sqlcl-users-guide.pdf -O pdfs/oracle-sqlcl-users-guide.pdf - !wget https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/ai-vector-search-users-guide.pdf -O pdfs/ai-vector-search-users-guide.pdf - !wget https://docs.oracle.com/en/operating-systems/oracle-linux/10/relnotes10.0/OL10-RELNOTES-10-0.pdf -O pdfs/OL10-RELNOTES-10-0.pdf + ``` + + mkdir pdfs + wget https://docs.oracle.com/en/database/oracle/sql-developer-command-line/19.2/sqcug/oracle-sqlcl-users-guide.pdf -O pdfs/oracle-sqlcl-users-guide.pdf + wget https://docs.oracle.com/en/database/oracle/oracle-database/23/vecse/ai-vector-search-users-guide.pdf -O pdfs/ai-vector-search-users-guide.pdf + wget https://docs.oracle.com/en/operating-systems/oracle-linux/10/relnotes10.0/OL10-RELNOTES-10-0.pdf -O pdfs/OL10-RELNOTES-10-0.pdf ``` ![Download PDFs](images/download_pdfs.png) -1. Run below for ADK that runs on a local machine. +2. Run the commands below for ADK running on a local machine. ``` @@ -38,82 +36,84 @@ Estimated Time: 30 minutes ``` -## Task 2: Upload the PDFs to object storage. +## Task 2: Upload the PDFs to Object Storage -1.Run below commands to push PDFs to object storage +1. Run the commands below to upload PDFs to Object Storage: -* via OCI Data science notebook. + Via OCI Data Science notebook: ``` - !oci os object bulk-upload --src-dir pdfs -bn "" -ns "" --auth "resource_principal" --prefix "oracle_pdfs/" - + oci os object bulk-upload --src-dir pdfs -bn "" -ns "" --auth "resource_principal" --prefix "oracle_pdfs/" ``` - ![Uploaded file](images/file_uploaded.png) -* via Locally installed OCI CLI. + ![Uploaded file](images/file_uploaded.png) + Via locally installed OCI CLI: ``` - !oci os object bulk-upload --src-dir pdfs -bn "" -ns "" --prefix "oracle_pdfs/" - + oci os object bulk-upload --src-dir pdfs -bn "" -ns "" --prefix "oracle_pdfs/" ``` -* You can download and upload the files manually too. -1. Validate the files via object storage bucket. + You can also download and upload the files manually. + +1. Validate the uploaded files via the Object Storage bucket. ![List files](images/os_file_list.png) -## Task 2: Create OCI AI Agents knowledge base. +## Task 3: Create OCI AI Agents Knowledge Base -1. Open OCI console > `Analytics & AI` > `Generative AI Agents` +1. Open OCI Console > Analytics & AI > Generative AI Agents ![Agents view](images/agents_view.png) -1. Click `Knowledge Bases` > `Create knowledge base`. - +2. Click Knowledge Bases > Create knowledge base. ![Create KB](images/create_kb_view.png) -1. Provide a `name` and `description`. -1. Select the compartment accordingly. -1. Select `Data store type` as `Object storage`. -1. Click option `Enable hybrid search`. +3. Provide a Name and Description. - ![New KB](images/new_kb.png) +4. Select the appropriate compartment. +5. Select Data store type as Object Storage. -1. Click `Specify data source`. +6. Enable the option Enable hybrid search. + + ![New KB](images/new_kb.png) + +7. Click Specify data source. ![Click specify the DS](images/specify_datasource.png) -1. Provide `Name`,`Description`,and select option `Enable multi-model parsing`. +8. Provide Name, Description, and select the option Enable multi-model parsing. ![New DS](images/new_ds_basic.png) -1. Select the bucket and select all the files that we have uploaded. +9. Select the bucket and all the files that were uploaded. -1. Click `Create`. +10. Click Create. ![Select files](images/select_files_for_ds.png) -1. It will take back the previous screen,ensure the option `Automatically start ingestion job for above data sources` selected. -1. Click `Create`. + +11. You will return to the previous screen—ensure the option Automatically start ingestion job for above data sources is selected. + +12. Click Create. ![Create KB](images/create_kb.png) -1. The status of the KB will be in `Creating`. +13. The status of the knowledge base will show as Creating. ![KB progress](images/kb_in_progress.png) -1. Once its become active ,make a note of the OCID for further steps. +14. Once it becomes active, make a note of the OCID for further steps. ![KB final](images/kb_active.png) -1. We will associate the knowledge base with agents later. +15. We will associate the knowledge base with agents later. **Proceed to the next lab.** diff --git a/generative-ai-agent-adk/references/references.md b/generative-ai-agent-adk/references/references.md index e2ab58b33..af209e422 100644 --- a/generative-ai-agent-adk/references/references.md +++ b/generative-ai-agent-adk/references/references.md @@ -1,9 +1,9 @@ # References ## Introduction -Reference section provides the sample snippet that we used as well some of the key links. -* The full sample that we have used during the labs can be referred below. +This reference section provides the sample snippet that we used, as well as some of the key links. + * The full sample used during the labs can be found below: ``` import nest_asyncio @@ -92,8 +92,6 @@ async def agent_handler(prompt:str="",init_run:bool=False,delete_session:bool=Tr question="give availability of room at The Palazzo at The Venetian Resort on 1st Aug 2025" response = asyncio.run(agent_handler(prompt=question,init_run=True)) response.pretty_print() - - ``` * Link to official documentation. diff --git a/generative-ai-agent-adk/sql-tools/sqltool.md b/generative-ai-agent-adk/sql-tools/sqltool.md index 2330943fe..35cc28089 100644 --- a/generative-ai-agent-adk/sql-tools/sqltool.md +++ b/generative-ai-agent-adk/sql-tools/sqltool.md @@ -2,45 +2,45 @@ ## Introduction -This lab will take you through the steps needed to setup a OCI Generative AI Agents SQL tool via console.Some of the key aspects that we cover as follows +This lab will take you through the steps needed to set up an OCI Generative AI Agents SQL tool via the console. Some of the key aspects we cover are as follows: -* *SQL Tool* - A SQL tool in Generative AI Agents converts natural language queries into Oracle SQL and SQLite statements and can run the SQL commands to generate responses against a connected database. -* *Databases* - The SQL tool in Generative AI Agents supports Oracle Database (Base Database and Autonomous Database). - -* *Database Schema* - A valid database schema must be provided when you add a SQL tool to an agent in Generative AI Agents. SQL tool creation fails at the validation step if the schema is invalid. - -* *Model Customization* - When creating a SQL tool, you can select between using a small or large model. -A small model provides faster response times. You'd select a small mode for simple queries such as "Get total sales for January 2025." -A large model provides more accuracy but at the cost of higher latency. You'd select a large model for more complex queries such as "Show the average sales of the top 5 performing products in Q1 2023 grouped by region." +- SQL Tool – A SQL tool in Generative AI Agents converts natural language queries into Oracle SQL and SQLite statements and can run the SQL commands to generate responses against a connected database. +- Databases – The SQL tool in Generative AI Agents supports Oracle Database (Base Database and Autonomous Database). +- Database Schema – A valid database schema must be provided when you add a SQL tool to an agent in Generative AI Agents. SQL tool creation fails at the validation step if the schema is invalid. +- Model Customization – When creating a SQL tool, you can select between using a small or large model. + - A small model provides faster response times. Use it for simple queries such as "Get total sales for January 2025." + - A large model provides more accuracy but at the cost of higher latency. Use it for complex queries such as "Show the average sales of the top 5 performing products in Q1 2023 grouped by region." Estimated Time: 30 minutes - ## Task 1: Configure SQL tool. -We will be using the *Database connection* created during the initial step to proceed further. +We will be using the database connection created during earlier steps. -1. Using OCI console > `Analytics & AI` > `Generative AI Agents` +1. Using OCI Console > Analytics & AI > Generative AI Agents ![Agent View](images/agent_view.png) -1. Click on the name of the desired agent. + +2. Click on the name of the desired agent. ![Agent details](images/agent_details.png) -1. Click `Tools` > `Create tool`. +3. Click Tools > Create tool. ![Create tool](images/create_tool.png) -1. Select option `SQL` +4. Select the SQL option. ![Sql choice](images/sql_choice.png) -1. Provide a name for the tool. -1. Provide description as `Tools for product related queries`. + +5. Provide a name for the tool. + +6. Provide the description: Tool for product-related queries. ![Sql routes](images/sqltool_routes.png) -1. Select `Inline` for schema and provide below information.We will be using some of the default tables available with our database. +7. Select Inline for the schema option and provide the information below. We will be using some of the default tables available with our database. ``` @@ -73,8 +73,9 @@ We will be using the *Database connection* created during the initial step to pr ![Schema](images/schema.png) -1. Select `Inline` for choice `In-context learning examples`. -1. Provide below sample learning examples. +8. Select Inline for the In-context learning examples option. + +9. Provide the following sample learning example: ``` @@ -83,8 +84,10 @@ We will be using the *Database connection* created during the initial step to pr ``` ![context learning](images/context_learning.png) -1. Select `Inline` for option `Description of tables and columns`. -1. Copy below and update. + +10. Select Inline for the option Description of tables and columns. + +11. Copy and update the following: ``` @@ -108,20 +111,25 @@ We will be using the *Database connection* created during the initial step to pr ![Table reference](images/table_description.png) -1. Select `Small (faster response)` for option `Model customization` -1. Select ` Oracle SQL` for option `Dialect`. +12. Select Small (faster response) for the Model customization option. + +13. Select Oracle SQL for the Dialect option. ![Custom model](images/custom_model.png) -1. Select the database connection created earlier,if necessary change the compartment name. -1. Click `Test connection` and validate the connection. + +14. Select the database connection created earlier. If necessary, change the compartment name. + +15. Click Test connection and validate the connection. ![Validate connection](images/validate_connection.png) -1. Enable SQL execution option. -1. Enable self correction option. + +16. Enable the SQL execution option. + +17. Enable the Self correction option. ![Sql options](images/options.png) -1. Provide below custom instructions. +18. Provide the following custom instructions: ``` @@ -132,8 +140,9 @@ We will be using the *Database connection* created during the initial step to pr ![Instructions](images/instruction.png) -1. Click create. -1. Wait for the tool to be `Active`.It may take few minutes. +19. Click Create. + +20. Wait for the tool to become Active. It may take a few minutes. ![Active tool](images/active_tool.png)