Improve agent logging

[tkattkat]

Why

The agent currently provides no indication when it stops due to reaching the max step limit. Users see success: false and completed: false but have no way to distinguish between a max steps stop vs other failure scenarios.

Additionally, tool logs display arguments as stringified JSON which is hard to read.

What Changed

Max steps indication:

• Added INFO-level log: Agent stopped: reached maximum steps (X)
• Set the result message field to indicate the stop reason
• Only triggers when step count actually reaches maxSteps (not on other incomplete executions)

Tool logging cleanup:

• Changed tool logs to use type: "object"
• Removed verbose/redundant fields (coordinates, processed) from some tool logs

Test Plan

• Run agent with a low maxSteps value (e.g., 2)
• Verify log output shows: Agent stopped: reached maximum steps (2)
• Verify result.message contains the max steps indication
• Verify result.success is false and result.completed is false
• Verify result.actions still contains all actions performed before stopping

[changeset-bot]

🦋 Changeset detected

Latest commit: a01ddd0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch
@browserbasehq/stagehand-server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

No issues found across 2 files

[greptile-apps]

Greptile Summary

This PR improves the user experience when an agent execution stops due to reaching the maximum step limit. Previously, users would only see success: false and completed: false with no clear indication of why the agent stopped.

Changes made:

• Added maxSteps parameter to consolidateMetricsAndResult method (passed from both execute and stream methods)
• Added a check in consolidateMetricsAndResult to detect when the agent stops due to max steps: !state.completed && maxSteps && result.steps?.length >= maxSteps
• When max steps is reached, logs an INFO message: "Agent stopped: reached maximum steps (X)"
• Sets state.finalMessage to indicate the stop reason, which becomes the result.message field returned to users

The implementation correctly distinguishes between normal completion (when the agent calls the close tool with taskComplete) and max steps termination. The logging and messaging provide clear feedback to help users understand why their agent execution did not complete successfully.

Confidence Score: 5/5

• This PR is safe to merge with no risk
• The changes are minimal, well-scoped, and purely additive - they only add logging and improve the user-facing error message. The logic correctly checks the max steps condition and doesn't affect any other code paths. No breaking changes or risky refactoring.
• No files require special attention

Important Files Changed

Filename	Overview
.changeset/early-hats-read.md	Standard changeset file documenting the improvement to agent logging
packages/core/lib/v3/handlers/v3AgentHandler.ts	Adds logging and result message when agent hits max steps limit - implementation looks correct

Sequence Diagram

sequenceDiagram
    participant User
    participant AgentHandler
    participant LLMClient
    participant Logger

    User->>AgentHandler: execute(instruction, maxSteps=2)
    AgentHandler->>AgentHandler: prepareAgent()
    AgentHandler->>LLMClient: generateText() with stopWhen
    
    loop Each Step
        LLMClient->>AgentHandler: onStepFinish(step)
        AgentHandler->>Logger: Log step finished
    end
    
    LLMClient-->>AgentHandler: result (steps.length >= maxSteps)
    AgentHandler->>AgentHandler: consolidateMetricsAndResult(result, maxSteps)
    
    alt Max steps reached
        AgentHandler->>AgentHandler: Check !completed && steps >= maxSteps
        AgentHandler->>Logger: Log "Agent stopped: reached maximum steps (2)"
        AgentHandler->>AgentHandler: Set finalMessage
    else Normal completion
        AgentHandler->>AgentHandler: Use collectedReasoning
    end
    
    AgentHandler-->>User: AgentResult {success: false, message: "Agent stopped...", completed: false}

Loading