How pixjobs/pixjobs-adk-hackathon works
Project Type & Purpose
• WorkMatch is a backend‐centric, multi‐agent career guidance assistant built on the Python Agent Development Kit (ADK) and deployed as a Cloud Run service.
• Its core purpose is to orchestrate modular “agents” that collaborate—with real‐time listings and structured logic—to guide users through career exploration, job discovery, and upskilling.
File Structure Analysis
• Top‐level:
– .dockerignore, Docker/Git configs, LICENSE, README.md
– backend/ – contains the runnable service
• backend/
– workmatch/ – main Python package
– agent.py, prompt.py – entry-points for root agent orchestration
– sub_agents/ – each module implements a specialized agent (entry_level, advanced_pathways, title_variants, etc.)
– tools/ – reusable career_tools for job logic, queries, formatting
– utils/ – integrations (adzuna API helper, Firestore helper, tracing, env/secret management)
README Insights
• Multi‐agent orchestration: a single root agent routes to many sub-agents, each with a focused role.
• ADK best practices: uses TracedAgentTool and TracedFunctionTool for observability with Langfuse.
• Deploys on Google Cloud Run; uses Firestore for persistent storage; Adzuna API for job data; Secret Manager for credentials.
• Future: a React+TypeScript frontend is planned, but currently uses the ADK Web interface for local/dev.
a. Main Components
– User & ADK Web UI (or future React UI)
– Cloud Run service (HTTP/gRPC endpoint)
– Root Agent (workmatch_root_agent)
– Sub-Agents modules (entry_level_agent, career_guidance_agent, advanced_pathways_agent, etc.)
– Tools layer (career_tools)
– Utility integrations: Adzuna API client, Firestore helper, Secret Manager, Langfuse tracing
– Firestore Database (persistent job listings)
– External services: Adzuna REST API, Google Secret Manager, Langfuse observability
b. Relationships & Interactions
1. User → ADK Web UI (or React frontend) → HTTP Request → Cloud Run
2. Cloud Run endpoint instantiates Root Agent
3. Root Agent analyzes user input, invokes sub-agent modules
4. Sub-Agents call Tools (career_tools) for business logic or function tools (e.g. TracedFunctionTool)
5. Tools/util modules interact with:
• Adzuna API (live job data)
• Firestore helper (read/write cached listings)
• Secret Manager (API keys)
• Langfuse (trace logs)
6. Responses bubble back up: Tool → Sub-Agent → Root Agent → Cloud Run → UI → User
c. Architectural Patterns & Principles
• Modular multi-agent orchestration (separation of concerns per agent)
• Layered design: Agents → Tools → Utils → External
• Observability baked in via traced tools (Langfuse)
• Cloud-native deployment (stateless service + managed DB + secret store)
d. Key Technologies & Frameworks
• Python ADK (Agent Dev Kit)
• Google Cloud Run
• Firestore (NoSQL)
• Google Secret Manager
• Adzuna REST API
• Langfuse for tracing/logs
Detail & Fidelity
• Integrations (e.g., “FirestoreHelper: read/write listings”) to convey function.
• Orchestration pattern (Root → Sub-Agents → Tools) is unmistakable.