designing-real-world-ai-agents-workshop

Executes multi-turn research workflows using Google Gemini API with built-in Google Search grounding to retrieve factual, up-to-date information. The Deep Research Agent (src/research/server.py) implements a tool-use pattern where Gemini can invoke search tools iteratively, refining queries based on intermediate results, and persists findings into a structured research.md file. Supports YouTube transcript extraction when URLs are provided, enabling multi-modal source integration.

Implements a two-server MCP architecture (Deep Research Agent + LinkedIn Writer Agent) using FastMCP framework, where each server exposes tools, resources, and prompts independently and communicates through standardized MCP protocol. The architecture decouples research and writing concerns, allowing each agent to be developed, tested, and scaled independently while maintaining a unified interface. Configuration is managed via .mcp.json and environment variables, enabling runtime server discovery and tool registration.

Centralizes configuration using Pydantic Settings models (src/research/config/, src/writing/config/) that load from environment variables and .env files, enabling environment-specific configuration without code changes. Configuration includes API keys, model parameters, evaluation thresholds, and server endpoints. Pydantic validation ensures type safety and provides helpful error messages for missing or invalid configuration.

Persists research findings to a structured markdown file (research.md) that serves as the knowledge base for the writing agent. The markdown format enables human readability while maintaining machine-parseable structure (headings, lists, citations). Research findings include source citations, timestamps, and iterative search history, creating an auditable record of how conclusions were reached. The writing agent reads this markdown to generate content, ensuring factual grounding.

Implements a multi-iteration content generation and evaluation pattern in the LinkedIn Writer Agent (src/writing/server.py) where an LLM generates initial content, an evaluator (LLM-as-judge) scores it against quality criteria, and an optimizer refines it based on feedback. The loop continues until quality thresholds are met or max iterations reached. Uses Opik for tracing and LLM-based evaluation metrics, enabling observable, measurable content quality improvement without human-in-the-loop.

Integrates Google Gemini's Imagen model for AI-generated images within the writing workflow, enabling automatic image creation to accompany generated LinkedIn posts. The image generation is triggered based on post content and writing profiles, with generated images persisted to the dataset directory. Supports prompt engineering for image generation based on post themes and audience preferences.

Implements a structured dataset system (datasets/ directory) with batch evaluation scripts that process multiple content samples through the writing workflow and score them using LLM-as-judge metrics via Opik. The evaluation system measures quality across dimensions (clarity, engagement, relevance) and aggregates results for statistical analysis. Supports dataset versioning and comparison across model versions or writing profiles.

Defines MCP tools and resources using FastMCP decorators (@mcp.tool, @mcp.resource) with JSON schema validation, enabling type-safe tool invocation and automatic schema generation. The research and writing servers expose distinct tool sets (search, research persistence, content generation, evaluation) with Pydantic-based input/output validation. MCP routers (src/research/routers/, src/writing/routers/) map tool invocations to application logic, decoupling tool definitions from implementation.

Implements a prompt template system (src/writing/profiles/) where writing profiles define tone, style, audience, and quality criteria as structured data, and prompt templates inject these profiles into system/user messages. The system uses Jinja2-style templating (or similar) to dynamically construct prompts based on profile attributes and research content. Profiles are versioned and can be A/B tested to measure impact on content quality.

Orchestrates a complete workflow (src/research/server.py → src/writing/server.py) where research findings are automatically fed into the writing agent, which generates, evaluates, and refines content, then generates accompanying images. The workflow is exposed as a high-level skill (.claude/skills/research-and-write/SKILL.md) that can be invoked from Claude Code or Cursor with a single topic input. Workflow state is persisted to the filesystem (research.md, generated posts, images), enabling resumption and inspection at any stage.

Integrates Opik for end-to-end tracing of agent workflows, capturing every LLM call, tool invocation, and evaluation metric. Opik traces are automatically generated for research iterations, content generation cycles, and evaluation steps, with links persisted in output metadata. The system enables post-hoc analysis of agent behavior, debugging of failed workflows, and measurement of cost/latency across workflow stages.

Provides Python scripts (scripts/test_research_workflow.py, batch dataset processing scripts) that automate end-to-end testing and evaluation of the multi-agent system. Scripts handle dataset loading, workflow invocation, result collection, and metric aggregation. Uses GNU Make (Makefile) for task orchestration, enabling developers to run complex workflows with simple commands (e.g., `make test-research`, `make evaluate-dataset`).