Agent Frameworks Compared — LangGraph, OpenAI Agents SDK and CrewAI

Build the same small agent three ways and compare control, state, tracing, lock-in and production readiness to choose a framework.

Est. 35 min Updated Suggest a fix
// Part 01 — The decision

Frameworks Organise the Loop; They Do Not Make It Safe

An agent framework provides structure around a model, tools and control flow. It may make it easier to express a workflow, keep state, route work or inspect a run. It cannot decide whether a refund is authorised, guarantee that a model follows instructions, or make an unsafe tool safe. Those responsibilities remain in your application and backend.

We will compare LangGraph, the OpenAI Agents SDK and CrewAI by implementing one bounded task: read a delivery status and explain it to a customer. The trusted order service supplies the status; the model must not invent it or choose a customer identity. This is intentionally small. A controlled workflow is a better comparison than a flashy multi-agent demo.

These are design tendencies, not a feature guarantee. Check each framework's current documentation before selecting it.
ChoiceUseful whenTrade-off to inspect
LangGraphYou need explicit state, graph control, branching and resumable workflow designMore concepts and graph code to own; persistence is a separate design concern
OpenAI Agents SDKYou want a focused agent, typed tools, handoffs and tracing in an OpenAI-centered stackProvider and SDK coupling; confirm your provider, deployment and data requirements
CrewAIYour problem maps naturally to role-oriented agents and assigned tasksRole/task abstractions can obscure control flow if the workflow is actually deterministic
Plain application codeA few predictable steps are enoughYou own the orchestration and observability conventions
🎯 Pro Tip
Start with a workflow diagram and failure cases, not a framework popularity poll. If a sequence of ordinary functions solves the problem, adding an agent framework creates another dependency without adding useful autonomy.
// Part 02 — Shared contract

Define the Work Before Comparing Implementations

All three implementations should receive the same trusted inputs and return the same output shape. The authenticated server supplies the customer ID. A narrow read-only function retrieves status. The model can explain the result but cannot change delivery data, issue a refund or access another customer's record.

support_contract.py
python
from dataclasses import dataclass

@dataclass(frozen=True)
class DeliveryFacts:
    order_id: str
    status: str
    eta: str | None

ORDERS = {
    "ORD-204": ("customer-7", DeliveryFacts("ORD-204", "in_transit", "2026-11-12")),
}

def lookup_delivery(order_id: str, authenticated_customer_id: str) -> DeliveryFacts | None:
    record = ORDERS.get(order_id.strip().upper())
    if record is None or record[0] != authenticated_customer_id:
        return None
    return record[1]

if __name__ == "__main__":
    print(lookup_delivery("ORD-204", "customer-7"))

This example runs with Python alone. In production, the order service should enforce tenant scoping in its query, not rely on a model-supplied identifier. Return the minimum facts needed for the task. Keep authentication, authorization and side effects outside model control.

⚠️ Important
Do not evaluate frameworks by letting each one use different prompts, tools or data. That tests the setup, not the framework. Hold the task contract constant, then compare how clearly you can implement the required control and recovery behavior.
// Part 03 — LangGraph

Make State Transitions Visible

A graph is useful when the next action depends on state: perhaps a lookup can fail, an approval can pause execution, or a retry must resume from a checkpoint. Nodes do work; edges express what happens next. The structure is explicit enough to inspect without asking the model to invent the process. Install the framework in an isolated environment and use the current official LangGraph documentation for the supported package API.

bash
python -m venv .venv
source .venv/bin/activate
pip install langgraph

The following is a minimal, runnable graph example using the stable StateGraph pattern. It deliberately keeps the response deterministic so that the example teaches orchestration rather than depending on a particular model provider.

graph_delivery.py
python
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END

class State(TypedDict):
    order_id: str
    customer_id: str
    status: str
    answer: str

def load_status(state: State) -> dict:
    known = {"ORD-204": ("customer-7", "in_transit")}
    record = known.get(state["order_id"])
    if record is None or record[0] != state["customer_id"]:
        return {"status": "not_found"}
    return {"status": record[1]}

def explain(state: State) -> dict:
    if state["status"] == "not_found":
        return {"answer": "I could not find an order available to this account."}
    return {"answer": f"Your order is currently {state['status']}."}

graph = StateGraph(State)
graph.add_node("load_status", load_status)
graph.add_node("explain", explain)
graph.add_edge(START, "load_status")
graph.add_edge("load_status", "explain")
graph.add_edge("explain", END)
app = graph.compile()

if __name__ == "__main__":
    result = app.invoke({
        "order_id": "ORD-204", "customer_id": "customer-7",
        "status": "", "answer": "",
    })
    print(result["answer"])

A real model node can turn verified facts into natural language, but it should receive only the scoped result. Add a conditional edge for cases that need escalation or a human decision. Add a checkpointer only after you decide which state is safe to persist, how long to retain it and how to resume idempotently.

// Part 04 — OpenAI Agents SDK

Use Agent and Tool Abstractions Deliberately

The OpenAI Agents SDK offers an agent-and-tool programming model, handoffs and tracing for supported workflows. Its fit is strongest when those abstractions match your stack and the provider constraints are acceptable. Keep the tool itself safe even if the model makes an unexpected call. Tool argument validation and authorization are application responsibilities.

bash
pip install openai-agents

This small example uses the SDK's familiar Agent, function_tool and Runner pattern. Configure the model through the environment; select a model your account and current SDK support. Never place a provider key in browser code.

sdk_delivery.py
python
import asyncio
import os
from agents import Agent, Runner, function_tool

@function_tool
def delivery_status(order_id: str) -> str:
    """Return a demo status for a previously authorised order."""
    allowed = {"ORD-204": "in_transit; expected date 2026-11-12"}
    return allowed.get(order_id, "not_found")

async def main() -> None:
    model_name = os.environ.get("LLM_MODEL")
    if not model_name:
        raise RuntimeError("Set LLM_MODEL to a model supported by your account")
    agent = Agent(
        name="Delivery helper",
        instructions=(
            "Use delivery_status to check the supplied order. Explain only the returned facts. "
            "Never claim to change an order or issue a refund."
        ),
        tools=[delivery_status],
        model=model_name,
    )
    result = await Runner.run(agent, "Check order ORD-204 and explain its status.")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

This tool is intentionally read-only and demo-scoped. In a web service, bind an authenticated principal to tool execution in trusted server context. Do not accept the customer identity from the prompt. Confirm tracing data retention and redact sensitive inputs before enabling production traces.

// Part 05 — CrewAI

Map Roles and Tasks to Actual Responsibilities

CrewAI expresses work using agents, tasks and a crew. Role language can be useful for a process with genuinely distinct responsibilities, such as a researcher gathering evidence followed by a reviewer checking a draft. It is not a reason to create several model calls for a simple status lookup. More agents mean additional latency, cost and failure surfaces.

The same delivery task could be represented as one agent assigned one task. The precise configuration options evolve; follow the current CrewAI documentation for model configuration and supported kickoff behavior. The design invariant is more important than a particular constructor flag: the task must use verified data and the tools must remain narrowly scoped.

bash
pip install crewai
crewai_delivery.py
python
import os
from crewai import Agent, Crew, Process, Task
from crewai.tools import tool

@tool("Read delivery status")
def delivery_status(order_id: str) -> str:
    """Return a demo status for a previously authorised order."""
    return {"ORD-204": "in_transit; expected date from verified order data"}.get(
        order_id, "not_found"
    )

model_name = os.environ.get("LLM_MODEL")
if not model_name:
    raise RuntimeError("Set LLM_MODEL to a supported model configuration")

helper = Agent(
    role="Delivery support helper",
    goal="Explain a verified delivery status without changing an order",
    backstory="You are a careful assistant that uses only provided order facts.",
    tools=[delivery_status],
    llm=model_name,
    verbose=False,
)
explain_status = Task(
    description=(
        "Check order ORD-204 with the read-only tool. Explain only its returned "
        "status. Do not promise a change, refund, or fact the tool did not return."
    ),
    expected_output="A short explanation grounded in the delivery lookup result.",
    agent=helper,
)
crew = Crew(agents=[helper], tasks=[explain_status], process=Process.sequential)
print(crew.kickoff())
💡 Note
CrewAI APIs and model configuration evolve. Verify the current official documentation for your selected release, especially how it configures providers and credentials. This one-agent example keeps the tool read-only; it does not make the model authoritative.
// Part 06 — Compare

Choose on Operational Fit, Not Demo Convenience

A useful proof of concept answers more than "can it call a tool?" Ask how you will validate state, resume after a process restart, identify a failed node, control external calls, and upgrade the dependency. Run a small acceptance suite against each candidate with the same task and test fixtures.

Use this as a review checklist, not a universal ranking. Validate current features and constraints in primary documentation.
QuestionLangGraphOpenAI Agents SDKCrewAI
Can I see and test the control flow?Graph nodes and edges are explicitAgent/tool/handoff structure is SDK-definedRoles and tasks are the primary abstractions
How will state survive a restart?Design a checkpointer and persistence policyConfirm the workflow and persistence facilities you needChoose and validate persistence for the crew workflow
How tightly coupled is the app?Framework-specific graph modelOpenAI ecosystem APIs and conceptsCrewAI roles/tasks and execution APIs
When can it be overkill?A simple linear function sequenceA single provider call with no toolsOne bounded task represented as a multi-agent crew
What must still be yours?Authorization, tests, budgets, deploymentAuthorization, tests, budgets, deploymentAuthorization, tests, budgets, deployment
  1. Write down the user outcome, trusted inputs, permitted tools and prohibited side effects.
  2. Build the simplest deterministic baseline before introducing a model or framework.
  3. Implement one equivalent proof of concept per plausible framework and record setup effort.
  4. Test normal, missing-data, timeout, malformed-tool-input and restart scenarios.
  5. Compare traces, deployment complexity, data handling, dependency health and team familiarity.
// Part 07 — Production choice

Keep a Framework Boundary You Can Change

Keep framework types inside an adapter layer. Your domain code should accept ordinary typed inputs and return ordinary typed outputs. Then a framework upgrade—or a decision to remove the framework—does not require changing your business rules and customer authorization logic at the same time.

agent_port.py
python
from dataclasses import dataclass

@dataclass(frozen=True)
class DeliveryRequest:
    order_id: str
    customer_id: str

@dataclass(frozen=True)
class DeliveryReply:
    text: str
    status: str

def run_delivery(request: DeliveryRequest, graph_runner) -> DeliveryReply:
    state = graph_runner({
        "order_id": request.order_id,
        "customer_id": request.customer_id,
        "status": "",
        "answer": "",
    })
    return DeliveryReply(text=state["answer"], status=state["status"])

# The HTTP route authenticates the user, builds DeliveryRequest, then calls this port.
# The agent never decides which customer_id is authorised.

Also version prompts, tool schemas and state records. When changing a framework, compare old and new behavior with regression cases rather than assuming equivalent prompts produce equivalent trajectories. Preserve a deterministic fallback for important user journeys where it is feasible.

🎯 Pro Tip
For an Indian delivery-support experience, a status lookup followed by a clear next step may outperform a conversational agent. Use autonomy only where it measurably improves completion, not just because an agent can be built.
// Part 08 — Pitfalls

Common Framework Selection Mistakes

Choosing the framework with the flashiest demo

Why: A demo often omits deployment, permissions, state retention and failure handling.

Fix: Run the same acceptance tests and operational review against every candidate.

Using multiple agents for one predictable task

Why: Extra model turns can add cost, delay and disagreement without improving the outcome.

Fix: Start with one agent or a deterministic workflow; add roles only for clear separation of work.

Assuming framework tools enforce authorization

Why: A schema constrains argument shape, not whether the caller may access a record.

Fix: Enforce identity and access in trusted service code for every invocation.

Persisting all agent state by default

Why: State can include personal data, untrusted text, stale facts or secrets.

Fix: Define a minimal state schema, access controls, retention and deletion before enabling persistence.

// Part 09 — Practice

Run a Small Framework Bake-Off

Practice

Compare frameworks using one delivery-support contract

  1. Write a deterministic lookup baseline with customer scoping and a missing-order case.
  2. Implement that state transition in LangGraph; add a branch for not-found without asking a model to choose access policy.
  3. Create a one-agent, one-tool OpenAI Agents SDK proof of concept using a model name from LLM_MODEL.
  4. Document how the same job would map to one CrewAI agent and task; verify exact APIs using current official docs.
  5. Run identical tests for authorised lookup, another customer, malformed ID, model refusal and tool timeout.
  6. Write a short decision note naming the operational trade-off that matters most for your team.

Hint: Use fake data and credentials. Do not wire a write-capable production tool into a comparison demo.

🎯 Key Takeaways

  • ✓A framework organises control flow; it does not supply authorization, safety or correctness automatically.
  • ✓LangGraph makes state transitions and conditional routing explicit, while introducing graph concepts to own.
  • ✓The OpenAI Agents SDK packages agents, tools, handoffs and tracing for supported OpenAI-oriented workflows.
  • ✓CrewAI role and task abstractions help when responsibilities are distinct; they are unnecessary for every short task.
  • ✓Compare equivalent implementations with the same fixtures, prompts, tools and failure tests.
  • ✓Keep business contracts and permission checks independent of framework-specific state and types.

Next

What comes next

You have compared orchestration choices. Next, learn how browser and desktop agents interact with visual interfaces, and when a direct Playwright workflow is a better tool.

Lesson 09 · Browser and Computer-Use Agents →

HELP US IMPROVE

How was this lesson?

Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.

Choose your feedback

Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.

Share

Discussion

0

Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.

Continue with GitHub
Loading...