配置智能体

智能体在初始化时完成全部装配：把模型、工具包和配置对象传入 Agent(...)，即可开始回复。以下示例涵盖最常见的几种配置场景。

from agentscope.agent import Agent
from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential

agent = Agent(
    name="my_agent",
    system_prompt="你是一个有帮助的助手。",
    model=DashScopeChatModel(
        credential=DashScopeCredential(api_key="YOUR_API_KEY"),
        model="qwen-max",
    ),
)

import os
from agentscope.agent import Agent
from agentscope.tool import Toolkit, Bash, Edit, Grep, Read, Write
from agentscope.mcp import MCPClient, HttpMCPConfig
from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential

agent = Agent(
    name="my_agent",
    system_prompt="你是一个有帮助的助手。",
    model=DashScopeChatModel(
        credential=DashScopeCredential(api_key="YOUR_API_KEY"),
        model="qwen-max",
    ),
    toolkit=Toolkit(
        tools=[Bash(), Edit(), Grep(), Read(), Write()],
        mcps=[
            MCPClient(
                name="amap",
                is_stateful=False,
                mcp_config=HttpMCPConfig(
                    url=f"https://mcp.amap.com/mcp?key={os.environ['AMAP_API_KEY']}",
                ),
            ),
        ],
        skills_or_loaders=["./skills"],
    ),
)

from agentscope.agent import Agent
from agentscope.agent import ContextConfig
from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential

agent = Agent(
    name="my_agent",
    system_prompt="你是一个有帮助的助手。",
    model=DashScopeChatModel(
        credential=DashScopeCredential(api_key="YOUR_API_KEY"),
        model="qwen-max",
    ),
    context_config=ContextConfig(
        trigger_ratio=0.7,       # 使用 70% 上下文时触发压缩
        reserve_ratio=0.2,       # 压缩后保留最近 20% 的内容
        tool_result_limit=1000,  # 工具结果超过 1000 token 时截断
    ),
)

from agentscope.agent import Agent
from agentscope.agent import ReActConfig
from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential

agent = Agent(
    name="my_agent",
    system_prompt="你是一个有帮助的助手。",
    model=DashScopeChatModel(
        credential=DashScopeCredential(api_key="YOUR_API_KEY"),
        model="qwen-max",
    ),
    react_config=ReActConfig(
        max_iters=30,                     # 最多 30 轮推理-行动迭代
        structured_output_grace_iters=3,  # 为完成结构化输出追加的迭代次数
        stop_on_reject=True,              # 工具调用被拒绝时停止回复
    ),
)

参数说明

所有配置都通过 Agent(...) 构造函数传入。下表列出全部参数，可调节项被归入各配置对象：

参数	类型	默认值	描述
`name`	`str`	必填	智能体标识符，用于消息和日志
`system_prompt`	`str`	必填	智能体的基础系统提示词
`model`	`ChatModelBase`	必填	用于推理的大语言模型
`toolkit`	`Toolkit \| None`	`None`	管理工具、MCP 客户端、技能和工具组
`state`	`AgentState \| None`	自动创建	保存上下文、权限上下文和会话状态
`offloader`	`Offloader \| None`	`None`	卸载压缩后的上下文与工具结果，需实现 `Offloader` 协议
`middlewares`	`list[MiddlewareBase] \| None`	`None`	应用于回复、推理、行动、模型调用和系统提示词等钩子
`model_config`	`ModelConfig`	默认值	重试次数和备用模型
`context_config`	`ContextConfig`	默认值	上下文压缩阈值和工具结果长度限制
`injection_config`	`InjectionConfig`	默认值	运行时状态注入：时间、任务与上下文用量（参见感知环境）
`react_config`	`ReActConfig`	默认值	最大迭代次数、结构化输出宽限迭代次数和拒绝处理方式

切换模型

切换模型 API 只需改动 model 参数：所有模型类都遵循相同的 Model(credential=..., model=...) 模式，智能体的其余部分保持不变。

from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential

model = DashScopeChatModel(
    credential=DashScopeCredential(api_key="YOUR_API_KEY"),
    model="qwen-max",
)

from agentscope.model import OpenAIChatModel
from agentscope.credential import OpenAICredential

model = OpenAIChatModel(
    credential=OpenAICredential(api_key="YOUR_API_KEY"),
    model="gpt-4o",
)

from agentscope.model import AnthropicChatModel
from agentscope.credential import AnthropicCredential

model = AnthropicChatModel(
    credential=AnthropicCredential(api_key="YOUR_API_KEY"),
    model="claude-sonnet-4-5",
)

from agentscope.model import GeminiChatModel
from agentscope.credential import GeminiCredential

model = GeminiChatModel(
    credential=GeminiCredential(api_key="YOUR_API_KEY"),
    model="gemini-2.5-pro",
)

from agentscope.model import OllamaChatModel
from agentscope.credential import OllamaCredential

model = OllamaChatModel(
    credential=OllamaCredential(host="http://localhost:11434"),
    model="qwen3:8b",
)

支持多实体对话

智能体并不局限于一人一智能体的对话。在智能体团队、群聊或带 NPC 的游戏中，来自多个具名实体的消息共享同一份上下文，智能体必须知道每句话出自谁口。在 AgentScope 中，每个发言者由其 Msg 的 name 字段标识。多实体对话就是一组带有不同名字的消息列表，直接喂给智能体即可：

from agentscope.message import UserMsg

msgs = [
    UserMsg(name="Alice", content="我投海边一票。"),
    UserMsg(name="Bob", content="我更想去爬山。"),
    UserMsg(name="user", content="小周，总结一下大家的偏好。"),
]
result = await agent.reply(msgs)

这些身份信息能否保留，取决于格式化器（Formatter），它负责在每次模型调用前把 Msg 对象转换为对应模型 API 的格式。默认的对话格式化器将消息映射到 API 原生的 user/assistant 角色上，适合一人一智能体的对话，但会丢掉名字，使发言者无法区分。针对多实体对话，AgentScope 为每种 API 都提供了对应的 MultiAgentFormatter。它把历史消息合并为一份带名字的对话记录（Alice: ...、Bob: ...），放进一条用户消息中，让大语言模型看到每个发言者的身份。切换方式是将其传入模型：

from agentscope.model import DashScopeChatModel
from agentscope.credential import DashScopeCredential
from agentscope.formatter import DashScopeMultiAgentFormatter

model = DashScopeChatModel(
    credential=DashScopeCredential(api_key="YOUR_API_KEY"),
    model="qwen-max",
    formatter=DashScopeMultiAgentFormatter(),
)

在多实体对话中，请在系统提示词里写明智能体自己的名字，让大语言模型知道自己扮演的是哪个角色。

AgentScope 为每种 API 都提供了配对的两种格式化器：

模型 API	对话格式化器（默认）	多智能体格式化器
DashScope	`DashScopeChatFormatter`	`DashScopeMultiAgentFormatter`
OpenAI	`OpenAIChatFormatter`	`OpenAIMultiAgentFormatter`
Anthropic	`AnthropicChatFormatter`	`AnthropicMultiAgentFormatter`
Gemini	`GeminiChatFormatter`	`GeminiMultiAgentFormatter`
Ollama	`OllamaChatFormatter`	`OllamaMultiAgentFormatter`
DeepSeek	`DeepSeekChatFormatter`	`DeepSeekMultiAgentFormatter`
Moonshot	`MoonshotChatFormatter`	`MoonshotMultiAgentFormatter`
XAI	`XAIChatFormatter`	`XAIMultiAgentFormatter`

工具

如何构建工具，接入 MCP 服务器与技能。

中间件

如何在回复、推理、行动和模型调用等钩子处插入自定义逻辑。

工作区

如何在不同沙箱中运行。

权限系统

如何控制工具调用的允许、询问与拒绝。

快速开始

核心模块

智能体即服务

其他

参数说明

切换模型

支持多实体对话

延伸阅读

工具

中间件

工作区

权限系统

​参数说明

​切换模型

​支持多实体对话

​延伸阅读

工具

中间件

工作区

权限系统

参数说明

切换模型

支持多实体对话

延伸阅读