Skip to content

Add background-workers agent example with Node.js Worker Threads#27

Open
cerashdan wants to merge 3 commits intomainfrom
feat/add-background-workers-agent-example
Open

Add background-workers agent example with Node.js Worker Threads#27
cerashdan wants to merge 3 commits intomainfrom
feat/add-background-workers-agent-example

Conversation

@cerashdan
Copy link
Copy Markdown
Contributor

This commit adds a new sample demonstrating how to use Node.js Worker Threads to handle CPU-blocking operations without freezing the agent's main thread. Due to the single-thread nature of Node JS, any blocking operation such as file operations and loop will block the AI agent from receiving new incoming requests.

New Features:

  • Background worker agent using worker_threads for CPU-intensive tasks
  • Fire-and-forget pattern: agent returns immediately without waiting for workers
  • get_task_status tool using app.getAsyncTaskInfo() for monitoring active tasks
  • Non-blocking architecture allowing concurrent request handling
  • Comprehensive documentation on blocking vs non-blocking operations

Changes:

  • primitives/runtime/background-workers/: New sample with agent, worker, and docs
  • primitives/runtime/async-agent/: Added get_task_status tool for consistency
  • primitives/runtime/README.md: Added link to new background-workers sample

The example demonstrates:

  • Worker threads for blocking operations (loops, dataset processing, calculations)

  • Main thread stays responsive while workers process in background

  • Multiple concurrent workers can run simultaneously

  • Health status tracking (Healthy/HealthyBusy)

  • Message passing between main thread and worker threads

  • New example

  • Bug fix

  • Documentation update

  • Configuration/tooling update

  • Other (describe below)

Related Issues

Closes #16

Checklist

  • I have read the CONTRIBUTING guidelines
  • My code follows the existing style patterns
  • I have run npm run validate locally and it passes
  • I have added/updated documentation as needed
  • I have tested my changes locally

This commit adds a new sample demonstrating how to use Node.js Worker Threads
to handle CPU-blocking operations without freezing the agent's main thread.

New Features:
- Background worker agent using worker_threads for CPU-intensive tasks
- Fire-and-forget pattern: agent returns immediately without waiting for workers
- get_task_status tool using app.getAsyncTaskInfo() for monitoring active tasks
- Non-blocking architecture allowing concurrent request handling
- Comprehensive documentation on blocking vs non-blocking operations

Changes:
- primitives/runtime/background-workers/: New sample with agent, worker, and docs
- primitives/runtime/async-agent/: Added get_task_status tool for consistency
- primitives/runtime/README.md: Added link to new background-workers sample

The example demonstrates:
- Worker threads for blocking operations (loops, dataset processing, calculations)
- Main thread stays responsive while workers process in background
- Multiple concurrent workers can run simultaneously
- Health status tracking (Healthy/HealthyBusy)
- Message passing between main thread and worker threads
@cerashdan cerashdan requested a review from niklas-palm February 1, 2026 16:15
@cerashdan cerashdan linked an issue Feb 1, 2026 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: Add background workers agent example

1 participant