This page provides a practical guide to installing AStack and creating your first components and pipelines. It covers installation prerequisites, basic setup, and two execution patterns: standalone components and pipeline orchestration. For detailed architectural concepts, see Key Concepts. For information about specific packages and their APIs, see Package System.
AStack requires the following system dependencies:
| Requirement | Version | Purpose |
|---|---|---|
| Node.js | v18.0.0 or higher | JavaScript runtime |
| Package Manager | pnpm (recommended), npm, or yarn | Dependency management |
The Node.js version requirement is specified in package.json6-8
Sources: package.json6-8
AStack is currently distributed as a monorepo that must be built from source:
The monorepo uses pnpm workspaces to manage four core packages located in packages/*:
@astack-tech/core - Pipeline execution engine and Component base class@astack-tech/components - Pre-built components (Agent, Memory, PromptTemplate, TextSplitter)@astack-tech/tools - Tool definition system@astack-tech/integrations - Model provider integrations (Deepseek, OpenAI)Build System Overview
Sources: README.md124-148 package.json1-51 README.zh-CN.md124-148
Components in AStack can execute independently without a Pipeline. This is useful for simple transformations and testing individual components.
The TextSplitter component splits text into chunks with configurable size and overlap:
Standalone Execution Flow
The run() method is defined in the base Component class and executes the component's _transform() method. All components inherit this capability.
Sources: examples/text-splitter/index.ts52-75
Pipelines orchestrate multiple components by connecting their input and output ports. The Pipeline class manages component registration and data flow.
Pipeline Architecture
The Pipeline class automatically injects internal components for orchestration:
| Component | Purpose | Port |
|---|---|---|
BaseProducer (START_COMPONENT_NAME) | Injects input data into pipeline | out |
BaseConsumer (END_COMPONENT_NAME) | Collects final output | in |
When pipeline.run(triggerName, params) is called:
Pipeline.addComponent() registers the component at packages/core/src/pipeline/index.ts66-72Pipeline.runWithBaseMode() creates internal start/end components at packages/core/src/pipeline/index.ts99-171Pipeline.connect() links component ports at packages/core/src/pipeline/index.ts84-90Flow engine executes the connected graphBaseConsumer captures output and resolves the PromiseSources: packages/core/src/pipeline/index.ts1-189 examples/text-splitter/index.ts48-80
To build multi-component pipelines, use pipeline.connect() to link output ports to input ports:
Multi-Component Pipeline Flow
The connect() method uses dot notation componentName.portName to specify connections. It internally calls from() and to() helper methods to retrieve the HLang port objects at packages/core/src/pipeline/index.ts23-58
Sources: packages/core/src/pipeline/index.ts84-90 website/components/Hero.tsx50-74
The examples/ directory contains four demonstration applications:
| Example | Purpose | Key Features |
|---|---|---|
text-splitter | Basic pipeline usage | Single component, standalone vs pipeline modes |
agent-with-tools | Tool integration | File system tools, multi-turn conversations |
simple-deep-research | Complex orchestration | Multiple coordinated components, feedback loops |
serve-astack | Production application | Fastify backend, Next.js frontend, streaming agents |
This example demonstrates both execution modes in examples/text-splitter/index.ts48-80:
pipeline.run('textSplitter.text', sampleText) at line 66textSplitter.run(sampleText) at line 70Each example directory contains its own README with specific setup instructions, including required API keys for examples using LLM integrations.
Sources: README.md145-148 examples/text-splitter/index.ts1-80
Components communicate through a port-based system inherited from HLang's Flow-Based Programming model. Understanding ports is essential for pipeline construction.
Port Types and Methods
Key methods for working with ports:
| Method | Signature | Purpose |
|---|---|---|
Component.Port.I(name) | attach(component) | Declare input port |
Component.Port.O(name) | attach(component) | Declare output port |
component.I(name) | Returns input port | Access input port for connection |
component.O(name) | Returns output port | Access output port for connection |
pipeline.from(name) | Returns output port | Internal helper for connect() |
pipeline.to(name) | Returns input port | Internal helper for connect() |
The Pipeline.connect() method at packages/core/src/pipeline/index.ts84-90 internally calls from() and to() to retrieve port objects and establish connections.
Sources: packages/core/src/pipeline/index.ts23-90
After completing this guide, you should understand:
addComponent() and connect()_transform() patternTo create custom components, extend the base Component class and implement the _transform() method. For detailed guidance, see Component System.
For AI agent development with tool integration, see:
Sources: README.md21-90 README.zh-CN.md21-90
Refresh this wiki