Astron Agent Documentation

Astron Agent is an enterprise-grade Agentic Workflow development platform. Its architecture is organized into several hierarchical layers:

1. UI Layer: Provides the web interface for agent and workflow management.
2. Console Backend Layer: Manages authentication, permissions, and CRUD operations for the management console.
3. Core Microservices Layer: Contains the primary execution engines (Agent, Workflow, Knowledge, Memory, Tenant).
4. Plugin System: Extends capabilities via AI Tools, RPA, and Link plugins.
5. Common Services Layer: Provides unified infrastructure abstraction (logging, observability, DB/MQ connections) for Python microservices.
6. Infrastructure Layer: Handles data persistence (MySQL, Redis, PostgreSQL), messaging (Kafka), and object storage (MinIO).

The Astron Console is a full-stack web application for managing AI agents and chatbots. It uses a decoupled architecture:

• Frontend: React 18.2.0, TypeScript 5.9.2, Vite 5.4.0, Ant Design 5.19.1, and Tailwind CSS 3.3.5.
• Backend: Java 21 with Spring Boot 3.5.4 microservices.
• Database/Storage: MyBatis Plus 3.5.7 for ORM, MinIO 8.5.10 for object storage, and Redis for caching/sessions.
• Communication: RESTful APIs and Server-Sent Events (SSE) for real-time updates.

Astron Agent configuration is divided into four primary domains. Use this overview to identify which area requires your attention:

1. Infrastructure: Covers databases, caches, object storage, networking, reverse proxies, and container runtime environments.
2. Models and AI Capabilities: Covers Model gateway/MaaS connection settings, API keys, authentication details, capability switches, and routing strategies.
3. Platform Capabilities: Covers MCP (Model Context Protocol) and external tool integration, RPA (Robotic Process Automation) execution environments, and multi-tenant/space/team capabilities.
4. Authentication and Security: Covers Casdoor and identity integration, environment variable management, and secret injection/permission boundaries.

For detailed technical specifications, refer to the Configuration Reference.

The workflow engine is split into two components:

• Java (Console backend / hub module): Manages high-level APIs, including CRUD, user authentication, and configuration management. It uses the astron_console database.
• Python (Workflow Service): Executes the actual workflow engine, parsing logic and scheduling nodes. It uses the workflow database.

Both components typically run on the same MySQL instance but use their respective independent databases.

The RPA Server provides the following core functionalities which are verified by the test suite:

• API Endpoints: Task execution interface, request validation, response handling, and streaming event responses.
• Task Management: Task creation, querying, status monitoring, and timeout handling.
• Configuration Management: Environment variable loading and configuration validation.
• Utility Functions: URL validation, logging system, and error code management.
• Exception Handling: Custom exceptions and error propagation.

Astron Agent is available in three distinct environments. Note that accounts, data, and quotas are isolated between them and do not sync:

• Online Experience Version: A cloud-deployed instance of the open-source version for zero-cost trial. Not recommended for production data.
• SaaS Version (agent.xfyun.cn): Official managed commercial service. Membership quotas from the web version cannot be used in private deployments.
• Open Source Self-Hosted Version: Deployed via Docker Compose or Helm. You maintain full data ownership and can connect any OpenAI-compatible model services.

The project is a microservices-based platform organized as follows:

• console/: Console subsystem
  • backend/: Java Spring Boot services (auth, commons, hub, toolkit, config)
  • frontend/: React TypeScript SPA
• core/: Core platform services
  • agent/: Agent execution engine (Python)
  • common/: Shared Python libraries
  • knowledge/: Knowledge base service (Python)
  • memory/: Memory management
  • plugin/: Plugin system
  • tenant/: Multi-tenant service (Go)
  • workflow/: Workflow orchestration (Python)
• docs/: Documentation
• makefiles/: Build system components
• .github/quality-requirements/: Code quality standards

To preview the documentation site on your local machine, navigate to the docs/ directory and run the following commands to install dependencies and start the VitePress development server.

cd docs
npm install
npm run docs:dev

Use these commands for routine development tasks:

# Format all code
make format

# Run code quality checks with pre-commit (recommended)
pre-commit run --all-files

# Run tests
make test

# Build all projects
make build

Follow these steps to update your database schema when changing models:

1. Modify Models: Update your SQLModel classes located in workflow/domain/models/.
2. Generate Migration: Run alembic revision --autogenerate -m "description".
3. Review: Inspect the generated file in alembic/versions/.
4. Manual Edits: Manually edit the file if the autogenerate process missed anything, such as:
   • Data migrations
   • Index renames
   • Complex constraint changes
5. Commit: Commit the migration file to your version control system (git).

alembic revision --autogenerate -m "add user table"

Observability/Trace is disabled by default in the Open Source version. To enable it and view call chains in the workflow Trace logs, follow these steps:

1. In docker-compose.yaml, uncomment the following four component containers:
   • elasticsearch
   • kibana
   • kafka
   • logstash
2. Set the environment variable KAFKA_ENABLE to 1.
3. Restart the project.