Remove Agent session create debounce to avoid reused session UUIDs and cached token failures

Developers
1

We are seeing an issue with the current debounce behavior around agent/session.create, and would like the platform team to consider removing or changing this mechanism.

Current behavior: when agent/session.create is called multiple times within a short time window, the platform may return the same session UUID. This can cause later agent/session.run calls to fail with:

no cached app_session token; create a new session

From a developer perspective, this behavior is difficult to handle reliably. Each session.create call means the caller expects a new, independent Agent session. This is especially important for multi-stage workflows, for example:

  1. Create a session for the authoring stage.
  2. Create a new session for the self-review stage.
  3. Create another new session for a fix or retry stage.

These stages may happen within one minute, but they are separate execution units from the application’s point of view. If the platform reuses the same session UUID, the caller believes a new session was created, while the internal cached app_session_token state may no longer match. The next session.run can then fail.

The impact is:

  • Developers cannot clearly tell whether session.create returned a new session or a debounced/reused old session.
  • Short, multi-stage workflows become unstable.
  • Applications have to add workarounds such as waiting 60-70 seconds, detecting repeated UUIDs, backing off after no cached app_session token, and retrying.
  • The debounce behavior is opaque to callers and does not match the intuitive meaning of a “create session” API.

Recommendation: remove the implicit debounce behavior for Agent session creation.

Preferred behavior:

  • Every agent/session.create call should return a new session UUID.
  • If the platform needs idempotency protection, the caller should provide an explicit idempotency key instead of the platform implicitly reusing sessions by time window.
  • If session creation is too frequent, the platform should return a clear rate limit or quota error, rather than returning an old session that may fail on session.run.

This would make Agent session lifecycle semantics clearer and avoid forcing applications to implement extra cooldown, retry, and UUID-guard logic just to work around implicit session reuse.

2

Hi! Thanks for the thoughtful write-up — your analysis was spot on, and I’ve got good news: we agree, and this is already fixed. :tada:

What was happening

[agent/session.create] had an internal “debounce” that, within a short time window, could quietly hand back the same session UUID for repeated create calls. As you found, that didn’t match the intuitive meaning of “create a session,” and it could leave the session token state out of sync — which is exactly why your later [session.run] hit [no cached app_session token].

You diagnosed it perfectly: for short, multi-stage workflows (authoring → review → fix, all within a minute), the implicit reuse made things unstable and forced you into cooldown/retry/UUID-guard workarounds.

It’s already fixed :white_check_mark:

We removed the implicit debounce entirely (shipped a couple days ago, in v1.1.0-beta.40). The new behavior matches your “Preferred behavior” almost exactly:

  • Every [agent/session.create] now returns a brand-new, independent session UUID. No more time-window reuse.
  • The platform no longer implicitly collapses sessions by time window, so there’s no hidden state to get out of sync.

We also added an [agent/session.list] method, in case it’s ever useful to enumerate the sessions your app has created.

What you can do

  1. Update your tooling and confirm you’re running against an up-to-date platform build (≥ v1.1.0-beta.40).
  2. Once you’re on it, you can safely remove your workarounds — the 60–70s waits, the repeated-UUID detection, and the back-off-and-retry-after-[no cached app_session token] logic. Each stage’s create will give you its own clean session.

If you ever still see [no cached app_session token] after upgrading, that would point to a different cause (e.g. a session token simply expiring), so just send us the logs and we’ll dig in with you.

Thanks again — your recommended behavior is exactly what we shipped. Happy building! :rocket: