This page explains how agents are defined, organized, and related to the runtime, based on catalog.yaml, AGENTS.md, and the agents/ tree.
catalog.yaml is the single source of truth for:
goal block (10K-MAU objective, time horizon, core channels).agents: list with, for each agent:
id, dept, tier (P0/P1/P2).purpose and growth_role.inputs and outputs data contracts.triggers (cron-like labels used by runtime/scheduler.py).tools, integrations, guardrails, kpis, secrets, and skills.agents/<dept>/<id>/ is the authoritative on-disk definition:
agent.yaml — full spec aligning with the catalog entry.agent.py — concrete BaseAgent subclass implementing handle(...).prompts/system.md — system prompt; optional user templates.tests/ — pytest-based checks and fixtures.tools/ — local tool definitions where applicable.AGENTS.md emphasizes: agent folders on disk are the only versioned source of truth. agents/registry.json is a cache for listing; every spawn or runtime run must re-read YAML + prompts from disk.
Agents are grouped into departments matching business functions:
customer-advisory — portfolio, goals, tax, retirement, insurance, debt, rebalancing, SIP, market and earnings digests, research reports, financial health scoring, what-if simulator.product — UI agents, insights dashboard, notification copy, feature flagging, A/B test analysis.engineering — code review, PR summarization, QA test generation, CI triage, DevOps releases, docs generation, dependency upgrades, incident postmortems, stock data pipeline.marketing — content writer, SEO optimizer, blog publisher, social scheduler, email campaign, newsletter, ad copy, brand monitor, influencer outreach, growth analytics, landing page optimizer.sales — lead qualifier, outreach, CRM updater, demo scheduler, pricing/quote, upsell recommender, partner outreach.support — ticket triage, chat support, voice support, KB curator, FAQ generator, escalation, feedback analyzer, CSAT followup.finance — bookkeeping, invoice processor, expense categorizer, reconciliation, revenue forecaster, cashflow monitor, tax filing assistant, payroll, vendor payment.legal-compliance — contract review, NDA generation, privacy policy updater, SEBI/RBI compliance monitors, audit log, disclosure checker, regulatory filings, onboarding assistant, KYC/AML, document OCR.data — data quality, ETL monitor, schema drift detection, report generator, dashboard builder, anomaly detection, feature store, ML experiment tracking.security — threat monitor, vulnerability scanner, access reviewer, incident responder, phishing detector, secret scanner, log analyzer.research — market research, competitor intel, trend spotting, regulatory watch, user interview synthesis.executive — CEO copilot, board reports, strategy analyst, investor updates, metrics digest.Tiers indicate impact on the 10K-MAU goal:
The scheduler (runtime/scheduler.py) and CLI (./bin/wi list --tier ...) use these tiers for filtering.
A notable engineering agent is agents/engineering/stock-data-pipeline/, documented in its own README. It:
shared/services/stock_data/ (models, providers, cache, pipeline, CLI) to fetch and maintain stock data for the WiseInvest universe.data/stocks/<TICKER>/stock_data.json containing stockData sections such as header, companyProfile, keyStatistics, peers, ownership, financials, businessOperations, performanceAndTechnicals, and esgScores.python3 -m shared.services.stock_data fetch|refresh|batch|status|list|show and can be run as an agent via python3 -m runtime run stock-data-pipeline.This agent is the connective tissue between the agents runtime and the static stock JSON consumed by wiseinvest.in.
runtime.loader.discover() scans agents/<dept>/<id>/agent.py and builds an in-memory map of id → class with dept/tier metadata.python3 -m runtime list and ./bin/wi list use this discovery to show all built agents.runtime.spawn can rebuild agents/registry.json as a cache for Copilot-style UIs; the registry is never the source of truth.When adding a new agent:
catalog.yaml with id, dept, tier, triggers, skills, and integrations.agents/<dept>/<id>/ (or copy _template/).python3 scripts/generate_specs.py if you rely on spec generation.python3 -m runtime.spawn registry --rebuild if you use it.Scheduler and Mission Control integration will automatically pick up agents with agent.py on disk once they exist in the catalog.