You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Short version: open an issue, open a PR, challenge a design decision. All three are welcome.
4
+
5
+
## What's worth contributing
6
+
7
+
-**A new agent stage** (or a variant of an existing one). The pipeline is intentionally modular — if you think there should be a `Critic` or `Verifier` stage between Planner and Executor, prototype it and send the PR.
8
+
-**A new provider adapter.** OpenAI-compatible endpoints work out of the box; other SDKs (Anthropic native, Bedrock, etc.) are good fits.
9
+
-**A new recipe.** The `Recipes` section of the README is a living document. If you found a pattern that keeps recurring, document it.
10
+
-**Better tests on the stage contracts.** Every Pydantic schema in `backend/models/schemas.py` is a test surface.
11
+
-**Docs fixes.** Typos, broken links, confusing phrasing — just open the PR.
12
+
13
+
## How to PR
14
+
15
+
1. Fork, branch from `main`.
16
+
2. Keep the change small. One stage, one feature, one fix.
17
+
3. If you change a stage contract, update the schema and the stage it belongs to in the same PR.
18
+
4. Run the pipeline end-to-end with `python run.py` before sending — a smoke test counts.
19
+
5. Open the PR with a one-paragraph "why" and a before/after if the behavior changed.
20
+
21
+
## Disagreement is welcome
22
+
23
+
If you think a design decision in the cookbook is wrong, open an issue titled `design: <thing you disagree with>`. We'd rather be challenged than be wrong in public.
24
+
25
+
## Code style
26
+
27
+
- Python: `ruff` defaults, type hints on public functions, Pydantic models for any cross-stage data.
<ahref="https://www.linkedin.com/company/opengraph-tech/"><imgsrc="https://img.shields.io/badge/LinkedIn-OpenGraph.tech-0A66C2?style=flat-square&logo=linkedin&logoColor=white"alt="Follow OpenGraph.tech on LinkedIn" /></a>
26
+
</p>
27
+
28
+
<palign="center">
29
+
<ahref="https://github.com/OpenGraph-AI/OpenAgent"><imgsrc="https://img.shields.io/badge/%E2%AD%90%20Star%20on%20GitHub-324D17?style=for-the-badge&logo=github&logoColor=white"alt="Star on GitHub" /></a>
30
+
31
+
<ahref="#demo"><imgsrc="https://img.shields.io/badge/%E2%96%B6%20Watch%20the%2090%E2%80%91second%20demo-324D17?style=for-the-badge"alt="Watch the 90-second demo" /></a>
<sub>Not playing? <ahref="https://youtu.be/WMqK6OoWpa8">Watch on YouTube ↗</a></sub>
28
55
</p>
29
56
30
57
---
31
58
32
-
## Why OpenGraph
59
+
## The product in one image
33
60
34
-
Most "AI agent" code you'll read online is one fat prompt wrapped in a loop. It demos well and falls apart the moment a real user types something vague. We built the opposite: a pipeline where every stage of an agent's reasoning is a **first-class, typed, independently testable unit**.
61
+
<palign="center">
62
+
<imgsrc="public/stages.svg"alt="OpenAgent — the five stages with typed input and output contracts"width="100%" />
63
+
</p>
35
64
36
-
- 🧠 **Five specialist stages, not one monolith.** Intent → Ambiguity → Clarifier → Planner → Executor. Each with one job, each observable and swappable.
37
-
- 🕸️ **Auto-resolving clarifier.** The agent searches the web for what the web can answer, and only asks the user for what only the user knows. User attention is the most expensive resource — we spend it last.
38
-
- 🔌 **Model-agnostic by default.** Any OpenAI-compatible endpoint works — OpenAI, Azure, Groq, Together, vLLM, Ollama. No SDK lock-in.
39
-
- 🧯 **Graceful degradation.** Missing an API key for Exa, Upstash, or PageIndex? The pipeline downgrades, never crashes. Run locally with `LLM_API_KEY` alone.
40
-
- 🪢 **Typed contracts between every stage.** Pydantic at every boundary. A bad output gets caught at parse time, not six steps later.
41
-
- 🔴 **Streams natively, pauses like a coroutine.** WebSocket-first. Clarification pauses the pipeline mid-flight and resumes cleanly.
65
+
<palign="center"><sub>Each stage has a <strong>typed input</strong> and a <strong>typed output</strong>. The Pydantic schema between any two stages is your test surface — and your debug trail.</sub></p>
42
66
43
67
---
44
68
45
-
## Who this is for
69
+
## What makes this different
70
+
71
+
> ### *"Most agents fail in one of five places.*
72
+
> ### *OpenAgent is built for all five."*
73
+
74
+
<table>
75
+
<tr>
76
+
<tdwidth="33%"valign="top">
46
77
47
-
-**Engineers building their first real agent** who are tired of cargo-culting `while True: llm()` loops and want a mental model that actually scales.
48
-
-**Platform teams** evaluating LangGraph / CrewAI / AutoGen who want something smaller, typed end-to-end, and free of framework ideology.
49
-
-**Technical founders and researchers** shipping LLM products who need to *debug* and *trace* why an agent produced what it did — not just vibe-check it.
78
+
#### 🧠 Five specialists, not one monolith
50
79
51
-
If you've ever said "the agent is doing something weird and I have no idea what stage broke," this is for you.
80
+
`Intent ▸ Ambiguity ▸ Clarifier ▸ Planner ▸ Executor` — each testable in isolation. When something breaks, you know **exactly where**.
81
+
82
+
</td>
83
+
<tdwidth="33%"valign="top">
84
+
85
+
#### 🕸️ Asks humans last
86
+
87
+
Clarifier searches the web first, auto-fills what it can, and asks you only what it genuinely couldn't find.
Open `http://localhost:8000/static/index.html` and type a fuzzy request. Watch each phase stream into the UI in real time: intent extraction, ambiguity flags, clarifying questions, the plan, and finally the executor producing the answer step-by-step.
118
+
Open `http://<your-domain>:8000/static/index.html` and type a fuzzy request. Watch each phase stream into the UI in real time: intent extraction, ambiguity flags, clarifying questions, the plan, and finally the executor producing the answer step-by-step.
66
119
67
120
**Minimum config** — one variable:
68
121
@@ -87,7 +140,7 @@ docker compose up
87
140
## The mental model
88
141
89
142
<palign="center">
90
-
<imgsrc="public/mental-model.svg"alt="OpenGraph.tech five-stage agent pipeline: raw text → Intent → Ambiguity → Clarifier → Planner → Executor → final output"width="520" />
143
+
<imgsrc="public/mental-model.svg"alt="OpenAgent five-stage agent pipeline: raw text → Intent → Ambiguity → Clarifier → Planner → Executor → final output"width="520" />
91
144
</p>
92
145
93
146
Each stage is a specialist. The output of one is the typed input of the next. If any stage misbehaves, you can swap it, mock it, or inspect it without touching the others.
@@ -102,6 +155,20 @@ Read this like a cookbook. Every stage answers a question you'll eventually have
102
155
103
156
Five questions. Five agents. That's the whole book.
104
157
158
+
<divalign="center">
159
+
160
+
| # | Stage | In | Out | Mission |
161
+
|:-:|:------|:---|:----|:--------|
162
+
|**01**| 🧠 **Intent**|`str`|`IntentSchema`| Turn fuzz into a typed goal |
163
+
|**02**| ❓ **Ambiguity**|`IntentSchema`|`AmbiguityReport`| Flag the known unknowns |
164
+
|**03**| 🕸️ **Clarifier**|`AmbiguityReport`|`ClarifiedIntent`| Auto-resolve, ask only the rest |
165
+
|**04**| 🗺️ **Planner**|`ClarifiedIntent`|`ExecutionPlan`| A DAG of verifiable steps |
166
+
|**05**| ⚡ **Executor**|`ExecutionPlan`|`ExecutionResult`| Run, stream, trace to goal |
167
+
168
+
</div>
169
+
170
+
171
+
105
172
### 1. Intent — "What is the user actually asking?"
106
173
107
174
**The problem.** Humans don't type goals. They type fragments, moods, half-sentences. *"can you make this better"* is not a specification — it's a vibe. Executing on a vibe gives you a confident-sounding wrong answer.
@@ -302,22 +369,32 @@ Small patterns that keep recurring once you start building real agents.
| Framework weight |~1.5k LOC| Heavy| Heavy | Heavy |
378
+
| Framework weight |~4k LOC, readable| Heavy | Heavy | Heavy |
312
379
| "Pause for user" as first-class | ✅ | ⚠️ Via interrupts | ❌ | ⚠️ Via prompts |
313
-
| Reads like a cookbook | ✅ By design |❌ It's a library | ❌| ❌ |
380
+
| Reads like a cookbook | ✅ By design |⚠️ Reference docs, not narrative| ❌ | ❌ |
314
381
315
-
**When to pick OpenGraph.** You want to understand every moving part, control each prompt, and own your agent's reasoning end-to-end — not inherit someone else's abstraction.
382
+
**When to pick OpenAgent.** You want to understand every moving part, control each prompt, and own your agent's reasoning end-to-end — not inherit someone else's abstraction.
316
383
317
384
**When to pick a framework instead.** You want to ship fast without thinking about architecture, and the framework's defaults happen to match your domain.
318
385
319
386
---
320
387
388
+
## Who this is for
389
+
390
+
|||
391
+
|---|---|
392
+
| 🛠️ **First-agent builders**| Five `while True: llm()` prototypes in a drawer. None ship. **Start here.**|
393
+
| 🏗️ **Framework evaluators**| You've read the LangGraph docs twice and still don't trust the abstractions. This is ~4k lines. Read it in an afternoon. |
394
+
| 🧪 **Production debuggers**|*"It's doing something weird in prod."* OpenAgent tells you exactly which stage lied — with the transcript. |
395
+
396
+
---
397
+
321
398
## Where to start reading the code
322
399
323
400
If you're here to learn, open files in this order:
@@ -330,15 +407,52 @@ If you're here to learn, open files in this order:
330
407
331
408
---
332
409
410
+
## What's next
411
+
412
+
-[x] Typed contracts between all five stages
413
+
-[ ] Anthropic-native tool use (beyond OpenAI-compatible)
414
+
-[ ] Step-level retries with plan-edit capability
415
+
-[ ] First-class observability (OpenTelemetry spans per stage)
416
+
-[ ] Browser extension: capture user intent from any form
417
+
418
+
*Roadmap subject to change. Open an issue if one of these matters to you and we'll bump it.*
419
+
420
+
---
421
+
333
422
## Contributing
334
423
335
-
Issues, patches, and hard questions are all welcome. If you disagree with a design choice in the cookbook, open an issue — we'd rather get challenged than be wrong in public. Every stage is intentionally small enough that a PR can meaningfully change one thing at a time.
424
+
Issues, patches, and hard questions are all welcome. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the short version — fork, keep the change small, smoke-test with `python run.py`, and open the PR with a one-paragraph *why*. Every stage is intentionally small enough that a PR can meaningfully change one thing at a time.
336
425
337
426
---
338
427
339
428
## About OpenGraph.tech
340
429
341
430
OpenGraph.tech builds the infrastructure for agents that reason openly, not opaquely. This repo is our reference pipeline — the thing we run, the thing we ship against, and the thing we learn from. If you're building agents in production and want to compare notes, we'd like to hear from you.
342
431
432
+
Follow us on <ahref="https://www.linkedin.com/company/opengraph-tech/">LinkedIn</a> — that's where we post build notes and what shipped this week.
<img src="https://contrib.rocks/image?repo=OpenGraph-AI/OpenAgent" alt="Contributors to OpenAgent" />
439
+
</a>
440
+
</p>
441
+
442
+
## Leave a ⭐ if this saved you a week
443
+
444
+
This repo is free. The cookbook is free. The walkthrough is [on YouTube](https://youtu.be/WMqK6OoWpa8), free. The only thing we ask back is **a star** — it's the one signal that tells us to write more of these, louder.
<img src="https://img.shields.io/badge/%E2%AD%90%20Star%20on%20GitHub-OpenGraph--AI%2FOpenAgent-324D17?style=for-the-badge&logo=github&logoColor=white" alt="Star OpenAgent on GitHub" />
449
+
</a>
450
+
451
+
<ahref="https://youtu.be/WMqK6OoWpa8">
452
+
<img src="https://img.shields.io/badge/%E2%96%B6%20Watch%20the%20demo-YouTube-324D17?style=for-the-badge&logo=youtube&logoColor=white" alt="Watch the demo on YouTube" />
453
+
</a>
454
+
</p>
455
+
456
+
<palign="center"><sub>One click. No account prompt. It genuinely helps.</sub></p>
343
457
344
458
<palign="center"><sub>Made with intent, by <ahref="https://opengraph.tech">OpenGraph.tech</a>.</sub></p>
0 commit comments