How fadynabil10/ai-salesgrid works
1. Repository shape
- This repo is mostly a packaged architecture reference plus a small Python agent application.
- The only source code shown is under agents/ai-salesgrid/ with agent.py and __init__.py, so the core runtime logic is likely concentrated in a single agent module.
- The PDFs and diagram folder are part of the architecture deliverable, not just supporting docs.
2. Primary runtime boundary
- The system is a Python 3.11 service built on the Google Agent Development Kit (ADK).
- It is intended to run as a containerized service via the root Dockerfile.
- Deployment targets Google Cloud Run, which makes the orchestration service serverless and HTTP-accessible.
3. Top-level orchestration pattern
- The main architectural concept is a multi-agent sales orchestrator.
- A root_agent / “Head Account Manager” acts as the control plane: it receives the sales request, decides which specialist agent should handle each subtask, and aggregates the outputs.
- This is an agent-to-agent workflow rather than a traditional layered CRUD app.
4. Specialized sub-agents
- The repository describes several domain-specific agents:
- solutionagent for client requirement analysis and mapping needs to company services
- pricingagent for pricing and discount-rule validation
- proposalagent for formal proposal generation
- riskagent for delivery, margin, and compliance assessment
- reportingagent for executive summaries and deal reporting
- These agents represent the main functional subsystems in the diagram.
5. Knowledge retrieval flow
- The specialist agents are designed to consult Vertex AI Search against an internal knowledge base named company-rules-kb.
- This is the main internal policy/service-data boundary: the agents should ground answers in approved company knowledge rather than free-form generation.
- The root agent also has access to Google Search for broader external context, which creates a separate outbound information path.
6. Enterprise data and integration layer
- The README positions the solution as ready to integrate with CRM systems, but no concrete CRM adapter code appears in the file tree.
- The architecture also references Firestore, BigQuery, and Cloud Storage as supporting data services.
- In diagram terms, these are downstream system boundaries for persistence, analytics, document storage, and sales context enrichment.
7. Model and AI platform dependency
- The generative layer is Vertex AI using Google Gemini gemini-2.5-flash.
- The model is the reasoning/generation engine inside each agent, while ADK handles agent orchestration and tool use.
- This means the AI boundary is outside the repo and provided by Google Cloud services.
8. Configuration and identity
- Runtime configuration is driven by environment variables such as GCP_PROJECT_ID, GCP_REGION, and GOOGLE_APPLICATION_CREDENTIALS.
- The service is expected to run under a Google Cloud service account with roles for Vertex AI, Firestore, BigQuery, Storage, and Cloud Run.
- This makes identity/authorization a first-class architecture concern.
9. Deployment path
- Local development uses Docker; the production path is Cloud Run.
- The README also shows an ADK deployment command (adk deploy cloud_run ...), which implies the agent framework can package and publish the service directly.
- So the deployment architecture is “build container → run on Cloud Run → connect to Vertex AI and Google data services.”
10. What is and isn’t implemented in the repo
- The repo strongly documents the intended enterprise architecture, but the checked-in code is minimal.
- There is no visible UI, no explicit API router, and no standalone CRM connector in the file tree.
- For an architecture diagram, treat the PDFs/README as the authoritative system design and agent.py as the implementation anchor for the agent graph.
11. Best diagram framing
- The clearest diagram should show:
- external user or sales system input
- the Cloud Run-hosted root agent
- delegated specialist agents
- internal knowledge retrieval via Vertex AI Search
- external Google Search when needed
- optional enterprise systems: CRM, Firestore, BigQuery, Cloud Storage
- generated outputs: pricing, proposals, risk scores, and executive reports
- The key idea is a centralized orchestrator with retrieval-augmented specialist agents, all running in Google Cloud.
Main entry points: agent.py Head Manager · Dockerfile Docker Image · __init__.py Agent Module · Architecture Diagram Docs & Diagrams
Components 20
Runtime
Containerized agent runtime and deployment boundary
- Sales Request · Incoming sales task or question
- Cloud Run · Production hosting target for the agent service
- Docker Image · Local and deployable runtime package
Dockerfile - ADK Deploy · Agent framework deployment path to Cloud Run
Orchestration
Root agent and specialist agent workflow
- Head Manager · Central orchestrator that routes work and aggregates results
agents/ai-salesgrid/agent.py - Agent Module · Implementation anchor for the salesgrid agent runtime
agents/ai-salesgrid/__init__.py - Solution Agent · Analyzes client needs and maps them to services
- Pricing Agent · Validates pricing, discounting, and margin rules
- Proposal Agent · Produces formal proposal content
- Risk Agent · Assesses delivery, compliance, and margin risk
- Reporting Agent · Summarizes deals for executives and reporting
AI Retrieval
Model and knowledge grounding services
- Gemini 2.5 Flash · Reasoning and generation engine used by the agents
- Vertex AI Search · Grounds agent answers in approved company knowledge
- Rules KB · Internal policy and sales knowledge store
- Google Search · Broader web context for the root agent
Enterprise Data
Operational and analytical systems the agents can consult
- CRM · Sales context and account integration boundary
- Firestore · Operational persistence and context storage
- BigQuery · Reporting and deal analytics sink
- Cloud Storage · Document and artifact storage boundary
Repo Artifacts
Packaged architecture reference materials
- Docs & Diagrams · Packaged architecture PDFs and diagram assets
Architecture Diagram
Connections 22
- Sales Request → Head Manager: submit request · A sales request enters the orchestrator
- Docker Image → Cloud Run: run as · Container image is deployed to Cloud Run
- ADK Deploy → Cloud Run: deploys · ADK publishes the agent service to Cloud Run
- Agent Module → Head Manager: implements · Python package contains the root agent implementation
- Head Manager → Solution Agent: delegate · Routes requirements analysis to the solution specialist
- Head Manager → Pricing Agent: delegate · Routes pricing work to the pricing specialist
- Head Manager → Proposal Agent: delegate · Routes proposal drafting to the proposal specialist
- Head Manager → Risk Agent: delegate · Routes risk review to the risk specialist
- Head Manager → Reporting Agent: delegate · Routes executive reporting to the reporting specialist
- Solution Agent → Vertex AI Search: retrieve · Solution analysis is grounded in company knowledge
- Pricing Agent → Vertex AI Search: validate · Pricing rules are checked against internal knowledge
- Proposal Agent → Vertex AI Search: ground · Proposal content uses approved company knowledge
- Risk Agent → Vertex AI Search: check · Risk assessment consults policy and guidance
- Reporting Agent → Vertex AI Search: summarize · Reports are informed by approved knowledge
- Vertex AI Search → Rules KB: index · Vertex AI Search indexes the internal rules base
- Head Manager → Google Search: search web · Root agent can gather broader external context
- Head Manager → Gemini 2.5 Flash: reason with · Agents use Gemini for generation and planning
- Solution Agent → CRM: enrich · Account and opportunity context may come from CRM
- Pricing Agent → Firestore: persist · Operational state can be stored in Firestore
- Reporting Agent → BigQuery: analyze · Executive reporting can feed analytics in BigQuery
- Proposal Agent → Cloud Storage: store docs · Generated proposals and artifacts can be stored in Cloud Storage
- Docs & Diagrams → Head Manager: documents · Repo docs describe the intended architecture and runtime