Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(platform): experts funnel + briefing instrumentation (#14038)

Abhimanyu Yadavb83a355814a8
diff --git a/autogpt_platform/backend/backend/api/features/experts/experts_db.py b/autogpt_platform/backend/backend/api/features/experts/experts_db.py
index b7bdfd18bc..1ccf97cf48 100644
--- a/autogpt_platform/backend/backend/api/features/experts/experts_db.py
+++ b/autogpt_platform/backend/backend/api/features/experts/experts_db.py
@@ -107,6 +107,7 @@ from backend.util.exceptions import (
NotFoundError,
)
from backend.util.feature_flag import Flag, is_feature_enabled
+from backend.util.funnel_analytics import emit_funnel_event
from backend.util.timezone_utils import get_user_timezone_or_utc
logger = logging.getLogger(__name__)
@@ -871,6 +872,33 @@ async def resolve_private_expert_tenancy(
async def hire_expert(user_id: str, template_id: str, name: str | None) -> HireResult:
+ try:
+ result, state = await _hire_expert_impl(user_id, template_id, name)
+ except Exception:
+ emit_funnel_event(
+ user_id,
+ "hire_failed",
+ {"template_id": template_id, "failed_preloads_count": 0},
+ )
+ raise
+ # An idempotent re-hire of an already-active expert is not a hire.
+ if state != "existing":
+ emit_funnel_event(
+ user_id,
+ "hire_completed",
+ {
+ "template_id": template_id,
+ "failed_preloads_count": len(result.failed_preloads),
+ },
+ )
+ return result
+
+
+async def _hire_expert_impl(
+ user_id: str, template_id: str, name: str | None
+) -> tuple[HireResult, Literal["existing", "revived", "created"]]:
+ """The hire result plus which transition produced it, so the funnel can
+ count a genuine hire once and stay silent on an idempotent retry."""
template = await prisma.models.Expert.prisma().find_first(
where={"id": template_id, "isTemplate": True, "isArchived": False},
include=_WORKFLOW_INCLUDE,
@@ -913,10 +941,10 @@ async def hire_expert(user_id: str, template_id: str, name: str | None) -> HireR
expert, state = await _reserve_hired_expert(user_id, template_id, create_data)
if state == "existing":
- return HireResult(expert=_to_model(expert), failed_preloads=[])
+ return HireResult(expert=_to_model(expert), failed_preloads=[]), state
if state == "revived":
expert = await _resume_revived_hire(expert)
- return HireResult(expert=_to_model(expert), failed_preloads=[])
+ return HireResult(expert=_to_model(expert), failed_preloads=[]), state
failed = await _install_preloads(expert.id, user_id, template.Workflows or [])
await _install_bundled_skills(user_id, expert.id, template.id)
@@ -926,7 +954,7 @@ async def hire_expert(user_id: str, template_id: str, name: str | None) -> HireR
)
if hydrated is None:
raise ExpertNotFoundError(expert.id)
- return HireResult(expert=_to_model(hydrated), failed_preloads=failed)
+ return HireResult(expert=_to_model(hydrated), failed_preloads=failed), state
async def _reserve_hired_expert(
@@ -1404,6 +1432,14 @@ async def _owned_active_expert(
async def update_soul(user_id: str, expert_id: str, soul: ExpertSoulUpdate) -> Expert:
+ before = await prisma.models.Expert.prisma().find_first(
+ where={
+ "id": expert_id,
+ "ownerUserId": user_id,
+ "isTemplate": False,
+ "isArchived": False,
+ },
+ )
updated = await prisma.models.Expert.prisma().update_many(
where={
"id": expert_id,
@@ -1425,6 +1461,10 @@ async def update_soul(user_id: str, expert_id: str, soul: ExpertSoulUpdate) -> E
expert = await get_expert(user_id, expert_id)
if expert is None:
raise ExpertNotFoundError(expert_id)
+ if before is not None:
+ _emit_writing_style_added(
+ user_id, expert_id, before.voicePreferences, soul.voice_preferences
+ )
return expert
@@ -1621,7 +1661,23 @@ async def update_soul_fields_if_current(
},
data=data,
)
- return updated == 1
+ if updated != 1:
+ return False
+ if voice_preferences is not None:
+ _emit_writing_style_added(
+ user_id, expert_id, expected_voice_preferences, voice_preferences
+ )
+ return True
+
+
+def _emit_writing_style_added(
+ user_id: str, expert_id: str, before: str | None, after: str | None
+) -> None:
+ """Only a first blank→nonblank writing style counts; rewrites and removals
+ are silent, so the funnel measures personalisation rather than edits."""
+ if (before or "").strip() or not (after or "").strip():
+ return
+ emit_funnel_event(user_id, "writing_style_added", {"expert_id": expert_id})
async def _install_preloads(
@@ -1773,6 +1829,15 @@ async def _install_library_workflow(
data={"expertId": expert_id, "libraryAgentId": library_agent_id},
include=_WORKFLOW_ROW_INCLUDE,
)
+ emit_funnel_event(
+ user_id,
+ "workflow_installed_on_expert",
+ {
+ "expert_id": expert_id,
+ "source": "library",
+ "library_agent_id": library_agent_id,
+ },
+ )
return _to_workflow_ref(row)
@@ -1813,6 +1878,15 @@ async def _install_marketplace_workflow(
if raced is None:
raise
return _to_workflow_ref(raced)
+ emit_funnel_event(
+ user_id,
+ "workflow_installed_on_expert",
+ {
+ "expert_id": expert_id,
+ "source": "marketplace",
+ "store_listing_version_id": store_listing_version_id,
+ },
+ )
return _to_workflow_ref(row)
@@ -1928,12 +2002,25 @@ async def archive_expert(user_id: str, expert_id: str) -> None:
"id": expert_id,
"ownerUserId": user_id,
"isTemplate": False,
+ "isArchived": False,
"visibility": ResourceVisibility.PRIVATE,
},
data={"isArchived": True},
)
if updated == 0:
- raise ExpertNotFoundError(expert_id)
+ already_archived = await prisma.models.Expert.prisma().find_first(
+ where={
+ "id": expert_id,
+ "ownerUserId": user_id,
+ "isTemplate": False,
+ "visibility": ResourceVisibility.PRIVATE,
+ },
+ )
+ if already_archived is None:
+ raise ExpertNotFoundError(expert_id)
+ # Re-archiving is an idempotent no-op; the funnel counts each firing once.
+ return
+ emit_funnel_event(user_id, "expert_fired", {"expert_id": expert_id})
try:
await scheduling.detach_expert_triggers(user_id, expert_id)
except Exception:
diff --git a/autogpt_platform/backend/backend/api/features/experts/experts_db_test.py b/autogpt_platform/backend/backend/api/features/experts/experts_db_test.py
index f84f900d6c..4792810565 100644
--- a/autogpt_platform/backend/backend/api/features/experts/experts_db_test.py
+++ b/autogpt_platform/backend/backend/api/features/experts/experts_db_test.py
@@ -6,7 +6,7 @@ from datetime import datetime, timedelta, timezone
from pathlib import Path
from test import load_store_agents as store_assets
from types import SimpleNamespace
-from unittest.mock import AsyncMock, patch
+from unittest.mock import AsyncMock, MagicMock, patch
from zoneinfo import ZoneInfo
import prisma.enums
@@ -5328,3 +5328,359 @@ async def test_seed_roster_files_every_template_under_a_canonical_category(
for entry in fixture_roster.values():
assert seeded[entry["name"]].categories == entry["categories"]
assert set(entry["categories"]) <= {c.value for c in StoreCategory}
+
+
+# =============================================================================
+# Funnel analytics emissions
+# =============================================================================
+
+
[email protected](loop_scope="session")
+async def test_hire_expert_emits_hire_completed(server: SpinTestServer, test_user):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.hire_expert(test_user.id, template.id, None)
+ emit.assert_called_once_with(
+ test_user.id,
+ "hire_completed",
+ {"template_id": template.id, "failed_preloads_count": 0},
+ )
+
+
[email protected](loop_scope="session")
+async def test_hire_expert_emits_hire_failed_on_unknown_template(
+ server: SpinTestServer, test_user
+):
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ with pytest.raises(experts_db.ExpertTemplateNotFoundError):
+ await experts_db.hire_expert(test_user.id, "missing-template-id", None)
+ emit.assert_called_once_with(
+ test_user.id,
+ "hire_failed",
+ {"template_id": "missing-template-id", "failed_preloads_count": 0},
+ )
+
+
[email protected](loop_scope="session")
+async def test_hire_completed_reports_failed_preloads_count(
+ server: SpinTestServer, test_user
+):
+ slv_id = await _seed_store_listing(server)
+ template = await _seed_template(name="Maria", preload_listings=[slv_id])
+ with patch.object(
+ experts_db.library_db,
+ "add_store_agent_to_library",
+ new_callable=AsyncMock,
+ side_effect=RuntimeError("install exploded"),
+ ):
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.hire_expert(test_user.id, template.id, None)
+ emit.assert_called_once_with(
+ test_user.id,
+ "hire_completed",
+ {"template_id": template.id, "failed_preloads_count": 1},
+ )
+
+
[email protected](loop_scope="session")
+async def test_idempotent_rehire_does_not_reemit_hire_completed(
+ server: SpinTestServer, test_user
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ await experts_db.hire_expert(test_user.id, template.id, None)
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.hire_expert(test_user.id, template.id, None)
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_reviving_archived_expert_emits_hire_completed(
+ server: SpinTestServer, test_user
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ await experts_db.archive_expert(test_user.id, hired.expert.id)
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.hire_expert(test_user.id, template.id, None)
+ emit.assert_called_once_with(
+ test_user.id,
+ "hire_completed",
+ {"template_id": template.id, "failed_preloads_count": 0},
+ )
+
+
[email protected](loop_scope="session")
+async def test_concurrent_revival_emits_hire_completed_once(
+ server: SpinTestServer, test_user
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ await experts_db.archive_expert(test_user.id, hired.expert.id)
+
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ first, second = await asyncio.gather(
+ experts_db.hire_expert(test_user.id, template.id, None),
+ experts_db.hire_expert(test_user.id, template.id, None),
+ )
+
+ assert first.expert.id == hired.expert.id
+ assert second.expert.id == hired.expert.id
+ assert not first.expert.is_archived
+ assert not second.expert.is_archived
+ emit.assert_called_once_with(
+ test_user.id,
+ "hire_completed",
+ {"template_id": template.id, "failed_preloads_count": 0},
+ )
+
+
[email protected](loop_scope="session")
+async def test_archive_expert_emits_expert_fired(server: SpinTestServer, test_user):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.archive_expert(test_user.id, hired.expert.id)
+ emit.assert_called_once_with(
+ test_user.id, "expert_fired", {"expert_id": hired.expert.id}
+ )
+
+
[email protected](loop_scope="session")
+async def test_rearchive_does_not_reemit_expert_fired(
+ server: SpinTestServer, test_user
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ await experts_db.archive_expert(test_user.id, hired.expert.id)
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.archive_expert(test_user.id, hired.expert.id)
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_archive_unknown_expert_still_raises(server: SpinTestServer, test_user):
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ with pytest.raises(experts_db.ExpertNotFoundError):
+ await experts_db.archive_expert(test_user.id, "missing-expert-id")
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_install_workflow_emits_workflow_installed(
+ server: SpinTestServer, test_user
+):
+ slv_id = await _seed_store_listing(server)
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.install_workflow(
+ test_user.id, hired.expert.id, store_listing_version_id=slv_id
+ )
+ emit.assert_called_once_with(
+ test_user.id,
+ "workflow_installed_on_expert",
+ {
+ "expert_id": hired.expert.id,
+ "source": "marketplace",
+ "store_listing_version_id": slv_id,
+ },
+ )
+
+
[email protected](loop_scope="session")
+async def test_install_workflow_emits_for_the_library_source_too(
+ server: SpinTestServer, test_user
+):
+ """Installing one of the caller's own library agents is the same funnel
+ step as installing a marketplace listing, and must be counted as one."""
+ slv_id = await _seed_store_listing(server)
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ library_agent = await experts_db.library_db.add_store_agent_to_library(
+ slv_id, test_user.id
+ )
+
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.install_workflow(
+ test_user.id, hired.expert.id, library_agent_id=library_agent.id
+ )
+ emit.assert_called_once_with(
+ test_user.id,
+ "workflow_installed_on_expert",
+ {
+ "expert_id": hired.expert.id,
+ "source": "library",
+ "library_agent_id": library_agent.id,
+ },
+ )
+
+ # A repeat install is the same attachment, so it is not a second step.
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.install_workflow(
+ test_user.id, hired.expert.id, library_agent_id=library_agent.id
+ )
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_install_workflow_race_returns_winner_without_emitting(
+ server: SpinTestServer, test_user
+):
+ slv_id = await _seed_store_listing(server)
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ winner = await experts_db.install_workflow(
+ test_user.id, hired.expert.id, store_listing_version_id=slv_id
+ )
+ winner_row = await prisma.models.ExpertWorkflow.prisma().find_first(
+ where={"id": winner.id}, include=experts_db._WORKFLOW_ROW_INCLUDE
+ )
+ assert winner_row is not None
+ workflow_client = MagicMock(
+ find_first=AsyncMock(side_effect=[None, winner_row]),
+ create=AsyncMock(side_effect=prisma.errors.UniqueViolationError({})),
+ )
+
+ with (
+ patch.object(
+ prisma.models.ExpertWorkflow,
+ "prisma",
+ return_value=workflow_client,
+ ),
+ patch.object(
+ experts_db.library_db,
+ "add_store_agent_to_library",
+ new_callable=AsyncMock,
+ return_value=SimpleNamespace(id=winner.library_agent_id),
+ ),
+ patch.object(experts_db, "emit_funnel_event") as emit,
+ ):
+ raced = await experts_db.install_workflow(
+ test_user.id, hired.expert.id, store_listing_version_id=slv_id
+ )
+
+ assert raced.id == winner.id
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_update_soul_emits_writing_style_when_voice_is_first_added(
+ server: SpinTestServer, test_user
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.update_soul(
+ test_user.id,
+ hired.expert.id,
+ ExpertSoulUpdate(
+ name="Mara",
+ identity="You are Mara, a thoughtful strategist.",
+ voice_preferences="Warm, concise, and direct.",
+ boundaries="Never invent customer evidence.",
+ ),
+ )
+ emit.assert_called_once_with(
+ test_user.id, "writing_style_added", {"expert_id": hired.expert.id}
+ )
+
+
+ "next_voice",
+ ["", "Deliberate, detailed, and formal."],
+ ids=["removed", "replaced"],
+)
[email protected](loop_scope="session")
+async def test_update_soul_skips_writing_style_when_existing_voice_changes(
+ server: SpinTestServer, test_user, next_voice: str
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ await experts_db.update_soul(
+ test_user.id,
+ hired.expert.id,
+ ExpertSoulUpdate(
+ name="Mara",
+ identity="You are Mara, a thoughtful strategist.",
+ voice_preferences="Warm, concise, and direct.",
+ boundaries="Never invent customer evidence.",
+ ),
+ )
+
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.update_soul(
+ test_user.id,
+ hired.expert.id,
+ ExpertSoulUpdate(
+ name="Mara",
+ identity="You are Mara, a thoughtful strategist.",
+ voice_preferences=next_voice,
+ boundaries="Never invent customer evidence.",
+ ),
+ )
+
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_copilot_soul_patch_emits_writing_style_on_first_add(
+ server: SpinTestServer, test_user
+):
+ """The copilot's Soul-edit path writes voicePreferences without going
+ through update_soul, so it needs the same first-add gate."""
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ await experts_db.update_soul_fields(
+ test_user.id, hired.expert.id, voice_preferences=""
+ )
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ applied = await experts_db.update_soul_fields_if_current(
+ test_user.id,
+ hired.expert.id,
+ voice_preferences="Warm, concise, and direct.",
+ expected_voice_preferences="",
+ )
+ assert applied
+ emit.assert_called_once_with(
+ test_user.id, "writing_style_added", {"expert_id": hired.expert.id}
+ )
+
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.update_soul_fields_if_current(
+ test_user.id,
+ hired.expert.id,
+ voice_preferences="Warm and brief.",
+ expected_voice_preferences="Warm, concise, and direct.",
+ )
+ emit.assert_not_called()
+
+
[email protected](loop_scope="session")
+async def test_update_soul_skips_writing_style_when_voice_unchanged(
+ server: SpinTestServer, test_user
+):
+ template = await _seed_template(name="Maria", preload_listings=[])
+ hired = await experts_db.hire_expert(test_user.id, template.id, None)
+ voice = "Warm, concise, and direct."
+ await experts_db.update_soul(
+ test_user.id,
+ hired.expert.id,
+ ExpertSoulUpdate(
+ name="Mara",
+ identity="You are Mara, a thoughtful strategist.",
+ voice_preferences=voice,
+ boundaries="Never invent customer evidence.",
+ ),
+ )
+ with patch.object(experts_db, "emit_funnel_event") as emit:
+ await experts_db.update_soul(
+ test_user.id,
+ hired.expert.id,
+ ExpertSoulUpdate(
+ name="Mara Two",
+ identity="You are Mara, refreshed.",
+ voice_preferences=voice,
+ boundaries="Never invent customer evidence.",
+ ),
+ )
+ emit.assert_not_called()
diff --git a/autogpt_platform/backend/backend/copilot/briefing/generate.py b/autogpt_platform/backend/backend/copilot/briefing/generate.py
index d403600735..a8a97f69d8 100644
--- a/autogpt_platform/backend/backend/copilot/briefing/generate.py
+++ b/autogpt_platform/backend/backend/copilot/briefing/generate.py
@@ -22,6 +22,7 @@ from backend.data.db_accessors import (
from backend.data.execution import ExecutionStatus, GraphExecutionMeta
from backend.util.clients import get_database_manager_async_client
from backend.util.feature_flag import Flag, evaluate_feature_flag, is_feature_enabled
+from backend.util.funnel_analytics import emit_funnel_event
from backend.util.timezone_utils import get_user_timezone_or_utc
from .models import BriefingContent, BriefingDecisionItem, BriefingRunItem
@@ -288,6 +289,16 @@ async def generate_and_deliver_briefing(user_id: str) -> BriefingResult:
# otherwise be re-gathered and re-composed on every future
# run. Stamp it so this user's cron stops reprocessing it.
await client.mark_briefing_delivered(user_id, record.id)
+ emit_funnel_event(
+ user_id,
+ "briefing_generated",
+ {"run_count": 0, "decision_count": 0, "has_content": False},
+ (
+ f"briefing_generated:{record.id}"
+ if record is not None
+ else f"briefing_generated:empty:{briefing_date.isoformat()}"
+ ),
+ )
return {"status": "skipped", "reason": "nothing_to_say"}
if record is None:
record = await client.create_briefing(
@@ -300,6 +311,16 @@ async def generate_and_deliver_briefing(user_id: str) -> BriefingResult:
await client.update_briefing_content(
user_id, record.id, content.model_dump(mode="json")
)
+ emit_funnel_event(
+ user_id,
+ "briefing_generated",
+ {
+ "run_count": content.completed_total + content.failed_total,
+ "decision_count": content.decision_total,
+ "has_content": True,
+ },
+ f"briefing_generated:{record.id}",
+ )
message_id = str(
uuid.uuid5(
@@ -314,6 +335,12 @@ async def generate_and_deliver_briefing(user_id: str) -> BriefingResult:
metadata={"kind": "morning_briefing", "briefing_id": record.id},
)
await client.mark_briefing_delivered(user_id, record.id)
+ emit_funnel_event(
+ user_id,
+ "briefing_delivered",
+ {"briefing_id": record.id},
+ f"briefing_delivered:{record.id}",
+ )
return {
"status": "delivered",
"briefing_id": record.id,
diff --git a/autogpt_platform/backend/backend/copilot/briefing/generate_test.py b/autogpt_platform/backend/backend/copilot/briefing/generate_test.py
index 78b0b463f6..b700234119 100644
--- a/autogpt_platform/backend/backend/copilot/briefing/generate_test.py
+++ b/autogpt_platform/backend/backend/copilot/briefing/generate_test.py
@@ -5,8 +5,10 @@ import pytest
from backend.copilot.briefing import generate as generate_module
from backend.copilot.briefing.generate import AgentInfo, compose_briefing
+from backend.copilot.briefing.models import BriefingContent
from backend.copilot.briefing.render import render_briefing_markdown
from backend.data.execution import ExecutionStatus, GraphExecutionMeta
+from backend.util import funnel_analytics
from backend.util.feature_flag import Flag
NOW = datetime(2026, 8, 7, 9, 0, tzinfo=timezone.utc)
@@ -284,6 +286,14 @@ async def test_generate_reports_an_unevaluated_flag_separately(monkeypatch):
assert result == {"status": "skipped", "reason": "flag_unavailable"}
+def funnel(monkeypatch):
+ """The funnel emitter is a module-level call now, not a client method."""
+ mock = MagicMock()
+ monkeypatch.setattr(generate_module, "emit_funnel_event", mock)
+ return mock
+
+
@pytest.mark.asyncio
async def test_generate_skips_when_already_delivered(monkeypatch):
from unittest.mock import AsyncMock, MagicMock
@@ -303,7 +313,9 @@ async def test_generate_skips_when_already_delivered(monkeypatch):
)
delivered_record = MagicMock(delivered_at=datetime(2026, 8, 7, 9, 5))
client = MagicMock(get_briefing_for_date=AsyncMock(return_value=delivered_record))
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
result = await generate.generate_and_deliver_briefing("user-1")
assert result == {"status": "skipped", "reason": "already_delivered"}
@@ -341,7 +353,9 @@ async def test_generate_delivers_and_composes_briefing(monkeypatch):
append_plain_session_message=AsyncMock(return_value="session-1"),
mark_briefing_delivered=AsyncMock(),
)
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
expert = make_expert()
execution = make_exec()
@@ -417,8 +431,6 @@ async def test_generate_delivers_and_composes_briefing(monkeypatch):
def _patch_generate_env(monkeypatch, generate, client):
"""Shared plumbing for the delivery-retry tests: fixed clock, flag on,
UTC user, and the given database-manager client."""
- from unittest.mock import AsyncMock, MagicMock
-
fixed_now = datetime(2026, 8, 7, 9, 0, tzinfo=timezone.utc)
fake_datetime = MagicMock(wraps=datetime)
fake_datetime.now.return_value = fixed_now
@@ -434,11 +446,15 @@ def _patch_generate_env(monkeypatch, generate, client):
"user_db",
lambda: MagicMock(get_user_by_id=AsyncMock(return_value=user)),
)
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
@pytest.mark.asyncio
-async def test_generate_retries_undelivered_briefing_without_recomposing(monkeypatch):
+async def test_generate_retries_undelivered_briefing_without_recomposing(
+ monkeypatch, funnel
+):
"""A stored-but-undelivered record (prior session post failed) is
redelivered from its stored content — no data gathering, no recompose,
no duplicate create."""
@@ -480,6 +496,12 @@ async def test_generate_retries_undelivered_briefing_without_recomposing(monkeyp
append_call = client.append_plain_session_message.await_args
assert append_call.kwargs["content"] == render_briefing_markdown(stored)
client.mark_briefing_delivered.assert_awaited_once_with("user-1", "briefing-1")
+ funnel.assert_called_once_with(
+ "user-1",
+ "briefing_delivered",
+ {"briefing_id": "briefing-1"},
+ "briefing_delivered:briefing-1",
+ )
@pytest.mark.asyncio
@@ -562,7 +584,9 @@ async def test_generate_keeps_library_link_when_workflow_has_no_library_agent_id
append_plain_session_message=AsyncMock(return_value="session-1"),
mark_briefing_delivered=AsyncMock(),
)
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
# The workflow shares "g-1" with the library agent below but carries no
# library_agent_id of its own — the merge must not clobber the
@@ -764,7 +788,9 @@ async def test_generate_writes_recomposed_content_back_to_an_unreadable_row(
append_plain_session_message=AsyncMock(return_value="session-1"),
mark_briefing_delivered=AsyncMock(),
)
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
monkeypatch.setattr(
generate,
@@ -800,7 +826,7 @@ async def test_generate_writes_recomposed_content_back_to_an_unreadable_row(
@pytest.mark.asyncio
async def test_generate_stops_reprocessing_an_unreadable_row_with_nothing_to_say(
- monkeypatch,
+ monkeypatch, funnel
):
"""Otherwise every future run re-gathers and re-composes the same row."""
from unittest.mock import AsyncMock, MagicMock
@@ -830,7 +856,9 @@ async def test_generate_stops_reprocessing_an_unreadable_row_with_nothing_to_say
append_plain_session_message=AsyncMock(),
mark_briefing_delivered=AsyncMock(),
)
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
monkeypatch.setattr(
generate,
@@ -860,6 +888,12 @@ async def test_generate_stops_reprocessing_an_unreadable_row_with_nothing_to_say
assert result == {"status": "skipped", "reason": "nothing_to_say"}
client.mark_briefing_delivered.assert_awaited_once_with("user-1", "briefing-1")
client.append_plain_session_message.assert_not_awaited()
+ funnel.assert_called_once_with(
+ "user-1",
+ "briefing_generated",
+ {"run_count": 0, "decision_count": 0, "has_content": False},
+ "briefing_generated:briefing-1",
+ )
@pytest.mark.asyncio
@@ -891,7 +925,9 @@ async def test_generate_bounds_the_execution_query(monkeypatch):
append_plain_session_message=AsyncMock(return_value="session-1"),
mark_briefing_delivered=AsyncMock(),
)
- monkeypatch.setattr(generate, "get_database_manager_async_client", lambda: client)
+ monkeypatch.setattr(
+ generate, "get_database_manager_async_client", lambda **kwargs: client
+ )
get_graph_executions = AsyncMock(return_value=[make_exec()])
monkeypatch.setattr(
@@ -1135,3 +1171,100 @@ def test_narrative_cannot_forge_briefing_structure(narrative):
).splitlines()[2]
assert line.startswith("\\")
+
+
+async def test_generate_emits_events_on_delivery(monkeypatch, funnel):
+ """A delivered briefing fires briefing_generated (with real counts) and
+ briefing_delivered through the DB-manager RPC client."""
+ briefing_record = MagicMock(id="briefing-1")
+ client = MagicMock(
+ get_briefing_for_date=AsyncMock(return_value=None),
+ create_briefing=AsyncMock(return_value=briefing_record),
+ append_plain_session_message=AsyncMock(return_value="session-1"),
+ mark_briefing_delivered=AsyncMock(),
+ )
+ _patch_generate_env(monkeypatch, generate_module, client)
+
+ content = BriefingContent(
+ generated_at=datetime(2026, 8, 7, 9, 0, tzinfo=timezone.utc),
+ timezone="UTC",
+ zero_expert_fallback=False,
+ run_items=[],
+ decision_items=[],
+ decision_total=2,
+ completed_total=3,
+ failed_total=1,
+ )
+ monkeypatch.setattr(
+ generate_module,
+ "_compose_fresh_briefing",
+ AsyncMock(return_value=content),
+ )
+
+ result = await generate_module.generate_and_deliver_briefing("user-1")
+
+ assert result["status"] == "delivered"
+ funnel.assert_any_call(
+ "user-1",
+ "briefing_generated",
+ {"run_count": 4, "decision_count": 2, "has_content": True},
+ "briefing_generated:briefing-1",
+ )
+ funnel.assert_any_call(
+ "user-1",
+ "briefing_delivered",
+ {"briefing_id": "briefing-1"},
+ "briefing_delivered:briefing-1",
+ )
+
+
+async def test_generate_emits_briefing_generated_when_nothing_to_say(
+ monkeypatch, funnel
+):
+ """An empty briefing still fires briefing_generated with has_content False."""
+ client = MagicMock(
+ get_briefing_for_date=AsyncMock(return_value=None),
+ )
+ _patch_generate_env(monkeypatch, generate_module, client)
+ monkeypatch.setattr(
+ generate_module, "_compose_fresh_briefing", AsyncMock(return_value=None)
+ )
+
+ result = await generate_module.generate_and_deliver_briefing("user-1")
+
+ assert result == {"status": "skipped", "reason": "nothing_to_say"}
+ funnel.assert_called_once_with(
+ "user-1",
+ "briefing_generated",
+ {"run_count": 0, "decision_count": 0, "has_content": False},
+ "briefing_generated:empty:2026-08-07",
+ )
+
+
+async def test_generate_still_delivers_when_posthog_is_down(monkeypatch):
+ """Isolation lives inside emit_funnel_event, so the real emitter is left in
+ place and PostHog is what fails."""
+ monkeypatch.setattr(
+ funnel_analytics,
+ "get_posthog_client",
+ MagicMock(side_effect=RuntimeError("analytics down")),
+ )
+ client = MagicMock(
+ get_briefing_for_date=AsyncMock(return_value=None),
+ create_briefing=AsyncMock(return_value=MagicMock(id="briefing-1")),
+ append_plain_session_message=AsyncMock(return_value="session-1"),
+ mark_briefing_delivered=AsyncMock(),
+ )
+ _patch_fresh_compose_env(monkeypatch, generate_module, client)
+
+ result = await generate_module.generate_and_deliver_briefing("user-1")
+
+ assert result == {
+ "status": "delivered",
+ "briefing_id": "briefing-1",
+ "session_id": "session-1",
+ }
+ client.mark_briefing_delivered.assert_awaited_once_with("user-1", "briefing-1")
diff --git a/autogpt_platform/backend/backend/executor/expert_posts.py b/autogpt_platform/backend/backend/executor/expert_posts.py
index 1624fd3125..276ba71314 100644
--- a/autogpt_platform/backend/backend/executor/expert_posts.py
+++ b/autogpt_platform/backend/backend/executor/expert_posts.py
@@ -60,16 +60,8 @@ def _post_run_result(
status: ExecutionStatus,
exec_stats: GraphExecutionStats,
) -> None:
- context = graph_exec.execution_context
- expert_id = context.expert_id if context else None
- if not expert_id or (context and context.dry_run):
- return
- # Sub-graph executions (AgentExecutorBlock) inherit expert_id from the
- # parent context; only the top-level run may post, or one logical run
- # would produce a message (and burn a cap slot) per nested sub-agent.
- if context and context.parent_execution_id is not None:
- return
- if status not in (ExecutionStatus.COMPLETED, ExecutionStatus.FAILED):
+ expert_id = completed_expert_id(graph_exec, status)
+ if expert_id is None:
return
# The key is captured once at admission and reused for release — a UTC
# midnight rollover between the two must not decrement the new day's
@@ -132,6 +124,20 @@ def _post_run_result(
_release_cap_slot(cap_key, expert_id)
+def completed_expert_id(
+ graph_exec: GraphExecutionEntry, status: ExecutionStatus
+) -> str | None:
+ context = graph_exec.execution_context
+ expert_id = context.expert_id if context else None
+ if not expert_id or (context and context.dry_run):
+ return None
+ if context and context.parent_execution_id is not None:
+ return None
+ if status not in (ExecutionStatus.COMPLETED, ExecutionStatus.FAILED):
+ return None
+ return expert_id
+
+
def build_expert_run_message(
agent_name: str,
succeeded: bool,
diff --git a/autogpt_platform/backend/backend/executor/manager.py b/autogpt_platform/backend/backend/executor/manager.py
index cac0cd1dac..571a7735b6 100644
--- a/autogpt_platform/backend/backend/executor/manager.py
+++ b/autogpt_platform/backend/backend/executor/manager.py
@@ -74,6 +74,7 @@ from backend.util.exceptions import (
get_execution_failure_reason,
)
from backend.util.file import clean_exec_files
+from backend.util.funnel_analytics import emit_funnel_event
from backend.util.llm.saturation import set_executor_id
from backend.util.logging import TruncatedLogger, configure_logging
from backend.util.process import AppProcess, set_service_name
@@ -700,6 +701,27 @@ async def _enqueue_next_nodes(
]
+def _expert_run_completed_event(
+ graph_exec: GraphExecutionEntry, status: ExecutionStatus
+) -> Optional[dict]:
+ """Funnel payload for a finished top-level expert run, else None.
+
+ Mirrors the gating in ``expert_posts._post_run_result`` so the funnel
+ counts exactly the runs that can post: an expert-attributed, non-dry-run,
+ top-level execution that reached a terminal status. Execution origin
+ (schedule vs manual vs webhook) is not persisted anywhere, so the event
+ covers every such run rather than pretending to know the trigger.
+ """
+ expert_id = expert_posts.completed_expert_id(graph_exec, status)
+ if expert_id is None:
+ return None
+ return {
+ "expert_id": expert_id,
+ "status": status.value,
+ "graph_exec_id": graph_exec.graph_exec_id,
+ }
+
+
class ExecutionProcessor:
"""
This class contains event handlers for the process pool executor events.
@@ -1096,6 +1118,15 @@ class ExecutionProcessor:
status=exec_meta.status,
stats=exec_stats,
)
+ # Only once the terminal state is persisted.
+ run_event = _expert_run_completed_event(graph_exec, exec_meta.status)
+ if run_event is not None:
+ emit_funnel_event(
+ graph_exec.user_id,
+ "expert_run_completed",
+ run_event,
+ f"expert_run_completed:{graph_exec.graph_exec_id}",
+ )
async def charge_node_usage(
self,
diff --git a/autogpt_platform/backend/backend/executor/manager_expert_events_test.py b/autogpt_platform/backend/backend/executor/manager_expert_events_test.py
new file mode 100644
index 0000000000..b1fa9ddbcf
--- /dev/null
+++ b/autogpt_platform/backend/backend/executor/manager_expert_events_test.py
@@ -0,0 +1,65 @@
+from types import SimpleNamespace
+
+from backend.data.execution import ExecutionStatus
+from backend.executor.manager import _expert_run_completed_event
+
+
+def _graph_exec(expert_id="e-1", dry_run=False, parent=None, user_id="u-1"):
+ return SimpleNamespace(
+ user_id=user_id,
+ graph_exec_id="run-1",
+ execution_context=SimpleNamespace(
+ expert_id=expert_id,
+ dry_run=dry_run,
+ parent_execution_id=parent,
+ ),
+ )
+
+
+def test_emits_for_terminal_expert_run():
+ event = _expert_run_completed_event(_graph_exec(), ExecutionStatus.COMPLETED)
+ assert event == {
+ "expert_id": "e-1",
+ "status": ExecutionStatus.COMPLETED.value,
+ "graph_exec_id": "run-1",
+ }
+
+
+def test_emits_for_failed_expert_run():
+ event = _expert_run_completed_event(_graph_exec(), ExecutionStatus.FAILED)
+ assert event == {
+ "expert_id": "e-1",
+ "status": ExecutionStatus.FAILED.value,
+ "graph_exec_id": "run-1",
+ }
+
+
+def test_skips_non_expert_run():
+ assert (
+ _expert_run_completed_event(
+ _graph_exec(expert_id=None), ExecutionStatus.COMPLETED
+ )
+ is None
+ )
+
+
+def test_skips_dry_run():
+ assert (
+ _expert_run_completed_event(
+ _graph_exec(dry_run=True), ExecutionStatus.COMPLETED
+ )
+ is None
+ )
+
+
+def test_skips_subgraph_run():
+ assert (
+ _expert_run_completed_event(
+ _graph_exec(parent="parent-1"), ExecutionStatus.COMPLETED
+ )
+ is None
+ )
+
+
+def test_skips_non_terminal_status():
+ assert _expert_run_completed_event(_graph_exec(), ExecutionStatus.RUNNING) is None
diff --git a/autogpt_platform/backend/backend/util/funnel_analytics.py b/autogpt_platform/backend/backend/util/funnel_analytics.py
new file mode 100644
index 0000000000..65614847ce
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/funnel_analytics.py
@@ -0,0 +1,59 @@
+"""Server-side funnel events for the experts loop (SECRT-2526 / SECRT-2552).
+
+PostHog is the store for these; the Sentry breadcrumb puts the same event on
+the timeline of any error raised after it. Nothing here needs Prisma, so the
+Prisma-less briefing scheduler and executor call it directly rather than
+through the DB manager.
+"""
+
+import logging
+from typing import Any
+from uuid import NAMESPACE_URL, uuid5
+
+import sentry_sdk
+
+from backend.util.posthog_client import get_posthog_client
+
+logger = logging.getLogger(__name__)
+
+
+def emit_funnel_event(
+ user_id: str, event: str, data: dict[str, Any], data_index: str | None = None
+) -> None:
+ """Record a funnel event without blocking or raising into the caller.
+
+ The breadcrumb is added in the caller's own scope, which is the only place
+ it attaches to an error from the action being measured — one added on a
+ background task or another thread lands in that scope and reaches nothing.
+ PostHog's client batches on its own thread, so the capture does not wait on
+ the network either.
+
+ ``data_index`` is an idempotency key for a redelivery or requeue that can
+ emit the same event twice; it is carried both as ``$insert_id`` and as a
+ deterministic event uuid.
+ """
+ # Separate boundaries: a breadcrumb failure must not cost the capture.
+ try:
+ sentry_sdk.add_breadcrumb(
+ category="funnel", message=event, data=dict(data), level="info"
+ )
+ except Exception:
+ logger.exception(f"Failed to breadcrumb funnel event {event}")
+
+ try:
+ client = get_posthog_client()
+ if client is None:
+ return
+ properties: dict[str, Any] = {**data}
+ event_uuid = None
+ if data_index is not None:
+ # Both, because the two are read at different layers: PostHog's
+ # ingestion keys on the event uuid, which the client otherwise
+ # randomises per call, and $insert_id is what its docs name.
+ properties["$insert_id"] = data_index
+ event_uuid = str(uuid5(NAMESPACE_URL, f"{user_id}:{event}:{data_index}"))
+ client.capture(
+ event=event, distinct_id=user_id, properties=properties, uuid=event_uuid
+ )
+ except Exception:
+ logger.exception(f"Failed to emit funnel event {event} for user {user_id}")
diff --git a/autogpt_platform/backend/backend/util/funnel_analytics_test.py b/autogpt_platform/backend/backend/util/funnel_analytics_test.py
new file mode 100644
index 0000000000..dcfca5cc6a
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/funnel_analytics_test.py
@@ -0,0 +1,160 @@
+import uuid
+from unittest.mock import MagicMock, patch
+
+from backend.util import funnel_analytics
+from backend.util.funnel_analytics import emit_funnel_event
+
+
+def test_captures_to_posthog_with_the_user_as_distinct_id():
+ client = MagicMock()
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "hire_completed", {"template_id": "tpl-1"})
+
+ client.capture.assert_called_once_with(
+ event="hire_completed",
+ distinct_id="user-1",
+ properties={"template_id": "tpl-1"},
+ uuid=None,
+ )
+
+
+def test_a_data_index_becomes_the_posthog_dedup_key():
+ client = MagicMock()
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event(
+ "user-1",
+ "briefing_delivered",
+ {"briefing_id": "b-1"},
+ "briefing_delivered:b-1",
+ )
+
+ assert client.capture.call_args.kwargs["properties"] == {
+ "briefing_id": "b-1",
+ "$insert_id": "briefing_delivered:b-1",
+ }
+
+
+def test_no_data_index_means_no_dedup_key():
+ client = MagicMock()
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "expert_fired", {"expert_id": "e-1"})
+
+ assert "$insert_id" not in client.capture.call_args.kwargs["properties"]
+
+
+def test_breadcrumb_carries_the_event_and_its_payload():
+ client = MagicMock()
+ with (
+ patch.object(funnel_analytics, "get_posthog_client", return_value=client),
+ patch.object(funnel_analytics.sentry_sdk, "add_breadcrumb") as crumb,
+ ):
+ emit_funnel_event("user-1", "hire_failed", {"template_id": "tpl-1"})
+
+ crumb.assert_called_once_with(
+ category="funnel",
+ message="hire_failed",
+ data={"template_id": "tpl-1"},
+ level="info",
+ )
+
+
+def test_breadcrumb_is_added_before_the_capture():
+ """It has to land in the caller's scope, ahead of whatever may raise next."""
+ calls = []
+ client = MagicMock()
+ client.capture.side_effect = lambda **_: calls.append("capture")
+ with (
+ patch.object(funnel_analytics, "get_posthog_client", return_value=client),
+ patch.object(
+ funnel_analytics.sentry_sdk,
+ "add_breadcrumb",
+ side_effect=lambda **_: calls.append("breadcrumb"),
+ ),
+ ):
+ emit_funnel_event("user-1", "expert_thread_created", {"expert_id": "e-1"})
+
+ assert calls == ["breadcrumb", "capture"]
+
+
+def test_a_disabled_posthog_still_leaves_a_breadcrumb():
+ with (
+ patch.object(funnel_analytics, "get_posthog_client", return_value=None),
+ patch.object(funnel_analytics.sentry_sdk, "add_breadcrumb") as crumb,
+ ):
+ emit_funnel_event("user-1", "expert_fired", {"expert_id": "e-1"})
+
+ crumb.assert_called_once()
+
+
+def test_a_throwing_breadcrumb_still_lets_the_capture_through():
+ """The two sinks are independent: losing Sentry must not lose PostHog."""
+ client = MagicMock()
+ with (
+ patch.object(funnel_analytics, "get_posthog_client", return_value=client),
+ patch.object(
+ funnel_analytics.sentry_sdk,
+ "add_breadcrumb",
+ side_effect=RuntimeError("sentry unavailable"),
+ ),
+ ):
+ emit_funnel_event("user-1", "hire_completed", {"template_id": "tpl-1"})
+
+ client.capture.assert_called_once()
+
+
+def test_a_data_index_also_becomes_a_deterministic_event_uuid():
+ """PostHog's ingestion keys on the event uuid, which the client otherwise
+ randomises per call, so a retry needs the same one."""
+ client = MagicMock()
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "briefing_delivered", {}, "briefing_delivered:b-1")
+ first = client.capture.call_args.kwargs["uuid"]
+ emit_funnel_event("user-1", "briefing_delivered", {}, "briefing_delivered:b-1")
+ second = client.capture.call_args.kwargs["uuid"]
+
+ assert first and first == second
+ assert uuid.UUID(first).version == 5
+
+
+def test_a_different_event_identity_gets_a_different_uuid():
+ client = MagicMock()
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "briefing_delivered", {}, "briefing_delivered:b-1")
+ a = client.capture.call_args.kwargs["uuid"]
+ emit_funnel_event("user-2", "briefing_delivered", {}, "briefing_delivered:b-1")
+ b = client.capture.call_args.kwargs["uuid"]
+
+ assert a != b
+
+
+def test_no_data_index_leaves_the_uuid_to_the_client():
+ client = MagicMock()
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "expert_fired", {"expert_id": "e-1"})
+
+ assert client.capture.call_args.kwargs["uuid"] is None
+
+
+def test_a_failing_capture_never_raises_into_the_caller():
+ client = MagicMock()
+ client.capture.side_effect = RuntimeError("posthog unreachable")
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "hire_completed", {"template_id": "tpl-1"})
+
+
+def test_a_failing_client_lookup_never_raises_into_the_caller():
+ with patch.object(
+ funnel_analytics,
+ "get_posthog_client",
+ side_effect=RuntimeError("settings unreadable"),
+ ):
+ emit_funnel_event("user-1", "hire_completed", {"template_id": "tpl-1"})
+
+
+def test_the_payload_is_copied_not_shared_with_the_caller():
+ client = MagicMock()
+ payload = {"expert_id": "e-1"}
+ with patch.object(funnel_analytics, "get_posthog_client", return_value=client):
+ emit_funnel_event("user-1", "expert_fired", payload, "expert_fired:e-1")
+
+ assert payload == {"expert_id": "e-1"}
diff --git a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/__tests__/HireStep.test.tsx b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/__tests__/HireStep.test.tsx
index a2090e2ab4..0e1ef3aac2 100644
--- a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/__tests__/HireStep.test.tsx
+++ b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/__tests__/HireStep.test.tsx
@@ -188,6 +188,30 @@ describe("HireStep — hiring", () => {
});
});
+ it("sends the funnel start and the DataFast hire goal", async () => {
+ // The backend emits this hire's hire_completed, so without the start the
+ // funnel's completion rate is unreadable for onboarding hires.
+ const datafast = vi.fn();
+ (window as unknown as { datafast: typeof datafast }).datafast = datafast;
+ mockTeam(TEAM);
+ render(<HireStep />);
+
+ await userEvent.click(
+ (await screen.findAllByRole("button", { name: "Hire" }))[0],
+ );
+
+ await waitFor(() =>
+ expect(capture).toHaveBeenCalledWith("hire_started", {
+ template_id: "tpl-maria",
+ }),
+ );
+ await waitFor(() =>
+ expect(datafast).toHaveBeenCalledWith("hire_completed", {
+ template_id: "tpl-maria",
+ }),
+ );
+ });
+
it("shows templates hired on an earlier visit as hired", async () => {
mockTeam(TEAM);
useOnboardingWizardStore.getState().markHired("tpl-max");
diff --git a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/useHireStep.ts b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/useHireStep.ts
index 7697761c53..3a8596f2b8 100644
--- a/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/useHireStep.ts
+++ b/autogpt_platform/frontend/src/app/(no-navbar)/onboarding/steps/HireStep/useHireStep.ts
@@ -4,6 +4,8 @@ import type { ExpertRecommendations } from "@/app/api/__generated__/models/exper
import type { RecommendedExpert } from "@/app/api/__generated__/models/recommendedExpert";
import { toast } from "@/components/molecules/Toast/use-toast";
import { invalidateExpertRosterQueries } from "@/services/experts/invalidate-experts";
+import { analytics } from "@/services/analytics";
+import { trackFunnel } from "@/services/experts/experts-analytics";
import { trackBrainDump } from "@/services/onboarding/brain-dump-analytics";
import { useQueryClient } from "@tanstack/react-query";
import { useEffect, useRef, useState } from "react";
@@ -83,9 +85,15 @@ export function useHireStep() {
template_id: expert.template_id,
source: "onboarding_hire_step",
});
+ // The backend counts this hire's completion, so the funnel sink needs its
+ // start too — otherwise onboarding hires make completion rate unreadable.
+ trackFunnel("hire_started", { template_id: expert.template_id });
setHiringTemplateId(expert.template_id);
try {
await hireExpert({ data: { template_id: expert.template_id } });
+ analytics.sendDatafastEvent("hire_completed", {
+ template_id: expert.template_id,
+ });
markHired(expert.template_id);
trackBrainDump("onboarding_expert_hired", {
template_id: expert.template_id,
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/expert-threads.test.tsx b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/expert-threads.test.tsx
index 3b3895f17c..5ced4909a3 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/expert-threads.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/__tests__/expert-threads.test.tsx
@@ -20,7 +20,7 @@ import userEvent from "@testing-library/user-event";
import { http, HttpResponse } from "msw";
import { parseAsString, useQueryState } from "nuqs";
import { withNuqsTestingAdapter } from "nuqs/adapters/testing";
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { RecipientChip } from "../components/ChatInput/components/RecipientChip";
import { useRecipientPicker } from "../components/EmptySession/useRecipientPicker";
import { ChatMessagesContainer } from "../components/ChatMessagesContainer/ChatMessagesContainer";
@@ -29,6 +29,25 @@ import { useChatSession } from "../useChatSession";
import { useCopilotUIStore } from "../store";
import { groupSessionsByExpert } from "../useSessionList";
+const { capture } = vi.hoisted(() => ({ capture: vi.fn() }));
+vi.mock("posthog-js", () => ({ default: { capture } }));
+
+/** Funnel events as PostHog received them, in order. */
+function funnelCalls() {
+ return capture.mock.calls.map(([event, data]) => ({
+ type: event as string,
+ data: (data ?? {}) as Record<string, unknown>,
+ }));
+}
+
+beforeEach(() => {
+ capture.mockReset();
+});
+
+function funnelEventNames() {
+ return capture.mock.calls.map(([event]) => event as string);
+}
+
const flagState = vi.hoisted(() => ({
values: { "hire-experts": true } as Record<string, boolean>,
}));
@@ -203,6 +222,18 @@ function ExpertSessionHarness() {
);
}
+function AutopilotSessionHarness() {
+ const { createSession, sessionId } = useChatSession();
+ return (
+ <div>
+ <div data-testid="session-id">{sessionId ?? "none"}</div>
+ <button onClick={() => void createSession().catch(() => {})}>
+ create
+ </button>
+ </div>
+ );
+}
+
/** Mirrors `CopilotPage`, which keys the chat host on the session id — every
* session change (including "New Chat" clearing it) remounts `useChatSession`
* with fresh refs. */
@@ -216,6 +247,11 @@ const NuqsWrapper = withNuqsTestingAdapter({
hasMemory: true,
});
+const EmptyNuqsWrapper = withNuqsTestingAdapter({
+ searchParams: "",
+ hasMemory: true,
+});
+
describe("useChatSession — expert sessions", () => {
it("creates a session with expert_id when visiting /copilot?expertId=expert-maria", async () => {
let createBody: unknown = null;
@@ -272,6 +308,67 @@ describe("useChatSession — expert sessions", () => {
// chosen for one chat leaked into every later chat.
expect(createBody).toEqual({ expert_id: "expert-maria" });
});
+ await waitFor(() =>
+ expect(
+ funnelCalls().find((event) => event.type === "expert_thread_created")
+ ?.data,
+ ).toEqual({ expert_id: "expert-maria" }),
+ );
+ });
+
+ it("does not emit expert_thread_created for an Autopilot session", async () => {
+ let transportInventoryLoaded = false;
+ server.use(
+ http.post("*/api/chat/sessions", () =>
+ HttpResponse.json({
+ id: "new-autopilot-session",
+ created_at: "2026-01-01T00:00:00Z",
+ user_id: "user-1",
+ expert_id: null,
+ }),
+ ),
+ http.get("*/api/chat/sessions/new-autopilot-session", () =>
+ HttpResponse.json({
+ id: "new-autopilot-session",
+ created_at: "2026-01-01T00:00:00Z",
+ updated_at: "2026-01-01T00:00:00Z",
+ user_id: "user-1",
+ messages: [],
+ }),
+ ),
+ http.get("*/api/chat/transports", () => {
+ transportInventoryLoaded = true;
+ return HttpResponse.json({
+ transports: [
+ {
+ auth_provider: "platform",
+ credential_id: null,
+ label: "AutoGPT Platform",
+ available: true,
+ default: true,
+ },
+ ],
+ });
+ }),
+ getGetV2ListSessionsMockHandler200({ sessions: [], total: 0 }),
+ );
+
+ render(
+ <CredentialsProvidersContext.Provider value={{}}>
+ <EmptyNuqsWrapper>
+ <AutopilotSessionHarness />
+ </EmptyNuqsWrapper>
+ </CredentialsProvidersContext.Provider>,
+ );
+ await waitFor(() => expect(transportInventoryLoaded).toBe(true));
+ fireEvent.click(screen.getByRole("button", { name: "create" }));
+ await waitFor(() =>
+ expect(screen.getByTestId("session-id").textContent).toBe(
+ "new-autopilot-session",
+ ),
+ );
+
+ expect(funnelEventNames()).not.toContain("expert_thread_created");
});
it("opens the expert's latest thread when one already exists", async () => {
diff --git a/autogpt_platform/frontend/src/app/(platform)/copilot/useChatSession.ts b/autogpt_platform/frontend/src/app/(platform)/copilot/useChatSession.ts
index bcc45aef30..d1fa67f50e 100644
--- a/autogpt_platform/frontend/src/app/(platform)/copilot/useChatSession.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/copilot/useChatSession.ts
@@ -9,6 +9,7 @@ import type { CreateSessionRequest } from "@/app/api/__generated__/models/create
import { SESSION_LIST_QUERY_KEY } from "./useSessionList";
import { useCopilotUIStore } from "./store";
import { toast } from "@/components/molecules/Toast/use-toast";
+import { trackFunnel } from "@/services/experts/experts-analytics";
import * as Sentry from "@sentry/nextjs";
import { useQueryClient } from "@tanstack/react-query";
import { parseAsString, useQueryState } from "nuqs";
@@ -314,6 +315,9 @@ export function useChatSession({
.getState()
.bindPendingFirstSendToSession(response.data.id);
setSessionId(response.data.id);
+ if (expertId) {
+ trackFunnel("expert_thread_created", { expert_id: expertId });
+ }
queryClient.invalidateQueries({
queryKey: SESSION_LIST_QUERY_KEY,
});
diff --git a/autogpt_platform/frontend/src/app/(platform)/home/__tests__/main.test.tsx b/autogpt_platform/frontend/src/app/(platform)/home/__tests__/main.test.tsx
index d2998182c9..a0f0ebfe41 100644
--- a/autogpt_platform/frontend/src/app/(platform)/home/__tests__/main.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/home/__tests__/main.test.tsx
@@ -1,6 +1,7 @@
import userEvent from "@testing-library/user-event";
import { http, HttpResponse } from "msw";
-import { afterEach, expect, test, vi } from "vitest";
+import { StrictMode } from "react";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
import type { HomeAgentStatus } from "@/app/api/__generated__/models/homeAgentStatus";
import type { HomeAttentionItem } from "@/app/api/__generated__/models/homeAttentionItem";
import type { HomeBriefingOutcome } from "@/app/api/__generated__/models/homeBriefingOutcome";
@@ -14,6 +15,25 @@ import {
} from "@/tests/integrations/test-utils";
import HomePage from "../page";
+const { capture } = vi.hoisted(() => ({ capture: vi.fn() }));
+vi.mock("posthog-js", () => ({ default: { capture } }));
+
+/** Funnel events as PostHog received them, in order. */
+function funnelCalls() {
+ return capture.mock.calls.map(([event, data]) => ({
+ type: event as string,
+ data: (data ?? {}) as Record<string, unknown>,
+ }));
+}
+
+beforeEach(() => {
+ capture.mockReset();
+});
+
+function funnelEventNames() {
+ return capture.mock.calls.map(([event]) => event as string);
+}
+
const { setFlagStatusMock } = vi.hoisted(() => ({
setFlagStatusMock: vi.fn(() => ({ enabled: true, ready: true })),
}));
@@ -341,6 +361,82 @@ test("approving an item one-tap sends the review decision", async () => {
},
],
});
+ await waitFor(() =>
+ expect(
+ funnelCalls().find((body) => body.type === "home_attention_actioned")
+ ?.data,
+ ).toEqual({ kind: "approval", action: "approve" }),
+ );
+});
+
+test("declining an item records the confirmed decline", async () => {
+ const user = userEvent.setup();
+ const reviewRequests: unknown[] = [];
+ mockDashboard({ ...dashboard, attention: [approvalItem] });
+ server.use(
+ http.post("/api/proxy/api/review/action", async ({ request }) => {
+ reviewRequests.push(await request.json());
+ return HttpResponse.json({ failed_count: 0, processed_count: 1 });
+ }),
+ );
+
+ render(<HomePage />);
+
+ await user.click(
+ await screen.findByRole("button", {
+ name: "Decline: Approve the camera shortlist",
+ }),
+ );
+ await user.click(
+ screen.getByRole("button", {
+ name: "Confirm decline: Approve the camera shortlist",
+ }),
+ );
+
+ await waitFor(() => expect(reviewRequests).toHaveLength(1));
+ expect(reviewRequests[0]).toEqual({
+ reviews: [
+ {
+ node_exec_id: "node-exec-1",
+ approved: false,
+ auto_approve_future: false,
+ },
+ ],
+ });
+ await waitFor(() =>
+ expect(
+ funnelCalls().find((body) => body.type === "home_attention_actioned")
+ ?.data,
+ ).toEqual({ kind: "approval", action: "decline" }),
+ );
+});
+
+test("does not count a failed attention decision as actioned", async () => {
+ const user = userEvent.setup();
+ let reviewAttempts = 0;
+ mockDashboard({ ...dashboard, attention: [approvalItem] });
+ server.use(
+ http.post("/api/proxy/api/review/action", () => {
+ reviewAttempts += 1;
+ return HttpResponse.json({
+ failed_count: 1,
+ processed_count: 0,
+ error: "review failed",
+ });
+ }),
+ );
+
+ render(<HomePage />);
+ const approveButton = await screen.findByRole("button", {
+ name: "Approve: Approve the camera shortlist",
+ });
+ await user.click(approveButton);
+
+ await waitFor(() => expect(reviewAttempts).toBe(1));
+ await waitFor(() =>
+ expect(approveButton.hasAttribute("disabled")).toBe(false),
+ );
+ expect(funnelEventNames()).not.toContain("home_attention_actioned");
});
test("keeps a Review deep link alongside the approval shortcuts", async () => {
@@ -369,6 +465,7 @@ test("shows calm, useful empty states and drops the empty inbox", async () => {
agents: [],
recent_work: { groups: [], total_count: 0 },
});
+ server.use();
render(<HomePage />);
@@ -379,6 +476,32 @@ test("shows calm, useful empty states and drops the empty inbox", async () => {
expect(screen.queryByText("You are all caught up")).toBeNull();
expect(screen.getByText(/Nothing is scheduled/)).toBeDefined();
expect(screen.getByRole("link", { name: "Browse experts" })).toBeDefined();
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(funnelEventNames()).not.toContain("briefing_opened");
+});
+
+test("tracks briefing outcomes and team members with useful dimensions", async () => {
+ const user = userEvent.setup();
+ mockDashboard(dashboard);
+ server.use();
+
+ render(<HomePage />);
+
+ await user.click(
+ await screen.findByRole("link", { name: /Your camera research is ready/ }),
+ );
+ await user.click(await screen.findByRole("link", { name: "Manage Maria" }));
+
+ await waitFor(() => {
+ expect(
+ funnelCalls().find((body) => body.type === "briefing_outcome_clicked")
+ ?.data,
+ ).toEqual({ status: "completed" });
+ expect(
+ funnelCalls().find((body) => body.type === "home_team_member_clicked")
+ ?.data,
+ ).toEqual({ expert_id: "maria" });
+ });
});
test("shows a retryable page error when the aggregate cannot load", async () => {
@@ -398,12 +521,25 @@ test("shows a retryable page error when the aggregate cannot load", async () =>
expect(
await screen.findByText("Your Home briefing could not be loaded"),
).toBeDefined();
+ expect(funnelEventNames()).not.toContain("home_viewed");
await user.click(screen.getByRole("button", { name: /try again/i }));
expect(
await screen.findByRole("heading", { name: "Needs you" }),
).toBeDefined();
+ await waitFor(() => expect(funnelEventNames()).toContain("home_viewed"));
+});
+
+test("does not track home_viewed while feature state is loading", async () => {
+ setFlagStatusMock.mockReturnValueOnce({ enabled: true, ready: false });
+ server.use();
+
+ render(<HomePage />);
+ expect(screen.getByLabelText("Loading Home…")).toBeDefined();
+ await new Promise((resolve) => setTimeout(resolve, 0));
+
+ expect(funnelEventNames()).not.toContain("home_viewed");
});
test("calls notFound when the experts feature is disabled", () => {
@@ -466,3 +602,43 @@ test("renders the briefing unchanged when no narrative was generated", async ()
).toBeDefined();
expect(screen.getByText("Your camera research is ready")).toBeDefined();
});
+
+test("emits the home_viewed funnel event once the dashboard mounts", async () => {
+ server.use();
+ mockDashboard(dashboard);
+
+ render(<HomePage />);
+
+ await screen.findByRole("heading", { name: "Needs you" });
+ await waitFor(() => expect(funnelEventNames()).toContain("home_viewed"));
+});
+
+test("view events fire exactly once under StrictMode effect replay", async () => {
+ server.use();
+ // briefing_opened is an exposure event, so the briefing has to actually render.
+ mockDashboard({
+ ...dashboard,
+ briefing: {
+ ...dashboard.briefing,
+ narrative: "Two runs finished overnight.",
+ },
+ });
+
+ render(
+ <StrictMode>
+ <HomePage />
+ </StrictMode>,
+ );
+
+ await screen.findByRole("heading", { name: "Recent work" });
+ await waitFor(() => {
+ expect(funnelEventNames()).toContain("home_viewed");
+ expect(funnelEventNames()).toContain("briefing_opened");
+ });
+ await new Promise((resolve) => setTimeout(resolve, 50));
+
+ expect(funnelEventNames().filter((e) => e === "home_viewed")).toHaveLength(1);
+ expect(
+ funnelEventNames().filter((e) => e === "briefing_opened"),
+ ).toHaveLength(1);
+});
diff --git a/autogpt_platform/frontend/src/app/(platform)/home/components/AgentTeam/components/AgentRow.tsx b/autogpt_platform/frontend/src/app/(platform)/home/components/AgentTeam/components/AgentRow.tsx
index f154374ab4..7456efa14c 100644
--- a/autogpt_platform/frontend/src/app/(platform)/home/components/AgentTeam/components/AgentRow.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/home/components/AgentTeam/components/AgentRow.tsx
@@ -3,6 +3,7 @@ import { Button } from "@/components/atoms/Button/Button";
import { BubbleChatIcon, Settings01Icon } from "@hugeicons/core-free-icons";
import { Text } from "@/components/atoms/Text/Text";
import { ExpertAvatar } from "@/components/molecules/ExpertAvatar/ExpertAvatar";
+import { trackFunnel } from "@/services/experts/experts-analytics";
import { formatWeeklySpend } from "../../../helpers";
import { formatUntil } from "../../NowNext/helpers";
import { StatusBadge } from "./StatusBadge";
@@ -66,6 +67,11 @@ export function AgentRow({ agent }: Props) {
size="icon-sm"
leadingIcon={Settings01Icon}
aria-label={`Manage ${agent.expert.name}`}
+ onClick={() =>
+ trackFunnel("home_team_member_clicked", {
+ expert_id: agent.expert.id,
+ })
+ }
/>
</div>
</div>
diff --git a/autogpt_platform/frontend/src/app/(platform)/home/components/NeedsYou/useAttentionDecisions.ts b/autogpt_platform/frontend/src/app/(platform)/home/components/NeedsYou/useAttentionDecisions.ts
index 2418f975ef..1c5b361f05 100644
--- a/autogpt_platform/frontend/src/app/(platform)/home/components/NeedsYou/useAttentionDecisions.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/home/components/NeedsYou/useAttentionDecisions.ts
@@ -4,6 +4,7 @@ import { getGetHomeDashboardQueryKey } from "@/app/api/__generated__/endpoints/h
import type { HomeAttentionItem } from "@/app/api/__generated__/models/homeAttentionItem";
import { useToast } from "@/components/molecules/Toast/use-toast";
import { useProcessReviews } from "@/hooks/useProcessReviews";
+import { trackFunnel } from "@/services/experts/experts-analytics";
export function useAttentionDecisions() {
const queryClient = useQueryClient();
@@ -38,6 +39,10 @@ export function useAttentionDecisions() {
const message = response.status === 200 ? response.data.error : null;
throw new Error(message || "The review could not be processed.");
}
+ trackFunnel("home_attention_actioned", {
+ kind: item.kind,
+ action: approved ? "approve" : "decline",
+ });
toast({ title: approved ? "Approved" : "Declined" });
await queryClient.invalidateQueries({
queryKey: getGetHomeDashboardQueryKey(),
diff --git a/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/RecentWork.tsx b/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/RecentWork.tsx
index c80daad4ed..896c9d310a 100644
--- a/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/RecentWork.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/RecentWork.tsx
@@ -4,6 +4,7 @@ import { WorkHistoryIcon } from "@hugeicons/core-free-icons";
import type { HomeDashboardResponse } from "@/app/api/__generated__/models/homeDashboardResponse";
import type { HomeRecentWorkGroup } from "@/app/api/__generated__/models/homeRecentWorkGroup";
import { Text } from "@/components/atoms/Text/Text";
+import { useTrackFunnelViewOnce } from "@/services/experts/use-track-funnel-view-once";
import { HomeTile } from "../HomeTile/HomeTile";
import { HomeTileEmpty } from "../HomeTileEmpty/HomeTileEmpty";
import { BriefingByline } from "./components/BriefingByline";
@@ -25,6 +26,10 @@ export function RecentWork({ dashboard, className }: Props) {
const failed = dashboard.recent_work?.failed_count ?? 0;
const isEmpty = groups.length === 0 && !briefing.narrative;
+ // An exposure event: the briefing is an inline byline with no expand step,
+ // so it counts as opened once its content actually renders.
+ useTrackFunnelViewOnce("briefing_opened", Boolean(briefing.narrative));
+
return (
<HomeTile
className={className}
diff --git a/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/components/OutcomeRow.tsx b/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/components/OutcomeRow.tsx
index 673f4b14c2..200f4e20b6 100644
--- a/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/components/OutcomeRow.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/home/components/RecentWork/components/OutcomeRow.tsx
@@ -4,6 +4,7 @@ import type { HomeBriefingOutcome } from "@/app/api/__generated__/models/homeBri
import { Icon } from "@/components/atoms/Icon/Icon";
import { Text } from "@/components/atoms/Text/Text";
import { cn } from "@/lib/utils";
+import { trackFunnel } from "@/services/experts/experts-analytics";
import { formatWorkTime, getRunTriggerLabel } from "../helpers";
interface Props {
@@ -61,6 +62,9 @@ export function OutcomeRow({ outcome, timezone, showAgentName }: Props) {
return (
<Link
href={outcome.link}
+ onClick={() =>
+ trackFunnel("briefing_outcome_clicked", { status: outcome.status })
+ }
title={outcome.summary}
className={cn(ROW_CLASS, LINK_CLASS)}
>
diff --git a/autogpt_platform/frontend/src/app/(platform)/home/page.tsx b/autogpt_platform/frontend/src/app/(platform)/home/page.tsx
index 130cb45381..d50ad8cba8 100644
--- a/autogpt_platform/frontend/src/app/(platform)/home/page.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/home/page.tsx
@@ -5,6 +5,7 @@ import { getGreetingName } from "@/app/(platform)/copilot/components/EmptySessio
import { Skeleton } from "@/components/atoms/Skeleton/Skeleton";
import { ErrorCard } from "@/components/molecules/ErrorCard/ErrorCard";
import { useAuth } from "@/lib/auth/hooks/useAuth";
+import { useTrackFunnelViewOnce } from "@/services/experts/use-track-funnel-view-once";
import { Flag, useFlagStatus } from "@/services/feature-flags/use-get-flag";
import { AgentTeam } from "./components/AgentTeam/AgentTeam";
import { HomeHeader } from "./components/HomeHeader/HomeHeader";
@@ -26,6 +27,11 @@ export default function HomePage() {
enabled: Boolean(enabled) && ready,
});
+ useTrackFunnelViewOnce(
+ "home_viewed",
+ ready && !isLoading && !isError && Boolean(dashboard) && Boolean(enabled),
+ );
+
if (!ready || isLoading) {
return <HomeSkeleton />;
}
diff --git a/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/experts-section.test.tsx b/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/experts-section.test.tsx
index 4e72367153..3a05995324 100644
--- a/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/experts-section.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/experts-section.test.tsx
@@ -14,6 +14,21 @@ import { HttpResponse, http } from "msw";
import { beforeEach, describe, expect, test, vi } from "vitest";
import { MainMarkeplacePage } from "../components/MainMarketplacePage/MainMarketplacePage";
+const { capture } = vi.hoisted(() => ({ capture: vi.fn() }));
+vi.mock("posthog-js", () => ({ default: { capture } }));
+
+/** Funnel events as PostHog received them, in order. */
+function funnelCalls() {
+ return capture.mock.calls.map(([event, data]) => ({
+ type: event as string,
+ data: (data ?? {}) as Record<string, unknown>,
+ }));
+}
+
+beforeEach(() => {
+ capture.mockReset();
+});
+
const mockUseAuth = vi.hoisted(() => vi.fn());
const hireExpertsFlag = vi.hoisted(() => ({ enabled: true }));
@@ -248,6 +263,22 @@ describe("Marketplace ExpertsSection", () => {
expect(await screen.findByText("Hired")).toBeDefined();
});
+ test("emits the section view event once the shelf has rendered", async () => {
+ server.use(
+ getListExpertTemplatesMockHandler([mariaTemplate]),
+ getListExpertsMockHandler([]),
+ );
+
+ render(<MainMarkeplacePage />);
+
+ await screen.findByText("Maria");
+ await waitFor(() =>
+ expect(funnelCalls().map((body) => body.type)).toContain(
+ "experts_section_viewed",
+ ),
+ );
+ });
+
test("template becomes viewable again once the expert is fired", async () => {
server.use(
getListExpertTemplatesMockHandler([mariaTemplate]),
diff --git a/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/install-on-expert.test.tsx b/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/install-on-expert.test.tsx
index bae53b70d4..e51672e06a 100644
--- a/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/install-on-expert.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/marketplace/__tests__/install-on-expert.test.tsx
@@ -90,8 +90,12 @@ function renderAgentPage() {
);
}
+const datafast = vi.fn();
+
describe("Install on Expert from marketplace detail", () => {
beforeEach(() => {
+ datafast.mockReset();
+ (window as unknown as { datafast: typeof datafast }).datafast = datafast;
mockUseAuth.mockReturnValue({
user: { id: "user-1" },
isLoggedIn: true,
@@ -131,6 +135,9 @@ describe("Install on Expert from marketplace detail", () => {
expect(await screen.findByText("Installed on Maria")).toBeDefined();
expect(installExpertId).toBe("expert-maria");
expect(installBody).toEqual({ store_listing_version_id: "listing-1" });
+ expect(datafast).toHaveBeenCalledWith("workflow_installed_on_expert", {
+ expert_id: "expert-maria",
+ });
});
test("toasts success when the workflow is already installed", async () => {
diff --git a/autogpt_platform/frontend/src/app/(platform)/marketplace/components/ExpertsSection/ExpertsSection.tsx b/autogpt_platform/frontend/src/app/(platform)/marketplace/components/ExpertsSection/ExpertsSection.tsx
index 9068698842..373ae3ffa7 100644
--- a/autogpt_platform/frontend/src/app/(platform)/marketplace/components/ExpertsSection/ExpertsSection.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/marketplace/components/ExpertsSection/ExpertsSection.tsx
@@ -3,6 +3,7 @@
import { Skeleton } from "@/components/atoms/Skeleton/Skeleton";
import { AITeamIcon } from "@/components/atoms/AITeamIcon/AITeamIcon";
import { Button } from "@/components/atoms/Button/Button";
+import { useTrackFunnelViewOnce } from "@/services/experts/use-track-funnel-view-once";
import { SectionHeader } from "../SectionHeader";
import { ExpertCard } from "./components/ExpertCard";
import { useExpertsSection } from "./useExpertsSection";
@@ -18,6 +19,11 @@ export function ExpertsSection({ category }: Props) {
const { isLoggedIn, templates, hiredTemplateIds, isLoading, isError } =
useExpertsSection({ category });
+ useTrackFunnelViewOnce(
+ "experts_section_viewed",
+ !isLoading && !isError && templates.length > 0,
+ );
+
if (isError || (!isLoading && templates.length === 0)) {
// Under a category filter an empty shelf means "no experts in this
// category", so the whole section goes rather than inviting a raise.
diff --git a/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertHireActions.tsx b/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertHireActions.tsx
index 0698cc9732..fd6ff6d3b3 100644
--- a/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertHireActions.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertHireActions.tsx
@@ -2,6 +2,7 @@ import { Expert } from "@/app/api/__generated__/models/expert";
import { Badge } from "@/components/atoms/Badge/Badge";
import { Button } from "@/components/atoms/Button/Button";
import { Icon } from "@/components/atoms/Icon/Icon";
+import { trackFunnel } from "@/services/experts/experts-analytics";
import { markHireStarted } from "@/services/experts/hire-timing";
import { CheckmarkCircle02Icon } from "@hugeicons/core-free-icons";
@@ -69,6 +70,7 @@ export function ExpertHireActions({
// in a dialog, and sometimes on another page entirely.
function handleHire() {
markHireStarted(expert.id);
+ trackFunnel("hire_started", { template_id: expert.id });
onHire();
}
diff --git a/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertPage.tsx b/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertPage.tsx
index 7c740c0dad..49ac04df0c 100644
--- a/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertPage.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/[expertId]/components/ExpertPage.tsx
@@ -26,6 +26,7 @@ import { ExpertSkills } from "./ExpertSkills";
import { ExpertWorkflowList } from "./ExpertWorkflowList";
import { useExpertPage } from "../useExpertPage";
import { useHireFlow } from "@/services/experts/useHireFlow";
+import { useTrackExpertProfileOpened } from "@/services/experts/use-track-funnel-view-once";
const MAIN_CLASS =
"mx-auto flex w-full max-w-[760px] flex-col px-6 pb-24 pt-8 md:px-8";
@@ -44,6 +45,7 @@ function BackToMarketplaceLink() {
export function ExpertPage() {
const { expertId } = useParams<{ expertId: string }>();
+ useTrackExpertProfileOpened(expertId);
const {
expert,
hiredExpert,
diff --git a/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/__tests__/expert-page.test.tsx b/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/__tests__/expert-page.test.tsx
index 3c19e012eb..7745df9dea 100644
--- a/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/__tests__/expert-page.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/marketplace/experts/__tests__/expert-page.test.tsx
@@ -20,6 +20,21 @@ import { HttpResponse, http } from "msw";
import { beforeEach, describe, expect, test, vi } from "vitest";
import { ExpertPage as MarketplaceExpertPage } from "../[expertId]/components/ExpertPage";
+const { capture } = vi.hoisted(() => ({ capture: vi.fn() }));
+vi.mock("posthog-js", () => ({ default: { capture } }));
+
+/** Funnel events as PostHog received them, in order. */
+function funnelCalls() {
+ return capture.mock.calls.map(([event, data]) => ({
+ type: event as string,
+ data: (data ?? {}) as Record<string, unknown>,
+ }));
+}
+
+beforeEach(() => {
+ capture.mockReset();
+});
+
const mockUseAuth = vi.hoisted(() => vi.fn());
const mockRouterPush = vi.hoisted(() => vi.fn());
const mockParams = vi.hoisted(() => ({ expertId: "template-maria" }));
@@ -199,6 +214,33 @@ describe("Marketplace expert page", () => {
);
});
+ test("emits the profile-opened and hire-started funnel events", async () => {
+ server.use(
+ getListExpertTemplatesMockHandler([mariaTemplate]),
+ getListExpertsMockHandler([]),
+ getHireExpertMockHandler({ expert: hiredMaria, failed_preloads: [] }),
+ );
+
+ renderPage();
+
+ await waitFor(() =>
+ expect(
+ funnelCalls().find((body) => body.type === "expert_profile_opened")
+ ?.data,
+ ).toEqual({ template_id: mariaTemplate.id }),
+ );
+
+ await userEvent.click(
+ await screen.findByRole("button", { name: "Hire Maria" }),
+ );
+
+ await waitFor(() =>
+ expect(
+ funnelCalls().find((body) => body.type === "hire_started")?.data,
+ ).toEqual({ template_id: mariaTemplate.id }),
+ );
+ });
+
test("says when a bundled workflow runs on a schedule, before hiring", async () => {
server.use(
getListExpertTemplatesMockHandler([
diff --git a/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.test.tsx b/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.test.tsx
index bdfce67ffe..feea27ed7e 100644
--- a/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.test.tsx
+++ b/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.test.tsx
@@ -59,6 +59,8 @@ describe("useFireExpertDialog invalidation", () => {
const client = makeClient();
const invalidateSpy = vi.spyOn(client, "invalidateQueries");
const onFired = vi.fn();
+ const datafast = vi.fn();
+ (window as unknown as { datafast: typeof datafast }).datafast = datafast;
const { result } = renderHook(
() =>
@@ -87,6 +89,9 @@ describe("useFireExpertDialog invalidation", () => {
containsKey(calls, getGetV1ListExecutionSchedulesForAUserQueryKey()),
).toBe(true);
expect(containsKey(calls, ["/api/library/agents"])).toBe(true);
+ expect(datafast).toHaveBeenCalledWith("expert_fired", {
+ expert_id: "expert-maria",
+ });
});
it("does not fire before the preview has resolved", async () => {
diff --git a/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.ts b/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.ts
index 4c1f99ed70..3373535094 100644
--- a/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.ts
+++ b/autogpt_platform/frontend/src/app/(platform)/team/components/FireExpertDialog/useFireExpertDialog.ts
@@ -9,6 +9,7 @@ import { toast } from "@/components/molecules/Toast/use-toast";
import { invalidateExpertRosterQueries } from "@/services/experts/invalidate-experts";
import { invalidateAllScheduleQueries } from "@/services/schedules/invalidate-schedules";
import { useQueryClient } from "@tanstack/react-query";
+import { analytics } from "@/services/analytics";
interface Args {
expertId: string;
@@ -34,6 +35,7 @@ export function useFireExpertDialog({
const { mutate, isPending: isFiring } = useArchiveExpert({
mutation: {
onSuccess: async () => {
+ analytics.sendDatafastEvent("expert_fired", { expert_id: expertId });
await Promise.all([
invalidateExpertRosterQueries(queryClient),
queryClient.invalidateQueries({
diff --git a/autogpt_platform/frontend/src/components/molecules/InstallWorkflowPicker/useInstallWorkflowPicker.ts b/autogpt_platform/frontend/src/components/molecules/InstallWorkflowPicker/useInstallWorkflowPicker.ts
index 32f227bc1d..4722e551d9 100644
--- a/autogpt_platform/frontend/src/components/molecules/InstallWorkflowPicker/useInstallWorkflowPicker.ts
+++ b/autogpt_platform/frontend/src/components/molecules/InstallWorkflowPicker/useInstallWorkflowPicker.ts
@@ -17,6 +17,7 @@ import { LibraryAgent } from "@/app/api/__generated__/models/libraryAgent";
import { StoreAgent } from "@/app/api/__generated__/models/storeAgent";
import { StoreAgentsResponse } from "@/app/api/__generated__/models/storeAgentsResponse";
import { toast } from "@/components/molecules/Toast/use-toast";
+import { analytics } from "@/services/analytics";
import { useDebouncedValue } from "@/hooks/useDebouncedValue";
import { useQueryClient } from "@tanstack/react-query";
import { useEffect, useState } from "react";
@@ -179,6 +180,9 @@ export function useInstallWorkflowPicker({
}
try {
await installWorkflow({ expertId: expert.id, data });
+ analytics.sendDatafastEvent("workflow_installed_on_expert", {
+ expert_id: expert.id,
+ });
// Both: the picker is opened from the team list and from one expert's
// own page, whose workflow section reads the single-expert query.
await Promise.all([
diff --git a/autogpt_platform/frontend/src/services/experts/experts-analytics.test.ts b/autogpt_platform/frontend/src/services/experts/experts-analytics.test.ts
new file mode 100644
index 0000000000..1764d9dac4
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/experts/experts-analytics.test.ts
@@ -0,0 +1,67 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { trackFunnel } from "./experts-analytics";
+
+const { capture, addBreadcrumb } = vi.hoisted(() => ({
+ capture: vi.fn(),
+ addBreadcrumb: vi.fn(),
+}));
+
+vi.mock("posthog-js", () => ({ default: { capture } }));
+vi.mock("@sentry/nextjs", () => ({ addBreadcrumb }));
+
+describe("trackFunnel", () => {
+ beforeEach(() => {
+ capture.mockReset();
+ addBreadcrumb.mockReset();
+ });
+
+ it("captures the event and its payload to PostHog", () => {
+ trackFunnel("expert_profile_opened", { template_id: "template-maria" });
+
+ expect(capture).toHaveBeenCalledExactlyOnceWith("expert_profile_opened", {
+ template_id: "template-maria",
+ });
+ });
+
+ it("captures a view event with no payload", () => {
+ trackFunnel("experts_section_viewed");
+
+ expect(capture).toHaveBeenCalledExactlyOnceWith(
+ "experts_section_viewed",
+ undefined,
+ );
+ });
+
+ it("leaves a breadcrumb so the step shows on an error's timeline", () => {
+ trackFunnel("hire_started", { template_id: "template-maria" });
+
+ expect(addBreadcrumb).toHaveBeenCalledExactlyOnceWith({
+ category: "funnel",
+ message: "hire_started",
+ data: { template_id: "template-maria" },
+ level: "info",
+ });
+ });
+
+ it("breadcrumbs before capturing, so a failing capture still leaves one", () => {
+ capture.mockImplementation(() => {
+ throw new Error("analytics unavailable");
+ });
+
+ expect(() => trackFunnel("home_viewed")).not.toThrow();
+ expect(addBreadcrumb).toHaveBeenCalledOnce();
+ });
+
+ it("still captures when the breadcrumb throws", () => {
+ // The two sinks are independent: losing Sentry must not lose PostHog.
+ addBreadcrumb.mockImplementation(() => {
+ throw new Error("sentry unavailable");
+ });
+
+ expect(() => trackFunnel("briefing_opened")).not.toThrow();
+ expect(capture).toHaveBeenCalledExactlyOnceWith(
+ "briefing_opened",
+ undefined,
+ );
+ });
+});
diff --git a/autogpt_platform/frontend/src/services/experts/experts-analytics.ts b/autogpt_platform/frontend/src/services/experts/experts-analytics.ts
index c8728a4bce..e6f63c7941 100644
--- a/autogpt_platform/frontend/src/services/experts/experts-analytics.ts
+++ b/autogpt_platform/frontend/src/services/experts/experts-analytics.ts
@@ -1,14 +1,60 @@
-// Hire-funnel events. The backend `hire_completed` record stays the
-// source-of-truth count; these answer how long the flow took and where people
-// drop out of it. Capture is best-effort — a blocked analytics host must
-// never interrupt a hire.
+// Experts + home funnel events (SECRT-2526 / SECRT-2552). Capture is
+// best-effort: a blocked analytics host must never break a hire, a briefing, or
+// a home render. The breadcrumb puts the same step on the timeline of any
+// error Sentry records afterwards.
+import * as Sentry from "@sentry/nextjs";
import posthog from "posthog-js";
-type ExpertsEvent =
- | "hire_started"
- | "hire_flow_completed"
- | "hire_flow_abandoned";
+export type FunnelViewEvent =
+ | "experts_section_viewed"
+ | "home_viewed"
+ | "briefing_opened";
+
+interface FunnelEventProperties {
+ expert_profile_opened: { template_id: string };
+ hire_started: { template_id: string };
+ expert_thread_created: { expert_id: string };
+ briefing_outcome_clicked: { status: string };
+ home_attention_actioned: {
+ kind: string;
+ action: "approve" | "decline";
+ };
+ home_team_member_clicked: { expert_id: string };
+}
+
+type FunnelEvent = FunnelViewEvent | keyof FunnelEventProperties;
+
+export function trackFunnel(event: FunnelViewEvent): void;
+export function trackFunnel<Event extends keyof FunnelEventProperties>(
+ event: Event,
+ properties: FunnelEventProperties[Event],
+): void;
+
+export function trackFunnel(
+ event: FunnelEvent,
+ properties?: Record<string, unknown>,
+) {
+ // Separate boundaries: a breadcrumb failure must not cost the capture.
+ try {
+ Sentry.addBreadcrumb({
+ category: "funnel",
+ message: event,
+ data: properties ?? {},
+ level: "info",
+ });
+ } catch {
+ // Analytics is never worth a broken interaction.
+ }
+
+ try {
+ posthog.capture(event, properties);
+ } catch {
+ // Analytics is never worth a broken interaction.
+ }
+}
+
+type ExpertsEvent = "hire_flow_completed" | "hire_flow_abandoned";
export function trackExperts(
event: ExpertsEvent,
diff --git a/autogpt_platform/frontend/src/services/experts/use-track-funnel-view-once.ts b/autogpt_platform/frontend/src/services/experts/use-track-funnel-view-once.ts
new file mode 100644
index 0000000000..3b65994884
--- /dev/null
+++ b/autogpt_platform/frontend/src/services/experts/use-track-funnel-view-once.ts
@@ -0,0 +1,24 @@
+import { useEffect, useRef } from "react";
+import { trackFunnel, type FunnelViewEvent } from "./experts-analytics";
+
+export function useTrackFunnelViewOnce(event: FunnelViewEvent, enabled = true) {
+ const trackedRef = useRef(false);
+
+ useEffect(() => {
+ if (trackedRef.current || !enabled) return;
+ trackedRef.current = true;
+ trackFunnel(event);
+ }, [enabled, event]);
+}
+
+/** Keyed on the id, not on the mount: Next.js reuses the expert page's tree
+ * when navigating between two profiles, which a mount-once guard would miss. */
+export function useTrackExpertProfileOpened(templateId: string | undefined) {
+ const trackedRef = useRef<string | null>(null);
+
+ useEffect(() => {
+ if (!templateId || trackedRef.current === templateId) return;
+ trackedRef.current = templateId;
+ trackFunnel("expert_profile_opened", { template_id: templateId });
+ }, [templateId]);
+}
diff --git a/autogpt_platform/frontend/src/services/experts/useHireFlow.tsx b/autogpt_platform/frontend/src/services/experts/useHireFlow.tsx
index 587e06f16f..b494f5c191 100644
--- a/autogpt_platform/frontend/src/services/experts/useHireFlow.tsx
+++ b/autogpt_platform/frontend/src/services/experts/useHireFlow.tsx
@@ -11,6 +11,7 @@ import {
buildVoicePreferences,
type VoicePickResult,
} from "@/components/organisms/VoicePicker/helpers";
+import { analytics } from "@/services/analytics";
import { trackExperts } from "@/services/experts/experts-analytics";
import { takeHireElapsedMs } from "@/services/experts/hire-timing";
import { invalidateExpertRosterQueries } from "@/services/experts/invalidate-experts";
@@ -79,6 +80,10 @@ export function useHireFlow(expert: Expert | null) {
try {
const response = await hireExpert({ data: { template_id: expert.id } });
const result = response.data as HireResult;
+ analytics.sendDatafastEvent("hire_completed", {
+ template_id: expert.id,
+ expert_id: result.expert.id,
+ });
await invalidateExpertRosterQueries(queryClient);
pendingCelebrationRef.current = result;
setHireResult(result);