I ran ArchSteer on OpenAI's Agents SDK. Here's what it found.

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:

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.

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:

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?