Expert guidance for developing a multi-agent dialectical debate system using PydanticAI + LangGraph architecture with Archon MCP knowledge base integration.
Expert guidance for developing and maintaining a multi-agent dialectical debate system built with PydanticAI + LangGraph unified architecture.
This skill helps you work with a debate system where AI agents engage in structured thesis-antithesis-synthesis cycles to arrive at better solutions through dialectical collaboration. The system uses PydanticAI for intelligent agents, LangGraph for orchestration, and Archon MCP for pattern knowledge.
The system follows a unified architecture where:
This is ONE integrated system, not separate frameworks glued together.
```
debate/colab/debate/
├── agents/ # PydanticAI agents (thesis, antithesis, synthesis, moderator)
├── graph/ # LangGraph orchestration (state, nodes, workflow)
├── api/ # FastAPI endpoints
└── tests/ # Test suite
```
When setting up the project:
1. Ensure you're in the `colab/debate` directory
2. Check for `.env.minimal.example` for quick start configuration
3. Verify required environment variables:
- `MODEL_PROVIDER` (openai, anthropic, or gemini)
- Corresponding API key (`OPENAI_API_KEY`, etc.)
- `ARCHON_API_KEY` for knowledge base access
4. Review `.env.example` for full configuration options
Run these commands in order:
```bash
cd colab/debate
pip install -r requirements.txt
```
Before making changes, validate the system:
```bash
python -c "from archon.client import ArchonClient; client = ArchonClient(); print('✓ Archon connected')"
python -c "from agents.thesis_agent import thesis_agent; print('✓ Thesis agent loaded')"
python -c "from graph.workflow import get_debate_graph; print('✓ Graph compiled')"
```
ALWAYS follow this order:
1. Query Archon MCP for existing patterns related to your task
2. Review examples in `PRPs/examples/` directory
3. Follow the unified architecture principles (agents for thinking, graphs for coordination)
4. Check if web search fallback is appropriate for your use case
When writing code:
**Agent Development (PydanticAI):**
```python
enable_web_fallback=True # Default
web_search_threshold=0.6 # Minimum Archon relevance score
```
**Graph Orchestration (LangGraph):**
```python
async def thesis_node(state: DebateState, writer) -> dict:
result = await thesis_agent.run(
state["messages"][-1].content,
deps=deps,
message_history=state.get("pydantic_message_history", [])
)
return {"agent_results": [result.data]}
```
**Dialectical Flow:**
1. Thesis: Agent proposes solution with high confidence
2. Antithesis: Agent critiques and finds flaws
3. Synthesis: Agent combines insights
4. Moderation: Agent tracks progress and terminates when converged
Execute tests in this order:
1. Unit test individual agents using TestModel
2. Test graph orchestration separately
3. Run integration tests for the complete unified system
4. Test web search fallback scenarios
Commands:
```bash
pytest tests/ -v --asyncio-mode=auto
pytest tests/test_debate.py -v --asyncio-mode=auto
```
Before committing:
```bash
black .
black --check .
mypy agents/ graph/ --ignore-missing-imports
```
Development mode:
```bash
cd colab/debate
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
```
Production mode:
```bash
uvicorn api.main:app --host 0.0.0.0 --port 8000
```
Available endpoints:
| Issue | Solution |
|-------|----------|
| Import Errors | Ensure you're in `colab/debate` directory |
| Async Warnings | Use `--asyncio-mode=auto` with pytest |
| Model Errors | Verify environment variables are set correctly |
| Archon Connection | Check Archon MCP accessibility and API key |
Agents automatically fall back to web search when Archon results are insufficient:
When asked to add a new agent capability:
1. Query Archon for similar patterns
2. Review existing agents in `agents/` directory
3. Implement agent with proper type hints
4. Create corresponding node wrapper in `graph/nodes.py`
5. Update workflow in `graph/workflow.py`
6. Write unit tests for agent
7. Write integration test for full flow
8. Run code quality checks
9. Test via API endpoint
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/debate-system-development/raw