Project Ops Agency

Agency Swarm v1.0.0 deployment that coordinates project management, research, and dashboard delivery. The Project Manager is the single user-facing entry point and delegates to research and dashboard specialists while keeping decisions in Notion.

What It Does

• Gathers requirements, timelines, and success criteria from the user
• Dispatches research with citations and requests follow-ups when needed
• Builds or updates dashboard artifacts in dashboard_builder_analyzer/files
• Logs plans, decisions, and statuses directly to Notion
• Returns concise status updates with links, owners, and blockers

Agents and Tools

• Project Manager (entry point)
  • Tool: NotionWorkspaceTool (create, fetch, update, append, and query pages/databases via the Notion API)
• Research Analyst
  • Tool: WebSearchTool (built-in OpenAI browsing) for live research with citations
• Dashboard Builder/Analyzer
  • Tools: FileManagerTool (list/read/write within dashboard_builder_analyzer/files), WebSearchTool for best-practice references

Communication flows: Project Manager ↔ Research Analyst, Project Manager ↔ Dashboard Builder/Analyzer. Only the Project Manager talks to the user.

Prerequisites

• Python 3.10+ and pip
• OPENAI_API_KEY for all agents
• Notion access for workspace updates (NOTION_API_KEY or NOTION_TOKEN; NOTION_MCP_OAUTH_TOKEN if using MCP auth)
• Optional: Docker if you want to containerize

Setup

1. Install dependencies:

pip install -r requirements.txt

2. Create .env in the repo root (see .env.template for keys):

OPENAI_API_KEY=sk-...
NOTION_API_KEY=...
NOTION_TOKEN=...
NOTION_MCP_OAUTH_TOKEN=...   # if applicable

3. (Optional) Activate the bundled virtual env .venv or create your own.

Run the Agency

• Interactive terminal demo (recommended):

python agency.py

• Programmatic use:

python -c "from agency import create_agency; agency = create_agency(); print(agency.get_response_sync('Project kickoff for Q1 revenue dashboard'))"

Working With Notion

• Keep target database/page IDs handy; pass them to the Project Manager when asked.
• Supported operations via NotionWorkspaceTool: list_databases, query_database, list_database_pages, fetch_page, update_page, append_block, create_page.
• Provide properties_json as valid JSON strings for create/update actions; include rich_text when appending content.

Working With Files

• Dashboard artifacts live in dashboard_builder_analyzer/files. The FileManagerTool is scoped to this folder.
• Share exact filenames or subpaths when asking for updates (CSV, JSON, Markdown supported out of the box).

Development Notes

• Shared context lives in shared_instructions.md; communication flows are defined in agency.py.
• For adjustments, edit the agent instructions in each <agent>/instructions.md and tools in <agent>/tools/.
• To add MCP servers or new tools, follow .cursor/commands/add-mcp.md and the workflow in .cursor/rules/workflow.mdc.

Troubleshooting

• Missing keys: ensure .env contains OPENAI_API_KEY and the correct Notion token.
• Notion errors: verify database/page IDs and JSON payloads; confirm the token has write access.
• File writes failing: ensure the path stays inside dashboard_builder_analyzer/files.

project

project-agent