Agentscope Go AI Agent

<p align="center"> <img src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg" alt="AgentScope" width="120" /> </p>

AgentScope Go

Español · Quick start · Examples · Documentation · Contributing

AgentScope Go is a Go library for building LLM applications with agents, tools and multi-agent workflows. It implements the core concepts of AgentScope through Go interfaces, contexts and channels, and can be embedded in a service or command-line program.

What you can build

• Tool-using assistants: connect model calls to Go functions, manage context and request human confirmation for tool execution. Use AskUser to collect structured choices through your own frontend. On main (unreleased), opt into bounded tool dispatch with agent.WithToolConcurrencyLimit(width).
• Multi-agent workflows: coordinate agents with pipelines, message routing and leader/worker teams. On main (unreleased), use the experimental TeamPipeline for serial named-member delegation and participant confirmation/external-result routing.
• Applications with memory: combine retrieval, conversation state and memory middleware with your own data sources.
• Services and experiments: expose an HTTP service or browser UI, record model responses, evaluate runs and inspect traces.

Quick start

You need Go 1.25+ and, for the program below, an Anthropic API key and an available model ID. Other adapters are listed under Model providers.

Install in your application

Install the latest tagged release from the community module path. Applications using github.com/alanfokco/agentscope-go/v2 need to update their import prefix; see the module migration notes.

From a new directory:

mkdir agentscope-demo
cd agentscope-demo
go mod init example.com/agentscope-demo
go get github.com/agentscope-ai/agentscope-go/v2@latest

Create an agent

Save this as main.go:

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/agentscope-ai/agentscope-go/v2/pkg/agentscope/agent"
	"github.com/agentscope-ai/agentscope-go/v2/pkg/agentscope/model"
)

func main() {
	cm, err := model.NewAnthropicChatModel(&model.AnthropicConfig{
		SecretAPIKey:    model.NewSecretStr(os.Getenv("ANTHROPIC_API_KEY")),
		Model:           os.Getenv("ANTHROPIC_MODEL"),
		MaxOutputTokens: 1024,
	})
	if err != nil {
		log.Fatal(err)
	}

	assistant := agent.NewUnifiedAgent(
		"assistant", "You are a helpful assistant. Keep answers concise.", cm,
	)

	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
	defer cancel()

	reply, err := assistant.Reply(ctx, "What is an AI agent? Explain in one sentence.")
	if err != nil {
		log.Fatal(err)
	}
	if text := reply.GetTextContent("\n"); text != nil {
		fmt.Println(*text)
	}
}

Set your key and a model ID available to your account, then run the program. These shell commands use Bash/Zsh syntax; in PowerShell, set environment variables with $env:NAME = 'value'.

export ANTHROPIC_API_KEY='your-api-key'
export ANTHROPIC_MODEL='your-model-id'
go mod tidy
go run .

The program makes a model API request and prints its reply. To add function calling, see the tool example; for configuration and next steps, see Getting started.

Model providers

Adapters are available for OpenAI (Chat Completions and Responses), Anthropic, DashScope, DeepSeek, Gemini, Moonshot, xAI, Ollama, Volcengine Ark and MiniMax. See provider configuration and the adapter source for options and defaults.

Tool calling, multimodal input, thinking and usage reporting depend on the provider and model. Provider ChatStream methods expose response chunks; UnifiedAgent.ReplyStream streams thinking/text deltas from ChatStream by default when no middleware is installed. Legacy middleware chains keep buffered Chat calls so response filters can run before publication. Use agent.WithModelStreaming(false) for the previous buffered behavior. See agent streaming for completion, cancellation and fallback semantics.

For local models, configure the context window and request timeout for your server and device. Model cards describe model capabilities; they do not configure the server. See edge deployment and the tracked local-model limitations.

Examples

Examples run from a repository checkout, separately from the application above. This worker-pool demo uses simulated jobs and needs no model API key:

git clone https://github.com/agentscope-ai/agentscope-go.git
cd agentscope-go
go run ./examples/agent_pool

Start with agent_v2 for function tools, model_call for direct model streaming, or webui for a browser interface. Check each example's source for its model choice, environment variables and required services or runtimes.

<details> <summary>Browse all examples</summary>

Example	Demonstrates
simple	A custom agent with a single model call
agent_v2	UnifiedAgent with a function tool
react_tool	A custom FunctionTool
react_builtin_tools	The built-in coding toolkit
streaming	Agent lifecycle events and provider text deltas
ask_user	Structured questions with a simulated model and host answer
console	Terminal chat and tool-call confirmation
managed_routing_eval	Managed fixed/rules/classifier comparisons, offline fixtures and opt-in live pilot
managed_routing	Managed pools, classification and fallback with offline fixtures
tier_routing	UnifiedAgent with fixed and three-tier routed fake ChatModels
embodied_demo	Single-device observation, edge/cloud planning and simulated action loop
managed_task	Fixed-model managed text execution with a local HTTP fixture
classifier	Typed classification with offline fake results and attempt accounting
piccolo	Local Piccolo text decisions with an offline fixture and opt-in live server
permission_advisory	Shadow-mode classifier advice with unchanged scripted user confirmation
model_call	Direct model streaming, tool calls and structured output
volcengine	Direct Ark chat streaming with API-key authentication
minimax	MiniMax tool use with preserved thinking and a streamed follow-up
structured_output	Structured output through tool calling
multi_provider	Provider configuration and model cards
multimodal	Image input using URLs and base64 data
multiagent	Multi-agent conversation
multiagent_multimodal	Multi-agent conversation with image input
openai_response	OpenAI Responses API
openai_server	OpenAI-compatible Chat Completions serving with a simulated order assistant
middleware	Model-call and tool-execution hooks
permission	Tool permission modes
tracing	Tracing with LoggerTracer
tracing_otlp	An OTLP integration setup pattern
agent_loop	Loop configuration and metrics
embedding	Text embeddings and similarity
long_term_memory	Long-term memory middleware
agentic_memory	File-based memory and MEMORY.md
rag_react	Retrieval with an in-memory index
pipeline_multi_agent	Pipeline and MsgHub coordination
goal_pipeline	Bounded executor-verifier loop with offline models and an actual artifact
team_pipeline	Offline named-member delegation with host confirmation and a follow-up
agent_team	Leader/worker agent coordination
mcp	MCP tool discovery and calls
mcp_streamable	MCP Streamable HTTP client with an in-process spec server
a2a_http	Agent-to-agent communication over HTTP
grpc_a2a	TCP messaging with newline-delimited JSON, not gRPC
replay	Simulated response tapes and file persistence
replayview	A terminal viewer for RunJSONL logs
rundiff	Compare RunJSONL logs
eval_harness	Score recorded response fixtures
agent_pool	A bounded worker pool with simulated jobs
hotreload	Typed configuration reloads
bench	Load testing and latency reports
quality_load	Task quality under scheduled arrivals, with offline fixtures
qdrant_filter	Metadata filtering against a local Qdrant server
wasm_sandbox	WASM runtime discovery and sandbox configuration
hub_install	Component registries and installation APIs
skill_partitions	Per-agent workspace skill directories
workspace_sharing	Session/workspace bindings and artifact access
access_control	Resource grants and access checks
document_parser	Document parsing and chunking
audit_logging	Sandbox policy checks and audit records
guardrail	Block, redact and warn with mock model responses
spend_cap	Observed-cost budgets with a mock model
agent_service	HTTP service and SSE events
scoped_service	Offline shared service with owner-scoped sessions and file tools
webui	Embedded browser UI
dingtalk_channel	DingTalk messages and confirmations
scheduled_task	One-shot and recurring tasks
realtime_echo	A realtime-interface echo client
edge_offline	Cloud/local routing with Ollama
edge_sensor	Sensor middleware with a mock sensor
edge_serial_robot	Device tools with a mock serial device
edge_fleet	In-memory pub/sub fleet simulation
werewolves	A multi-agent Werewolves game
k8s_workspace	Kubernetes workspace configuration and cluster tools

</details>

The examples guide provides running instructions and links to the same catalog.

Documentation

Topic	Guide
Setup and a first agent	Getting started
Models and tools	Providers · Tools
Context compaction	Experimental tool-exchange retention
Managed text tasks	Fixed-deployment execution, limits and accounting · Routing and deployment pools · Evaluation workflow
Probabilistic classification	Classifier API and attempt accounting · Jev adapter · Bailian adapter · OpenAI Decisions adapter
Middleware and memory	Middleware
Goal execution	Experimental GoalPipeline and Agent adapters
Named-member teams	Experimental serial TeamPipeline and host interactions
Shared HTTP service	Experimental owner-scoped sessions and request-aware construction
Application deployment	Deployment · Execution and session limits · Reply recovery
OpenAI-compatible serving	Experimental Chat Completions handler and client contract
Runtime and evaluation	Runtime features · Load and quality testing · Replay and evaluation source
Local models and devices	Edge deployment · Device tools · Multi-device coordination · Offline operation
Implementation and compatibility	Source map · API stability · Changelog

Project status

Stability varies by package. The core model, message, agent, tool, permission, formatter and error APIs have documented stability commitments; other packages include experimental interfaces. Read STABILITY.md for the exact scope and remaining hardening work. Features on main may not be in a release.

For deployments that execute shell commands or access files, configure and test the appropriate workspace backend and permissions. Permission checks alone do not provide complete process, network or resource isolation. Deployment requirements depend on the selected providers and backends.

Contributing

Bug reports, regression tests, documentation and focused feature contributions are welcome. For a bug, include the version or commit, configuration and a minimal reproduction with secrets removed. For a larger feature, open an issue to discuss the use case and API before starting a broad implementation.

Read CONTRIBUTING.md for setup and the PR process, and AGENTS.md for validation and review requirements. Small PRs with a clear purpose are easier to review; there is no need to take on a whole subsystem. Please follow our Code of Conduct.

Report suspected vulnerabilities privately through SECURITY.md, not in a public issue.

License and citation

Licensed under Apache-2.0. For research using AgentScope, see AgentScope: A Flexible yet Robust Multi-Agent Platform.