I wanted to test ArchSteer on a codebase that was both substantial and directly
connected to agentic software development. OpenAI's
Agents SDK for Python was an
obvious choice: it is active, open source, and had roughly 27,000 GitHub stars
when I ran this analysis.
The question was simple: can a zero-config architecture pass tell us
something useful about a repository this large?
It can. It also gets some things wrong. Both parts are worth looking at.
Credit: The architecture model, component inventory, dependency counts,
and report in this article were produced by the ArchSteer 0.10.0
distribution. I reviewed
and interpreted the output; ArchSteer did the repository analysis.
What I ran
I analyzed commit
974733e
on July 30, 2026.
git clone --depth 1 https://github.com/openai/openai-agents-python.git
cd openai-agents-python
pipx install archsteer
archsteer xray
That last command is read-only. It statically reads the repository and writes
the results under .archsteer/. It does not run the SDK, call a model, or
upload the code.
The first pass found:
| Repository-wide result | ArchSteer output |
|---|---|
| Components mapped | 844 |
| External call sites | 431 |
| Automatically inferred layers | 2 |
| Architecture baseline | Created |
The report above is the direct ArchSteer output. The odd suffix in the title
comes from the temporary directory used for the analysis.
The runtime package tells the more useful story
The 844-component total includes tests, examples, documentation scripts, and
repository tooling. I narrowed the generated model to src/agents/, which is
the shipped runtime package.
| Runtime package signal | Observed value |
|---|---|
| Python components | 295 |
| Lines mapped | 103,197 |
| Import edges | 3,370 |
| External call sites | 149 |
Those numbers are not a grade. They are a map of where to look.
The most useful finding was the way architectural context gathers around a
small set of orchestration files.
openai_realtime.py led the list with 62 import edges, followed by the internal
run loop with 56. agent.py, tool execution, and run state were close behind.
None of that means these files are poorly designed. It means a change there
needs more context than a change to a small adapter. They sit where model
providers, tools, state, tracing, guardrails, streaming, and handoffs meet.
That is useful for a human reviewer. It is even more useful for a coding agent.
If an agent touches the run loop, ArchSteer can tell it which boundaries and
decisions matter before it starts copying a nearby pattern.
The new graph makes a component's neighborhood concrete
ArchSteer 0.10.0 adds a graph command. Instead of reading the entire model,
you can ask one focused question:
archsteer graph src/agents/agent.py
For agent.py, ArchSteer reported 29 direct local dependencies and 55 direct
dependents. The second number includes runtime code, tests, and examples because
the X-ray covers the repository as a whole.
This view is more actionable than a generic complexity score. The left side
shows what agent.py needs in order to work. The right side shows the blast
radius of changing it. Before an agent edits this file, that two-way
neighborhood is the context I would want it to see.
The graph count is deliberately different from the earlier import-edge chart.
The chart counts all parsed import edges, including external imports. The
graph command resolves direct repository components and shows both dependency
directions.
State and tool execution are the governance seams
The largest runtime files reinforced the same point:
-
run_state.py— 3,820 mapped lines -
tool.py— 2,735 -
run_internal/tool_execution.py— 2,554 -
run_internal/turn_resolution.py— 2,500
Agent frameworks are often described in terms of prompts and handoffs. The
engineering weight is elsewhere: durable state, tool-call ownership,
interruption and resumption, provider translation, error behavior, and
tracing.
Those are exactly the places where a plausible patch can pass a narrow test and
still bend the architecture. A tool result may be persisted in the wrong place.
A provider-specific type may leak into core state. A new execution path may
skip an established guardrail.
ArchSteer gives a team a way to turn those expectations into explicit rules.
For this kind of SDK, maintainers might choose rules such as:
- core run state cannot depend on a concrete model provider;
- provider adapters can depend on core interfaces, but not the reverse;
- tool execution must pass through the approved tracing and guardrail paths;
- session backends stay behind the session abstraction; and
- sandbox-provider integrations do not leak into the core run loop.
Those examples are my interpretation, not rules declared by the OpenAI
maintainers. The important point is that ArchSteer can check whatever intent a
team actually chooses.
The first map was useful—and clearly incomplete
Here is the honest limitation from this run: ArchSteer inferred only model and
util as layers. Within src/agents/, 266 of 295 components remained
unassigned.
The SDK plainly has a richer shape than that. It contains core agent
abstractions, orchestration, tools, handoffs, guardrails, providers, sessions,
tracing, realtime behavior, MCP integrations, sandboxes, and extensions.
So I would not present the two-layer diagram as “the architecture of the OpenAI
Agents SDK.” It is a first hypothesis derived from names and code structure.
That is still helpful. Starting from an imperfect map is much faster than
starting from a blank page. A maintainer can name the real boundaries once,
store that intent with the repository, and let ArchSteer keep comparing the
code against it.
The data-store detection also produced noise. The repository-wide report showed
60 store-like signals, but that list mixed genuine persistence concepts with
SQL tokens, variable names, and example code. It does not mean the SDK uses
60 databases.
I like that the file-level evidence is visible. A false positive can be
inspected and corrected instead of disappearing behind a confident score.
Why this matters now
Coding agents are excellent at local consistency. They read the files around an
edit and imitate what they see.
That becomes a problem when a repository contains two competing patterns. A
half-finished migration often has more examples of the old approach than the
new one. An architecture diagram in a slide deck will not help the agent if it
never enters the working context.
The dangerous result is not obviously broken code. It is code that compiles,
passes tests, and makes the intended architecture a little less true.
ArchSteer addresses that with a control loop rather than a one-time diagram:
The “check” step uses a ratchet. A team can baseline known violations and block
only net-new drift. Existing debt stays visible, but it does not force a
big-bang cleanup before the tool becomes useful.
That is the part of ArchSteer I find most relevant to agentic development. The
same model serves four moments:
| Moment | What ArchSteer contributes |
|---|---|
| Before the edit | Shows components, dependencies, hotspots, and external calls |
| While the agent works | Supplies file-scoped architectural guidance |
| During review and CI | Detects net-new boundary violations |
| After the change | Records evolution and drafts decisions worth preserving |
What this run proves—and what it does not
One static X-ray cannot tell us whether the SDK is secure, reliable, or “well
architected.” Python is dynamic. Configuration, dependency injection, generated
code, and runtime behavior can hide edges from any static tool.
I also did not apply maintainer-authored intent, so there is no meaningful
conformance score here.
What the run did prove is more practical: ArchSteer turned a large, active
repository into an inspectable architecture dataset with one command. It
identified the files where architectural context concentrates, created a
baseline for future changes, and made the gaps in automatic inference obvious.
That is a credible starting point for architecture work in an agent-heavy
development process.
Try the same X-ray
ArchSteer is local-first, open source, and MIT licensed:
pipx install archsteer
cd your-repository
archsteer xray
open .archsteer/report.html
The best first question is not “did I get a perfect diagram?” It is:
What did ArchSteer show me that I would want a coding agent to know before its
next edit?
Run the same local X-ray: Get started with ArchSteer · Original case study
Top comments (0)