Building Real-World AI Systems with PydanticAI: Lessons from Anthropic’s Agent Design Patterns

Agents
Pydantic
Author

Fabian

Published

May 21, 2025

Introduction: Why Agent Design Patterns Matter

As AI continues to reshape industries—from legal and healthcare to marketing and customer service—developers face a growing need to build robust, modular, and intelligent systems. This is where agent design patterns come into play.

In a pivotal post titled Building Effective Agents, Anthropic introduced core agent patterns that help AI engineers build complex yet maintainable systems. These include strategies like prompt chaining, routing, parallel execution, orchestration, and optimization.

In this post, we’ll translate these patterns into real-world applications using PydanticAI—a framework that makes it easy to define and run structured AI agents. We’ll walk through five major patterns and how they apply to real use cases, with fully working code samples.

https://www.anthropic.com/engineering/building-effective-agents

Augmenting LLM’s

2. Routing – Use Case: Customer Support Agent

Scenario: Route customer inquiries to specialized support agents (billing, technical, general).

billing_agent = Agent(model=model,
                    system_prompt="Answer billing questions."
                       )
tech_agent = Agent(model=model,
                    system_prompt="Handle technical support.")
general_agent = Agent(model=model,
                    system_prompt="Answer general customer questions.")

def route_query(input_text: str):
    if "bill" in input_text.lower():
        return billing_agent.run_sync(input_text)
    elif "error" in input_text.lower():
        return tech_agent.run_sync(input_text)
    else:
        return general_agent.run_sync(input_text)

response = route_query("I have a problem with my last invoice.")
print(response.data)
I'm sorry to hear that you're having an issue with your invoice. Could you please provide more details about the problem? For example, are there discrepancies in the amount, missing charges, or any other specific concerns? This will help me assist you better.

3. Parallelization – Use Case: Market Intelligence Dashboard

Scenario: Gather insights on competitors, customer reviews, and product trends concurrently.

import asyncio
from pydantic_ai.common_tools.duckduckgo import duckduckgo_search_tool

competitor_agent = Agent(
    model=model,
    tools=[duckduckgo_search_tool()],
    system_prompt='Search DuckDuckGo for the given query and return the results. Summarize competitor activity.',
)

reviews_agent = Agent(
    model=model,
    tools=[duckduckgo_search_tool()],
    system_prompt='Search DuckDuckGo for the given query and return the results. Summarize customer reviews.',
)

trends_agent = Agent(
    model=model,
    tools=[duckduckgo_search_tool()],
    system_prompt='Search DuckDuckGo for the given query and return the results. Summarize industry trends.',
)

async def collect_insights():
    competitor_task = asyncio.create_task(competitor_agent.run("Company A"))
    reviews_task = asyncio.create_task(reviews_agent.run("Product XYZ"))
    trends_task = asyncio.create_task(trends_agent.run("Industry trends"))

    insights = await asyncio.gather(competitor_task, reviews_task, trends_task)
    return insights

insights = asyncio.run(collect_insights())
for insight in insights:
    print(insight.data)

4. Orchestrator-Worker – Use Case: Content Generation Pipeline

Scenario: An orchestrator agent creates a blog post outline, then worker agents write sections.

from pydantic import BaseModel
from typing import List

class Section(BaseModel):
    title: str
    description: str

class FullPost(BaseModel):
    title: str
    sections: List[Section]

outline_agent = Agent(
    model=model,
    result_type=FullPost,
    system_prompt="""
    You are a content strategist. Given a blog topic, outline the title and 3-5 key sections.
    Each section should include a title and a short description of what it should cover.
    Return the output in JSON format matching the FullPost schema.
    """
)

class WrittenSection(BaseModel):
    title: str
    content: str

writer_agent = Agent(
    model=model,
    result_type=WrittenSection,
    system_prompt="""
    You are a blog writer. Expand the following blog section.
    Return a well-written paragraph or two based on the given title and description.
    Output in JSON format with the section title and full content.
    """
)

def generate_blog_post(topic: str):
    # Step 1: Get outline from orchestrator
    outline = outline_agent.run_sync(topic)
    post_title = outline.data.title
    section_plans = outline.data.sections

    # Step 2: Generate each section via writer agent
    final_sections = []
    for section in section_plans:
        section_input = f"Title: {section.title}\nDescription: {section.description}"
        written = writer_agent.run_sync(section_input)
        final_sections.append({
            "title": written.data.title,
            "content": written.data.content
        })

    return {
        "title": post_title,
        "sections": final_sections
    }

# Example usage
post = generate_blog_post("The Future of AI in Personalized Education")

print(f"Title: {post['title']}")
for sec in post["sections"]:
    print(f"\n### {sec['title']}\n{sec['content']}")
Title: The Future of AI in Personalized Education

### Introduction to AI in Education
Artificial Intelligence (AI) is revolutionizing the landscape of education by providing tailored learning experiences that cater specifically to the individual needs of each student. In various educational settings, AI is being employed to analyze data regarding students' learning patterns, preferences, and overall performance. This enables teachers and educators to create personalized lesson plans and instructional approaches, ensuring that no student is left behind in their learning journey. 

From intelligent tutoring systems that offer immediate feedback to adaptive learning platforms that adjust the curriculum based on a student’s strengths and weaknesses, AI is enhancing the overall educational experience. Moreover, AI-powered analytics tools are helping educators identify at-risk students early on, allowing for timely intervention and support. As technology continues to advance, the potential for AI to enrich and transform education becomes increasingly evident, paving the way for a more inclusive and effective learning environment.

### Benefits of Personalized Learning Through AI
Personalized learning through artificial intelligence (AI) is revolutionizing the educational landscape by offering a multitude of advantages that cater to individual student needs. One of the most significant benefits is the ability to deliver tailored content that aligns with each learner's unique pace, interests, and comprehension levels. AI algorithms analyze data from students' interactions with learning materials, allowing it to recommend resources that are most relevant and beneficial for their specific circumstances. This level of customization not only enhances engagement but also fosters a deeper understanding of the subject matter.

In addition, AI facilitates adaptive learning pathways, adjusting the difficulty and style of instruction based on real-time assessment of a student’s progress. This means that if a student struggles with a concept, the AI can provide additional resources or change the approach to ensure mastery before moving forward. Furthermore, continuous performance assessment enables educators to track progress and identify areas needing improvement efficiently. With timely feedback provided by AI tools, teachers can make informed decisions about instructional strategies, ensuring that each student receives the support they need to succeed. Ultimately, the integration of AI in personalized learning not only empowers students but also optimizes educational outcomes and fosters a more inclusive learning environment.

### Challenges and Ethical Considerations
As artificial intelligence (AI) continues to reshape the landscape of personalized education, it brings with it a host of challenges and ethical considerations that cannot be overlooked. One of the most pressing issues is data privacy. In order for AI systems to effectively tailor educational content and strategies to individual learning styles, they require access to vast amounts of personal data. This can include sensitive information about students' academic performance, behavioral patterns, and even socio-economic backgrounds. The collection, storage, and analysis of this data raise significant concerns about its misuse or unauthorized access, leading to potential breaches of privacy. Schools and educational institutions must navigate these challenges carefully, ensuring robust data protection measures are in place to maintain the trust of students and their families.

Another critical issue is algorithmic bias. AI algorithms are only as good as the data they are trained on; if that data reflects existing societal biases, the resulting AI systems may inadvertently perpetuate these inequalities. For example, if an AI tool prioritizes students from resource-rich backgrounds, it may neglect or disadvantage those from marginalized communities. This raises ethical questions about fairness and equity in education. Stakeholders must be vigilant in monitoring and auditing AI systems to detect and correct biases, ensuring that personalized education serves all students equally and inclusively. Addressing these challenges is essential for the responsible adoption of AI in educational settings and for creating a fair learning environment for every student.

### Case Studies and Success Stories
In recent years, numerous educational institutions have successfully integrated artificial intelligence (AI) into their teaching and learning frameworks, leading to significant improvements in student learning outcomes. One notable example is Georgia State University, which implemented an AI-driven advising system known as "Pounce." This system proactively reaches out to students based on their academic performance, thereby helping them navigate challenges and stay on track for graduation. Since its launch, the university has witnessed a remarkable increase in graduation rates, particularly among minority and first-generation college students, showcasing how personalized support through AI can enhance educational equity.

Another compelling case study comes from the K-12 sector, where Pennsylvania's South Fayette School District has adopted AI tools to tailor educational experiences for elementary school students. Utilizing platforms that analyze student performance data, teachers can identify individual learning styles and adapt their instructional strategies accordingly. This targeted approach has led to an uptick in engagement and mastery in subjects such as mathematics and literacy. Furthermore, the district has noticed improved collaboration among staff, as AI-driven insights facilitate data-informed discussions about student progress, ultimately fostering a culture of continuous improvement.

These success stories illustrate the transformative power of AI in education, highlighting not only the advancements in individual student achievement but also the broader implications for institutional practices and policies. By leveraging AI, educators can create a more responsive and personalized learning environment, empowering students to achieve their fullest potential.

### The Future Landscape of AI in Education
As we gaze into the future of AI in education, it's evident that we are on the brink of a transformative shift in how learners engage with knowledge and educators facilitate learning. Personalized education is set to become the hallmark of the academic experience, powered by advanced AI systems that adapt to each student's unique learning style, pace, and requirements. These intelligent systems will harness vast amounts of data to tailor educational content and methods, ensuring that every student receives support that is perfectly aligned with their individual needs.

Emerging technologies such as virtual reality (VR) and augmented reality (AR) are expected to enhance this personalized learning experience. Imagine classrooms where students can explore ancient civilizations through immersive VR environments or manipulate 3D models in real-time to grasp complex scientific concepts. Furthermore, AI will likely evolve to include sophisticated chatbots and virtual tutors that provide instant feedback and assistance, allowing learners to explore topics in depth outside of traditional classroom hours. As teaching methodologies blend with these innovative tools, educators may find themselves taking on more of a mentorship role, focusing on fostering critical thinking and creativity, rather than simply delivering content. Overall, the intersection of these evolving technologies with pedagogical approaches heralds an exciting future for education—one that is more engaging, inclusive, and effective than ever before.

5. Evaluator-Optimizer: Best Marketing Copy Selection

Use Case: Generate multiple slogans, evaluate their impact, and select the best.

from pydantic import BaseModel

class Tagline(BaseModel):
    text: str
    persuasiveness: float

generator = Agent(model=model, result_type=list[str], system_prompt="Generate 5 marketing taglines.")
evaluator = Agent(model=model, result_type=Tagline, system_prompt="Evaluate the persuasiveness of this tagline.")

taglines = generator.run_sync("Launch campaign for eco-friendly bottles")
evaluated = [evaluator.run_sync(t) for t in taglines.data]
best = max(evaluated, key=lambda t: t.data.persuasiveness)

print(taglines.data)
print(evaluated)
print(f"Best Tagline: {best.data.text} (Score: {best.data.persuasiveness})")
['Sip Sustainably with Every Drop!', 'Drink Green, Live Clean!', 'Eco Bottles: Bottle Your Impact!', 'Refill, Reuse, Revive the Planet!', 'Hydration with a Conscience!']
[RunResult(_all_messages=[ModelRequest(parts=[SystemPromptPart(content='Evaluate the persuasiveness of this tagline.', dynamic_ref=None, part_kind='system-prompt'), UserPromptPart(content='Sip Sustainably with Every Drop!', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 16, 99475, tzinfo=datetime.timezone.utc), part_kind='user-prompt')], kind='request'), ModelResponse(parts=[ToolCallPart(tool_name='final_result', args=ArgsJson(args_json='{"text":"Sip Sustainably with Every Drop!","persuasiveness":8}'), tool_call_id='call_ufRsb9U6feCV9W6LXppNwvxJ', part_kind='tool-call')], timestamp=datetime.datetime(2025, 6, 1, 1, 18, 15, tzinfo=datetime.timezone.utc), kind='response'), ModelRequest(parts=[ToolReturnPart(tool_name='final_result', content='Final result processed.', tool_call_id='call_ufRsb9U6feCV9W6LXppNwvxJ', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 17, 202590, tzinfo=datetime.timezone.utc), part_kind='tool-return')], kind='request')], _new_message_index=0, data=Tagline(text='Sip Sustainably with Every Drop!', persuasiveness=8.0), _result_tool_name='final_result', _usage=Usage(requests=1, request_tokens=78, response_tokens=26, total_tokens=104, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0, 'cached_tokens': 0})), RunResult(_all_messages=[ModelRequest(parts=[SystemPromptPart(content='Evaluate the persuasiveness of this tagline.', dynamic_ref=None, part_kind='system-prompt'), UserPromptPart(content='Drink Green, Live Clean!', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 17, 203808, tzinfo=datetime.timezone.utc), part_kind='user-prompt')], kind='request'), ModelResponse(parts=[ToolCallPart(tool_name='final_result', args=ArgsJson(args_json='{"text":"Drink Green, Live Clean!","persuasiveness":8}'), tool_call_id='call_UVHTqnt3mthpDYt5IFolcFnf', part_kind='tool-call')], timestamp=datetime.datetime(2025, 6, 1, 1, 18, 16, tzinfo=datetime.timezone.utc), kind='response'), ModelRequest(parts=[ToolReturnPart(tool_name='final_result', content='Final result processed.', tool_call_id='call_UVHTqnt3mthpDYt5IFolcFnf', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 18, 302909, tzinfo=datetime.timezone.utc), part_kind='tool-return')], kind='request')], _new_message_index=0, data=Tagline(text='Drink Green, Live Clean!', persuasiveness=8.0), _result_tool_name='final_result', _usage=Usage(requests=1, request_tokens=77, response_tokens=25, total_tokens=102, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0, 'cached_tokens': 0})), RunResult(_all_messages=[ModelRequest(parts=[SystemPromptPart(content='Evaluate the persuasiveness of this tagline.', dynamic_ref=None, part_kind='system-prompt'), UserPromptPart(content='Eco Bottles: Bottle Your Impact!', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 18, 304064, tzinfo=datetime.timezone.utc), part_kind='user-prompt')], kind='request'), ModelResponse(parts=[ToolCallPart(tool_name='final_result', args=ArgsJson(args_json='{"text":"Eco Bottles: Bottle Your Impact!","persuasiveness":75}'), tool_call_id='call_f8Aj5izB6SJ0Ug9OVUh9YGPE', part_kind='tool-call')], timestamp=datetime.datetime(2025, 6, 1, 1, 18, 17, tzinfo=datetime.timezone.utc), kind='response'), ModelRequest(parts=[ToolReturnPart(tool_name='final_result', content='Final result processed.', tool_call_id='call_f8Aj5izB6SJ0Ug9OVUh9YGPE', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 19, 510346, tzinfo=datetime.timezone.utc), part_kind='tool-return')], kind='request')], _new_message_index=0, data=Tagline(text='Eco Bottles: Bottle Your Impact!', persuasiveness=75.0), _result_tool_name='final_result', _usage=Usage(requests=1, request_tokens=79, response_tokens=27, total_tokens=106, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0, 'cached_tokens': 0})), RunResult(_all_messages=[ModelRequest(parts=[SystemPromptPart(content='Evaluate the persuasiveness of this tagline.', dynamic_ref=None, part_kind='system-prompt'), UserPromptPart(content='Refill, Reuse, Revive the Planet!', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 19, 511390, tzinfo=datetime.timezone.utc), part_kind='user-prompt')], kind='request'), ModelResponse(parts=[ToolCallPart(tool_name='final_result', args=ArgsJson(args_json='{"text":"Refill, Reuse, Revive the Planet!","persuasiveness":8}'), tool_call_id='call_jSp4FmfekthFFDeoreduQv7z', part_kind='tool-call')], timestamp=datetime.datetime(2025, 6, 1, 1, 18, 18, tzinfo=datetime.timezone.utc), kind='response'), ModelRequest(parts=[ToolReturnPart(tool_name='final_result', content='Final result processed.', tool_call_id='call_jSp4FmfekthFFDeoreduQv7z', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 20, 781845, tzinfo=datetime.timezone.utc), part_kind='tool-return')], kind='request')], _new_message_index=0, data=Tagline(text='Refill, Reuse, Revive the Planet!', persuasiveness=8.0), _result_tool_name='final_result', _usage=Usage(requests=1, request_tokens=82, response_tokens=30, total_tokens=112, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0, 'cached_tokens': 0})), RunResult(_all_messages=[ModelRequest(parts=[SystemPromptPart(content='Evaluate the persuasiveness of this tagline.', dynamic_ref=None, part_kind='system-prompt'), UserPromptPart(content='Hydration with a Conscience!', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 20, 784210, tzinfo=datetime.timezone.utc), part_kind='user-prompt')], kind='request'), ModelResponse(parts=[ToolCallPart(tool_name='final_result', args=ArgsJson(args_json='{"text":"Hydration with a Conscience!","persuasiveness":8}'), tool_call_id='call_3Ez7cRY8noqIjkuwYpKqdFzR', part_kind='tool-call')], timestamp=datetime.datetime(2025, 6, 1, 1, 18, 20, tzinfo=datetime.timezone.utc), kind='response'), ModelRequest(parts=[ToolReturnPart(tool_name='final_result', content='Final result processed.', tool_call_id='call_3Ez7cRY8noqIjkuwYpKqdFzR', timestamp=datetime.datetime(2025, 6, 1, 1, 18, 21, 773118, tzinfo=datetime.timezone.utc), part_kind='tool-return')], kind='request')], _new_message_index=0, data=Tagline(text='Hydration with a Conscience!', persuasiveness=8.0), _result_tool_name='final_result', _usage=Usage(requests=1, request_tokens=78, response_tokens=26, total_tokens=104, details={'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0, 'cached_tokens': 0}))]
Best Tagline: Eco Bottles: Bottle Your Impact! (Score: 75.0)
Back to top