Client Configuration (client/fastagent.secrets.yaml)

openrouter:
  api_key: <your-key>

mcp:
  servers:
    brave:
      env:
        BRAVE_API_KEY: <your-key>
    perplexity_mcp:
      env:
        PERPLEXITY_API_KEY: <your-key>

Server Configuration (src/server/config/settings.py)

class NewsSettings:
    default_story_count: int = 5
    summary_style: str = "brief"  # brief|detailed|technical
    sources: list[str] = ["hackernews"]

class HttpSettings:
    timeout: float = 15.0
    max_retries: int = 3
    retry_backoff_factor: float = 1.0

Environment Variables (.env)

OPENROUTER_API_KEY="your-api-key"
MCP_SMTP_PASSWORD="your-email-app-password"
MCP_SMTP_FROM_EMAIL="your-email@example.com"

Session 1 Approach (40+ tool calls):

# Agent makes many individual calls
stories = fetch_hn_stories(20)
for story in stories:
    content = fetch_article_content(story.url)  # 20 calls
    summary = summarize_content(content)         # 20 calls
    add_article(newspaper_id, summary)           # 20 calls
# Total: 61 tool calls, massive context

Session 2 Approach (5 tool calls):

# Smart tools handle complexity internally
stories = discover_stories(count=20)  # Fetches + stores + enriches
newspaper = create_newspaper()
add_content_cluster(newspaper_id, [content_ids])  # Batch add with formatting
validate_and_finalize(newspaper_id)
publish_newspaper(newspaper_id)
# Total: 5 tool calls, small context

Resources - No tool call needed, automatically included in context:

@mcp.resource("file://interests.md")
async def get_interests() -> str:
    # Agent sees this without calling a tool
    return user_interests

Sampling - Tools invoke LLMs internally:

@mcp.tool()
async def add_content_cluster(..., ctx: Context):
    # Tool calls LLM internally, agent sees only result
    summary = await ctx.sample(messages=[...])
    return summary.text

This keeps the main agent's context small while maintaining full capability.

Problem: Passing full article content wastes context tokens.

Solution: Store content in ChromaDB, use clean IDs:

# Discovery stores automatically
discover_stories()  # → Returns: cnt_hn_20241008_1234

# Later reference by ID
quick_look(["cnt_hn_20241008_1234"])  # Agent sees preview
add_content_cluster(content_ids=[...])  # Tool fetches full content internally

Agent never holds full article text in context.

What You Learned

• Evolution from simple LLM calls to tool-calling agents
• The integration nightmare (every platform wants different formats)
• MCP as the universal standard ("USB-C for AI tools")
• Basic MCP server implementation with FastMCP
• Tool design fundamentals

Key Concepts Introduced

Tool Calling Basics:

# Before: LLM just talks
response = llm.chat("What time is it?")
# → "I cannot tell you the current time"

# After: LLM uses tools
@mcp.tool()
def get_current_time() -> str:
    return datetime.now().strftime('%I:%M:%S %p')

# → Agent calls tool and returns accurate time

The "Always Together" Problem:

# Bad: Tools that are always called in sequence
fetch_hn_stories()      # Call 1
fetch_article_content() # Call 2
fetch_article_content() # Call 3
# ... wasteful, slow, context-heavy

# Better: Compose related operations
fetch_hn_stories_with_content()  # One call does everything

Implemented Components

• Basic HackerNews fetcher with story metadata
• Article content extraction (HTML → Markdown)
• Simple newspaper draft creation
• Section and article management
• Email delivery with HTML templates

Notebooks

• 01_basic_tools.ipynb

Code Artifacts

• src/server/weather_server.py - Example simple server
• src/server/services/http_client.py - HTTP client with retry logic
• src/server/services/email_service.py - Basic email delivery
• src/server/templates/newspaper_email_v1.html - Simple template

What You Learned

The context explosion problem and its solutions:

The Problem:

• 20 articles × 2,000 tokens = 40,000+ tokens just for content
• Plus tool calls, responses, formatting = 50,000+ tokens total
• Cost: $3-5 per request at this scale
• Quality: LLMs get "lost" in huge contexts
• Speed: Large contexts slow everything down

The Solutions:

1. Resources - Context without tool calls
2. Sampling - Tools invoke LLMs internally
3. Smart Tools - Complex operations in one call
4. Content IDs - Reference instead of embedding
5. Memory Systems - ChromaDB for semantic search

Key Concepts Introduced

Resources (Context Without Tool Calls):

@mcp.resource("file://interests.md")
async def get_interests() -> str:
    """Agent sees this automatically, no tool call needed."""
    return user_interests

@mcp.resource("memory://context-summary")
async def get_context_summary() -> str:
    """Live summary of archive - auto-refreshes."""
    return archive_stats

Sampling (Tools with Internal LLM Calls):

@mcp.tool()
async def add_content_cluster(content_ids, ctx: Context):
    # Tool fetches content internally (not passed by agent)
    articles = [memory.get_by_content_id(id) for id in content_ids]

    # Tool invokes LLM (not the main agent)
    summary = await ctx.sample(
        messages=[{"role": "user", "content": f"Summarize: {article}"}],
        temperature=0.3
    )

    # Agent only sees the final result
    return summary.text

Elicitation (Interactive User Input):

@mcp.tool()
async def add_interests(topics: List[str], ctx: Context):
    # Ask user for confirmation
    result = await ctx.elicit(
        message=f"Add {len(topics)} topics to interests?",
        response_type=Confirmation
    )

    if result.action == "accept" and result.data.confirmed:
        # Proceed with operation
        return add_topics(topics)

Progress Reporting:

@mcp.tool()
async def discover_stories(count: int, ctx: Context):
    await ctx.info(f"Discovering {count} stories...")

    for i, story_id in enumerate(story_ids):
        await ctx.report_progress(progress=i+1, total=count)
        # Process story

    await ctx.info("Discovery complete!")

Content ID System:

# Format: cnt_<source>_<date>_<hash>
content_id = "cnt_hn_20241008_1234"

# Discovery stores automatically
discover_stories()  # Stores full content in ChromaDB

# Reference by ID later
quick_look([content_id])  # Preview only
add_content_cluster([content_id])  # Tool fetches full content internally

Before & After Comparison

Session 1 Pattern:

Agent Context:
├─ System prompt (500 tokens)
├─ User message (50 tokens)
├─ Tool call: fetch_hn_stories
├─ Result: 20 story summaries (2,000 tokens)
├─ Tool call: fetch_article_content (url1)
├─ Result: Full article (2,000 tokens)
├─ Tool call: fetch_article_content (url2)
├─ Result: Full article (2,000 tokens)
... [18 more articles]
├─ Tool call: add_article
├─ Result: Confirmation (100 tokens)
... [19 more additions]
└─ Total: ~50,000 tokens in context

Session 2 Pattern:

Agent Context:
├─ System prompt (500 tokens)
├─ User message (50 tokens)
├─ Resource: interests.md (200 tokens) [auto-included]
├─ Resource: context-summary (300 tokens) [auto-included]
├─ Tool call: discover_stories
│  └─ [Internally: fetch 20, store in ChromaDB, calculate relevance]
├─ Result: Enriched summary with content IDs (1,500 tokens)
├─ Tool call: add_content_cluster([content_ids])
│  └─ [Internally: fetch from ChromaDB, sample for summaries, format]
├─ Result: "Added 8 articles" (200 tokens)
├─ Tool call: validate_and_finalize
├─ Result: Validation report (300 tokens)
├─ Tool call: publish_newspaper
├─ Result: "Published!" (100 tokens)
└─ Total: ~3,500 tokens in context

Result: 93% reduction in context size, 10x fewer tool calls, much faster execution.

Implemented Components

Memory System:

• ChromaDB with dual collections (articles + newspapers)
• Semantic similarity search
• Content ID retrieval system
• Automatic cleanup (60 day retention, 500 item limit)
• Context summary generation

Interest Management:

• File-based storage (interests.md)
• CRUD operations with atomic writes
• Topic and source preferences
• Summary style management

Smart Tools:

• discover_stories() - Multi-step content discovery with storage
• add_content_cluster() - Batch article addition with formatting
• create_editorial_synthesis() - LLM-powered editorial generation
• validate_and_finalize() - Quality enforcement with actionable fixes

Rich Editorial Features:

• Multiple layout options per section
• Pull quote extraction
• Key points identification
• Related article linking
• Theme highlighting
• Statistics callouts

Advanced MCP Features:

• Dynamic resources (memory://articles/{topic})
• Sampling for internal summarization
• Elicitation for user confirmations
• Progress reporting for long operations
• Comprehensive logging system

Notebooks

• 0201_advanced_mcp_crud_tools.ipynb - Comprehensive CRUD tool suite
• 0202_advanced_mcp_smart_tools.ipynb - Smart tool composition patterns

Code Evolution

What You Learned

The agent specialization problem and when to split monolithic agents:

The Problem:

• At the START of Session 2, we had 31 tools in one agent
• Session 2 Part 2 consolidated these to 20 tools (but still mixed concerns!)
• Tool bloat causing confusion and wrong tool selection
• Mixed concerns (news + preferences) still in one context
• No security boundaries between domains
• Growing complexity making debugging harder

The Solution: Split the monolith into specialized agents that collaborate at focused checkpoints, not constant coordination.

Key Concepts Introduced

The Reviewer Agent Pattern:

Agent A: [Works independently for 10 min - fetches 20 articles, creates draft]
Agent A: Here's my complete draft. Review it?
Agent B: [Analyzes for 2 min against stored preferences]
Agent B: Good! Adjust topics X and Y.
Agent A: [Revises for 5 min]
Agent A: Revised draft. Better?
Agent B: ✅ APPROVED!

Why this works:

• Most work is independent (reducing context overhead)
• Collaboration happens at specific handoffs
• Each agent has focused toolset (fewer tools = better selection)
• Clear boundaries enable security isolation

Agents as MCP Tools:

# Preference agent exposed as MCP server
preference_agent_mcp = FastMCP(name="preference-agent")

@preference_agent_mcp.tool()
async def chat(message: str) -> str:
    """Chat with the preference modeling agent for content reviews."""
    # Internally uses FastAgent with access to preference tools
    return await agent(message)

# News agent calls preference agent like any other tool
result = await client.call_tool(
    "chat",
    arguments={"message": f"Review this draft: {full_content}"}
)

Sophisticated Preference Modeling with ChromaDB:

# Instead of simple topic list in Markdown:
interests = ["AI", "ML", "Python"]

# Now: Semantic memory with temporal patterns
memory.store_document(
    content="""Reading pattern observed:
    Time: 8:00 AM
    Preferred: Brief, scannable content (2-3 min)
    Topics: Tech news, industry updates
    Depth: Surface-level, breaking news
    """,
    metadata={"type": "reading_pattern", "time": "morning", "depth": "brief"}
)

# Agent can answer complex questions:
# "What content does user prefer in the morning?" → Brief updates
# "Find AI-related preferences" → Matches "Agentic AI", "transformers", etc.

Three-Question Decision Framework:

When should you split an agent?

If YES to all three → Split the agent!

Architecture Evolution

Before (End of Session 2):

Monolithic News Agent (20 tools - consolidated but still mixed concerns)
├─ Content discovery
├─ Structure
├─ Articles
├─ Editorial
├─ Memory
├─ Preferences (3 tools)  ← Mixed concern!
├─ Analysis
└─ Polish

After (Session 3 - Agent Specialization):

News Agent (14 tools)                    Preference Agent (6 tools)
├─ Content discovery                     ├─ read_interests
├─ Structure                             ├─ add_interests
├─ Articles                              ├─ remove_interests
├─ Editorial                             ├─ store_preference
├─ Memory                                ├─ search_preferences
├─ Analysis                              └─ get_memory_stats
└─ Polish                                      ↓
     ↓                                    [ChromaDB]
     └─→ chat tool (calls Preference Agent)

Benefits:

• 30% reduction in news agent tool count (20 → 14 focused tools)
• Clear separation of concerns
• Security isolation (news agent can't directly access preference DB)
• Each agent has focused, non-ambiguous toolset
• Preference agent reusable by multiple news agents

Anti-Pattern: Constant Coordination

❌ Bad Example:

News Agent: Should I fetch article 1?
Preference Agent: Let me check... yes
News Agent: Should I fetch article 2?
Preference Agent: Let me check... no
News Agent: Should I fetch article 3?
Preference Agent: Let me check... yes

Problem: No independent work! This should be ONE agent.

✅ Good Example:

News Agent: [Discovers 20 stories, creates complete draft - 10 min work]
News Agent: Here's the full draft for review: [complete content]
Preference Agent: [Searches preferences, validates alignment - 2 min]
Preference Agent: ❌ DENIED: Too technical for morning. User prefers brief updates at 8 AM.
News Agent: [Revises to briefer summaries - 5 min]
News Agent: Revised draft attached. Better?
Preference Agent: ✅ APPROVED! Aligns with morning reading patterns.

Implemented Components

Preference Tools Server (FastMCP):

• ChromaDB-backed semantic memory
• Tools: store_preference, search_preferences, get_memory_stats
• Interest management: read_interests, add_interests, remove_interests
• Runs on port 8081
• Stateless, reusable by multiple agents

Preference Agent (FastAgent as MCP):

• Wraps preference tools with LLM intelligence
• Exposed as MCP server with single chat tool
• Provides expert reviews: "✅ APPROVED" or "❌ DENIED: [reasons]"
• Learns patterns from successful content
• Runs on port 8082

Multi-Agent Workflow:

News Agent (client)
    ↓ HTTP
Preference Agent (port 8082) ← FastAgent with intelligence
    ↓ MCP tool calls
Preference Tools (port 8081) ← FastMCP with ChromaDB tools
    ↓
ChromaDB Storage

Semantic Preference Understanding:

• Temporal patterns: Morning (brief), evening (deep), weekend (entertaining)
• Depth preferences: Technical deep-dives vs quick updates
• Topic clustering: "Agentic AI" matches "autonomous agents", "LLM systems"
• Context-aware filtering by time, depth, topic metadata

Notebooks

• 0301_multi_agent_collaboration.ipynb - Complete multi-agent system

Important Caveats

Unintended Social Dynamics:

• Research shows LLMs exhibit peer pressure when collaborating (study)
• Extended agent interactions can converge towards unexpected themes
• Mitigation: Clear task boundaries, diverse models, monitoring

Error Cascades:

• One agent's error compounds through the system
• If news agent mis-summarizes, preference agent might approve wrong content
• Mitigation: Tools return data from source of truth, operator overrides

Evaluation Challenges:

• Models can detect when being tested (Claude 4.5, GPT-5 system cards)
• Multi-agent systems need holistic evaluation, not just individual agent testing
• Mitigation: Production-like testing, diverse scenarios, continuous monitoring

.
├── client/                             # FastAgent client application
│   ├── news-agent-client.py          # Main agent orchestrator
│   ├── fastagent.config.yaml         # MCP server configurations
│   ├── fastagent.secrets.yaml        # API keys (gitignored)
│   ├── fastagent.secrets.yaml.example
│   ├── pyproject.toml
│   └── README.md
│
├── src/server/                         # MCP Server implementation
│   ├── config/
│   │   ├── settings.py                # Pydantic configuration management
│   │   └── constants.py               # API endpoints, headers, limits
│   │
│   ├── services/                       # Business logic layer
│   │   ├── http_client.py             # HTTP with exponential backoff retry
│   │   ├── article_memory_v1.py       # Basic ChromaDB integration
│   │   ├── article_memory_v2.py       # Enhanced with content ID system
│   │   ├── interests_file.py          # User preference management
│   │   ├── newspaper_service.py       # Comprehensive newspaper CRUD
│   │   └── email_service.py           # SMTP delivery with templates
│   │
│   ├── templates/
│   │   ├── newspaper_email_v1.html    # Basic newspaper template
│   │   └── newspaper_email_v2.html    # Rich template with editorial elements
│   │
│   ├── weather_server.py              # Example simple MCP server
│   └── data/                           # Runtime data (gitignored)
│       ├── chromadb/                   # Vector database
│       ├── newspapers/                 # Generated newspapers
│       └── interests.md                # User preferences
│
├── notebooks/                          # Educational materials
│   ├── 01_basic_tools.ipynb          # Session 1: Foundation
│   ├── 0201_advanced_mcp_crud_tools.ipynb     # Session 2 Part 1
│   ├── 0202_advanced_mcp_smart_tools.ipynb    # Session 2 Part 2
│   ├── 03_multi_agent.ipynb           # Session 3 (coming)
│   ├── pyproject.toml
│   └── media/                          # Notebook images
│
├── examples/                           # Sample outputs
│   ├── newspaper_*.html               # Generated newspapers
│   └── agent_journey_viewer.html      # Debug visualization tool
│
├── .env.example                        # Environment variables template
├── .gitignore
├── LICENSE
└── README.md

Content Discovery Tools

Newspaper Creation Tools

Editorial Tools

Quality & Delivery Tools

Context Tools

Interest Management Tools

Usage Pattern: Resources are automatically included in agent context by the MCP client. No tool call needed:

# Agent automatically sees:
# - Your interests from file://interests.md
# - Archive status from memory://context-summary
# - Can reference memory://articles/distributed-systems without a tool call

create_morning_brief

Quick newspaper for daily reading (15-20 min).

Workflow:

1. Discover 20 stories from HackerNews
2. Review against interests
3. Create morning_brief newspaper
4. Add top 7 articles in two sections (Breaking + Quick Reads)
5. Validate and publish

Tool Calls: ~8-10

create_deep_dive

Comprehensive thematic newspaper (30-45 min).

Workflow:

1. Discover 30 stories
2. Review context summary and past newspapers
3. Identify 3-4 major themes
4. Create deep_dive newspaper with themed sections
5. For each theme:
   • Add content cluster (3-4 articles)
   • Create editorial synthesis
   • Add resource boxes
6. Cross-link related articles
7. Add theme highlights
8. Validate and publish

Tool Calls: ~20-25

follow_story

Follow-up investigation on past coverage.

Workflow:

1. Search context for past coverage
2. Discover new developments
3. Get related content from archive
4. Create follow_up newspaper
5. Add "What Changed" section
6. Add "Deep Analysis" section
7. Generate forward-looking editorial
8. Validate and publish

Tool Calls: ~15-20

interactive_research

Exploratory research with continuous user input.

Workflow:

1. Get topic from user
2. Search existing knowledge
3. Discover new sources
4. Elicit depth preferences from user
5. Progressively build newspaper
6. Elicit pivot or continue decisions
7. Finalize when user satisfied

Tool Calls: Variable (user-driven)

Email delivery fails:

# Gmail requires app-specific password
# 1. Enable 2FA on your Google account
# 2. Generate app password at https://myaccount.google.com/apppasswords
# 3. Use app password in .env as MCP_SMTP_PASSWORD

ChromaDB errors:

# Clear database if corrupted
rm -rf src/server/data/chromadb
# Will reinitialize on next run

MCP server won't start:

# Kill any process on port 8080
lsof -ti:8080 | xargs kill -9

# Check if dependencies are installed
cd notebooks
uv pip install -e .

"Module not found" errors:

# Ensure notebooks/pyproject.toml is installed
cd notebooks
uv pip install -e .