{"id":37192316,"url":"https://github.com/voocel/mas","last_synced_at":"2026-02-10T06:03:44.098Z","repository":{"id":282731818,"uuid":"949007383","full_name":"voocel/mas","owner":"voocel","description":"Multi-Agent Framework for Go","archived":false,"fork":false,"pushed_at":"2026-01-03T13:15:39.000Z","size":521,"stargazers_count":13,"open_issues_count":0,"forks_count":4,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-04T22:33:47.963Z","etag":null,"topics":["agent","agents","ai","go","llm","multi-agent","multi-agent-systems","workflows"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/voocel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-15T13:18:31.000Z","updated_at":"2026-01-03T14:55:53.000Z","dependencies_parsed_at":"2025-12-31T00:06:47.018Z","dependency_job_id":null,"html_url":"https://github.com/voocel/mas","commit_stats":null,"previous_names":["voocel/mas"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/voocel/mas","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voocel%2Fmas","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voocel%2Fmas/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voocel%2Fmas/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voocel%2Fmas/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/voocel","download_url":"https://codeload.github.com/voocel/mas/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/voocel%2Fmas/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28436274,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T21:32:52.117Z","status":"ssl_error","status_checked_at":"2026-01-14T21:32:33.442Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","agents","ai","go","llm","multi-agent","multi-agent-systems","workflows"],"created_at":"2026-01-14T22:18:37.850Z","updated_at":"2026-01-14T22:18:38.428Z","avatar_url":"https://github.com/voocel.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MAS\n\n**MAS** (Multi-Agent System) is a lightweight, elegant Go SDK for building powerful multi-agent systems with minimal complexity.\n\n\u003e *Build production-ready AI agents in Go — simple to start, powerful to scale.*\n\n### Positioning\n\n- **Lightweight Core, Powerful Kernel**: Minimal API surface with strong execution and policy control.\n- **Easy to Embed**: Designed to integrate into existing systems without heavy frameworks.\n- **Policy-Driven Governance**: Tool, file, and network access can be explicitly controlled.\n- **Extensible by Design**: Pluggable tools, transports, and runtimes.\n- **Clear Boundary**: Not an OS-level sandbox; focuses on controllable execution and policy governance.\n\n### Design Philosophy\n\n- **Agent as Descriptor**: Agents hold configuration (prompt, tools, metadata) — no execution logic, no state management\n- **Runner-Driven Execution**: The Runner controls the execution loop; agents remain passive\n- **Explicit over Implicit**: No hidden state — execution flow is fully observable\n- **Minimal API Surface**: 3 lines for core scenarios, advanced capabilities compose on demand\n\n[Examples](./examples/) | [Chinese](./README_CN.md)\n\n## Install\n\n```bash\ngo get github.com/voocel/mas\n```\n\n## Quick Start\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"os\"\n\n    \"github.com/voocel/mas\"\n    \"github.com/voocel/mas/agent\"\n    \"github.com/voocel/mas/llm\"\n    \"github.com/voocel/mas/runner\"\n    \"github.com/voocel/mas/schema\"\n    \"github.com/voocel/mas/tools/builtin\"\n)\n\nfunc main() {\n    model := llm.NewOpenAIModel(\n        \"gpt-5\",\n        os.Getenv(\"OPENAI_API_KEY\"),\n        os.Getenv(\"OPENAI_API_BASE_URL\"),\n    )\n\n    // Minimal entry (recommended)\n    resp, err := mas.Query(\n        context.Background(),\n        model,\n        \"Compute 15 * 8 + 7\",\n        mas.WithPreset(\"assistant\"),\n        mas.WithTools(builtin.NewCalculator()),\n    )\n    if err != nil {\n        fmt.Println(\"error:\", err)\n        return\n    }\n    fmt.Println(resp.Content)\n\n    // Advanced: custom Runner\n    ag := agent.New(\n        \"assistant\",\n        \"assistant\",\n        agent.WithSystemPrompt(\"You are a helpful assistant.\"),\n        agent.WithTools(builtin.NewCalculator()),\n    )\n\n    r := runner.New(runner.Config{Model: model})\n\n    resp, err := r.Run(context.Background(), ag, schema.Message{\n        Role:    schema.RoleUser,\n        Content: \"Compute 15 * 8 + 7\",\n    })\n    if err != nil {\n        fmt.Println(\"error:\", err)\n        return\n    }\n\n    fmt.Println(resp.Content)\n}\n```\n\n## Session Client\n\n```go\ncli, _ := mas.NewClient(\n    model,\n    mas.WithPreset(\"assistant\"),\n    mas.WithTools(builtin.NewCalculator()),\n)\nresp, _ := cli.Send(context.Background(), \"Continue with 9 * 9\")\n```\n\n## Structured Output (JSON Schema)\n\n```go\nformat := \u0026llm.ResponseFormat{\n    Type: \"json_object\",\n}\nresp, _ := mas.Query(\n    context.Background(),\n    model,\n    \"Return JSON {\\\"answer\\\": 42}\",\n    mas.WithResponseFormat(format),\n)\n```\n\n## Full Result (Usage/Tool Trace)\n\n```go\nresult, _ := mas.QueryWithResult(\n    context.Background(),\n    model,\n    \"Compute 6 * 7\",\n)\nfmt.Println(result.Message.Content, result.Usage.TotalTokens)\n```\n\n## Multi‑Agent (Team)\n\n```go\nimport \"github.com/voocel/mas/multi\"\n\nteam := multi.NewTeam()\nteam.Add(\"researcher\", researcher)\nteam.Add(\"writer\", writer)\n\nag, _ := team.Route(\"researcher\")\nresp, _ := runner.Run(ctx, ag, msg)\n```\n\nBy default, multi‑agent runs are memory‑isolated per agent. To share minimal context (final outputs only), pass a shared memory store:\n\n```go\nshared := memory.NewBuffer(0)\nresp, _ := multi.RunSequentialWithOptions(ctx, r, []*agent.Agent{researcher, writer}, msg,\n    multi.WithSharedMemory(shared),\n)\n```\n\n## Collaboration Modes (Light but Powerful)\n\n```go\n// Sequential collaboration\nresp, _ := multi.RunSequential(ctx, r, []*agent.Agent{researcher, writer}, msg)\n\n// Parallel collaboration + reduce\nresp, _ := multi.RunParallel(ctx, r, []*agent.Agent{a1, a2}, msg, multi.FirstReducer)\n\n// Dynamic routing (handoff)\nrouter := \u0026multi.KeywordRouter{\n    Rules:   map[string]string{\"stats\": \"analyst\", \"write\": \"writer\"},\n    Default: \"assistant\",\n}\nresp, _ := multi.RunHandoff(ctx, r, team, router, msg, multi.WithMaxSteps(3))\n```\n\nHandoff uses `transfer_to_\u003cagent\u003e` tool calls only (no JSON/text handoff).\n\n## Middleware \u0026 Policies\n\n```go\nimport \"github.com/voocel/mas/middleware\"\n\nr := runner.New(runner.Config{\n    Model: model,\n    Middlewares: []runner.Middleware{\n        \u0026middleware.TimeoutMiddleware{LLMTimeout: 10 * time.Second, ToolTimeout: 20 * time.Second},\n        \u0026middleware.RetryMiddleware{MaxAttempts: 3},\n        middleware.NewToolAllowlist(\"calculator\", \"web_search\"),\n        middleware.NewToolCapabilityPolicy(\n            middleware.AllowOnly(tools.CapabilityNetwork),\n            middleware.Deny(tools.CapabilityFile),\n        ),\n    },\n})\n```\n\n## Observability \u0026 Tracing\n\n```go\nimport \"github.com/voocel/mas/observer\"\n\nr := runner.New(runner.Config{\n    Model:    model,\n    Observer: observer.NewLoggerObserver(os.Stdout),\n    Tracer:   observer.NewSimpleTimerTracer(os.Stdout),\n})\n```\nLogs include `run_id`, `step_id`, and `span_id` for correlation.\n\n## Structured Logs \u0026 Metrics\n\n```go\nimport (\n    \"github.com/voocel/mas/middleware\"\n    \"github.com/voocel/mas/observer\"\n)\n\nmetrics := \u0026middleware.MetricsObserver{}\nobs := observer.NewCompositeObserver(\n    observer.NewJSONObserver(os.Stdout),\n    metrics,\n)\n```\n\n## Routing (Optional)\n\n```go\nrouter := \u0026multi.KeywordRouter{\n    Rules:   map[string]string{\"stats\": \"analyst\", \"write\": \"writer\"},\n    Default: \"assistant\",\n}\nag, _ := router.Select(msg, team)\n```\n\n## Core Concepts\n\n- **Agent**: describes role, system prompt and tools\n- **Runner**: drives the execution loop (LLM → tools → feedback)\n- **Tool**: independent capability with optional side‑effect flags\n- **Memory**: conversation store (in‑memory window by default)\n  - System prompts are injected by Runner at build time and are not stored in Memory.\n\n## Tool Execution Layer (Executor)\n\n- `executor` provides ToolExecutor abstraction and Policy for tool execution/runtime integration.\n- `mas-sandboxd` is a control-plane harness (protocol + execution framework only; no OS-level isolation).\n- For detailed sandbox flow, setup, and examples: [executor/sandbox/README.md](executor/sandbox/README.md).\n\n## License\n\nApache License 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoocel%2Fmas","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoocel%2Fmas","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoocel%2Fmas/lists"}