Merge branch 'google:main' into nb-update-3

Author: joefernandez

examples/gemini/python/docs-agent/README.md

@@ -7,6 +7,36 @@ Docs Agent provides a set of easy-to-use self-service tools designed to give you
 your team access to Google's [Gemini API][genai-doc-site] for learning, experimentation,
 and project deployment.
 
+## Docs Agent MCP integration [NEW]
+
+With the latest MCP (Model Context Protocol) integration, you can set up and launch
+a MCP server and enable the Docs Agent CLI (`agent tools`) to use this MCP server.
+
+The following example shows Docs Agent interacting with a
+[`git` MCP server][git-mcp-server] on the host machine:
+
+```
+$ agent tools Show me the latest commit in the Docs Agent project.
+
+Using tools: ['git']
+
+Commit: 082949927e88df429c76e6dbf0a9e216c88fa5b0
+Author: Bob Alice
+Date: Tue May 13 11:22:19 2025 -0700
+Message: Update BeautifulSoup findAll to find_all.
+```
+
+To enable a MCP server, update the `config.yaml` file in your Docs Agent project,
+for example:
+
+```
+mcp_servers:
+  - server_type: "stdio"
+    command: "uv"
+    name: "git"
+    args: ["--directory","/usr/local/home/user01/mcp_servers/servers/src/git", "run", "mcp-server-git"]
+```
+
 ## Docs Agent web app
 
 Docs Agent uses a technique known as **Retrieval Augmented Generation (RAG)**, which
@@ -64,8 +94,6 @@ The list below summarizes the tasks and features supported by Docs Agent:
   chunks that are most relevant to user questions.
 - **Add context to a user question**: Add chunks returned from a semantic search as
   [context][prompt-structure] to a prompt.
-- **Fact-check responses**: This [experimental feature][fact-check-section] composes
-  a follow-up prompt and asks the language model to “fact-check” its own previous response.
 - **Generate related questions**: In addition to answering a question, Docs Agent can
   [suggest related questions][related-questions-section] based on the context of the
   question.
@@ -113,6 +141,13 @@ The list below summarizes the tasks and features supported by Docs Agent:
   You can use this feature for creating tasks as well. For example, see the
   [DescribeImages][describe-images] task.
 
+- **Interact with LLM using external tools**: The `agent tools` command allows
+  you to interact with the Gemini model using configured external tools
+  (through MCP - Model Context Protocol). This enables the agent to perform
+  actions by leveraging specialized tools. (See
+  [Docs Agent CLI reference][cli-reference] and
+  [Docs Agent concepts][docs-agent-concepts]).
+
 For more information on Docs Agent's architecture and features,
 see the [Docs Agent concepts][docs-agent-concepts] page.
 
@@ -244,7 +279,19 @@ Clone the Docs Agent project and install dependencies:
    poetry install
    ```
 
-4. Enter the `poetry` shell environment:
+4. Set up the Poetry environment:
+
+   ```
+   poetry env activate
+   ```
+
+5. Install the `shell` plugin:
+
+   ```
+   poetry self add poetry-plugin-shell
+   ```
+
+6. Enter the `poetry` shell environment:
 
    ```
    poetry shell
@@ -253,7 +300,7 @@ Clone the Docs Agent project and install dependencies:
    **Important**: From this point, all `agent` command lines below need to
    run in this `poetry shell` environment.
 
-5. (**Optional**) To enable autocomplete commands and flags related to
+7. (**Optional**) To enable autocomplete commands and flags related to
    Docs Agent in your shell environment, run the following command:
 
    ```
@@ -450,7 +497,6 @@ Meggin Kearney (`@Meggin`), and Kyo Lee (`@kyolee415`).
 [set-up-docs-agent]: #set-up-docs-agent
 [preprocess-dir]: ./docs_agent/preprocess/
 [populate-vector-database]: ./docs_agent/preprocess/populate_vector_database.py
-[fact-check-section]: ./docs/concepts.md#using-a-language-model-to-fact_check-its-own-response
 [related-questions-section]: ./docs/concepts.md#using-a-language-model-to-suggest-related-questions
 [submit-a-rewrite]: ./docs/concepts.md#enabling-users-to-submit-a-rewrite-of-a-generated-response
 [like-generated-responses]: ./docs/concepts.md#enabling-users-to-like-generated-responses
@@ -479,3 +525,4 @@ Meggin Kearney (`@Meggin`), and Kyo Lee (`@kyolee415`).
 [tasks-dir]: tasks/
 [describe-images]: tasks/describe-images-for-alt-text-task.yaml
 [create-a-new-task]: docs/create-a-new-task.md
+[git-mcp-server]: https://github.com/modelcontextprotocol/servers/tree/main/src/git

examples/gemini/python/docs-agent/apps_script/drive_to_markdown.gs

@@ -75,7 +75,7 @@ function convertDriveFolder(folderName, outputFolderName="", indexFile="") {
     while (myfiles.hasNext()) {
       var myfile = myfiles.next();
       var ftype = myfile.getMimeType();
-      // If this is a shorcut, retrieve the target file
+      // If this is a shortcut, retrieve the target file
       if (ftype == "application/vnd.google-apps.shortcut") {
         var fid = myfile.getTargetId();
         var myfile = DriveApp.getFileById(fid);
@@ -105,7 +105,7 @@ function convertDriveFolder(folderName, outputFolderName="", indexFile="") {
       var furl = myfile.getUrl();
       var fcreate = myfile.getDateCreated();
 
-      //Function returns an array, assign each array value to seperate variables
+      //Function returns an array, assign each array value to separate variables
       var backup_results = returnBackupHash(sheet, "Backup", fid, start_data_row, 1, 9, 3);
       if (backup_results != undefined && backup_results[0] != "no_results") {
         var backup_fid = backup_results[0];
@@ -229,7 +229,7 @@ function convertDriveFolder(folderName, outputFolderName="", indexFile="") {
         status,
       ];
       sheet.appendRow(metadata);
-      // Return final row to inserRichText into correct rows
+      // Return final row to insertRichText into correct rows
       row_number = sheet.getLastRow();
       insertRichText(sheet, original_chip, "C", row_number);
       insertRichText(sheet, md_chip, "E", row_number);

examples/gemini/python/docs-agent/apps_script/gmail_to_markdown.gs

@@ -66,7 +66,7 @@ function exportEmailsToMarkdown(search, folderName) {
           let md5_hash = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5,hash_content,
                           Utilities.Charset.US_ASCII);
           let hash_str = byteToStr(md5_hash);
-          //Function returns an array, assign each array value to seperate variables. For emails, only need to retrieve
+          //Function returns an array, assign each array value to separate variables. For emails, only need to retrieve
           // backup markdown ids
           var backup_results = returnBackupHash(sheet, "Backup", hash_str, start_data_row, 7, 4, 5);
           if (backup_results != undefined && backup_results[0] != "no_results") {
@@ -134,4 +134,4 @@ function exportEmailsToMarkdown(search, folderName) {
     Logger.log("There is a total of " + unchangedEmails + " unchanged emails.");
     Logger.log("Grand total of " + emailTotal + " emails.");
   }
-}
+}

examples/gemini/python/docs-agent/apps_script/main.gs

@@ -24,4 +24,4 @@ var folderInput = "input-folder"
 function main() {
   convertDriveFolderToMDForDocsAgent(folderInput);
   exportEmailsToMarkdown(SEARCH_QUERY, folderOutput);
-}
+}

examples/gemini/python/docs-agent/config.yaml

@@ -17,8 +17,8 @@
 configs:
   - product_name: "Fuchsia"
     models:
-      - language_model: "models/gemini-1.5-flash-latest"
-        embedding_model: "models/embedding-001"
+      - language_model: "gemini-2.0-flash"
+        embedding_model: "text-embedding-004"
         api_endpoint: "generativelanguage.googleapis.com"
         embedding_api_call_limit: 1400
         embedding_api_call_period: 60
@@ -41,10 +41,16 @@ configs:
         Read the context below first and answer the user's question at the end.
         In your answer, provide a summary in three or five sentences. (BUT DO NOT USE
         ANY INFORMATION YOU KNOW ABOUT THE WORLD.)"
-        fact_check_question: "Can you compare the text below to the information
-        provided in this prompt above and write a short message that warns the readers
-        about which part of the text they should consider fact-checking? (Please keep
-        your response concise, focus on only one important item, but DO NOT USE BOLD
-        TEXT IN YOUR RESPONSE.)"
         model_error_message: "Gemini is not able to answer this question at the moment.
         Rephrase the question and try asking again."
+    # mcp_servers:
+    #   - name: "git"
+    #     server_type: "stdio"
+    #     command: "uv"
+    #     args: ["--directory","/usr/local/home/mcp_servers/servers/src/git", "run", "mcp-server-git"]
+    #   - name: "puppeteer"
+    #     server_type: "stdio"
+    #     command: "npx"
+    #     args: ["-y", "@modelcontextprotocol/server-puppeteer"]
+    #     env:
+    #       PUPPETEER_LAUNCH_OPTIONS: '{ "headless": true, "args": [] }'

examples/gemini/python/docs-agent/docs/cli-reference.md

@@ -176,12 +176,18 @@ agent helpme <REQUEST> --file <PATH_TO_FILE>
 ```
 
 Replace `REQUEST` with a prompt and `PATH_TO_FILE` with a file's
-absolure or relative path, for example:
+absolute or relative path, for example:
 
 ```sh
 agent helpme write comments for this C++ file? --file ../my-project/test.cc
 ```
 
+You can also provide multiple files for the same request, for example:
+
+```sh
+agent helpme summarize the content of this file? --file ../my-project/example_01.md --file ../my-project/example_02.md --file ~/my-new-project/example.md
+```
+
 ### Ask for advice using RAG
 
 The command below uses a local or online vector database (specified in
@@ -258,6 +264,32 @@ For example:
 agent helpme write a concept doc covering all features in this project? --allfiles ~/my-project --new
 ```
 
+### Ask the model to read a list of file names from an input file
+
+Similar to the `--perfile` flag, the command below reads the input
+file that contains a list of filenames and applies the request to
+each file in the list:
+
+```sh
+agent helpme <REQUEST> --list_file <PATH_TO_FILE>
+```
+
+For example:
+
+```sh
+agent helpme write an alt text string for this image? --list_file ./mylist.txt
+```
+
+where the `mylist.txt` file contains a list of file names in plain text
+as shown below:
+
+```none
+$ cat mylist.txt
+docs/images/apps-script-screenshot-01.png
+docs/images/docs-agent-ui-screenshot-01.png
+docs/images/docs-agent-embeddings-01.png
+```
+
 ### Ask the model to print the output in JSON
 
 The command below prints the output from the model in JSON format:
@@ -379,6 +411,18 @@ The command below deletes an online corpus:
 agent delete-corpus --name corpora/example01
 ```
 
+### Interact with the model using external tools
+
+The command below sends your prompt to the Gemini model and allows the model to
+use configured external tools (through MCP servers defined in `config.yaml`) to
+fulfill the request.
+
+Note: You can use a `-v` flag to enable verbose mode to see the tool execution.
+
+```sh
+agent tools <PROMPT>
+```
+
 <!-- Reference links -->
 
 [config-yaml]: ../config.yaml