AgentScope Go

A Go-native multi-agent application framework.

English | 简体中文

What Is AgentScope Go?

AgentScope Go is agents, messages, model adapters, tools, state, workspace resources, and event-based execution. It is designed for developers who want to build AI agent systems in Go while keeping the runtime explicit, testable, and easy to integrate with existing Go services.

Requirements

• Go 1.26.3 or newer.
• GNU Make for the provided development targets.
• Python 3.13+, Node.js 22+, and npm 10+ if you want to run all local linting and documentation tools through make setup.

Quick Start

Install the Agentscope Go in your Go project:

go get github.com/yuluo-yx/agentscope-go@latest

Domain APIs are organized under the pkg/ import root. For example, import github.com/yuluo-yx/agentscope-go/pkg/agent for agents, github.com/yuluo-yx/agentscope-go/pkg/message for messages, and github.com/yuluo-yx/agentscope-go/pkg/model/dashscope for the DashScope model adapter. The module root github.com/yuluo-yx/agentscope-go keeps a small facade package with aliases for common core APIs.

Run a local example without a model API key:

go run ./example/message

Run a live DashScope chat example:

export AI_DASHSCOPE_API_KEY="<your DashScope API key>"
go run ./example/model/dashscope

Minimal ChatModel usage:

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/yuluo-yx/agentscope-go/pkg/message"
    asmodel "github.com/yuluo-yx/agentscope-go/pkg/model"
    "github.com/yuluo-yx/agentscope-go/pkg/model/dashscope"
)

func main() {
    chat, err := dashscope.NewChatModel(
        dashscope.NewCredential(os.Getenv("AI_DASHSCOPE_API_KEY")),
        "qwen-plus",
    )
    if err != nil {
        panic(err)
    }

    user, err := message.NewUserMessage("user", "Say hello in one short sentence.")
    if err != nil {
        panic(err)
    }

    response, err := chat.Call(context.Background(), asmodel.CallRequest{
        Messages: []*message.Message{user},
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(response.Content)
}

Examples

Each example is an independent Go module with its own go.mod, English README.md, and Chinese README-zh.md.

Example	Purpose
example/agent/basic	Build a basic agent backed by a ChatModel.
example/agent/configuration	Configure model fallback, ReAct limits, and context cleanup.
example/agent/context_strategy	Configure summary compression, workspace offload, and custom context strategies.
example/agent/external	Pause and resume an Agent around externally executed tools.
example/agent/hooks	Implement Agent middleware hooks around reply, reasoning, model calls, acting, and system prompts.
example/agent/middleware_tracing	Trace reply, model-call, and tool-execution middleware spans.
example/agent/permission	Handle permission confirmation and resume a pending tool call.
example/message	Compose user, assistant, system, and tool messages.
example/model/dashscope	Call DashScope models and demonstrate model tool calling.
example/model/providers	Compare the available model provider adapters.
example/integration/gin	Expose direct ChatModel streaming and Agent event streaming through Gin.
example/integration/kratos	Expose direct ChatModel streaming and Agent event streaming through Kratos.
example/tool/function	Register and execute function tools from model tool calls.
example/tool/builtin	Use builtin shell and filesystem tools with permissions.
example/tool/mcp	Connect to MCP servers and expose MCP tools to an agent.
example/tool/skill	Load local SKILL.md resources as agent tools.
example/tool/task	Wrap task-style work as tools.
example/workspace/local	Provide local workspace files for AI-assisted tool workflows.
example/workspace/docker	Run workspace tools inside a Docker container and send the result through a ChatModel.
example/workspace/microsandbox	Run workspace tools inside a local Microsandbox microVM and optionally summarize with DashScope.
example/workspace/agentsandbox	Run workspace tools inside a Kubernetes Agent Sandbox runtime.

Start with the examples if you want the quickest path to a working agent.

Tip: If you encounter dependency issues, please run go mod tidy before go run ..

Development

Bootstrap the local toolchain:

make setup
make install-tools

Common targets:

Command	Purpose
make fmt	Format Go code.
make lint-go	Run golangci-lint.
make test	Run the full Go test suite with the race detector.
make coverage	Generate full coverage output.
make docs-check	Build and lint documentation.
make security-check	Run the local secret scan.
.venv/bin/pre-commit run --all-files	Run the same local checks used before commit.

Release automation is intentionally not documented here. Follow the repository maintainer's release instructions when a release is planned.

Security

Read SECURITY.md before reporting a vulnerability. A Chinese version is available at SECURITY_zh.md. AgentScope Go is a library framework, not a hosted service; application authors control which tools, model providers, workspaces, MCP servers, and credentials are available at runtime.

Contributing

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request, and follow the project CODE_OF_CONDUCT.md. Chinese versions are available at CONTRIBUTING_zh.md and CODE_OF_CONDUCT_zh.md.

Contributors

License

AgentScope Go is licensed under the Apache License 2.0.