{"id":27914880,"url":"https://github.com/vladkol/crm-data-agent","last_synced_at":"2026-01-19T22:18:27.923Z","repository":{"id":291196615,"uuid":"976897830","full_name":"vladkol/crm-data-agent","owner":"vladkol","description":"CRM Data Q\u0026A Agent - Advanced RAG with NL2SQL over Salesforce Data","archived":false,"fork":false,"pushed_at":"2025-06-17T19:16:42.000Z","size":4904,"stargazers_count":63,"open_issues_count":0,"forks_count":10,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-17T20:22:37.902Z","etag":null,"topics":["adk","agents","ai","bigquery","nl2sql","salesforce","vertex-ai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vladkol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-03T00:56:49.000Z","updated_at":"2025-06-17T19:16:46.000Z","dependencies_parsed_at":"2025-05-21T23:22:39.994Z","dependency_job_id":"0381f8da-5484-4f68-8df2-9f41131726ef","html_url":"https://github.com/vladkol/crm-data-agent","commit_stats":null,"previous_names":["vladkol/crm-data-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vladkol/crm-data-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkol%2Fcrm-data-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkol%2Fcrm-data-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkol%2Fcrm-data-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkol%2Fcrm-data-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladkol","download_url":"https://codeload.github.com/vladkol/crm-data-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladkol%2Fcrm-data-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28587226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T20:45:59.482Z","status":"ssl_error","status_checked_at":"2026-01-19T20:45:41.500Z","response_time":67,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adk","agents","ai","bigquery","nl2sql","salesforce","vertex-ai"],"created_at":"2025-05-06T15:31:30.458Z","updated_at":"2026-01-19T22:18:27.916Z","avatar_url":"https://github.com/vladkol.png","language":"Python","funding_links":[],"categories":["🌟 Community Excellence"],"sub_categories":["Multi-Agent Systems"],"readme":"# CRM Data Q\u0026A Agent - Advanced RAG with NL2SQL over Salesforce Data\n\n| | |\n| ------------ | ------------- |\n| \u003cimg src=\"src/web/images/logo-dark.svg\" width=\"256\"/\u003e | This is a 📊 Data Analytics Agent that grounds its conversation in Salesforce data replicated to a Data Warehouse in BigQuery.    |\n\nThe agent demonstrates an advanced [Retrieval-Augmented Generation](https://cloud.google.com/use-cases/retrieval-augmented-generation) workflow\nin a multi-agentic system with contextualized Natural-Language-to-SQL\ncomponents powered by Long Context and In-Context Learning capabilities of [Gemini 2.5 Pro](https://deepmind.google/technologies/gemini).\n\n🚀 **Blog post**: [Forget vibe coding, vibe Business Intelligence is here!](https://medium.com/@vladkol_eqwu/business-intelligence-in-ai-era-how-agents-and-gemini-unlock-your-data-ce158081c678)\n\nThe agent is built with [Agent Development Kit](https://google.github.io/adk-docs/).\n\n* The agent interprets questions about state of the business how it's reflected in CRM rather than directly referring to Salesforce data entities.\n* It generates SQL query to gather data necessary for answering the question\n* It creates interactive [Vega-Lite](https://vega.github.io/vega-lite/) diagrams.\n* It analyzes the results, provides key insights and recommended actions.\n\n\u003ca href=\"tutorial/img/screenshot-dark.png\"\u003e\n\u003cimg src=\"tutorial/img/screenshot-dark.png\" alt=\"What are our best lead source in every country?\" style=\"width:900px;\"/\u003e\n\u003c/a\u003e\n\n## Agent Development Kit\n\n\u003cimg src=\"https://google.github.io/adk-docs/assets/agent-development-kit.png\" style=\"width:64px;\"/\u003e\n\nThe agent is built using [Agent Development Kit](https://google.github.io/adk-docs/) (ADK) - a flexible\nand modular framework for developing and deploying AI agents.\n\nThe sample also demonstrates:\n\n* How to build a Web UI for ADK-based data agents using [streamlit](https://streamlit.io/).\n* How to use [Artifact Services](https://google.github.io/adk-docs/artifacts/) with ADK.\n* How to stream and interpret session [events](https://google.github.io/adk-docs/events/).\n* How to create and use a custom [Session Service](https://google.github.io/adk-docs/sessions/session/).\n\n## 🕵🏻‍♀️ Simple questions are complex\n\n\u003cimg src=\"tutorial/img/top_5_customers.jpg\" alt=\"Top 5 customers by impact in the US this year\" style=\"width:800px;\"/\u003e\n\n### Examples of questions the agent can answer\n\n* \"Top 5 customers in every country\"\n* \"What are our best lead sources?\"\n  * or more specific \"What are our best lead sources by value?\"\n* Lead conversion trends in the US.\n\n### High-Level Design\n\n\u003cimg src=\"tutorial/img/data_agent_design.jpg\" alt=\"Top 5 customers in every country\" style=\"width:800px;\"/\u003e\n\n## 🚀 Deploy and Run\n\nTo deploy the sample with demo data to a publicly available Cloud Run service,\nuse `Run on Google Cloud` button below.\n\n[![Run on Google Cloud](https://deploy.cloud.run/button.svg)](https://console.cloud.google.com/cloudshell/?cloudshell_git_repo=https://github.com/vladkol/crm-data-agent\u0026cloudshell_image=gcr.io/cloudrun/button\u0026show=terminal\u0026utm_campaign=CDR_0xc245fc42_default_b417442301\u0026utm_medium=external\u0026utm_source=blog)\n\nYou need a Google Cloud Project with a [Billing Account](https://console.cloud.google.com/billing?utm_campaign=CDR_0xc245fc42_default_b417442301\u0026utm_medium=external\u0026utm_source=blog).\n\n### Manual deployment\n\n* Clone this repository:\n\n```bash\ngit clone https://github.com/vladkol/crm-data-agent \u0026\u0026 cd crm-data-agent\n```\n\n* Create a Python virtual Environment\n\n\u003e [uv](https://docs.astral.sh/uv/) makes it easy: `uv venv .venv --python 3.11 \u0026\u0026 source .venv/bin/activate`\n\n* Install dependencies\n\n`pip install -r src/requirements.txt`\n\nor, with `uv`:\n\n`uv pip install -r src/requirements.txt`\n\n* Create `.env` file in `src` directory. Set configuration values as described below.\n\n\u003e [src/.env-template](src/.env-template) is a template to use for your `.env` file.\n\n### Configuration variables\n\n\u003e `src/.env` must be created and variables specified before taking further steps in deployment, local or cloud.\n\n`GOOGLE_CLOUD_PROJECT` - [REQUIRED] Project Id of a Google Cloud Project that will be used with Vertex AI (and Cloud Run if deployed).\n\n`GOOGLE_CLOUD_LOCATION` - [REQUIRED] Google Cloud Region to use with Vertex AI (and Cloud Run if deployed).\n\n`AI_STORAGE_BUCKET` - [REQUIRED] Cloud Storage Bucket for ADK Asset Service and for staging Vertex AI assets.\nPlease create one.\n\n`BQ_LOCATION` - [REQUIRED] BigQuery location of the Salesforce datasets.\n\n`SFDC_BQ_DATASET` - [REQUIRED] Name of the Salesforce dataset (in project *SFDC_DATA_PROJECT_ID*).\n\n`FIRESTORE_SESSION_DATABASE` - [REQUIRED] Name of a Firestore database. Please create one. ADK will store its session data here.\n\n`BQ_PROJECT_ID` - *[OPTIONAL]* Project Id of a Google Cloud Project that will be used for running BigQuery query jobs. If not defined, `GOOGLE_CLOUD_PROJECT` value will be used.\n\n`SFDC_DATA_PROJECT_ID` - *[OPTIONAL]* Project Id of a Google Cloud Project of the Salesforce dataset.\nIf not defined, `BQ_LOCATION` value will be used.\n\n`SFDC_METADATA_FILE` - *[OPTIONAL]* Salesforce Metadata file (do not change this value if using the demo data).\n\n\u003e If you are deploying a demo, do not set `BQ_PROJECT_ID` and `SFDC_DATA_PROJECT_ID`.\n\u003e All resources will be created in GOOGLE_CLOUD_PROJECT project.\n\n**If you deploy the agent to Cloud Run**, its service account must have the following roles:\n\n* BigQuery Job User (`roles/bigquery.jobUser`) in BQ_PROJECT_ID project (or GOOGLE_CLOUD_PROJECT, if BQ_PROJECT_ID is not defined).\n* BigQuery Data Viewer (`roles/bigquery.dataViewer`) for SFDC_BQ_DATASET dataset.\n* Storage Object User (`roles/storage.objectUser`) for AI_STORAGE_BUCKET bucket.\n* Vertex AI User (`roles/aiplatform.user`) in GOOGLE_CLOUD_PROJECT project.\n\n### Enable APIs in your project\n\n```bash\ngcloud services enable \\\n    aiplatform.googleapis.com \\\n    cloudbuild.googleapis.com \\\n    run.googleapis.com \\\n    firestore.googleapis.com \\\n    bigquery.googleapis.com \\\n\n    --project=[GOOGLE_CLOUD_PROJECT]\n```\n\n\u003e Replace `[GOOGLE_CLOUD_PROJECT]` with GOOGLE_CLOUD_PROJECT value you put in `src/.env` file.\n\n### Deploy Salesforce Data\n\n#### Demo data\n\nRun `utils/deploy_demo_data.py` script.\n\n\u003e **Note**: Demo data contains records dated 2020-2022. If you ask questions with \"last year\" or \"6 months ago\", they will likely return no data.\n\n#### Real Salesforce Data\n\nCreate a [BigQuery Data Transfer for Salesforce](https://cloud.google.com/bigquery/docs/salesforce-transfer).\n\nMake sure you transfer the following objects:\n\n* Account\n* Case\n* CaseHistory\n* Contact\n* CurrencyType\n* DatedConversionRate\n* Event\n* Lead\n* Opportunity\n* OpportunityHistory\n* RecordType\n* Task\n* User\n\n#### Deployment with your custom Salesforce.com metadata\n\n*COMING SOON!*\n\nThis will allow you to use your customized metadata in addition to analyzing your real data replicated to BigQuery.\n\n### Run Locally\n\n* Run `.\\run_local.sh`\n* Open `http://localhost:8080` in your browser.\n\n#### Deploy and Run in Cloud Run\n\n* Run `.\\deploy_to_cloud_run.sh`\n\n\u003e This deployment uses default Compute Service Account for Cloud Run.\nTo make changes in how the deployment is done, adjust `gcloud` command in [deploy_to_cloud_run.py](utils/deploy_to_cloud_run.py)\n\n**Cloud Run Authentication Note**:\n\nBy default, this script deploys a Cloud Run service that requires authentication.\nYou can switch to unauthenticated mode in [Cloud Run](https://console.cloud.google.com/run) or configure a [Load Balancer and Identity Access Proxy](https://cloud.google.com/iap/docs/enabling-cloud-run) (recommended).\n\n## 📃 License\n\nThis repository is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## 🗒️ Disclaimers\n\nThis is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).\n\nCode and data from this repository are intended for demonstration purposes only. It is not intended for use in a production environment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladkol%2Fcrm-data-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladkol%2Fcrm-data-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladkol%2Fcrm-data-agent/lists"}