> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentscope.io/llms.txt > Use this file to discover all available pages before exploring further. # 配置智能体 > 用模型、工具与配置对象组装一个智能体 智能体在初始化时完成全部装配：把模型、工具包和配置对象传入 `Agent(...)`，即可开始回复。以下示例涵盖最常见的几种配置场景。 ```python 最简配置 theme={null} 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", ), ) ``` ```python 配置工具/MCP/技能 theme={null} 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"], ), ) ``` ```python 自定义上下文配置 theme={null} 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 时截断 ), ) ``` ```python 自定义 ReAct 配置 theme={null} 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` | 默认值 | 运行时状态注入：时间、任务与上下文用量（参见[感知环境](/versions/2.0.5dev/zh/building-blocks/context/environment-awareness)） | | `react_config` | `ReActConfig` | 默认值 | 最大迭代次数、结构化输出宽限迭代次数和拒绝处理方式 | ## 切换模型 切换模型 API 只需改动 `model` 参数：所有模型类都遵循相同的 `Model(credential=..., model=...)` 模式，智能体的其余部分保持不变。 ```python DashScope theme={null} from agentscope.model import DashScopeChatModel from agentscope.credential import DashScopeCredential model = DashScopeChatModel( credential=DashScopeCredential(api_key="YOUR_API_KEY"), model="qwen-max", ) ``` ```python OpenAI theme={null} from agentscope.model import OpenAIChatModel from agentscope.credential import OpenAICredential model = OpenAIChatModel( credential=OpenAICredential(api_key="YOUR_API_KEY"), model="gpt-4o", ) ``` ```python Anthropic theme={null} from agentscope.model import AnthropicChatModel from agentscope.credential import AnthropicCredential model = AnthropicChatModel( credential=AnthropicCredential(api_key="YOUR_API_KEY"), model="claude-sonnet-4-5", ) ``` ```python Gemini theme={null} from agentscope.model import GeminiChatModel from agentscope.credential import GeminiCredential model = GeminiChatModel( credential=GeminiCredential(api_key="YOUR_API_KEY"), model="gemini-2.5-pro", ) ``` ```python Ollama theme={null} 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` 字段标识。多实体对话就是一组带有不同名字的消息列表，直接喂给智能体即可： ```python theme={null} 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: ...`），放进一条用户消息中，让大语言模型看到每个发言者的身份。切换方式是将其传入模型： ```python theme={null} 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 服务器与技能。 如何在回复、推理、行动和模型调用等钩子处插入自定义逻辑。 如何在不同沙箱中运行。 如何控制工具调用的允许、询问与拒绝。