feat: typescript graph support #76
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Implement is_node_graph() to detect TS/JS graphs by file extension - Add node_version validation following LangGraph CLI patterns - Create AegraConfig class for loading and validating aegra.json - Support mixed Python/TypeScript graph configurations
- Create TypeScriptRuntime class for managing Node.js processes - Implement IPC communication via JSON streams - Add support for both bun and node runtimes - Create TypeScript wrapper script for graph execution - Integrate with PostgreSQL checkpointer for state persistence - Auto-detect and prefer bun over node when available
- Import TypeScript detection and runtime modules - Detect graph type (Python/TypeScript) in _load_graph_registry - Add _get_typescript_graph() method for TS graph wrappers - Route TypeScript graphs to TS runtime manager - Lazy-load TypeScript runtime when needed - Maintain backward compatibility with Python graphs
- Create ts_example_agent as reference implementation - Add simple chatbot graph with state management - Include package.json with LangGraph dependencies - Configure TypeScript with tsconfig.json - Update aegra.json to register TypeScript graph - Add node_version configuration
- Create @aegra/sdk package with full type definitions - Implement AegraClient with Assistants/Threads/Runs APIs - Add SSE streaming support for run execution - Support authentication and custom headers - Follow LangGraph SDK patterns for compatibility - Include comprehensive README with examples - Configure TypeScript build with declarations
- Explain TypeScript graph execution architecture - Provide configuration reference and examples - Document TypeScript SDK usage - Include troubleshooting guide - Add performance considerations - Show migration path from LangGraph Platform
- Create unit tests for configuration parser - Add tests for graph type detection - Test Node.js version validation - Add integration tests for mixed Python/TS graphs - Create manual testing guide with examples - Include debugging section - Add performance testing guidance
- Add database mocking to avoid initialization requirement - Tests now run without PostgreSQL running - All 5 integration tests now pass - Verify TypeScript detection and wrapper creation
- Remove manually specified versions - Use bun add to install @langchain/langgraph@1.0.0 - Use bun add to install @langchain/core@1.0.1 - Add proper devDependencies with bun add -D - Update SDK package.json with bun-installed versions - Include bun-generated files
- Add astream() method required by LangGraph SDK - Delegate to stream() method for compatibility - Fixes: 'TypeScriptGraphWrapper' object has no attribute 'astream'
- Add **kwargs to astream() signature - Merge kwargs into config for compatibility - Fixes: astream() got unexpected keyword argument 'context'
- Use os.getenv('DATABASE_URL') instead of db_manager.database_url
- db_manager doesn't expose database_url as attribute
- Fixes: 'DatabaseManager' object has no attribute 'database_url'
- Change wrapper path from ts_graph_wrapper.js to .ts - Bun can execute TypeScript files directly - Fixes: TypeScript graph wrapper not found
- Remove callbacks, tags from config before JSON serialization - Add _is_json_serializable() helper method - Keep configurable dict for thread_id, run_id, etc. - Fixes: Object of type LangchainCallbackHandler is not JSON serializable
Fixed three critical issues with TypeScript graph execution:
1. Event format (ts_graph_wrapper.ts): Removed double-wrapping of events
- Events now stream in proper LangGraph format
- Matches Python graph streaming behavior
2. TypeScript SDK (sdk/src/client.ts): Fixed compilation and parsing
- Added type assertions to fix 3 compilation errors
- Implemented proper SSE parsing (separate event: and data: lines)
- SDK now correctly extracts event types from SSE stream
3. Backwards compatibility (langgraph_service.py): Fixed unit tests
- Use .get("type", "python") to handle missing type field
- Prevents KeyError in existing code and tests
All 512 tests now passing (344 unit + 147 integration + 21 manual).
TypeScript graphs work with both Python SDK and TypeScript SDK.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added comprehensive end-to-end tests for TypeScript graphs: 1. test_typescript_graph_execution_e2e: Basic TypeScript graph execution - Verifies assistant creation with TypeScript graph - Tests streaming functionality - Validates response format and content 2. test_typescript_graph_multiple_runs_e2e: State persistence - Tests multiple runs on same thread - Ensures state is maintained across runs 3. test_typescript_graph_with_python_graphs_e2e: Coexistence - Verifies TypeScript and Python graphs can coexist - Tests both graph types in same server instance - Ensures no conflicts between runtimes All 3 tests passing. Complements existing unit (344) and integration (147) tests for complete TypeScript support test coverage. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
Remove global singleton pattern and implement proper dependency injection: - Runtime now managed as instance variable in LangGraphService - Initialize during service startup if TypeScript graphs detected - Remove unused process pool and shutdown() method Add production-ready logging and validation: - Replace print() with structured logging (logger.info/warning/error) - Add input validation with early error detection - Improve error messages with context Performance and maintainability improvements: - Cache runtime detection (one-time check during initialization) - Add JS_RUNTIME environment variable (auto/node/bun) - Optimize JSON serialization check (type-based instead of dumps) - Add module-level constants for config filtering - Move all imports to top of file Testing and documentation: - Add 16 new unit tests for error handling and validation - Add JS_RUNTIME documentation to .env.example - Fix TypeScript error handling with better type safety - Update integration tests for new architecture Results: - 368 tests passing (360 unit + 5 integration + 3 e2e) - Zero breaking changes - All pre-commit hooks pass
Fix integration tests to include explicit 'type' field in graph registry entries, matching the updated architecture that requires this field.
Remove TESTING_TYPESCRIPT.md and .cursor directories that were added during development but shouldn't be in the repository.
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds proof-of-concept TypeScript/JavaScript graph support to Aegra, enabling developers to write LangGraph agents in TypeScript that execute via Node.js/Bun while sharing PostgreSQL state persistence with Python graphs.
Key Changes:
- Added TypeScript runtime manager for executing TS/JS graphs via subprocess with IPC communication
- Extended configuration parsing to detect and validate TypeScript graphs alongside Python graphs
- Created comprehensive TypeScript SDK for client-side API interaction
Reviewed Changes
Copilot reviewed 27 out of 30 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
src/agent_server/core/ts_runtime.py |
Runtime manager for spawning Node.js/Bun processes and handling TypeScript graph execution |
src/agent_server/core/ts_graph_wrapper.ts |
Node.js wrapper script that loads TS graphs and streams results back to Python |
src/agent_server/core/config.py |
Configuration parser with TypeScript graph detection and Node.js version validation |
src/agent_server/services/langgraph_service.py |
Extended service to support both Python and TypeScript graphs with type field in registry |
sdk/src/client.ts |
TypeScript SDK client implementation with streaming support |
sdk/src/types.ts |
Type definitions for Aegra API |
graphs/ts_example_agent/graph.ts |
Example TypeScript LangGraph agent demonstrating the integration |
tests/unit/test_core/test_ts_runtime.py |
16 unit tests for TypeScript runtime manager |
tests/unit/test_core/test_config.py |
14 unit tests for configuration parser |
tests/integration/test_typescript_graph.py |
5 integration tests for TypeScript graph loading |
tests/e2e/test_typescript/test_typescript_execution.py |
3 E2E tests for full TypeScript execution flow |
Comments suppressed due to low confidence (1)
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
Comment on lines
+15
to
+16
| _.log | ||
| report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json |
There was a problem hiding this comment.
Incorrect glob pattern syntax: _.log should be *.log to match all log files. The underscore is not a wildcard character in gitignore patterns.
Suggested change
| _.log | |
| report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json | |
| *.log | |
| report.[0-9]_[0-9]_[0-9]_[0-9].json |
Owner
|
@PieterPel Nice work on this PR! I’ll go through it in detail soon, thanks! |
Codecov Report❌ Patch coverage is
📢 Thoughts on this report? Let us know! |
Owner
|
@PieterPel can you please update the pr by merging main and resolving the failing CI check please. |
PieterPel
changed the title
- Merged latest changes from upstream/main - Resolved merge conflicts in .env.example, aegra.json, and langgraph_service.py - Added missing 'type' field to graph registry in unit tests - All unit and integration tests passing (653/653)
Author
Hi I merged and changed the PR title to full lowercase to follow the conventional commits, which caused the failing CI. Let me know if there is anything else I can do |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add TypeScript/JavaScript Graph Support
Description
Add proof-of-concept support for TypeScript and JavaScript graphs alongside existing Python graphs.
This allows developers to write LangGraph agents in TypeScript/JavaScript that execute via Node.js or Bun while sharing the same PostgreSQL state persistence as Python graphs.
I am very much open to hearing feedback and suggestions on this PR.
Type of Change
feat: New featuretest: Tests added/updateddocs: Documentation changesRelated Issues
N/A - New feature addition
Changes Made
Core Implementation
TypeScript SDK
Testing
Documentation
Testing
Test results: 38 new tests, all passing
Checklist
make lint)make type-check) - pre-existing mypy issues in codebaseAdditional Notes
Backwards Compatibility
All changes are fully backwards compatible. Existing Python graphs work unchanged. TypeScript support is opt-in via configuration.
Architecture
TypeScript graphs execute in separate Node.js/Bun processes with JSON-based IPC. They share the same PostgreSQL checkpointer as Python graphs for state persistence.
Configuration
Optional JS_RUNTIME environment variable allows explicit runtime selection (auto/node/bun). Defaults to auto-detection (prefers bun over node).