feat(react): add enabled prop to useAgent hook for conditional connections

[Suhaib3100]

Summary

This PR adds an enabled prop to the useAgent hook, allowing for conditional agent connections. This is a feature that was requested in issue #533.

Problem

Currently, when using useAgent, the connection is always established immediately when the hook is called. This makes it difficult to implement patterns like:

• Only connecting when a user is authenticated
• Deferring connection until a component is visible (lazy loading)
• Feature flag based conditional connections

Solution

Added an enabled optional boolean prop to UseAgentOptions that controls whether the agent connection should be established.

Implementation Details

1. Type Definition: Added enabled?: boolean to UseAgentOptions with JSDoc documentation explaining the behavior
2. Default Value: enabled defaults to true to maintain backward compatibility
3. Initial State: Uses startClosed: !enabled to control the initial connection state via PartySocket
4. State Transitions: Added a useEffect with a prevEnabledRef to handle dynamic changes:
   • When enabled transitions from false to true: calls agent.reconnect()
   • When enabled transitions from true to false: calls agent.close()

Usage Example

const [isAuthenticated, setIsAuthenticated] = useState(false);

// Connection is only established when isAuthenticated is true
const agent = useAgent({
  agent: MyAgent,
  enabled: isAuthenticated,
});

Changes

• packages/agents/src/react.tsx: Added enabled prop to UseAgentOptions type and implementation in useAgent hook
• packages/agents/src/react-tests/enabled-prop.test.ts: Added comprehensive test suite (14 tests) covering:
  • Type definitions
  • Connection lifecycle (startClosed logic)
  • State transition logic
  • Integration with other options
  • Common use cases (auth-based, feature flag, lazy loading)

Testing

All 14 new tests pass:

✓ useAgent enabled prop (issue #533) > Type definitions > should accept enabled as an optional boolean prop
✓ useAgent enabled prop (issue #533) > Type definitions > should default enabled to true when not specified
✓ useAgent enabled prop (issue #533) > Connection lifecycle > should start closed when enabled is false
... (11 more tests)

Checklist

• Tests added
• Types updated
• Documentation (JSDoc) added
• Changeset added
• Backward compatible (defaults to true)

Closes #533

[changeset-bot]

🦋 Changeset detected

Latest commit: 6c09b80

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

This PR includes changesets to release 4 packages

Name	Type
agents	Major
@cloudflare/ai-chat	Major
@cloudflare/codemode	Major
hono-agents	Major

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/cloudflare/agents@798

commit: 6c09b80

[threepointone]

fixed in cloudflare/partykit#315