> ## 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 development documentation. Use it only with the matching development source. 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.

# Configure Agent

> Assemble an agent from a model, tools, and configuration

An agent is assembled entirely at initialization: pass the model, toolkit, and config objects to `Agent(...)` and it is ready to reply. The examples below cover the most common setups.

<CodeGroup>
  ```python Minimal Setup theme={null}
  from agentscope.agent import Agent
  from agentscope.model import DashScopeChatModel
  from agentscope.credential import DashScopeCredential

  agent = Agent(
      name="my_agent",
      system_prompt="You are a helpful assistant.",
      model=DashScopeChatModel(
          credential=DashScopeCredential(api_key="YOUR_API_KEY"),
          model="qwen-max",
      ),
  )
  ```

  ```python With Tools/MCPs/Skills 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="You are a helpful assistant.",
      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 With Custom Context Config 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="You are a helpful assistant.",
      model=DashScopeChatModel(
          credential=DashScopeCredential(api_key="YOUR_API_KEY"),
          model="qwen-max",
      ),
      context_config=ContextConfig(
          trigger_ratio=0.7,       # compress when 70% of context is used
          reserve_ratio=0.2,       # keep the most recent 20% after compression
          tool_result_limit=1000,  # truncate tool results at 1000 tokens
      ),
  )
  ```

  ```python With Custom ReAct Config 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="You are a helpful assistant.",
      model=DashScopeChatModel(
          credential=DashScopeCredential(api_key="YOUR_API_KEY"),
          model="qwen-max",
      ),
      react_config=ReActConfig(
          max_iters=30,                     # at most 30 reasoning-acting iterations
          structured_output_grace_iters=3,  # extra iterations to finish structured output
          stop_on_reject=True,              # stop replying when tool calls are rejected
      ),
  )
  ```
</CodeGroup>

## Parameters

All configuration enters through the `Agent(...)` constructor. The table below lists every parameter, with the tunable knobs grouped into config objects:

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | `str` | required | Agent identifier, used in messages and logs |
| `system_prompt` | `str` | required | The agent's base system prompt |
| `model` | `ChatModelBase` | required | The LLM used for reasoning |
| `toolkit` | `Toolkit \| None` | `None` | Manages tools, MCP clients, skills, and tool groups |
| `state` | `AgentState \| None` | auto-created | Holds context, permission context, and session state |
| `offloader` | `Offloader \| None` | `None` | Offloads compressed context and tool results; must implement the `Offloader` protocol |
| `middlewares` | `list[MiddlewareBase] \| None` | `None` | Applied at reply, reasoning, acting, model call, and system prompt hooks |
| `model_config` | `ModelConfig` | default | Retry count and fallback model |
| `context_config` | `ContextConfig` | default | Context compression thresholds and tool result limits |
| `injection_config` | `InjectionConfig` | default | Runtime state injection: time, tasks, and context usage (see [Environment Awareness](/en/versions/2.0.6/building-blocks/context/environment-awareness)) |
| `react_config` | `ReActConfig` | default | Max iterations, structured output grace iterations, and rejection handling |

## Switch Models

Switching the LLM provider only changes the `model` argument: every provider follows the same `Model(credential=..., model=...)` pattern, and the rest of the agent stays untouched.

<CodeGroup>
  ```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",
  )
  ```
</CodeGroup>

## Support Multi-Entity Conversations

An agent is not limited to one-user-one-agent chat. In an agent team, a group chat, or a game with NPCs, messages from **multiple named entities** share the same context, and the agent must know who said what.

In AgentScope, each speaker is identified by the `name` field of its `Msg`. A multi-entity conversation is simply a list of messages with different names fed into the agent:

```python theme={null}
from agentscope.message import UserMsg

msgs = [
    UserMsg(name="Alice", content="I vote for the beach."),
    UserMsg(name="Bob", content="I'd rather go hiking."),
    UserMsg(name="user", content="Friday, summarize everyone's preference."),
]
result = await agent.reply(msgs)
```

Whether these identities survive is decided by the **formatter**, the component that converts `Msg` objects into the provider's API format before each model call. The default chat formatter maps messages onto the API's bare `user`/`assistant` roles, which fits one-user-one-agent chat but drops the names, leaving the speakers indistinguishable.

For multi-entity conversations, each provider ships a `MultiAgentFormatter`. It merges the history into a single named transcript (`Alice: ...`, `Bob: ...`) carried in a user message, so the LLM sees each speaker's identity. Switch by passing it to the model:

```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>
  In multi-entity conversations, state the agent's own name in its system prompt, so the LLM knows which speaker it is playing.
</Tip>

Each provider has a matching pair:

| Provider | Chat formatter (default) | Multi-agent formatter |
| - | - | - |
| DashScope | `DashScopeChatFormatter` | `DashScopeMultiAgentFormatter` |
| OpenAI | `OpenAIChatFormatter` | `OpenAIMultiAgentFormatter` |
| Anthropic | `AnthropicChatFormatter` | `AnthropicMultiAgentFormatter` |
| Gemini | `GeminiChatFormatter` | `GeminiMultiAgentFormatter` |
| Ollama | `OllamaChatFormatter` | `OllamaMultiAgentFormatter` |
| DeepSeek | `DeepSeekChatFormatter` | `DeepSeekMultiAgentFormatter` |
| Moonshot | `MoonshotChatFormatter` | `MoonshotMultiAgentFormatter` |
| XAI | `XAIChatFormatter` | `XAIMultiAgentFormatter` |

## Next Steps

<CardGroup cols={2}>
  <Card title="Tool" icon="wrench" href="/en/versions/2.0.6/building-blocks/tool/overview">
    How to build tools, and connect MCP servers and skills.
  </Card>

  <Card title="Middleware" icon="layer-group" href="/en/versions/2.0.6/building-blocks/middleware">
    How to hook into reply, reasoning, acting, and model calls.
  </Card>

  <Card title="Workspace" icon="box" href="/en/versions/2.0.6/building-blocks/workspace/overview">
    How to work in different sandboxes.
  </Card>

  <Card title="Permission System" icon="lock" href="/en/versions/2.0.6/building-blocks/permission-system/overview">
    How to control which tool calls run, ask, or are denied.
  </Card>
</CardGroup>


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