GeezerVison

Problem

heartbeat_if_in_workflow() in src/agentex/lib/utils/temporal.py never sends a heartbeat:

def heartbeat_if_in_workflow(heartbeat_name: str):
    if in_temporal_workflow():          # workflow.in_workflow()
        activity.heartbeat(heartbeat_name)

activity.heartbeat() is only legal inside an activity, and inside an activity workflow.in_workflow() is False. So the guard never passes where a heartbeat is possible. The helper is called 36 times across the ADK services: tasks, messages, streaming, the LiteLLM/OpenAI/SGP providers (including inside their streaming loops), ACP, tracing and templating. All of those run inside activities, and none of them heartbeat.

The shipped defaults hide this because each provider module sets heartbeat_timeout equal to start_to_close_timeout. An agent that sets a shorter heartbeat_timeout on a long activity gets ActivityTaskTimedOut (HEARTBEAT) on every attempt, which is the standard Temporal pattern for long LLM calls. It also means activity cancellation is never delivered through the heartbeat channel.

Fix

• Add heartbeat_if_in_activity(). It heartbeats when activity.in_activity() is true and is a silent no-op everywhere else, including workflow code and sync agents.
• Keep heartbeat_if_in_workflow() as an alias, so every existing call site starts heartbeating without being touched. Renaming the call sites can be a follow-up if you want the old name gone.

One behaviour change to expect: with heartbeats flowing, activities now receive Temporal's cancellation when their workflow cancels them, instead of running to completion.

Verification

• temporalio.testing.ActivityEnvironment, with on_heartbeat collecting heartbeats from an activity that calls the helper:
  • On main: heartbeat_if_in_workflow("doing slow work") records [].
  • On this branch: it records [('doing slow work',)]. The new heartbeat_if_in_activity records the same.
• New tests in tests/lib/test_temporal_utils.py:
  • one heartbeat inside an activity, for both names;
  • a silent no-op outside an activity.
• uv run pytest -n 0 tests/lib/test_temporal_utils.py tests/lib/core/services tests/lib/core/temporal: 74 passed.
• ruff check and pyright are clean on both files.

Confidence Score: 4/5

The PR is not ready to merge because a long pause in a streamed turn can still time out the activity.

Findings

1.  Live OpenAI streams time out ▶

### Issue 1
src/agentex/lib/utils/temporal.py:22-23
`run_agent_streamed_auto_send` now sends a heartbeat at the start, but sends none while it streams. If a caller sets `heartbeat_timeout` shorter than the stream’s duration, Temporal can time out and retry an activity that is still sending messages. This path needs heartbeats while the stream runs.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

The PR routes shared Temporal heartbeat calls through the activity context and adds a heartbeat for every event delivered by auto_send(). The old helper name stays available, so existing callers use the corrected behavior.

• Activity heartbeats now reach Temporal from activity code.
• Streamed-turn delivery sends heartbeats as events arrive.

_{Reviews (2) · Last reviewed commit: "fix(harness): heartbeat while auto_send ..."}