How to choose a framework
You have already hand-written an Agent and know what each step in the loop does. This section looks at what the mainstream frameworks each do for you, which scenarios they suit, and rewrites the Chapter 2 example using one of them.
Anthropic's advice in "Building effective agents" is worth remembering first: Start by calling the large model's API directly—many patterns can be implemented in a few lines of code; if you use a framework, understand what it does under the hood.
A table
| What it is | Language | Can it use domestic / local models | Best for | |
|---|---|---|---|---|
| Hand-written (this lesson) | A while loop | Any | Yes, any OpenAI-compatible API | Learning the principles; simple needs, full control |
| OpenAI Agents SDK | A lightweight Agent framework: Agent, tools, handoffs, guardrails, sessions, tracing | Python (0.25.0) | Yes, the official docs give instructions for connecting other providers; we tested it working with local Ollama | You want ready-made multi-Agent collaboration and guardrails without being locked to one model provider |
| Claude Agent SDK | Uses Claude Code as a library: the same tools, loop, context management | Python, TypeScript | The official docs only mention using Claude via platforms like Bedrock, Google Cloud, and Microsoft Foundry; they do not state that other vendors' models can be connected | You need a powerful coding Agent that can read and write files and run commands |
| LangGraph | A low-level orchestration framework: defines workflows as a graph of "state + nodes + edges" | Python | Yes | Complex workflows that run long, need persistence, human intervention, and explicit control of every step |
| Dify | An open-source AI application building platform with visual orchestration | No coding needed | Yes | Non-programmers building internal tools; when private deployment is needed |
| Coze | ByteDance's platform; the open-source version is called Coze Studio | No coding needed | — | Visual building |
A few details that need clarifying:
- Can Claude Agent SDK use domestic models? This is a common question in searches. The official docs we found only mention authenticating with Anthropic's API Key, or using Claude through cloud platforms such as Amazon Bedrock, Google Cloud, and Microsoft Foundry; they do not mention connecting other vendors' models.
- Dify's license is not standard Apache 2.0, but a "modified Apache 2.0": you may not use its source code to run a multi-tenant service without authorization, and you may not remove the frontend logo and copyright information. Latest version 1.20.0 (2026-11-18).
- Coze: coze.cn now positions itself as an "AI office assistant"; the open-source Coze Studio uses Apache 2.0, but its most recent release is v0.5.1 on 2026-2-5.
Rewriting Chapter 2 with OpenAI Agents SDK
pip install openai-agents, then (download step_sdk.py):
import os
from agents import Agent, Runner, AsyncOpenAI, OpenAIChatCompletionsModel, set_tracing_disabled
from agents.decorators import tool
set_tracing_disabled(disabled=True) # 没有 OpenAI 平台的 key 时要关掉 tracing
client = AsyncOpenAI(base_url=os.environ.get("AGENT_BASE_URL", "http://localhost:11434/v1"),
api_key=os.environ.get("AGENT_API_KEY", "ollama"))
model = OpenAIChatCompletionsModel(model=os.environ.get("AGENT_MODEL", "qwen3:8b"), openai_client=client)
@tool
def add(a: float, b: float) -> float:
"""计算两个数的和"""
return a + b
@tool
def multiply(a: float, b: float) -> float:
"""计算两个数的积"""
return a * b
agent = Agent(name="计算助手", instructions="用工具做计算,最后用中文回答。", tools=[add, multiply], model=model)
result = Runner.run_sync(agent, "一箱苹果 24 个,我买了 17 箱,又多拿了 9 个。一共多少个?请用工具计算。")
print(result.final_output)You should see (local qwen3:8b):
A total of 417 apples were bought. The calculation is as follows:
1. 17 boxes of apples: 17 × 24 = 408
2. Adding the 9 extra taken: 408 + 9 = 417Compared with Chapter 2: the JSON Schema for tools no longer needs to be hand-written (it is generated from type annotations and docstrings), and the loop, tool_call_id matching, and message assembly are all handled by Runner.
Three key points when connecting non-OpenAI models (from the official docs):
- Use
OpenAIChatCompletionsModel: the SDK defaults to OpenAI's new Responses API, which many other providers do not support, causing a 404. - If you don't have an OpenAI platform key,
set_tracing_disabled(True), otherwise trace uploads will fail with 401. @toolis shorthand for@function_toolin the new version; the@function_toolwritten in older tutorials online still works.
How to choose
Look it upMy situation is…
Click one to see.
Quiz timeWhen connecting the OpenAI Agents SDK to local Ollama, why use OpenAIChatCompletionsModel?
Check yourself
- I can name the scenarios each of the five options suits
- I got the example connecting a local model working with OpenAI Agents SDK
- I know the caveats for Claude Agent SDK and Dify
Next section: Safety: permissions, sandboxes, and prompt injection.