asteros

package
v0.34.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 29, 2025 License: MIT Imports: 11 Imported by: 0

README

AsterOS - 统一运行时系统

AsterOS 是 Aster 框架的统一运行时系统，提供多智能体协作的完整解决方案。它管理所有 Agents、Stars、Workflows，并自动生成 REST API 端点，支持多种 Interface 类型。

🌟 核心特性

统一资源管理
  • Cosmos: 智能体生命周期管理器，替代原有的 Pool 概念
  • Stars: 多智能体协作单元，替代原有的 Room 概念
  • Workflows: 工作流管理和执行
  • 自动发现: 自动注册和发现所有资源
多接口支持
  • HTTP Interface: RESTful API 接口
  • A2A Interface: Agent-to-Agent 通信接口
  • AGUI Interface: 控制平面 UI 集成接口
  • 插件化: 支持自定义 Interface 扩展
自动 API 生成
  • 为所有注册的 Agents 自动生成 REST 端点
  • 为所有 Stars 自动生成协作管理 API
  • 为所有 Workflows 自动生成执行 API
  • 支持健康检查、指标监控、认证授权

🚀 快速开始

基本使用
package main

import (
    "context"
    "log"

    "github.com/astercloud/aster/pkg/agent"
    "github.com/astercloud/aster/pkg/asteros"
    "github.com/astercloud/aster/pkg/cosmos"
    "github.com/astercloud/aster/pkg/stars"
)

func main() {
    // 创建依赖
    deps := createDependencies()

    // 创建 Cosmos
    cosmos := cosmos.New(&cosmos.Options{
        Dependencies: deps,
        MaxAgents:    10,
    })

    // 创建 AsterOS
    os, err := asteros.New(&asteros.Options{
        Name:   "MyAsterOS",
        Port:   8080,
        Cosmos: cosmos,
    })
    if err != nil {
        log.Fatal(err)
    }

    // 启动服务
    if err := os.Serve(); err != nil {
        log.Fatal(err)
    }
}
注册 Agent
// 创建 Agent
agentConfig := &types.AgentConfig{
    AgentID:    "chat-agent",
    TemplateID: "chat-template",
    ModelConfig: &types.ModelConfig{
        Provider: "anthropic",
        Model:    "claude-sonnet-4-5",
        APIKey:   "your-api-key",
    },
}

ag, err := agent.Create(ctx, agentConfig, deps)
if err != nil {
    log.Fatal(err)
}

// 注册到 AsterOS
if err := os.RegisterAgent("chat-agent", ag); err != nil {
    log.Fatal(err)
}
创建 Stars 协作
// 创建 Stars
starsInstance := stars.New(cosmos, "ChatTeam")

// 添加成员
if err := starsInstance.AddMember("leader", "agent-1", "leader"); err != nil {
    log.Fatal(err)
}
if err := starsInstance.AddMember("worker", "agent-2", "worker"); err != nil {
    log.Fatal(err)
}

// 注册到 AsterOS
if err := os.RegisterStars("chat-team", starsInstance); err != nil {
    log.Fatal(err)
}
添加 Interface
// 添加 HTTP Interface (默认已包含)
httpIface := asteros.NewHTTPInterface()
os.AddInterface(httpIface)

// 添加 A2A Interface
a2aIface := asteros.NewA2AInterface()
os.AddInterface(a2aIface)

// 添加 AGUI Interface
aguiIface := asteros.NewAGUIInterface("/agui")
os.AddInterface(aguiIface)

📡 API 端点

AsterOS 自动生成以下 REST API 端点：

Agent 管理
GET    /api/agents              # 列出所有 Agent
POST   /api/agents/{id}/run     # 运行指定 Agent
GET    /api/agents/{id}/status  # 获取 Agent 状态
Stars 协作
GET    /api/stars                # 列出所有 Stars
POST   /api/stars/{id}/run       # 运行 Stars 协作
POST   /api/stars/{id}/join      # 加入 Stars
POST   /api/stars/{id}/leave     # 离开 Stars
GET    /api/stars/{id}/members   # 获取成员列表
Workflow 执行
GET    /api/workflows             # 列出所有 Workflow
POST   /api/workflows/{id}/execute # 执行 Workflow
系统
GET    /health                    # 健康检查
GET    /metrics                   # Prometheus 指标

⚙️ 配置选项

type Options struct {
    // 基本配置
    Name        string          // AsterOS 名称
    Port        int             // HTTP 端口 (默认: 8080)
    Cosmos      *cosmos.Cosmos  // Cosmos 实例 (必需)

    // API 配置
    APIPrefix   string          // API 路径前缀 (默认: /api)

    // 功能开关
    AutoDiscover   bool         // 自动发现 (默认: true)
    EnableCORS     bool         // CORS 支持 (默认: true)
    EnableAuth     bool         // 认证授权 (默认: false)
    EnableMetrics  bool         // 指标监控 (默认: true)
    EnableHealth   bool         // 健康检查 (默认: true)
    EnableLogging  bool         // 日志记录 (默认: true)

    // 认证配置
    APIKey        string        // API 密钥

    // 日志配置
    LogLevel      string        // 日志级别 (默认: info)
}

🎯 架构设计

核心组件
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   HTTP API      │    │   A2A Interface │    │   AGUI Interface│
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
┌─────────────────────────────────────────────────────────────────┐
│                    AsterOS Registry                             │
├─────────────────┬─────────────────┬─────────────────────────────┤
│   Agents        │    Stars        │      Workflows              │
└─────────────────┴─────────────────┴─────────────────────────────┘
         │                       │                       │
┌─────────────────────────────────────────────────────────────────┐
│                      Cosmos                                     │
│                  (Agent Manager)                                │
└─────────────────────────────────────────────────────────────────┘
Interface 抽象
type Interface interface {
    // 基本信息
    Name() string
    Type() InterfaceType

    // 生命周期管理
    Start(ctx context.Context, os *AsterOS) error
    Stop(ctx context.Context) error

    // 事件回调
    OnAgentRegistered(agent *agent.Agent) error
    OnStarsRegistered(stars *stars.Stars) error
    OnWorkflowRegistered(wf workflow.Agent) error
}

🌌 与 Cosmos 和 Stars 的关系

Cosmos (宇宙)
  • 职责: Agent 生命周期管理
  • 功能: 创建、销毁、监控 Agent
  • 类似: Kubernetes 的 Pod Manager
Stars (星座)
  • 职责: 多 Agent 协作管理
  • 功能: 编组、通信、协作调度
  • 类似: Kubernetes 的 Service/Deployment
AsterOS (星系操作系统)
  • 职责: 统一运行时和 API 网关
  • 功能: 资源注册、API 生成、接口管理
  • 类似: Kubernetes API Server + Ingress Controller

🔧 扩展开发

自定义 Interface
type MyInterface struct {
    BaseInterface
    // 自定义字段
}

func (i *MyInterface) Start(ctx context.Context, os *AsterOS) error {
    // 自定义启动逻辑
    return nil
}

func (i *MyInterface) OnAgentRegistered(agent *agent.Agent) error {
    // 自定义 Agent 注册处理
    return nil
}
自定义中间件
// 添加自定义中间件到 Router
os.Router().Use(myMiddleware)

📊 监控和观测

健康检查
curl http://localhost:8080/health
Prometheus 指标
curl http://localhost:8080/metrics
日志输出

AsterOS 使用结构化日志，支持不同级别：

🌟 AsterOS 'MyAsterOS' is running on http://localhost:8080
[Agent Create] Total tools loaded: 5
[Stars Join] Agent 'worker-1' joined stars 'chat-team'

🛡️ 安全特性

认证授权
// 启用认证
os, err := asteros.New(&asteros.Options{
    EnableAuth: true,
    APIKey:     "your-secret-api-key",
})
CORS 支持
// 启用 CORS (默认已启用)
os, err := asteros.New(&asteros.Options{
    EnableCORS: true,
})

🔍 故障排除

常见问题

  1. **"cosmos is required" 错误

    • 确保在创建 AsterOS 时提供了有效的 Cosmos 实例

  2. 端口占用

    • 检查指定的端口是否被其他程序占用
    • 使用不同的端口号

  3. Agent 注册失败

    • 检查 Agent 配置是否正确
    • 确保 Cosmos 中有足够的 Agent 容量
调试模式
os, err := asteros.New(&asteros.Options{
    LogLevel: "debug",  // 启用详细日志
})

📚 示例项目

查看 examples/asteros/ 目录下的完整示例：

  • basic/: 基本 AsterOS 使用
  • interfaces/: 多种 Interface 使用示例
  • collaboration/: Stars 协作示例

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进 AsterOS！

📄 许可证

本项目采用 Apache 2.0 许可证。

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// 配置错误
	ErrPoolRequired = errors.New("pool is required")
	ErrInvalidPort  = errors.New("invalid port number")

	// 资源错误
	ErrAgentNotFound    = errors.New("agent not found")
	ErrRoomNotFound     = errors.New("room not found")
	ErrWorkflowNotFound = errors.New("workflow not found")
	ErrResourceExists   = errors.New("resource already exists")

	// Interface 错误
	ErrInterfaceNotFound = errors.New("interface not found")
	ErrInterfaceExists   = errors.New("interface already exists")

	// 运行时错误
	ErrNotRunning     = errors.New("asteros is not running")
	ErrAlreadyRunning = errors.New("asteros is already running")
)

Functions

This section is empty.

Types

type AgentRunRequest 

type AgentRunRequest struct {
	Message string         `json:"message" binding:"required"`
	Stream  bool           `json:"stream,omitempty"`
	Context map[string]any `json:"context,omitempty"`
}

AgentRunRequest Agent 运行请求

type AsterOS 

type AsterOS struct {
	// contains filtered or unexported fields
}

AsterOS Aster 框架的统一运行时系统 AsterOS 负责管理所有 Agents、Rooms、Workflows， 并自动生成 REST API 端点，支持多种 Interface。

func New 

func New(opts *Options) (*AsterOS, error)

New 创建 AsterOS 实例

func (*AsterOS) AddInterface 

func (os *AsterOS) AddInterface(iface Interface) error

AddInterface 添加 Interface

func (*AsterOS) IsRunning 

func (os *AsterOS) IsRunning() bool

IsRunning 检查是否正在运行

func (*AsterOS) Name 

func (os *AsterOS) Name() string

Name 获取 AsterOS 名称

func (*AsterOS) Pool added in v0.13.0 

func (os *AsterOS) Pool() *core.Pool

Pool 获取 Pool 实例

func (*AsterOS) RegisterAgent 

func (os *AsterOS) RegisterAgent(id string, ag *agent.Agent) error

RegisterAgent 注册 Agent

func (*AsterOS) RegisterRoom added in v0.13.0 

func (os *AsterOS) RegisterRoom(id string, r *core.Room) error

RegisterRoom 注册 Room

func (*AsterOS) RegisterWorkflow 

func (os *AsterOS) RegisterWorkflow(id string, wf workflow.Agent) error

RegisterWorkflow 注册 Workflow

func (*AsterOS) Registry 

func (os *AsterOS) Registry() *Registry

Registry 获取 Registry 实例

func (*AsterOS) RemoveInterface 

func (os *AsterOS) RemoveInterface(name string) error

RemoveInterface 移除 Interface

func (*AsterOS) Router 

func (os *AsterOS) Router() *gin.Engine

Router 获取 Gin Router

func (*AsterOS) Serve 

func (os *AsterOS) Serve() error

Serve 启动 AsterOS

func (*AsterOS) Shutdown 

func (os *AsterOS) Shutdown() error

Shutdown 关闭 AsterOS

type BaseInterface 

type BaseInterface struct {
	// contains filtered or unexported fields
}

BaseInterface 基础 Interface 实现 提供默认的空实现，子类可以选择性覆盖

func NewBaseInterface 

func NewBaseInterface(name string, typ InterfaceType) *BaseInterface

NewBaseInterface 创建基础 Interface

func (*BaseInterface) Name 

func (i *BaseInterface) Name() string

Name 返回 Interface 名称

func (*BaseInterface) OnAgentRegistered 

func (i *BaseInterface) OnAgentRegistered(agent *agent.Agent) error

OnAgentRegistered Agent 注册事件（默认空实现）

func (*BaseInterface) OnRoomRegistered added in v0.13.0 

func (i *BaseInterface) OnRoomRegistered(room *core.Room) error

OnRoomRegistered Room 注册事件（默认空实现）

func (*BaseInterface) OnWorkflowRegistered 

func (i *BaseInterface) OnWorkflowRegistered(wf workflow.Agent) error

OnWorkflowRegistered Workflow 注册事件（默认空实现）

func (*BaseInterface) Start 

func (i *BaseInterface) Start(ctx context.Context, os *AsterOS) error

Start 启动 Interface（默认空实现）

func (*BaseInterface) Stop 

func (i *BaseInterface) Stop(ctx context.Context) error

Stop 停止 Interface（默认空实现）

func (*BaseInterface) Type 

func (i *BaseInterface) Type() InterfaceType

Type 返回 Interface 类型

type Interface 

type Interface interface {
	// Name 返回 Interface 名称
	Name() string

	// Type 返回 Interface 类型
	Type() InterfaceType

	// Start 启动 Interface
	Start(ctx context.Context, os *AsterOS) error

	// Stop 停止 Interface
	Stop(ctx context.Context) error

	// OnAgentRegistered Agent 注册事件
	OnAgentRegistered(agent *agent.Agent) error

	// OnRoomRegistered Room 注册事件
	OnRoomRegistered(room *core.Room) error

	// OnWorkflowRegistered Workflow 注册事件
	OnWorkflowRegistered(wf workflow.Agent) error
}

Interface AsterOS 接口抽象 Interface 定义了 AsterOS 与外部系统交互的标准接口

type InterfaceType 

type InterfaceType string

InterfaceType Interface 类型 

const (
	InterfaceTypeHTTP  InterfaceType = "http"  // HTTP REST API
	InterfaceTypeA2A   InterfaceType = "a2a"   // Agent-to-Agent
	InterfaceTypeAGUI  InterfaceType = "agui"  // Agent GUI
	InterfaceTypeSlack InterfaceType = "slack" // Slack 集成
)

type Options 

type Options struct {
	// 基本配置
	Name string // AsterOS 实例名称
	Port int    // HTTP 服务端口，默认 8080

	// 核心组件
	Pool *core.Pool // Pool 实例（必需）

	// 自动发现
	AutoDiscover bool // 是否自动发现和注册资源，默认 true

	// API 配置
	APIPrefix  string // API 路径前缀，默认 ""
	EnableCORS bool   // 是否启用 CORS，默认 true

	// 安全配置
	EnableAuth bool   // 是否启用认证，默认 false
	APIKey     string // API Key（如果启用认证）

	// 监控配置
	EnableMetrics bool // 是否启用 Prometheus 指标，默认 true
	EnableHealth  bool // 是否启用健康检查，默认 true

	// 日志配置
	EnableLogging bool   // 是否启用请求日志，默认 true
	LogLevel      string // 日志级别：debug, info, warn, error，默认 info
}

Options AsterOS 配置选项

func DefaultOptions 

func DefaultOptions() *Options

DefaultOptions 返回默认配置

func (*Options) Validate 

func (o *Options) Validate() error

Validate 验证配置

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry 资源注册表

func NewRegistry 

func NewRegistry() *Registry

NewRegistry 创建资源注册表

func (*Registry) Clear 

func (r *Registry) Clear()

Clear 清空所有资源

func (*Registry) GetAgent 

func (r *Registry) GetAgent(id string) (*agent.Agent, bool)

GetAgent 获取 Agent

func (*Registry) GetRoom added in v0.13.0 

func (r *Registry) GetRoom(id string) (*core.Room, bool)

GetRoom 获取 Room

func (*Registry) GetWorkflow 

func (r *Registry) GetWorkflow(id string) (workflow.Agent, bool)

GetWorkflow 获取 Workflow

func (*Registry) ListAgents 

func (r *Registry) ListAgents() []string

ListAgents 列出所有 Agents

func (*Registry) ListAll 

func (r *Registry) ListAll() []Resource

ListAll 列出所有资源

func (*Registry) ListRooms added in v0.13.0 

func (r *Registry) ListRooms() []string

ListRooms 列出所有 Rooms

func (*Registry) ListWorkflows 

func (r *Registry) ListWorkflows() []string

ListWorkflows 列出所有 Workflows

func (*Registry) RegisterAgent 

func (r *Registry) RegisterAgent(id string, ag *agent.Agent) error

RegisterAgent 注册 Agent

func (*Registry) RegisterRoom added in v0.13.0 

func (r *Registry) RegisterRoom(id string, room *core.Room) error

RegisterRoom 注册 Room

func (*Registry) RegisterWorkflow 

func (r *Registry) RegisterWorkflow(id string, wf workflow.Agent) error

RegisterWorkflow 注册 Workflow

func (*Registry) UnregisterAgent 

func (r *Registry) UnregisterAgent(id string) error

UnregisterAgent 注销 Agent

func (*Registry) UnregisterRoom added in v0.13.0 

func (r *Registry) UnregisterRoom(id string) error

UnregisterRoom 注销 Room

func (*Registry) UnregisterWorkflow 

func (r *Registry) UnregisterWorkflow(id string) error

UnregisterWorkflow 注销 Workflow

type Resource 

type Resource struct {
	ID   string       // 资源 ID
	Name string       // 资源名称
	Type ResourceType // 资源类型
	Data any          // 资源数据（Agent、Room 或 Workflow）
}

Resource 资源信息

type ResourceType 

type ResourceType string

ResourceType 资源类型 

const (
	ResourceTypeAgent    ResourceType = "agent"
	ResourceTypeRoom     ResourceType = "room"
	ResourceTypeWorkflow ResourceType = "workflow"
)

type RoomJoinRequest added in v0.13.0 

type RoomJoinRequest struct {
	Name    string `json:"name" binding:"required"`
	AgentID string `json:"agent_id" binding:"required"`
}

RoomJoinRequest Room 加入请求

type RoomLeaveRequest added in v0.13.0 

type RoomLeaveRequest struct {
	Name string `json:"name" binding:"required"`
}

RoomLeaveRequest Room 离开请求

type RoomSayRequest added in v0.13.0 

type RoomSayRequest struct {
	From string `json:"from" binding:"required"`
	Text string `json:"text" binding:"required"`
}

RoomSayRequest Room 发送消息请求

type WorkflowExecuteRequest 

type WorkflowExecuteRequest struct {
	Message string         `json:"message" binding:"required"`
	Context map[string]any `json:"context,omitempty"`
}

WorkflowExecuteRequest Workflow 执行请求

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.