> ## 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.

# FAQ

> Frequently asked questions about AgentScope.

<Info>
  Based on official documentation and community discussions (as of Feb 2026).
</Info>

## About AgentScope

<AccordionGroup>
  <Accordion title="What is AgentScope?">
    AgentScope is a multi-agent framework designed to provide a simple yet efficient way to build LLM-empowered agent applications.
  </Accordion>

  <Accordion title="What's the difference between AgentScope v1.0 and v0.x?">
    AgentScope v1.0 is a complete refactoring of the framework, equipped with new features and improvements. The most notable change is the shift to a **code-first development model**—the drag-and-drop Workstation UI from v0.x is **no longer maintained or recommended** for new projects.
  </Accordion>

  <Accordion title="Does AgentScope support automated planning like Manus?">
    Yes. You can refer to the [Plan with ReAct Agent](https://github.com/agentscope-ai/agentscope/tree/main/examples/functionality/plan#plan-with-react-agent) example on GitHub.
  </Accordion>

  <Accordion title="Can I use AgentScope with AI coding assistants like Cursor or Claude Code?">
    Absolutely. AgentScope's clean codebase and tutorials are highly compatible with AI pair programmers. Provide the GitHub repo or tutorial source (`docs/tutorial/en/src/`) as context for best results.
  </Accordion>

  <Accordion title="Are there community examples beyond the official demos?">
    Yes. Explore [agentscope-samples](https://github.com/agentscope-ai/agentscope-samples) for real-world use cases like Werewolf games, debates, and customer service bots built by the community.
  </Accordion>

  <Accordion title="How does AgentScope-Java relate to Spring AI Alibaba?">
    * **AgentScope-Java** is the Java port of AgentScope (under active development), aligned with the Python version in design and features.
    * **Spring AI Alibaba** will adopt AgentScope-Java as its underlying engine. If you use Spring AI Alibaba's Agentic APIs, you'll automatically gain AgentScope capabilities after upgrading—no need to integrate AgentScope-Java separately.
  </Accordion>
</AccordionGroup>

## About Models

<AccordionGroup>
  <Accordion title="What models does AgentScope support?">
    AgentScope has built-in support for **DashScope**, **Gemini**, **OpenAI**, **Anthropic**, and **Ollama** APIs, as well as `OpenAIChatModel` compatible with DeepSeek and vLLM models.
  </Accordion>

  <Accordion title="How do I integrate my own model with AgentScope?">
    Create a custom model class by inheriting from `agentscope.model.ChatModelBase` and implement the `__call__` method.
  </Accordion>

  <Accordion title="How do I monitor token usage in AgentScope?">
    AgentScope Studio provides visualization of token usage and tracing. See the [Observability](/versions/1.0.21/en/observe-and-evaluate/observability) section for details.
  </Accordion>

  <Accordion title="Why do I need different Formatters for different LLMs?">
    LLM providers (e.g., OpenAI, Anthropic, DashScope) have **different input format requirements** such as role names and tool call syntax. AgentScope uses **Formatters** to convert internal messages into API-compliant payloads, ensuring correctness even when vendors only partially support OpenAI-style APIs.
  </Accordion>

  <Accordion title="What is MultiAgentFormatter used for?">
    `MultiAgentFormatter` flattens multi-agent conversation history into a single string like `"Alice: Hello\nBob: Hi"` and sends it as a `user`-role message. This preserves global context but **loses per-agent identity and tool semantics** in the LLM's view. It's best suited for summary or coordination tasks—not fine-grained collaboration.
  </Accordion>

  <Accordion title="What's the difference between model fine-tuning and memory retrieval?">
    * **Fine-tuning** updates model weights for better task performance.
    * **Memory retrieval** injects relevant context at inference time (e.g., via vector databases).

    The two are **complementary**—you can even fine-tune a model to better leverage retrieved memories.
  </Accordion>
</AccordionGroup>

## About Agents & Tools

<AccordionGroup>
  <Accordion title="How do I create my own agent?">
    You can use the `ReActAgent` class directly, or create a custom agent by inheriting from `AgentBase` or `ReActAgentBase`. See the [Agent](/versions/1.0.21/en/basic-concepts/agent) section for details.
  </Accordion>

  <Accordion title="What's the difference between agent_base, react_agent_base, and react_agent?">
    * `agent_base`: Abstract base class defining the core agent interface.
    * `react_agent_base`: Implements the ReAct (Reason + Act) paradigm, handling thought-action loops.
    * `react_agent`: A concrete, ready-to-use agent that extends `react_agent_base` with tool integration.
  </Accordion>

  <Accordion title="Does AgentScope support dynamic Pydantic models for structured output?">
    Yes. AgentScope supports **dynamic JSON Schema generation** and leverages Pydantic for validation in ReAct agents. See the [Agent](/versions/1.0.21/en/basic-concepts/agent) page for details.
  </Accordion>

  <Accordion title="Can I use Anthropic-style skills in AgentScope?">
    Yes. Place your skill definitions in a directory following AgentScope's [skill structure](https://github.com/agentscope-ai/agentscope/blob/main/examples/functionality/agent_skill/README.md), then register them via `toolkit.register_agent_skill()`.
  </Accordion>

  <Accordion title="How do I forward the streaming output of agents to my own frontend?">
    Use the pre-hook of the `print` function to forward printed messages. See the [Hooking Functions](/versions/1.0.21/en/building-blocks/hooking-functions) section for details.
  </Accordion>

  <Accordion title="What built-in tools does AgentScope provide?">
    AgentScope includes a set of built-in tools such as `execute_python_code`, `execute_shell_command`, and `write_text_file`. You can find the full list under the `agentscope.tool` module.
  </Accordion>

  <Accordion title="Is MCP (Model Control Protocol) supported?">
    Yes. AgentScope supports standard-compliant MCP for tool and service integration. See the [Tool Capabilities](/versions/1.0.21/en/building-blocks/tool-capabilities) page for details.
  </Accordion>
</AccordionGroup>

## About AgentScope Runtime

<AccordionGroup>
  <Accordion title="Why use AgentScope Runtime instead of my own HTTP server + Docker setup?">
    Your current approach works well for **single-agent, single-environment** deployments. AgentScope Runtime is designed for more advanced scenarios:

    * **Decouples business logic from execution environment** via a unified protocol.
    * Enables **independent upgrades** of the runtime engine without touching agent code.
    * Supports **elastic scaling** of multiple agent instances (e.g., on Kubernetes).

    If you only deploy fixed agents in one environment, your existing workflow is sufficient. Use Runtime when you need **portability, scalability, or multi-platform deployment**.
  </Accordion>

  <Accordion title="What's the relationship between AgentApp and Runner?">
    * `AgentApp` defines the service interface (similar to FastAPI), using decorators such as `@agent_app.query(framework="agentscope")`.
    * `Runner` implements the actual agent execution logic.

    Requests sent to `AgentApp` are delegated to the `Runner`. The **decorator-based pattern** is the recommended approach—see the [QuickStart guide](https://runtime.agentscope.io/en/quickstart.html).
  </Accordion>

  <Accordion title="How does the Sandbox work? Can I validate commands in the Sandbox and run them on the host?">
    The Sandbox provides an **isolated, secure environment** for executing code, file operations, or browser actions.

    <Warning>
      Never re-run sandbox-validated operations on the host system.
    </Warning>

    Instead, follow these safe practices:

    * Mount **read-only host directories** into the sandbox for data access.
    * Let agents write to a **dedicated sandbox workspace**.
    * Use sandbox outputs (e.g., downloaded files) directly in downstream steps.

    The goal is **zero risk to the host system**.
  </Accordion>

  <Accordion title="Will Runtime simplify Kubernetes deployment?">
    Yes. Starting with **v1.0.2**, AgentScope Runtime will support **CLI-based deployment**, reducing boilerplate for Kubernetes and other platforms. The aim is to let you deploy the same agent artifact across ModelStudio, AgentRun, K8s, and more—without any code changes.
  </Accordion>
</AccordionGroup>

## Reporting Bugs & Community

<AccordionGroup>
  <Accordion title="How do I report a bug in AgentScope?">
    If you encounter a bug, open an issue on the [AgentScope GitHub repository](https://github.com/agentscope-ai/agentscope/issues).
  </Accordion>

  <Accordion title="How do I report a security vulnerability in AgentScope?">
    If you discover a security issue, report it through the [Alibaba Security Response Center (ASRC)](https://security.alibaba.com/).
  </Accordion>

  <Accordion title="Where can I find the community and get help?">
    Join the official community group through Discord or DingTalk:

    | [**Discord**](https://discord.gg/eYMpfnkG8h)                                                                                                                   | **DingTalk**                                                                                                                                                                                                               |
    | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | [![Discord](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/mPdnpEbk9rGLgqw9/img/aae46e38-9875-4867-9de0-01ccbefcd610.png)](https://discord.gg/eYMpfnkG8h) | [![DingTalk](https://alidocs.oss-cn-zhangjiakou.aliyuncs.com/res/mPdnpEbk9rGLgqw9/img/57e53bf1-c52b-457e-9a21-b295a49136a9.png)](https://github.com/agentscope-ai/agentscope/blob/main/assets/images/dingtalk_qr_code.png) |
  </Accordion>
</AccordionGroup>

***