Choose and compare agent frameworks

What you will learn

A framework can manage execution, state, tool interfaces, and observability. It does not decide whether a task needs an agent or whether a proposed action is authorized. Complete the guarded tool registry and durable-state labs first; this lesson translates those contracts into framework concepts.

Compare the abstraction, then the package

These are starting points, not exclusive capabilities or a ranking. Review the selected version's API, persistence behavior, model support, and deployment constraints before adopting it. Package choice does not replace the runtime authorization contract.

Guided workshop: express the same flow two ways

Use the fixed search → draft → review workflow from the task-graph lab. The plain-Python baseline already exists. Here is a deterministic LangGraph translation using a typed state, with no model or API key required:

Copy codefrom typing import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    question: str
    evidence: list[str]
    draft: str

def search(state: State):
    evidence = ["Reset passwords in Settings."] if "reset" in state["question"] else []
    return {"evidence": evidence}

def draft(state: State):
    return {"draft": state["evidence"][0] if state["evidence"] else "Needs review"}

builder = StateGraph(State)
builder.add_node("search", search)
builder.add_node("draft", draft)
builder.add_edge(START, "search")
builder.add_edge("search", "draft")
builder.add_edge("draft", END)
app = builder.compile()
result = app.invoke({"question": "reset password", "evidence": [], "draft": ""})
assert result["draft"] == "Reset passwords in Settings."

In a separate virtual environment, install the checked version with python -m pip install "langgraph==1.2.12", record the resolved environment with python -m pip freeze, and run the file. This example has no persistent checkpointer: the presence of a graph does not make it durable. Add persistence and an explicit review interruption only after comparing the deterministic behavior to your baseline.

For a model-selected tool loop with the OpenAI Agents SDK, the corresponding interface is an Agent with a function tool executed by a Runner. This optional example makes paid model calls when run; supply credentials through the environment and choose a model available to your account.

Copy codeimport os
from agents import Agent, Runner, function_tool

@function_tool
def search_docs(query: str) -> str:
    """Search synthetic public help content."""
    return "Reset passwords in Settings." if "reset" in query.casefold() else "No evidence"

agent = Agent(
    name="Support drafting exercise",
    model=os.environ["ACADEMY_MODEL"],
    instructions="Use search_docs. Draft from its evidence or say evidence is missing. Do not send messages.",
    tools=[search_docs],
)
result = Runner.run_sync(agent, "How do I reset my password?", max_turns=3)
print(result.final_output)

Install the checked version with python -m pip install "openai-agents==0.22.3" in its own environment, record the installed version, and configure tracing and data handling before using anything beyond public fixtures. Catch and classify budget exhaustion and provider errors in your application's boundary. A final output is still subject to your grounding and schema checks.

Exercise and review

Run the same fixtures through the plain implementation and one framework implementation. Test missing evidence, invalid input, tool failure, maximum turns, and a resumed task. Compare normalized results rather than framework-specific trace formatting. Then implement a second architecture with the same total budget, using ADK's workflow composition, a CrewAI flow, PydanticAI typed dependencies, or a Koog workflow according to your team's language and operational needs.

Expected artifact: a contract test suite, dependency lock, versioned setup command, trace examples, and a decision record describing what the framework removed and what it added. At least one failure must be reproduced after restarting the process if you claim durable execution.

Quiz: does a framework's human-in-the-loop API establish that the approver has access to the target ticket? No; your application still verifies identity, resource permission, proposal version, and expiry. Does replacing a framework fix a poor evaluation dataset? No; the same biased cases can mislead every implementation.

Primary references

Use these as API references after the course exercises: OpenAI Agents SDK, ADK workflows, LangGraph graph API, CrewAI, PydanticAI, and Koog. Framework-dependent examples are distinct from the course's dependency-free verification suite.