[MarceloAdan73]

Summary

Documents the two self-host gateway caveats behind the never-sent retry rule introduced in #7027, in the self-host networking reference (new "Retry semantics and your gateway" section) plus a cross-link note in the remote deploy guide.

The rule reads a 404/503 with no x-ag- response header as proof the request never reached the workflow service, so a retry is allowed. Two gateway behaviours invalidate that reasoning in self-hosted topologies, and neither was documented anywhere.

A turn that did start can be reported as never sent (and run twice) behind an Envoy or Istio gateway that answers 503 after forwarding, and a proxy rule that strips or blanks x-ag- response headers silently turns a stamped in-run 503 into an unstamped never-sent one, because the rule fails open.

Documents both caveats and their mitigations (answer 502 post-forward or ensure a 503 cannot follow a forwarded request; keep x-ag- headers on the workflow service path and exclude the prefix from stripping rules).

Closes #7042

Testing

Verified locally

N/A - documentation-only change (two MDX pages, no application code touched). Both documents follow the existing section structure of their files.

Added or updated tests

N/A - no code or tests changed.

QA follow-up

N/A - documentation change. Links used point to existing paths (/self-host/infrastructure/networking maps to docs/docs/self-host/reference/02-networking.mdx).

Demo

N/A - no UI change.

Checklist

• Demo shows the real app running this branch (not a mock-up or recreated UI), or is marked N/A
• Relevant tests pass locally
• Relevant linting and formatting pass locally
• I have signed the CLA, or I will sign it when the bot prompts me

[github-actions]

✅ Thanks @MarceloAdan73! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Advanced

Run ID: ecf767f1-629d-4f40-84d8-4e769fa10f7f

📥 Commits

Reviewing files that changed from the base of the PR and between e502a01 and 351ccd7.

📒 Files selected for processing (2)

• docs/docs/self-host/deploy/01-deploy-remotely.mdx
• docs/docs/self-host/reference/02-networking.mdx

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says: Thank you, Marcelo, for documenting the gateway caveats behind the never-sent retry rule. The project is not taking this change now, so we are closing the PR. We have also closed issue #7042. You are welcome to contribute to Agenta again.