I mapped OpenAI's Agents SDK: 844 components and one architecture lesson

ArchSteer — Thu, 30 Jul 2026 20:16:32 +0000

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

The Architecture X-Ray Challenge: Find One Surprise in Your Codebase

ArchSteer — Thu, 23 Jul 2026 15:34:21 +0000

Most teams have an architecture diagram. Fewer have a diagram they trust.

The codebase is the only completely current record of the system, but reading
it file by file is a poor way to see boundaries, dependency direction, data
access, and how the shape has changed over time.

So this week I am running a deliberately simple experiment:

Run an architecture X-ray on one repository and find one thing you did not
know.

The challenge

You need Python 3.10 or newer:

pipx install archsteer
cd your-repo
archsteer xray

Open .archsteer/report.html, then look for one surprise:

a dependency crossing a boundary you thought was clean;
a module that owns much more of the system than its name suggests;
data access in an unexpected layer;
an external call site nobody remembered;
a legacy architecture still living inside the current one; or
a structural change that should have produced an ADR.

Share the finding, open an issue if the model is wrong, or keep the result
private. All three outcomes are useful.

What it does and does not do

ArchSteer statically reads the repository and emits a code-derived model,
living architecture documentation, diagrams, an evolution feed, and draft ADRs
for boundary-altering changes. It runs locally, does not execute the target
code, does not upload the repository, and requires no account.

The model is heuristic. It is supposed to be an always-current starting point
that an architect can curate, not a formal proof that the system behaves a
certain way. A confidently wrong boundary is exactly the kind of result I want
reported.

Current language support covers Python, TypeScript/JavaScript, Java Spring, and
Salesforce Apex.

Why this matters more with coding agents

Coding agents learn the local pattern from the files around an edit. In a
half-migrated codebase, legacy examples outnumber target examples, so an agent
can produce perfectly plausible code that pushes the architecture backward.

An accurate current model makes a control loop possible:

derive the architecture the code actually implements;
declare one target invariant;
put the relevant invariant into the coding agent's file-scoped context;
check the resulting code; and
block only net-new violations, so delivery continues while debt ratchets down.

The challenge starts with step one because it should provide value before a
team writes any rules.

Participate

Run:

pipx install archsteer && archsteer xray

Then share one surprising finding and link to
ArchSteer on GitHub, or file the
most specific example you can where the model got your architecture wrong.
ArchSteer is free and MIT licensed.

Originally published at archsteer.com. I build ArchSteer and welcome blunt feedback on the model.

DEV Community: ArchSteer