Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

chore(agents): show how to call the go ai gateway (#129701)

Charles Vien081c345378b5
diff --git a/.agents/architecture.md b/.agents/architecture.md
index cf374bef750e..0f85c270847e 100644
--- a/.agents/architecture.md
+++ b/.agents/architecture.md
@@ -53,4 +53,20 @@ Each rule is tagged with what catches a violation.
## LLM gateway
-- **`services/llm-gateway` is under an unofficial code freeze** while callers move to [`PostHog/ai-gateway`](https://github.com/PostHog/ai-gateway). `[review]` If a task asks you to change it, tell the user about the freeze in your reply. New callers and features belong on the Go gateway. A Python gateway change needs a documented parity blocker for an active caller and stays limited to it — read [`services/llm-gateway/PARITY.md`](../services/llm-gateway/PARITY.md). Its Postgres role reads only allowlisted tables: a new table read needs the SELECT grant landed in posthog-cloud-infra for every environment first, then a declaration in `required_tables.py`. The readiness probe checks every declared grant on every probe, so a missing grant holds a rollout instead of serving 500s. Use `/auditing-llm-gateway-parity` for contract changes, `/finding-llm-gateway-migration-candidates` to pick the next caller, `/migrating-llm-gateway-callers` to move one.
+- **App code sends inference through the Go AI gateway.** `[review]`
+ A provider API key is never the client.
+- **A change to gateway behavior lands in [`PostHog/ai-gateway`](https://github.com/PostHog/ai-gateway).** `[review]`
+ Read that repo when the change is the gateway itself.
+ This monorepo only calls the gateway.
+- **A monorepo caller builds its client with a helper in `posthog/llm/gateway_client.py`.** `[review]`
+ Use `build_openai_client`, `build_async_openai_client`, `build_anthropic_client`, `build_async_anthropic_client`, `build_gemini_client`, `build_ai_gateway_openai_client`, or `build_ai_gateway_anthropic_client`.
+ Those helpers read `AI_GATEWAY_URL` and `AI_GATEWAY_API_KEY`.
+ Read [`products/tasks/backend/logic/services/title_generator.py`](../products/tasks/backend/logic/services/title_generator.py) for a real call.
+- **`services/llm-gateway` is under an unofficial code freeze.** `[review]`
+ If a task asks you to change it, tell the user about the freeze in your reply.
+ A change needs a documented parity blocker for an active caller and stays limited to that caller.
+ Read [`services/llm-gateway/PARITY.md`](../services/llm-gateway/PARITY.md) before the change.
+ Read `/auditing-llm-gateway-parity` when the gateway contract changes.
+ Its Postgres role reads only allowlisted tables.
+ A new table read needs the SELECT grant in posthog-cloud-infra for every environment first, then a declaration in `required_tables.py`.
+ The readiness probe checks every declared grant on every probe, so a missing grant holds a rollout instead of serving 500s.
diff --git a/AGENTS.md b/AGENTS.md
index 2b9c8ccc06f2..fd11b5be5288 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -150,14 +150,14 @@ Before your first edit, plan, or review finding, open every guide whose area the
Reviewing a diff counts: the diff touches the areas it changes.
Each guide's row below holds its full trigger. A section may still link one part of a guide for a rule it states.
-| Guide | Read it before you write or review |
-| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [.agents/architecture.md](.agents/architecture.md) | Application or dev-stack code in any language, such as a model, view, serializer, task, or React component: entrypoints, `team_id` scoping, personhog, transactions, API schemas, Celery and Temporal, outbound calls, storage, Django settings, Django admin, and the `services/llm-gateway` freeze |
-| [.agents/code-style.md](.agents/code-style.md) | Python; frontend code such as a component, kea logic, a button, or a form; comments; tests; Markdown; or a choice between quill and LemonUI |
-| [.agents/feature-usage-tracking.md](.agents/feature-usage-tracking.md) | A feature a user interacts with, such as a new action, menu item, or scene, a change to what a user can do there, or the removal of a feature for low usage |
-| [.agents/ci.md](.agents/ci.md) | A workflow, `.nvmrc`, a publish job, event ingestion, tests that read event properties, or a flaky CI run |
-| [.agents/agent-automation.md](.agents/agent-automation.md) | The automation of a convention, a Claude Code hook, `.claude/settings.json`, a lint-staged task, or a pre-commit check |
-| [.agents/security.md](.agents/security.md) | Auth, secrets, service-to-service calls, raw SQL, HogQL string building, a new external origin, an inline script under the Content Security Policy, or a PR for a security fix |
+| Guide | Read it before you write or review |
+| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [.agents/architecture.md](.agents/architecture.md) | Application or dev-stack code in any language, such as a model, view, serializer, task, or React component: entrypoints, `team_id` scoping, personhog, transactions, API schemas, Celery and Temporal, outbound calls, storage, Django settings, Django admin, and LLM inference / AI gateway |
+| [.agents/code-style.md](.agents/code-style.md) | Python; frontend code such as a component, kea logic, a button, or a form; comments; tests; Markdown; or a choice between quill and LemonUI |
+| [.agents/feature-usage-tracking.md](.agents/feature-usage-tracking.md) | A feature a user interacts with, such as a new action, menu item, or scene, a change to what a user can do there, or the removal of a feature for low usage |
+| [.agents/ci.md](.agents/ci.md) | A workflow, `.nvmrc`, a publish job, event ingestion, tests that read event properties, or a flaky CI run |
+| [.agents/agent-automation.md](.agents/agent-automation.md) | The automation of a convention, a Claude Code hook, `.claude/settings.json`, a lint-staged task, or a pre-commit check |
+| [.agents/security.md](.agents/security.md) | Auth, secrets, service-to-service calls, raw SQL, HogQL string building, a new external origin, an inline script under the Content Security Policy, or a PR for a security fix |
## CI / GitHub Actions