> ## 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 Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to the newest documentation and may move ahead of /stable/ when a development version exists. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# 配置智能体

> 用模型、工具与配置对象组装一个智能体

智能体在初始化时完成全部装配：把模型、工具包和配置对象传入 `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 时截断
        max_image_num=5,         # 只保留最近 5 张图片
    ),
)
```

```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` | 默认值 | 运行时状态注入：时间、任务与上下文用量（参见[感知环境](https://docs.agentscope.io/zh/versions/2.0.12dev/building-blocks/context/environment-awareness.md)） |
| `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(),
)
```

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

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` |

## 延伸阅读

> **[工具](https://docs.agentscope.io/zh/versions/2.0.12dev/building-blocks/tool/overview.md)**
>
> 如何构建工具，接入 MCP 服务器与技能。

> **[中间件](https://docs.agentscope.io/zh/versions/2.0.12dev/building-blocks/middleware.md)**
>
> 如何在回复、推理、行动和模型调用等钩子处插入自定义逻辑。

> **[工作区](https://docs.agentscope.io/zh/versions/2.0.12dev/building-blocks/workspace/overview.md)**
>
> 如何在不同沙箱中运行。

> **[权限系统](https://docs.agentscope.io/zh/versions/2.0.12dev/building-blocks/permission-system/overview.md)**
>
> 如何控制工具调用的允许、询问与拒绝。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.