diff --git a/generative-ai-agent-adk/adk-installation/adk_install.md b/generative-ai-agent-adk/adk-installation/adk_install.md index 4733850b7..23dc6480b 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 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. +This lab guides you through installing ADK using the Python installer. We recommend using an *OCI Data Science* notebook, as it includes all necessary software. Optional steps are provided for installing the ADK client on a local machine. Estimated Time: 30 minutes diff --git a/generative-ai-agent-adk/agent-config/agentconfig.md b/generative-ai-agent-adk/agent-config/agentconfig.md index 4ea074045..49f37ebd8 100644 --- a/generative-ai-agent-adk/agent-config/agentconfig.md +++ b/generative-ai-agent-adk/agent-config/agentconfig.md @@ -34,9 +34,7 @@ This task imports various ADK Python modules as well as some optional libraries ``` ![](images/module_import.png) - -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. - +1. In notebooks, use the *Play* button to run these commands. For Python scripts, use your editor or run with the *python script.py* command. ## Task 2: Define variables. @@ -66,7 +64,7 @@ This task imports various ADK Python modules as well as some optional libraries ## Task 3: Define a custom tool based on function. -1. Use the below code to set a simple custom function-based tool, which will return the season based on a location. +1. Use the code below to create a simple custom function-based tool that returns the season for a given location. ``` @@ -97,9 +95,9 @@ This task imports various ADK Python modules as well as some optional libraries ## Task 4: Define MCP call using stdIO mode. -* 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 Node.js and npx are available to run. +* We use an open-source MCP library to fetch information from the public internet. +* Library details and credit: https://github.com/openbnb-org/mcp-server-airbnb. +* For local client execution, ensure Node.js and npx are available. 1. Copy the below to a notebook or local script to define the MCP. @@ -170,11 +168,10 @@ This task imports various ADK Python modules as well as some optional libraries -## 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. +## Task 7: Initialize and setup the agent. +During the process, ADK will check the defined tools and associate them with the Agent. This may take several minutes, depending on the tools and their configuration. -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. +1. Run the following to set up and execute a sample query. Setup is required only the first time or when configuration changes need to be pushed from local or notebook to the agent. You may also update your query as needed. ``` diff --git a/generative-ai-agent-adk/agent-run/agentrun.md b/generative-ai-agent-adk/agent-run/agentrun.md index 676307c9a..ae4813f94 100644 --- a/generative-ai-agent-adk/agent-run/agentrun.md +++ b/generative-ai-agent-adk/agent-run/agentrun.md @@ -2,12 +2,11 @@ ## Introduction -This lab will provide various run modes with the Agent we have configured. - +This lab demonstrates various run modes available with the configured *Agent*. ## Task 1: Run a query using RAG tool. -1. Run the query below to fetch answers from the OCI Agent RAG tool based on the attached knowledge base. +1. Run the query below to fetch answers from the OCI Agent RAG tool, using the attached knowledge base. ``` @@ -16,6 +15,7 @@ This lab will 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 tool. The agent will run and share the information based on the RAG tool. @@ -23,7 +23,7 @@ This lab will provide various run modes with the Agent we have configured. ## Task 2: Validate SQL tool execution. -1. Run the query below to fetch information via the agent, which will retrieve and report the data from the Autonomous AI Database. +1. Run the query below to fetch information through the agent, which will retrieve and report data from the Autonomous AI Database. ``` @@ -32,13 +32,13 @@ This lab will provide various run modes with the Agent we have configured. response.pretty_print() ``` -* Here, the query about the secondary category will be translated to the product subcategory based on the column description defined during SQL tool setup. +* Here, the query about secondary category will be mapped to the product subcategory, based on the column description defined during SQL Tool setup. ![SQL Run](images/sql-run.png) ## Task 3: Validate function execution. -1. Run the command below to see how the agent reacts based on the function tool we defined. +1. Run the code below to see how the agent responds using the defined function tool. ``` @@ -50,10 +50,9 @@ This lab will 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 use the OCI Python SDK to run the agent endpoint and fetch results. -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. +1. Use the snippet below to retrieve results with the OCI SDK. Comment or uncomment the authentication section, region, and endpoint details as needed. ``` @@ -117,7 +116,7 @@ Here we are using the OCI Python SDK to run the agent endpoint and fetch results ``` ![SDK Run](images/sdk-run.png) -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. +1. A sample execution result is shown below for demonstration purposes. The same outcome can be achieved using ADK. The SDK operates at a lower API level, while ADK functions at a higher abstraction layer. ![SDK run output](images/sdk-output.png) @@ -134,4 +133,4 @@ Here we are using the OCI Python SDK to run the agent endpoint and fetch results * **Author** * **Rahul MR**, Prinicipal Solutions Architect - OCI * **Contributors** - * **Sanjeeva Kalva**, Principal Data Scientist - OCI \ No newline at end of file + * **Sanjeeva Kalva**, Principal Data Scientist - OCI diff --git a/generative-ai-agent-adk/agent-setup/images/adb_base_config.png b/generative-ai-agent-adk/agent-setup/images/adb_base_config.png index 2349ef16c..4ecf578c1 100644 Binary files a/generative-ai-agent-adk/agent-setup/images/adb_base_config.png and b/generative-ai-agent-adk/agent-setup/images/adb_base_config.png differ diff --git a/generative-ai-agent-adk/agent-setup/images/bucket_created.png b/generative-ai-agent-adk/agent-setup/images/bucket_created.png index d91b9eba0..47ebb66ac 100644 Binary files a/generative-ai-agent-adk/agent-setup/images/bucket_created.png and b/generative-ai-agent-adk/agent-setup/images/bucket_created.png differ diff --git a/generative-ai-agent-adk/agent-setup/images/bucket_view.png b/generative-ai-agent-adk/agent-setup/images/bucket_view.png index 86a94b22d..f74f8f8a3 100644 Binary files a/generative-ai-agent-adk/agent-setup/images/bucket_view.png and b/generative-ai-agent-adk/agent-setup/images/bucket_view.png differ diff --git a/generative-ai-agent-adk/agent-setup/setup.md b/generative-ai-agent-adk/agent-setup/setup.md index c2fa22640..177c4552f 100644 --- a/generative-ai-agent-adk/agent-setup/setup.md +++ b/generative-ai-agent-adk/agent-setup/setup.md @@ -15,7 +15,7 @@ Estimated Time: 30 minutes ## Task 1: Dynamic Group and Policy Definition -This task will help you ensure that the Dynamic Group and Policy are correctly defined. +This task will help you setup and verify that the Dynamic Group and Policy are correctly defined. 1. Locate Domains under Identity & Security @@ -26,8 +26,7 @@ This task will help you ensure that the Dynamic Group and Policy are correctly d 3. Click on Dynamic Groups, and then your Dynamic Group name. ![Dynamic group](images/domain_dg.png) - -4. Click Create dynamic group. Provide a name and a description. Select the option Match any rules defined below. +1. Click *Create Dynamic Group.* Provide a name and description, then select the "Match any rules defined below" option. ![Create Dynamic group](images/create_dg.png) @@ -51,7 +50,7 @@ This task will help you ensure that the Dynamic Group and Policy are correctly d ## Task 2: Create Policies -This task will help you associate necessary policies with the dynamic group. +This task will help you associate the necessary policies with the dynamic group. 1. Select Policies from the Identity & Security section. @@ -65,9 +64,8 @@ This task will help you associate necessary policies with the dynamic group. ![create policy](images/create_policy.png) -5. Click the Show manual editor option. - -6. Add the policy statements below, ensuring to update the OCIDs accordingly: +1. Click *Show manual editor* option. +1. Add below policy statements,ensure to update resource's OCIDs accordingly. ``` @@ -88,7 +86,7 @@ This task will help you associate necessary policies with the dynamic group. ## Task 3: Create Virtual Cloud Network and Subnet -This task allows you to create the VCN that we will use for various transactions. +This task allows you to create the VCN that will be used for various transactions. 1. From OCI Console, select Networking > Virtual Cloud Networks @@ -102,15 +100,14 @@ This task allows you to create the VCN that we will use for various transactions ![VCN options](images/vcn_options.png) -4. Provide a name and description. Use the default information and create the VCN. - -5. Wait for the VCN state to become Active. +1. Provide a name and description, use the default settings, and create the VCN. +1. Wait for the vcn state to be *Active*. ![VCN State](images/vcn_active.png) ## Task 4: Create Autonomous AI Database (ADB). -This task helps to create an ADB that we will use for NL2SQL tool usage. +This task helps you create the ADB for use with the NL2SQL tool. 1. From OCI Console > Oracle AI Database > Autonomous AI Databases @@ -122,7 +119,7 @@ This task helps to create an ADB that we will use for NL2SQL tool usage. ![Create DB](images/create_db_basic.png) -4. Select version 26ai. Select other default configuration values. +1. Select version as *26ai*.Select other default configuration values. ![ADB config](images/adb_base_config.png) @@ -142,22 +139,15 @@ This task helps to create an ADB that we will use for NL2SQL tool usage. ## Task 5: Create a Vault -This task helps to set up the OCI Vault. - -1. From OCI Console > Identity & Security > Key Management & Secret Management > Vault +This task helps you set up the OCI Vault. +1. From the OCI Console, go to *Identity & Security* > *Key Management & Secret Management* > *Vault*. ![Create vault](images/create_vault.png) - -2. Click Create Vault. Provide a name and click Create Vault. - +1. Click *Create Vault*, provide a name, and click *Create Vault*. ![Create vault](images/vault_master.png) - -3. Click Create Master Key. Provide a name and use the default options. Click Create Key. - - +1. Click *Create Master Key*, provide a name, use the default options, and click *Create Key*. ![Create master key](images/create_vault_key.png) - -4. Wait until the resources are in Active state before moving to the next section. +1. Wait until the resources are in the active state before proceeding to the next section. ## Task 6: Create Database Connection @@ -167,7 +157,7 @@ This task allows you to create a DB connection for agent usage. ![DB connections](images/db_connection.png) -2. Click Create Connection. Provide a name for the connection. Always ensure the desired compartment is selected. +1. Click *Create connection*.Provide name for the connection.Always ensure you have selected the desired compartment. ![DB connection create](images/connection_basics.png) diff --git a/generative-ai-agent-adk/introduction/introduction.md b/generative-ai-agent-adk/introduction/introduction.md index 0c12a8387..9866f13b0 100644 --- a/generative-ai-agent-adk/introduction/introduction.md +++ b/generative-ai-agent-adk/introduction/introduction.md @@ -14,7 +14,13 @@ Estimated Workshop Time: 2 hours ### Objectives -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: +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 Agent +* Configure and use custom tools with OCI Generative AI Agents - OCI Generative AI Agent build and deploy - Configure and use the inbuilt Retrieval Augmented Generation (RAG) tool @@ -26,13 +32,13 @@ The objective of this workshop is to configure, build, deploy, and run OCI Gener 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 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 +* 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 for allocating all necessary resources. +* An Administrator Account or permissions to manage the following 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 diff --git a/generative-ai-agent-adk/rag-tools/ragtools.md b/generative-ai-agent-adk/rag-tools/ragtools.md index 2be88849b..0fb9ca769 100644 --- a/generative-ai-agent-adk/rag-tools/ragtools.md +++ b/generative-ai-agent-adk/rag-tools/ragtools.md @@ -2,24 +2,24 @@ ## Introduction -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: +This lab will guide you through the steps to set up knowledge bases, configure data sources, and connect with OCI Agents. The lab covers the following OCI Generative AI Agent 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 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. +* *RAG Tool* - In Generative AI Agents, a RAG tool retrieves information from one or more knowledge bases and provides relevant, context-aware responses in natural language. +* *Knowledge Bases* - A knowledge base contains the data sources that an agent can use to retrieve information for chat responses. You can create a knowledge base in advance and then add it to an agent's RAG tool. +* *Data Source* - A data source specifies where the data resides. After adding a data source to a knowledge base, you must ingest the data so that agents using the knowledge base can access it. Estimated Time: 30 minutes ## Task 1: Download PDFs for the RAG usage. -1. Run the command below if using a Data Science notebook. Otherwise, move to the next step for ADK running on a local machine. +1. Run the command below for the Data Science notebook, or proceed to the next step for running ADK 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/26/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 ``` @@ -31,7 +31,7 @@ Estimated Time: 30 minutes 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/database/oracle/oracle-database/26/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 ``` @@ -109,7 +109,7 @@ Estimated Time: 30 minutes ![KB progress](images/kb_in_progress.png) -14. Once it becomes active, make a note of the OCID for further steps. +1. Once its become active,make a note of the OCID for further steps. ![KB final](images/kb_active.png) diff --git a/generative-ai-agent-adk/references/references.md b/generative-ai-agent-adk/references/references.md index af209e422..ac14ce4f0 100644 --- a/generative-ai-agent-adk/references/references.md +++ b/generative-ai-agent-adk/references/references.md @@ -1,9 +1,9 @@ # References ## Introduction +The reference section provides sample snippets used in the lab, along with key links. -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: +* The complete sample used during the labs is provided below. ``` import nest_asyncio diff --git a/generative-ai-agent-adk/sql-tools/sqltool.md b/generative-ai-agent-adk/sql-tools/sqltool.md index 35cc28089..bad69e7d5 100644 --- a/generative-ai-agent-adk/sql-tools/sqltool.md +++ b/generative-ai-agent-adk/sql-tools/sqltool.md @@ -2,15 +2,14 @@ ## Introduction -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. 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." +This lab guides you through the steps to set up an OCI Generative AI Agents SQL tool via the console. Key aspects covered include: + +* *SQL Tool* - In Generative AI Agents, the SQL tool converts natural language queries into Oracle SQL and SQLite statements, and can execute these commands to generate responses from a connected database. +* *Databases* - The SQL tool supports Oracle Database (Base Database and Autonomous Database). +* *Database Schema* - A valid database schema must be provided when adding a SQL tool to an agent. SQL tool creation will fail at the validation step if the schema is invalid. +* *Model Customization* - When creating a SQL tool, you can choose between a small or large model. + A small model offers faster response times and is recommended for simple queries, such as "Get total sales for January 2025." + A large model provides higher accuracy but with increased latency, making it suitable 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