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

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

1. Prompt Chaining – Use Case: Legal Document Review Workflow

Scenario: Automating the extraction, summarization, and risk analysis of legal documents.

import os
from dotenv import load_dotenv
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel 

import nest_asyncio
nest_asyncio.apply()

# Load environment variables from .env file
load_dotenv()

# Get the OpenAI API key from the environment variable
OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY")  

if not OPENAI_API_KEY:
    raise ValueError("OPENAI_API_KEY environment variable not set.")

# Initialize our LLM model
model = OpenAIModel( 
    model_name='gpt-4o-mini', 
    api_key=OPENAI_API_KEY,
)


class ExtractedClauses(BaseModel):
    clauses: list[str]

class Summary(BaseModel):
    summary: str

class RiskAssessment(BaseModel):
    risk_level: str
    issues: list[str]

extractor = Agent(
    model="openai:gpt-4",
    result_type=ExtractedClauses,
    system_prompt="Extract key clauses from the legal document."
)

summarizer = Agent(
    model="openai:gpt-4",
    result_type=Summary,
    system_prompt="Summarize the extracted legal clauses."
)

risk_analyzer = Agent(
    model="openai:gpt-4",
    result_type=RiskAssessment,
    system_prompt="Assess potential legal risks in the summary."
)

# Read the terms file from open ai copied into a txt file. http://openai.com/policies/row-terms-of-use/
with open('./openai-terms.txt', 'r') as file:
    text = file.read()
print(text[0:100])
clauses = extractor.run_sync(text)
summary = summarizer.run_sync(str(clauses.data.clauses))
risk = risk_analyzer.run_sync(summary.data.summary)

print(clauses.data)
print(summary.data)
print(risk.data)

Thank you for using OpenAI!

These Terms of Use apply to your use of ChatGPT, DALL·E, and OpenAI’s o
clauses=['These Terms of Use apply to your use of ChatGPT, DALL·E, and OpenAI’s other services for individuals, along with any associated software applications and websites (all together, “Services”).', 'These Terms form an agreement between you and OpenAI, L.L.C., a Delaware company, and they include our Service Terms\u2060 and important provisions for resolving disputes through arbitration.', 'By using our Services, you agree to these Terms.', 'Our Business Terms\u2060 govern use of ChatGPT Enterprise, our APIs, and our other services for businesses and developers.', 'Our Privacy Policy\u2060 explains how we collect and use personal information.', 'You must provide accurate and complete information to register for an account to use our Services.', 'You represent and warrant that you have all rights, licenses, and permissions needed to provide Input to our Services.', 'We may use Content to provide, maintain, develop, and improve our Services, comply with applicable law, enforce our terms and policies, and keep our Services safe.', 'We and our affiliates own all rights, title, and interest in and to the Services.', 'You can cancel\u2060(opens in a new window) your paid subscription at any time.', 'OUR SERVICES ARE PROVIDED “AS IS.”', 'NEITHER WE NOR ANY OF OUR AFFILIATES OR LICENSORS WILL BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES.', 'YOU AND OPENAI AGREE TO THE FOLLOWING MANDATORY ARBITRATION AND CLASS ACTION WAIVER PROVISIONS: MANDATORY ARBITRATION.', 'If you are a business or organization, to the extent permitted by law, you will indemnify and hold harmless us, our affiliates, and our personnel, from and against any costs, losses, liabilities, and expenses (including attorneys’ fees) from third party claims arising out of or relating to your use of the Services and Content or any violation of these Terms.', 'You may not assign or transfer any rights or obligations under these Terms and any attempt to do so will be void.', 'We are continuously working to develop and improve our Services.', 'We will give you at least 30 days advance notice of changes to these Terms that materially adversely impact you either via email or an in-product notification.', 'You must comply with all applicable trade laws, including sanctions and export control laws.', 'California law will govern these Terms except for its conflicts of laws principles.']
summary="The Terms of Use apply to the use of OpenAI's Services including ChatGPT and DALL·E. The terms, which form an agreement between the user and OpenAI, require accurate and complete registration information, and grant the company the right to use Content to maintain and improve their Services. OpenAI owns all rights to the services, but users can cancel their subscription at any time. The Services are provided 'as is', with no liability for consequential damages, and all disputes are to be resolved via mandatory arbitration. Businesses using the Services take the burden of indemnity and cannot transfer their obligations under the Terms. OpenAI will provide 30 days notice of significant changes to the Terms, and users must comply with all trade laws. The governing law is that of California."
risk_level='Low' issues=["Possible dissatisfaction from users due to 'as is' provision of the services", 'Potential disputes regarding the mandatory arbitration clause, particularly if users feel unheard or unfairly treated', 'Risk of non-compliance by users with trade laws, which could have legal repercussions for both the user and OpenAI', 'Potential disputes related to indemnity obligations of businesses using the Services', 'Risk of users not acknowledging significant changes to the Terms within the provided 30 day notice period', 'Potential legal conflicts with users based outside of California due to differing laws']

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)