PostHog tracking for agents & agent playground

[ashrafchowdury]

Context

Agent activity was either grouped into generic app events or missing when the interaction never reached the API. The API analytics middleware could identify a request from its path, but it could not inspect the committed agent configuration. Shared @agenta/entity-ui components also could not call the OSS app's PostHog helpers without breaking package boundaries.

This PR implements the tracking plan. API handlers now enrich middleware-owned events through an explicit request.state allowlist, while the OSS app injects a capture function into @agenta/entity-ui for UI-only discovery events. The package remains analytics-provider agnostic and silently no-ops when no host capture function is registered.

Trackers added

The properties column lists the event-specific tags added by this PR. Existing middleware context such as project, organization, user, path, method, and status remains unchanged.

Event tag	Change	Capture site	Properties / tags	Why
app_revision_created	Existing event, enriched	API middleware after application or workflow revision commit	is_agent, is_application, is_snippet, tool_count, mcp_server_count, skill_count, trigger_count, has_triggers, harness, connection_mode	Measures agent configuration commits and the feature composition present at the committed revision.
app_archived	New event mapping	API middleware for workflow/application archive routes	is_application, is_snippet	Measures application lifecycle and churn while keeping shared workflow routes segmentable by artifact role.
tool_connection_created	New event	API middleware after a tool connection is created	integration	Measures which third-party integrations are connected.
agent_playground_opened	New frontend event	Apps table, when an agent is opened in the playground from its menu	appId, source: "menu"	Measures agent playground entry because the action is client-side navigation with no dedicated backend signal.
agent_session_created	New frontend event	Agent chat session tab + action	None	Measures explicit new-session creation. Bootstrap and trigger-created sessions are excluded.
agent_tool_approval_submitted	New frontend event	Agent tool approval buttons	approved	Measures human-in-the-loop adoption and approval rate.
agent_tool_picker_opened	New frontend event	Agent tool picker open transition	toolCount	Distinguishes tool discovery from committed tool adoption.
agent_trigger_menu_opened	New frontend event	Agent trigger menu open transition	None	Distinguishes trigger discovery from committed trigger adoption.
agent_mcp_server_add_started	New frontend event	Add MCP server action	mcpServerCount	Measures MCP setup intent before a configuration is committed.
agent_skill_add_started	New frontend event	Add skill action	skillCount	Measures skill setup intent before a configuration is committed.

Implementation notes

• Backend handlers derive agent feature counts from committed parameters.agent data. Missing or unexpected shapes omit a property instead of reporting an incorrect value.
• Only allowlisted handler properties cross from request.state into PostHog. false and 0 values are retained for accurate segmentation.
• @agenta/entity-ui exposes a small capture registration seam. The OSS playground bridge connects it to the existing PostHog atom, so the package does not import app-layer analytics code.
• Agent run volume and message counts continue to come from existing tracing and spans_created; this PR does not add a duplicate run event.

Tests / notes

• git diff --check passes for the resolved tracking changes.
• pnpm --filter @agenta/entity-ui types:check currently stops at the unrelated existing type mismatch in useModelHarness.tsx:266 (string | null | undefined to string | null).

What to QA

• Commit an agent revision with tools, MCP servers, skills, and triggers. Confirm app_revision_created includes the agent role and matching feature-composition tags.
• Commit a non-agent app revision. Confirm the role tags are present without agent feature-composition tags.
• Archive an app and create a tool connection. Confirm app_archived and tool_connection_created carry their listed tags.
• From the Apps page, open an agent playground, create a session, and approve or reject a tool call. Confirm each frontend event fires once with the listed payload.
• Open the tool and trigger pickers, then start adding an MCP server and a skill. Confirm the four discovery events fire once and do not commit configuration by themselves.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 2, 2026 11:50am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2bf76306-2a32-4bc7-afa7-9e06d2abf139

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/posthog-tracker-for-agents

---

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.}