Skip to content

visualize the complete Agent Loop with an interactive UML #713

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

EnggQasim
Copy link
Contributor

🤔 Why we need this

The “Agent Loop” is the SDK’s most complex subsystem:

  1. It spans ~2 000 lines across run.py, guardrails, hand-offs, and streaming helpers.
  2. Contributors often ask “Where do guardrails fire?” or “How does the Runner decide between tool-calls and hand-offs?”

A single picture out-ranks a thousand words; the diagram turns that spaghetti into a map:

Runner ──▶ Agent ──▶ Model ──▷ Response
  ▲           │           │
  │           ▼           ▼
Guardrails ◀──┘     Tool-Calls / Handoffs

#### 🤔 Why we need this

The “Agent Loop” is the SDK’s most complex subsystem:

1. It spans \~2 000 lines across `run.py`, guardrails, hand-offs, and streaming helpers.
2. Contributors often ask *“Where do guardrails fire?”* or *“How does the Runner decide between tool-calls and hand-offs?”*

A single picture out-ranks a thousand words; the diagram turns that spaghetti into a map:

```
Runner ──▶ Agent ──▶ Model ──▷ Response
  ▲           │           │
  │           ▼           ▼
Guardrails ◀──┘     Tool-Calls / Handoffs
```
Copy link

This PR is stale because it has been open for 10 days with no activity.

@github-actions github-actions bot added the stale label May 29, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant