mirror of
https://github.com/encounter/adk-python.git
synced 2026-07-09 18:19:28 -07:00
Josh SorefandCopybara-Service
aa1233608a
Merge https://github.com/google/adk-python/pull/2447 This PR corrects misspellings identified by the [check-spelling action](https://github.com/marketplace/actions/check-spelling) The misspellings have been reported at https://github.com/jsoref/adk-python/actions/runs/16840838898/attempts/1#summary-47711379253 The action reports that the changes in this PR would make it happy: https://github.com/jsoref/adk-python/actions/runs/16840839269/attempts/1#summary-47711380479 Note: while I use tooling to identify errors, the tooling doesn't _actually_ provide the corrections, I'm picking them on my own. I'm a human, and I may make mistakes. I've included a couple of changes to make CI happy. Personally, I object to CI being in a state of "random drive by person who adds a blank line in the middle of a file must fix all the preexisting bugs in the file", but that appears to be the state for this repository. COPYBARA_INTEGRATE_REVIEW=https://github.com/google/adk-python/pull/2447 from jsoref:spelling d85398e7fd154d124d477c6af6181481a01f34e0 PiperOrigin-RevId: 827629615
120 lines
5.6 KiB
Markdown
120 lines
5.6 KiB
Markdown
# ADK Answering Agent
|
|
|
|
The ADK Answering Agent is a Python-based agent designed to help answer questions in GitHub discussions for the `google/adk-python` repository. It uses a large language model to analyze open discussions, retrieve information from document store, generate response, and post a comment in the github discussion.
|
|
|
|
This agent can be operated in three distinct modes:
|
|
|
|
- An interactive mode for local use.
|
|
- A batch script mode for oncall use.
|
|
- A fully automated GitHub Actions workflow.
|
|
|
|
---
|
|
|
|
## Interactive Mode
|
|
|
|
This mode allows you to run the agent locally to review its recommendations in real-time before any changes are made to your repository's issues.
|
|
|
|
### Features
|
|
* **Web Interface**: The agent's interactive mode can be rendered in a web browser using the ADK's `adk web` command.
|
|
* **User Approval**: In interactive mode, the agent is instructed to ask for your confirmation before posting a comment to a GitHub issue.
|
|
* **Question & Answer**: You can ask ADK related questions, and the agent will provide answers based on its knowledge on ADK.
|
|
|
|
### Running in Interactive Mode
|
|
To run the agent in interactive mode, first set the required environment variables. Then, execute the following command in your terminal:
|
|
|
|
```bash
|
|
adk web
|
|
```
|
|
This will start a local server and provide a URL to access the agent's web interface in your browser.
|
|
|
|
---
|
|
|
|
## Batch Script Mode
|
|
|
|
The `main.py` script supports batch processing for ADK oncall team to process discussions.
|
|
|
|
### Features
|
|
* **Single Discussion**: Process a specific discussion by providing its number.
|
|
* **Batch Process**: Process the N most recently updated discussions.
|
|
* **Direct Discussion Data**: Process a discussion using JSON data directly (optimized for GitHub Actions).
|
|
|
|
### Running in Batch Script Mode
|
|
To run the agent in batch script mode, first set the required environment variables. Then, execute one of the following commands:
|
|
|
|
```bash
|
|
export PYTHONPATH=contributing/samples
|
|
|
|
# Answer a specific discussion
|
|
python -m adk_answering_agent.main --discussion_number 27
|
|
|
|
# Answer the 10 most recent updated discussions
|
|
python -m adk_answering_agent.main --recent 10
|
|
|
|
# Answer a discussion using direct JSON data (saves API calls)
|
|
python -m adk_answering_agent.main --discussion '{"number": 27, "title": "How to...", "body": "I need help with...", "author": {"login": "username"}}'
|
|
```
|
|
|
|
---
|
|
|
|
## GitHub Workflow Mode
|
|
|
|
The `main.py` script is automatically triggered by GitHub Actions when new discussions are created in the Q&A category. The workflow is configured in `.github/workflows/discussion_answering.yml` and automatically processes discussions using the `--discussion` flag with JSON data from the GitHub event payload.
|
|
|
|
### Optimization
|
|
The GitHub Actions workflow passes discussion data directly from `github.event.discussion` using `toJson()`, eliminating the need for additional API calls to fetch discussion information that's already available in the event payload. This makes the workflow faster and more reliable.
|
|
|
|
---
|
|
|
|
## Update the Knowledge Base
|
|
|
|
The `upload_docs_to_vertex_ai_search.py` is a script to upload ADK related docs to Vertex AI Search datastore to update the knowledge base. It can be executed with the following command in your terminal:
|
|
|
|
```bash
|
|
export PYTHONPATH=contributing/samples # If not already exported
|
|
python -m adk_answering_agent.upload_docs_to_vertex_ai_search
|
|
```
|
|
|
|
## Setup and Configuration
|
|
|
|
Whether running in interactive or workflow mode, the agent requires the following setup.
|
|
|
|
### Dependencies
|
|
The agent requires the following Python libraries.
|
|
|
|
```bash
|
|
pip install --upgrade pip
|
|
pip install google-adk
|
|
```
|
|
|
|
The agent also requires gcloud login:
|
|
|
|
```bash
|
|
gcloud auth application-default login
|
|
```
|
|
|
|
The upload script requires the following additional Python libraries.
|
|
|
|
```bash
|
|
pip install google-cloud-storage google-cloud-discoveryengine
|
|
```
|
|
|
|
### Environment Variables
|
|
The following environment variables are required for the agent to connect to the necessary services.
|
|
|
|
* `GITHUB_TOKEN=YOUR_GITHUB_TOKEN`: **(Required)** A GitHub Personal Access Token with `issues:write` permissions. Needed for both interactive and workflow modes.
|
|
* `GOOGLE_GENAI_USE_VERTEXAI=TRUE`: **(Required)** Use Google Vertex AI for the authentication.
|
|
* `GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID`: **(Required)** The Google Cloud project ID.
|
|
* `GOOGLE_CLOUD_LOCATION=LOCATION`: **(Required)** The Google Cloud region.
|
|
* `VERTEXAI_DATASTORE_ID=YOUR_DATASTORE_ID`: **(Required)** The full Vertex AI datastore ID for the document store (i.e. knowledge base), with the format of `projects/{project_number}/locations/{location}/collections/{collection}/dataStores/{datastore_id}`.
|
|
* `OWNER`: The GitHub organization or username that owns the repository (e.g., `google`). Needed for both modes.
|
|
* `REPO`: The name of the GitHub repository (e.g., `adk-python`). Needed for both modes.
|
|
* `INTERACTIVE`: Controls the agent's interaction mode. For the automated workflow, this is set to `0`. For interactive mode, it should be set to `1` or left unset.
|
|
|
|
The following environment variables are required to upload the docs to update the knowledge base.
|
|
|
|
* `GCS_BUCKET_NAME=YOUR_GCS_BUCKET_NAME`: **(Required)** The name of the GCS bucket to store the documents.
|
|
* `ADK_DOCS_ROOT_PATH=YOUR_ADK_DOCS_ROOT_PATH`: **(Required)** Path to the root of the downloaded adk-docs repo.
|
|
* `ADK_PYTHON_ROOT_PATH=YOUR_ADK_PYTHON_ROOT_PATH`: **(Required)** Path to the root of the downloaded adk-python repo.
|
|
|
|
For local execution in interactive mode, you can place these variables in a `.env` file in the project's root directory. For the GitHub workflow, they should be configured as repository secrets.
|