feat: add get_current_state workflow query to BaseWorkflow

[gabrycina]

Summary

Adds a default @workflow.query handler named get_current_state to BaseWorkflow, enabling external callers to query an agent's current workflow state via Temporal queries.

Problem

When programmatically invoking agentic agents in multi-turn conversations, there's no way to know when the agent has finished processing a turn. The task stays RUNNING throughout. During long-running operations (e.g. deep research), agents emit multiple progress messages that look like responses but aren't the final answer.

Solution

Add a get_current_state query to BaseWorkflow that returns the workflow's current state string. By default it returns _workflow_state (set to "initialized").

Agents using the StateMachine SDK should override this to return the actual state:

@workflow.query(name="get_current_state")
def get_current_state(self) -> str:
    return self.state_machine.get_current_state()

This enables callers to detect "waiting_for_input" — the definitive signal that the agent has finished its turn.

Companion PR

• Server endpoint: feat: add workflow query endpoint for agent state inspection scale-agentex#173 — adds GET /tasks/{task_id}/query/{query_name} to the Agentex REST API

Together, these changes enable:

GET /tasks/{task_id}/query/get_current_state
→ {"result": "waiting_for_input"}   # agent is done with this turn
→ {"result": "researching"}          # agent is still working

Follows the pattern of Google A2A protocol's INPUT_REQUIRED task state.

🤖 Generated with Claude Code

Greptile Summary

This PR adds a get_current_state Temporal query handler to BaseWorkflow, enabling external callers to poll the workflow's current state via the forthcoming GET /tasks/{task_id}/query/{query_name} REST endpoint. The base implementation returns "unknown", with documentation showing how StateMachine-based subclasses should override it to expose meaningful states like "waiting_for_input".

Key changes:

• Adds @workflow.query(name="get_current_state") to BaseWorkflow returning "unknown" by default.
• Documents the override pattern for StateMachine-based agents so they can return the actual state machine state.
• The previous review concern about _workflow_state never being updated is resolved — the final implementation drops the attribute entirely and simply returns "unknown".
• Note: the two scaffolding templates (temporal/project/workflow.py.j2 and temporal-openai-agents/project/workflow.py.j2) are not updated here; agents generated from those templates will always return "unknown" until they explicitly override this method.

Confidence Score: 5/5

• Safe to merge — minimal, non-breaking addition of a single query handler with a sensible default.
• The change is small (one method, ~15 lines), purely additive, and has no side-effects on existing workflows. The default "unknown" return is honest and non-breaking; callers that don't yet use this query are unaffected. The docstring clearly guides subclass authors on the correct override pattern including re-applying the @workflow.query decorator, consistent with how @workflow.signal overrides are already handled in the templates.
• No files require special attention.

Important Files Changed

Filename	Overview
src/agentex/lib/core/temporal/workflows/workflow.py	Adds a get_current_state Temporal query handler to BaseWorkflow returning "unknown" by default, with documentation showing how StateMachine-based subclasses should override it.

Sequence Diagram

sequenceDiagram
    participant Caller as External Caller
    participant Agentex as Agentex API
    participant Temporal as Temporal Worker
    participant WF as Workflow (BaseWorkflow subclass)
    participant SM as StateMachine (optional)

    Caller->>Agentex: GET /tasks/{task_id}/query/get_current_state
    Agentex->>Temporal: QueryWorkflow("get_current_state")
    Temporal->>WF: get_current_state()
    alt StateMachine-based workflow
        WF->>SM: get_current_state()
        SM-->>WF: "waiting_for_input" / "researching" / ...
    else Base/non-SM workflow
        WF-->>WF: return "unknown"
    end
    WF-->>Temporal: state string
    Temporal-->>Agentex: result
    Agentex-->>Caller: {"result": "waiting_for_input"}

Loading

_{Reviews (4): Last reviewed commit: "feat: add get_current_state workflow que..." | Re-trigger Greptile}