docs(prompt-management): add a guide for prompts in Temporal workflows by jurajmajerik · Pull Request #21180 · PostHog/posthog.com

jurajmajerik · 2026-10-14T08:14:57Z

Changes

Adds a page under Prompt management on using prompts inside Temporal workflows. Teams fetching prompts from Temporal activities had no guidance and hit the same problems one by one. Closes PostHog/posthog#106807.

The page covers, with Python and TypeScript samples:

Fetch prompts in activities, not workflow code.
Create one client per worker process.
Warm the cache with get_all / getAll when the worker starts.
Return the prompt name and version from the activity and stamp them on the generation event.
Set the activity timeout above the SDK's 10 second fetch timeout.
Shut down the PostHog client with the worker.

New page, so no before screenshot. The nav gets a third entry under Prompt management.

The page says concurrent fetches share one request. That is true for @posthog/ai (PostHog/posthog-js#5266) and for Python once PostHog/posthog-python#1059 is released, so this should land after that release.

Checklist

I've read the docs and/or content style guides.
Words are spelled using American English
Use relative URLs for internal links
I've checked the pages added or changed in the Vercel preview build
If I moved a page, I added a redirect in vercel.json

github-actions · 2026-10-14T08:15:11Z

Deploy preview

Status	Details	Updated (UTC)
🟢 Ready	View preview	Oct 14, 2026 08:52AM

Changed pages

Page	Source
Using prompts in Temporal workflows	`contents/docs/prompt-management/temporal.mdx`

github-actions · 2026-10-14T08:15:54Z

Vale prose linter → found 0 errors, 2 warnings, 0 suggestions in your markdown

Full report → Copy the linter results into an LLM to batch-fix issues.

Linter being weird? Update the rules!

contents/docs/prompt-management/temporal.mdx — 0 errors, 2 warnings, 0 suggestions

Line	Severity	Message	Rule
2:34	warning	Capitalize 'Workflows' for PostHog's product. Use 'workflows' for the general industry concept.	`PostHogBase.ProductNames`
11:32	warning	Capitalize 'Workflows' for PostHog's product. Use 'workflows' for the general industry concept.	`PostHogBase.ProductNames`

posthog

PostHog Review · Standard · reviewed dcc8f7d: 2 Should fix.

posthog · 2026-10-14T08:17:11Z

+  host: 'https://us.posthog.com',
+  personalApiKey: '<your_personal_api_key>',
+})
+const prompts = new Prompts({ posthog })


P2 · Export the prompt client used by the TypeScript worker

When readers combine the TypeScript examples, worker.ts accesses activities.prompts, but activities.ts declares prompts without exporting it. TypeScript rejects that access; running without type checking instead throws before Worker.create(), so the documented worker never starts. Export the shared prompts instance used by the warm-up call.

fixed in 4df1bee

posthog · 2026-10-14T08:17:11Z

+from activities import draft_reply, prompts
+
+async def main():
+    prompts.get_all(label='production')


P2 · Handle cache warm-up failures before starting the worker

When the prompt API is unavailable during startup, get_all() and getAll() throw instead of returning a fallback. Both worker examples let that exception escape before the worker starts polling, so the activity's documented fallback never runs and support tasks stop processing. Catch and log warm-up failures, then start the worker with its activity fallbacks.

fixed in 4df1bee

…ed cache warm-up

posthog

PostHog Review · Standard · reviewed 4df1bee: 2 Should fix.

posthog · 2026-10-14T08:26:09Z

+try {
+  await worker.run()
+} finally {
+  await posthog.shutdown()


P2 · Reference the shared client in the shutdown examples

When readers add this cleanup to the worker examples, worker.ts only imports activities, and worker.py only imports draft_reply and prompts. Neither defines posthog, so TypeScript fails to compile and Python raises NameError on shutdown instead of flushing queued generation events. Use activities.posthog in TypeScript and import the shared client in Python.

fixed in 5f59972

posthog · 2026-10-14T08:26:09Z

+
+## Set timeouts above the fetch timeout
+
+Each SDK fetch gives up after 10 seconds. Give the activity a `start_to_close_timeout` (Python) or `startToCloseTimeout` (TypeScript) longer than that, so a slow prompt fetch surfaces as a fallback instead of an activity timeout.


P2 · Account for Python HTTP retries in the activity timeout

During a Python prompt API outage, prompts.get() uses a Requests session with two retries, so timeout=10 applies per attempt and fetching can take 30 seconds. An activity configured just above 10 seconds times out before fallback, while asyncio.to_thread keeps fetching and Temporal retries the activity. Document the full retry budget and reserve time for the LLM call.

fixed in 5f59972

…ll Python fetch budget

github-actions · 2026-10-14T08:49:38Z

Bundle report

Total JS (gzip)

10.10 MiB (-0.9 KiB / -0.0%)

Eager graph (modules shipped in each entrypoint's initial chunks)

Entrypoint	Eager size	Budget	Modules
✅ `app`	19.39 MiB (-9.1 KiB / -0.0%)	report-only	2085

Largest modules in the app closure

Module	Size
`./src/data/mcp-tools.json`	1348.5 KiB
`css ./node_modules/.pnpm/[email protected][email protected]/node_modules/css-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[1]!./node_modules/.pnpm/[email protected][email protected][email protected]/node_modules/postcss-loader/dist/cjs.js??ruleSet[1].rules[8].oneOf[1].use[2]!./src/styles/global.css`	811.7 KiB
`./src/components/Stickers/Stickers.tsx`	696.4 KiB
`./node_modules/.pnpm/@[email protected][email protected]/node_modules/@radix-ui/react-icons/dist/react-icons.esm.js`	481.4 KiB
`./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/x-ray.mjs`	481.2 KiB
`./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/trenchcoat.mjs`	450.8 KiB
`./node_modules/.pnpm/[email protected]/node_modules/rehype-raw/lib/index.js + 29 modules`	395.1 KiB
`./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/im-the-driver.mjs`	385.8 KiB
`./src/hooks/useCustomers.tsx + 59 modules`	380.8 KiB
`./node_modules/.pnpm/@[email protected][email protected][email protected][email protected]/node_modules/@posthog/icons/dist/posthog-icons.es.js`	354.8 KiB
`./node_modules/.pnpm/[email protected]_@[email protected][email protected]/node_modules/react-markdown/lib/react-markdown.js + 88 modules`	351.4 KiB
`./src/components/ProductComparisonTable/index.tsx + 127 modules`	310.3 KiB
`./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/doll-house.mjs`	284.1 KiB
`./node_modules/.pnpm/[email protected][email protected]/node_modules/cloudinary-core/cloudinary-core.js`	281.9 KiB
`./node_modules/.pnpm/@[email protected][email protected]/node_modules/@posthog/brand/dist/generated/hoggies/svg/director.mjs`	275.7 KiB

Eager-graph budgets are report-only until a baseline is established. Sizes are gzip of public/**/*.js; eager size is webpack module source bytes for the modules actually shipped in the entrypoint's initial chunks (post-tree-shake).

docs(prompt-management): add a guide for prompts in Temporal workflows

dcc8f7d

github-project-automation Bot added this to PostHog.com planning Oct 14, 2026

github-actions Bot added the docs Improvements or additions to product documentation, "Docs" label Oct 14, 2026

posthog Bot reviewed Oct 14, 2026

View reviewed changes

docs(prompt-management): export the worker clients and survive a fail…

4df1bee

…ed cache warm-up

posthog Bot reviewed Oct 14, 2026

View reviewed changes

docs(prompt-management): shut down the shared client and state the fu…

5f59972

…ll Python fetch budget

jurajmajerik merged commit d67e8c6 into master Oct 14, 2026
27 checks passed

jurajmajerik deleted the docs/prompts-temporal branch October 14, 2026 12:08

github-project-automation Bot moved this from Backlog to Done in PostHog.com planning Oct 14, 2026

jurajmajerik mentioned this pull request Oct 15, 2026

Sprint - October 19 to October 30 PostHog/posthog#116781

Open


		## Set timeouts above the fetch timeout

		Each SDK fetch gives up after 10 seconds. Give the activity a `start_to_close_timeout` (Python) or `startToCloseTimeout` (TypeScript) longer than that, so a slow prompt fetch surfaces as a fallback instead of an activity timeout.

Conversation

jurajmajerik commented Oct 14, 2026

Changes

Checklist

Uh oh!

github-actions Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploy preview

Changed pages

Uh oh!

github-actions Bot commented Oct 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

posthog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

posthog Bot Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

jurajmajerik Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

posthog Bot Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

jurajmajerik Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

posthog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

posthog Bot Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

jurajmajerik Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

posthog Bot Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

jurajmajerik Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Oct 14, 2026

Bundle report

Total JS (gzip)

Eager graph (modules shipped in each entrypoint's initial chunks)

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

github-actions Bot commented Oct 14, 2026 •

edited

Loading

github-actions Bot commented Oct 14, 2026 •

edited

Loading