AGAgent · Architecture
Community homeHot discussions Latest posts Best of Knowledge base Resources About

Agent · Architecture · Building an internal platform with agent-design from scratch: architecture and decision log

92
AGr/agent-design·posted by ops_wang·just nowOpen source

Building an internal platform with agent-design from scratch: architecture and decision log

Short version: agent-design needs almost no tuning at small and medium scale — the point where it starts to hurt is much further out than most people assume. Full measurements below.

What genuinely surprised me was the tail. The average looked great while P99 jumped by an order of magnitude past some threshold. The cause was not agent-design itself but our upstream connection reuse — the load test traffic was too clean and hid the long-tail requests.

Image placeholder · object storage in production
POST /api/uploads → CDN origin pull
31 comments

31 comments

M
Llinlin·28 minutes agoedited

Worth learning from this debugging approach. We went straight at the logs and took a much longer route.

460
KkiteOPMod·2 hours ago

I see point 3 differently. The trade-off depends on your read/write ratio: read-heavy with little writing means caching actually widens the inconsistency window.

381
Nnikic·just now

One counter-example: below agent-design 7.4 the semantics of that code are different, so do not copy it verbatim. We got burned in staging and rolled back once.

40
Sslow_query·3 minutes ago

There is actually a simpler fix that needs no architecture change: move this check up to the gateway and the problem disappears. The cost is one extra lookup at the gateway.

313
Cchen_dev·28 minutes ago

Saved. I am reworking this area this week — this saves a lot of wrong turns.

311
Rrase·yesterday

I see point 3 differently. The trade-off depends on your read/write ratio: read-heavy with little writing means caching actually widens the inconsistency window.

67
Ddev_zhou·3 minutes ago

This matches what we see in production. We only hit it past 3k QPS; the earlier load tests showed nothing — the test traffic was too clean, with no long-tail requests.

4
Llinlin·just now

Can you give a minimal reproduction? I ran it locally for ten minutes and could not reproduce on macOS with the latest version.

1
Kkite·2 hours ago

There is actually a simpler fix that needs no architecture change: move this check up to the gateway and the problem disappears. The cost is one extra lookup at the gateway.

43
Rran_bo·just now

Sharing our numbers, 8 cores 16GB, same scenario:

| Concurrency | P50 | P99 |
|---|---|---|
| 200 | 12ms | 88ms |
| 500 | 31ms | 340ms |

P99 clearly collapses at 500 concurrency, which lines up with your knee point.

20
Oops_wangOP·2 days ago

I just read the agent-design source — the author actually explains the reasoning in a comment, roughly "so that it degrades into predictable behaviour in extreme cases".

393
Bbob_chen·28 minutes ago

One counter-example: below agent-design 7.4 the semantics of that code are different, so do not copy it verbatim. We got burned in staging and rolled back once.

1
Bbob_chenOPMod·2 days agoedited

Agreeing with the above. One addition: with this option enabled the GC count in your metrics doubles, so adjust the alert threshold at the same time or it will keep firing.

8
Kkernel_panicOP·3 minutes ago

This is not a agent-design problem, it is a usage problem. The docs say this API is not thread-safe and you must lock around it yourself.

5
Ttang_hao·2 days ago

Has anyone run a controlled experiment? I did, reducing it to a single variable, and the difference was 4% — within noise. So I suspect the main cause is something else.

12
Rrase·12 minutes ago

This matches what we see in production. We only hit it past 3k QPS; the earlier load tests showed nothing — the test traffic was too clean, with no long-tail requests.

10
Aalice_dev·12 minutes ago

A question: what changes in a container with a 512Mi memory limit? That is how we run it in production.

290
Bbob_chen·28 minutes ago

We have run this in production for two years without hitting it. That said, we never reached this scale, so our experience is not really evidence here.

396
Wwinter·5 hours ago

Agreeing with the above. One addition: with this option enabled the GC count in your metrics doubles, so adjust the alert threshold at the same time or it will keep firing.

205
Sslow_query·yesterday

A question: what changes in a container with a 512Mi memory limit? That is how we run it in production.

183
Hhuang_ke·1 hour ago

Saved. I am reworking this area this week — this saves a lot of wrong turns.

128
Bbob_chen·28 minutes ago

Thanks for sharing real numbers — far more useful than the articles that only cover concepts.

126
WwinterMod·28 minutes ago

Worth learning from this debugging approach. We went straight at the logs and took a much longer route.

105
Nnikic·12 minutes ago

We have run this in production for two years without hitting it. That said, we never reached this scale, so our experience is not really evidence here.

192
Nnikic·12 minutes ago

This matches what we see in production. We only hit it past 3k QPS; the earlier load tests showed nothing — the test traffic was too clean, with no long-tail requests.

4
Ddev_zhou·2 days ago

Has anyone run a controlled experiment? I did, reducing it to a single variable, and the difference was 4% — within noise. So I suspect the main cause is something else.

152
Mmike_xu·2 days agoedited

I see point 3 differently. The trade-off depends on your read/write ratio: read-heavy with little writing means caching actually widens the inconsistency window.

92
Cchen_dev·yesterday

This is not a agent-design problem, it is a usage problem. The docs say this API is not thread-safe and you must lock around it yourself.

50
Sslow_query·28 minutes ago

Thanks for sharing real numbers — far more useful than the articles that only cover concepts.

34
Aalice_dev·2 days ago

I just read the agent-design source — the author actually explains the reasoning in a comment, roughly "so that it degrades into predictable behaviour in extreme cases".

14
Hhuang_ke·yesterday

Sharing our numbers, 8 cores 16GB, same scenario:

| Concurrency | P50 | P99 |
|---|---|---|
| 200 | 12ms | 88ms |
| 500 | 31ms | 340ms |

P99 clearly collapses at 500 concurrency, which lines up with your knee point.

1

This is the post detail page /en/c/agent-design/post/p1. Posts and comments are generated deterministically from a seeded PRNG, so the same post always renders the same content and the link can be shared, reloaded and indexed. In production this page reads MySQL for the post, Redis for hot-post caching, and fetches the whole comment tree in a single query on the path column.

See the database schema →