diff --git a/README.md b/README.md index 2c8c5c2..0c95dbd 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,17 @@ # AgentScope Documentation -This repository contains the official documentation for [AgentScope](https://github.com/modelscope/agentscope), a production-ready, multi-agent framework for building LLM-empowered agent applications. The docs site is built with [Mintlify](https://mintlify.com). +This repository contains the unified documentation site for [AgentScope](https://github.com/agentscope-ai/agentscope) and [ReMe](https://github.com/agentscope-ai/ReMe). The site is built with [Mintlify](https://mintlify.com) and deployed at [docs.agentscope.io](https://docs.agentscope.io). -## Overview +## Documentation Sets -AgentScope provides a simple yet efficient way to build LLM-empowered agent applications, with built-in support for: +- **AgentScope**: a framework for building agent applications. +- **ReMe**: a local-first, file-native memory layer for AI agents. -- Multi-agent orchestration -- Multiple model providers (DashScope, Gemini, OpenAI, Anthropic, Ollama) -- Memory (short-term and long-term) -- Tools and RAG -- Observability and evaluation +Each project owns its version history and bilingual navigation. Version selectors are defined independently for the `AgentScope` and `ReMe` tabs in `docs.json`. -## Development +## Local Development -### Prerequisites - -- Node.js version 19 or higher - -### Local Preview +Use an active Node.js LTS release (Node 20 or 22). Install the [Mintlify CLI](https://www.npmjs.com/package/mint): @@ -26,47 +19,53 @@ Install the [Mintlify CLI](https://www.npmjs.com/package/mint): npm i -g mint ``` -Start the local development server at the root of this repository (where `docs.json` is located): +From the repository root, validate the site or start a preview: ```bash +mint validate mint dev ``` -View your local preview at `http://localhost:3000`. +The preview is available at `http://localhost:3000` by default. ## Repository Structure -``` +```text . -├── basic-concepts/ # Core AgentScope concepts (msg, agent, model, memory, tool) -├── building-blocks/ # Advanced building blocks -├── tutorial/ # Step-by-step tutorials -├── out-of-box-agents/ # Pre-built agents -├── api-reference/ # API documentation -├── observe-and-evaluate/ # Monitoring and evaluation -├── tune-agent/ # Agent tuning guides -├── deploy-and-serve/ # Deployment options -├── essentials/ # Documentation components -├── others/ # FAQ and additional resources -└── docs.json # Mintlify navigation config +├── agentscope/ +│ └── /{en,zh}/ # Versioned AgentScope documentation +├── reme/ +│ └── /{en,zh}/ # Versioned ReMe documentation +├── images/ # Shared static assets +├── scripts/ # Documentation maintenance scripts +├── docs.json # Mintlify navigation and redirects +└── CLAUDE.md # Writing and review guidelines ``` -## Contributing +## Version Management -When adding or updating documentation: +Published documentation is immutable within its version directory. For a new release: -1. Place `.mdx` files in the appropriate directory -2. Update `docs.json` to include new pages in the navigation -3. Start every page with YAML frontmatter (`title` and `description`) -4. Follow the [writing style guidelines](CLAUDE.md) in this repo -5. Preview changes locally before submitting a PR +1. Copy the latest relevant version into a new project version directory. +2. Update every version-specific internal link in the copied pages. +3. Add the version under the matching project tab for both languages in `docs.json`. +4. Point that project's `latest` or `stable` redirect at the new version. +5. Run `mint validate` before submitting the change. -## Troubleshooting +AgentScope versions can be created with `scripts/create-version.sh`. ReMe follows the same directory and navigation model under `reme/` and uses project-scoped aliases such as `/reme/stable/...` so its releases do not affect AgentScope aliases. + +## Contributing + +When adding or updating documentation: -- **Dev server not running**: Run `mint update` to get the latest CLI version. -- **Page shows 404**: Ensure you are running in the folder containing `docs.json`. +1. Place `.mdx` files in the correct project, version, and language directory. +2. Update `docs.json` when pages or versions change. +3. Start every page with YAML frontmatter containing `title` and `description`. +4. Follow [CLAUDE.md](CLAUDE.md) for writing and review conventions. +5. Run `mint validate` before submitting a pull request. ## Resources - [AgentScope GitHub](https://github.com/agentscope-ai/agentscope) +- [ReMe GitHub](https://github.com/agentscope-ai/ReMe) - [Mintlify Documentation](https://mintlify.com/docs) diff --git a/versions/1.0.21/en/basic-concepts/agent.mdx b/agentscope/1.0.21/en/basic-concepts/agent.mdx similarity index 100% rename from versions/1.0.21/en/basic-concepts/agent.mdx rename to agentscope/1.0.21/en/basic-concepts/agent.mdx diff --git a/versions/1.0.21/en/basic-concepts/context-and-memory.mdx b/agentscope/1.0.21/en/basic-concepts/context-and-memory.mdx similarity index 96% rename from versions/1.0.21/en/basic-concepts/context-and-memory.mdx rename to agentscope/1.0.21/en/basic-concepts/context-and-memory.mdx index 5143ae7..59657f4 100644 --- a/versions/1.0.21/en/basic-concepts/context-and-memory.mdx +++ b/agentscope/1.0.21/en/basic-concepts/context-and-memory.mdx @@ -7,7 +7,7 @@ icon: 'database' This document introduces how AgentScope handles context and memory in agent workflows. -For implementation details and APIs, see [Context and Memory](/versions/1.0.21/en/building-blocks/context-and-memory). +For implementation details and APIs, see [Context and Memory](/agentscope/1.0.21/en/building-blocks/context-and-memory). --- diff --git a/versions/1.0.21/en/basic-concepts/model.mdx b/agentscope/1.0.21/en/basic-concepts/model.mdx similarity index 99% rename from versions/1.0.21/en/basic-concepts/model.mdx rename to agentscope/1.0.21/en/basic-concepts/model.mdx index 39ab3dc..03d5a9a 100644 --- a/versions/1.0.21/en/basic-concepts/model.mdx +++ b/agentscope/1.0.21/en/basic-concepts/model.mdx @@ -45,7 +45,7 @@ To support multi-agent conversations in a chatbot format, AgentScope designs a f Such formatters are distinguished by the suffix `ChatFormatter` (e.g., `DashScopeChatFormatter`) and `MultiAgentFormatter` (e.g., `DashScopeMultiAgentFormatter`) — the former is for two-party conversations (user + assistant), while the latter is for multi-agent conversations. -For detailed usage examples and a full provider reference table mapping each model class to its corresponding formatter, see [Models](/versions/1.0.21/en/building-blocks/models). +For detailed usage examples and a full provider reference table mapping each model class to its corresponding formatter, see [Models](/agentscope/1.0.21/en/building-blocks/models). diff --git a/versions/1.0.21/en/basic-concepts/msg.mdx b/agentscope/1.0.21/en/basic-concepts/msg.mdx similarity index 100% rename from versions/1.0.21/en/basic-concepts/msg.mdx rename to agentscope/1.0.21/en/basic-concepts/msg.mdx diff --git a/versions/1.0.21/en/basic-concepts/tool.mdx b/agentscope/1.0.21/en/basic-concepts/tool.mdx similarity index 100% rename from versions/1.0.21/en/basic-concepts/tool.mdx rename to agentscope/1.0.21/en/basic-concepts/tool.mdx diff --git a/versions/1.0.21/en/building-blocks/agent.mdx b/agentscope/1.0.21/en/building-blocks/agent.mdx similarity index 99% rename from versions/1.0.21/en/building-blocks/agent.mdx rename to agentscope/1.0.21/en/building-blocks/agent.mdx index f83b2fa..9c03c72 100644 --- a/versions/1.0.21/en/building-blocks/agent.mdx +++ b/agentscope/1.0.21/en/building-blocks/agent.mdx @@ -39,7 +39,7 @@ AgentScope provides several built-in agent types to cover different use cases. U | Memory compression | Automatically compress long conversation history | | Parallel tool calls | Execute multiple tool calls concurrently | | Structured output | Return typed, schema-validated responses | -| Fine-grained MCP control | See [MCP integration](/versions/1.0.21/en/building-blocks/tool-capabilities#mcp-integration) | +| Fine-grained MCP control | See [MCP integration](/agentscope/1.0.21/en/building-blocks/tool-capabilities#mcp-integration) | | Meta tool | Agent-controlled tool management | | Long-term memory | Self-controlled persistent memory | | Plan | Break complex tasks into managed subtasks and execute them systematically | diff --git a/versions/1.0.21/en/building-blocks/context-and-memory.mdx b/agentscope/1.0.21/en/building-blocks/context-and-memory.mdx similarity index 97% rename from versions/1.0.21/en/building-blocks/context-and-memory.mdx rename to agentscope/1.0.21/en/building-blocks/context-and-memory.mdx index 4de105a..b17487d 100644 --- a/versions/1.0.21/en/building-blocks/context-and-memory.mdx +++ b/agentscope/1.0.21/en/building-blocks/context-and-memory.mdx @@ -19,7 +19,7 @@ This mechanism supports high-level memory management in agents. For example, in The memory module focuses on storage and management. Algorithmic logic (for example, compression strategy) is implemented at the agent layer. -> For conceptual background, see [Context and Memory](/versions/1.0.21/en/basic-concepts/context-and-memory). +> For conceptual background, see [Context and Memory](/agentscope/1.0.21/en/basic-concepts/context-and-memory). In AgentScope, memory can be viewed in two layers: @@ -442,10 +442,10 @@ If your backend supports all methods, it can be used in `both` mode. ## Further Reading - + Understand the agent's core methods and the ReAct paradigm. - + Learn how to extend agents with native functions, MCP, and skills. diff --git a/versions/1.0.21/en/building-blocks/hooking-functions.mdx b/agentscope/1.0.21/en/building-blocks/hooking-functions.mdx similarity index 100% rename from versions/1.0.21/en/building-blocks/hooking-functions.mdx rename to agentscope/1.0.21/en/building-blocks/hooking-functions.mdx diff --git a/versions/1.0.21/en/building-blocks/models.mdx b/agentscope/1.0.21/en/building-blocks/models.mdx similarity index 98% rename from versions/1.0.21/en/building-blocks/models.mdx rename to agentscope/1.0.21/en/building-blocks/models.mdx index c024771..51c690b 100644 --- a/versions/1.0.21/en/building-blocks/models.mdx +++ b/agentscope/1.0.21/en/building-blocks/models.mdx @@ -22,7 +22,7 @@ This document covers detailed usage examples and provider-specific references fo -For core concepts and design principles, see [Model](/versions/1.0.21/en/basic-concepts/model). For details on `Msg` and content blocks, see [Msg](/versions/1.0.21/en/basic-concepts/msg). +For core concepts and design principles, see [Model](/agentscope/1.0.21/en/basic-concepts/model). For details on `Msg` and content blocks, see [Msg](/agentscope/1.0.21/en/basic-concepts/msg). --- @@ -236,7 +236,7 @@ The `tool_choice` parameter controls invocation behavior: - `""`: Force a specific tool -Use the `Toolkit` class to auto-generate JSON schemas from Python functions with docstrings. See [Tool](/versions/1.0.21/en/basic-concepts/tool) for details. +Use the `Toolkit` class to auto-generate JSON schemas from Python functions with docstrings. See [Tool](/agentscope/1.0.21/en/basic-concepts/tool) for details. ### Provider Reference diff --git a/versions/1.0.21/en/building-blocks/orchestration.mdx b/agentscope/1.0.21/en/building-blocks/orchestration.mdx similarity index 99% rename from versions/1.0.21/en/building-blocks/orchestration.mdx rename to agentscope/1.0.21/en/building-blocks/orchestration.mdx index 0851bc3..86f2860 100644 --- a/versions/1.0.21/en/building-blocks/orchestration.mdx +++ b/agentscope/1.0.21/en/building-blocks/orchestration.mdx @@ -388,7 +388,7 @@ await chat_room.stop() # Disconnect all agents ## Formatter Reference -> For an introduction to Chat vs MultiAgent formatters and how to choose one, see [Model — Formatter](/versions/1.0.21/en/basic-concepts/model#chat-model). +> For an introduction to Chat vs MultiAgent formatters and how to choose one, see [Model — Formatter](/agentscope/1.0.21/en/basic-concepts/model#chat-model). ### Formatter Table diff --git a/versions/1.0.21/en/building-blocks/rag.mdx b/agentscope/1.0.21/en/building-blocks/rag.mdx similarity index 98% rename from versions/1.0.21/en/building-blocks/rag.mdx rename to agentscope/1.0.21/en/building-blocks/rag.mdx index ce325b6..3263820 100644 --- a/versions/1.0.21/en/building-blocks/rag.mdx +++ b/agentscope/1.0.21/en/building-blocks/rag.mdx @@ -318,10 +318,10 @@ asyncio.run(example_multimodal_rag()) ## Further Reading - + Memory backends for storing and managing session messages. - + ReActAgent internals, tool registration, and reply lifecycle. diff --git a/versions/1.0.21/en/building-blocks/tool-capabilities.mdx b/agentscope/1.0.21/en/building-blocks/tool-capabilities.mdx similarity index 100% rename from versions/1.0.21/en/building-blocks/tool-capabilities.mdx rename to agentscope/1.0.21/en/building-blocks/tool-capabilities.mdx diff --git a/versions/1.0.21/en/deploy-and-serve/agent-as-service.mdx b/agentscope/1.0.21/en/deploy-and-serve/agent-as-service.mdx similarity index 100% rename from versions/1.0.21/en/deploy-and-serve/agent-as-service.mdx rename to agentscope/1.0.21/en/deploy-and-serve/agent-as-service.mdx diff --git a/versions/1.0.21/en/deploy-and-serve/sandbox-and-tool.mdx b/agentscope/1.0.21/en/deploy-and-serve/sandbox-and-tool.mdx similarity index 100% rename from versions/1.0.21/en/deploy-and-serve/sandbox-and-tool.mdx rename to agentscope/1.0.21/en/deploy-and-serve/sandbox-and-tool.mdx diff --git a/versions/1.0.21/en/index.mdx b/agentscope/1.0.21/en/index.mdx similarity index 63% rename from versions/1.0.21/en/index.mdx rename to agentscope/1.0.21/en/index.mdx index 808dcc7..80ec2aa 100644 --- a/versions/1.0.21/en/index.mdx +++ b/agentscope/1.0.21/en/index.mdx @@ -15,11 +15,11 @@ We design for increasingly agentic LLMs. Our approach leverages the models' reas ## Start with AgentScope -* [Quickstart ->](/versions/1.0.21/quickstart): Build your first chatbot agent in 5 minutes -* [Out-of-box agents ->](/versions/1.0.21/out-of-box-agents): Try out our collection of pre-built agents for various use cases -* [Basic concepts & building blocks ->](/versions/1.0.21/basic-concepts): Learn about the core abstractions in AgentScope and how to use them -* [Observe & evaluate ->](/versions/1.0.21/observe-and-evaluate): Learn how to observe and evaluate your agents with built-in OTel support and evaluation tools -* [Deploy & serve ->](/versions/1.0.21/deploy-and-serve): Deploy your agents locally, as serverless in the cloud or on your K8s cluster, with different protocols and tool sandboxes +* [Quickstart ->](/agentscope/1.0.21/quickstart): Build your first chatbot agent in 5 minutes +* [Out-of-box agents ->](/agentscope/1.0.21/out-of-box-agents): Try out our collection of pre-built agents for various use cases +* [Basic concepts & building blocks ->](/agentscope/1.0.21/basic-concepts): Learn about the core abstractions in AgentScope and how to use them +* [Observe & evaluate ->](/agentscope/1.0.21/observe-and-evaluate): Learn how to observe and evaluate your agents with built-in OTel support and evaluation tools +* [Deploy & serve ->](/agentscope/1.0.21/deploy-and-serve): Deploy your agents locally, as serverless in the cloud or on your K8s cluster, with different protocols and tool sandboxes --- diff --git a/versions/1.0.21/en/observe-and-evaluate/evaluation.mdx b/agentscope/1.0.21/en/observe-and-evaluate/evaluation.mdx similarity index 100% rename from versions/1.0.21/en/observe-and-evaluate/evaluation.mdx rename to agentscope/1.0.21/en/observe-and-evaluate/evaluation.mdx diff --git a/versions/1.0.21/en/observe-and-evaluate/observability.mdx b/agentscope/1.0.21/en/observe-and-evaluate/observability.mdx similarity index 98% rename from versions/1.0.21/en/observe-and-evaluate/observability.mdx rename to agentscope/1.0.21/en/observe-and-evaluate/observability.mdx index 3827ced..4797c51 100644 --- a/versions/1.0.21/en/observe-and-evaluate/observability.mdx +++ b/agentscope/1.0.21/en/observe-and-evaluate/observability.mdx @@ -206,7 +206,7 @@ def my_sync_fn(x: int) -> int: Token usage is tracked by the model layer and is included in trace metadata where supported. When you connect to **AgentScope Studio**, token consumption is visualized in the Studio UI so you can monitor cost and usage per run. For third-party backends, token-related attributes are exported with the LLM spans according to the OpenTelemetry semantic conventions used by AgentScope. -For programmatic access to usage after a model call, use the `usage` field on the [ChatResponse](/versions/1.0.21/en/building-blocks/models) returned by the model. +For programmatic access to usage after a model call, use the `usage` field on the [ChatResponse](/agentscope/1.0.21/en/building-blocks/models) returned by the model. --- @@ -217,4 +217,4 @@ For programmatic access to usage after a model call, use the `usage` field on th - Use **tracing_url** to send traces to Arize-Phoenix, Langfuse, Alibaba Cloud CloudMonitor, or any OTLP endpoint. - Use **@trace_llm**, **@trace_reply**, **@trace_format**, **@trace_toolkit**, **@trace_embedding**, and **@trace** when implementing custom models, agents, or formatters so they appear in the same trace tree. -For evaluation of agent behavior and benchmarks, see [Evaluation](/versions/1.0.21/en/observe-and-evaluate/evaluation). +For evaluation of agent behavior and benchmarks, see [Evaluation](/agentscope/1.0.21/en/observe-and-evaluate/evaluation). diff --git a/versions/1.0.21/en/others/contribution.mdx b/agentscope/1.0.21/en/others/contribution.mdx similarity index 100% rename from versions/1.0.21/en/others/contribution.mdx rename to agentscope/1.0.21/en/others/contribution.mdx diff --git a/versions/1.0.21/en/others/faq.mdx b/agentscope/1.0.21/en/others/faq.mdx similarity index 94% rename from versions/1.0.21/en/others/faq.mdx rename to agentscope/1.0.21/en/others/faq.mdx index 7dea341..129c112 100644 --- a/versions/1.0.21/en/others/faq.mdx +++ b/agentscope/1.0.21/en/others/faq.mdx @@ -52,7 +52,7 @@ Create a custom model class by inheriting from `agentscope.model.ChatModelBase` -AgentScope Studio provides visualization of token usage and tracing. See the [Observability](/versions/1.0.21/en/observe-and-evaluate/observability) section for details. +AgentScope Studio provides visualization of token usage and tracing. See the [Observability](/agentscope/1.0.21/en/observe-and-evaluate/observability) section for details. @@ -77,7 +77,7 @@ The two are **complementary**—you can even fine-tune a model to better leverag -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. +You can use the `ReActAgent` class directly, or create a custom agent by inheriting from `AgentBase` or `ReActAgentBase`. See the [Agent](/agentscope/1.0.21/en/basic-concepts/agent) section for details. @@ -87,7 +87,7 @@ You can use the `ReActAgent` class directly, or create a custom agent by inherit -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. +Yes. AgentScope supports **dynamic JSON Schema generation** and leverages Pydantic for validation in ReAct agents. See the [Agent](/agentscope/1.0.21/en/basic-concepts/agent) page for details. @@ -95,7 +95,7 @@ Yes. Place your skill definitions in a directory following AgentScope's [skill s -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. +Use the pre-hook of the `print` function to forward printed messages. See the [Hooking Functions](/agentscope/1.0.21/en/building-blocks/hooking-functions) section for details. @@ -103,7 +103,7 @@ AgentScope includes a set of built-in tools such as `execute_python_code`, `exec -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. +Yes. AgentScope supports standard-compliant MCP for tool and service integration. See the [Tool Capabilities](/agentscope/1.0.21/en/building-blocks/tool-capabilities) page for details. diff --git a/versions/1.0.21/en/out-of-box-agents/alias-finance.mdx b/agentscope/1.0.21/en/out-of-box-agents/alias-finance.mdx similarity index 100% rename from versions/1.0.21/en/out-of-box-agents/alias-finance.mdx rename to agentscope/1.0.21/en/out-of-box-agents/alias-finance.mdx diff --git a/versions/1.0.21/en/out-of-box-agents/alias.mdx b/agentscope/1.0.21/en/out-of-box-agents/alias.mdx similarity index 100% rename from versions/1.0.21/en/out-of-box-agents/alias.mdx rename to agentscope/1.0.21/en/out-of-box-agents/alias.mdx diff --git a/versions/1.0.21/en/out-of-box-agents/browser-use.mdx b/agentscope/1.0.21/en/out-of-box-agents/browser-use.mdx similarity index 100% rename from versions/1.0.21/en/out-of-box-agents/browser-use.mdx rename to agentscope/1.0.21/en/out-of-box-agents/browser-use.mdx diff --git a/versions/1.0.21/en/out-of-box-agents/data-science.mdx b/agentscope/1.0.21/en/out-of-box-agents/data-science.mdx similarity index 98% rename from versions/1.0.21/en/out-of-box-agents/data-science.mdx rename to agentscope/1.0.21/en/out-of-box-agents/data-science.mdx index f93398c..f1fe474 100644 --- a/versions/1.0.21/en/out-of-box-agents/data-science.mdx +++ b/agentscope/1.0.21/en/out-of-box-agents/data-science.mdx @@ -92,7 +92,7 @@ The Data Science Agent supports multiple data source formats: All uploaded files are automatically copied to the `/workspace` directory in the sandbox for secure processing. -The Data Science Agent is built with DashScope chat models. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/versions/1.0.21/en/building-blocks/models#provider-reference). +The Data Science Agent is built with DashScope chat models. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/agentscope/1.0.21/en/building-blocks/models#provider-reference). diff --git a/versions/1.0.21/en/out-of-box-agents/datajuicer-agent.mdx b/agentscope/1.0.21/en/out-of-box-agents/datajuicer-agent.mdx similarity index 100% rename from versions/1.0.21/en/out-of-box-agents/datajuicer-agent.mdx rename to agentscope/1.0.21/en/out-of-box-agents/datajuicer-agent.mdx diff --git a/versions/1.0.21/en/out-of-box-agents/deep-research.mdx b/agentscope/1.0.21/en/out-of-box-agents/deep-research.mdx similarity index 98% rename from versions/1.0.21/en/out-of-box-agents/deep-research.mdx rename to agentscope/1.0.21/en/out-of-box-agents/deep-research.mdx index 760ad2f..2404c5a 100644 --- a/versions/1.0.21/en/out-of-box-agents/deep-research.mdx +++ b/agentscope/1.0.21/en/out-of-box-agents/deep-research.mdx @@ -118,7 +118,7 @@ while True: ``` -The example is built with DashScope chat model. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/versions/1.0.21/en/building-blocks/models#provider-reference). +The example is built with DashScope chat model. If you want to change the model, ensure you also update the formatter accordingly. The correspondence between built-in models and formatters is listed in the [Provider Reference](/agentscope/1.0.21/en/building-blocks/models#provider-reference). diff --git a/versions/1.0.21/en/out-of-box-agents/evo-trader.mdx b/agentscope/1.0.21/en/out-of-box-agents/evo-trader.mdx similarity index 100% rename from versions/1.0.21/en/out-of-box-agents/evo-trader.mdx rename to agentscope/1.0.21/en/out-of-box-agents/evo-trader.mdx diff --git a/versions/1.0.21/en/quickstart.mdx b/agentscope/1.0.21/en/quickstart.mdx similarity index 100% rename from versions/1.0.21/en/quickstart.mdx rename to agentscope/1.0.21/en/quickstart.mdx diff --git a/versions/1.0.21/en/tune-agent/model-selection-tuning.mdx b/agentscope/1.0.21/en/tune-agent/model-selection-tuning.mdx similarity index 95% rename from versions/1.0.21/en/tune-agent/model-selection-tuning.mdx rename to agentscope/1.0.21/en/tune-agent/model-selection-tuning.mdx index 9653628..de61a7a 100644 --- a/versions/1.0.21/en/tune-agent/model-selection-tuning.mdx +++ b/agentscope/1.0.21/en/tune-agent/model-selection-tuning.mdx @@ -81,7 +81,7 @@ The workflow function executes your agent logic with a given model and returns a - Run inference using that model - Return a `WorkflowOutput` object containing the model's response -This pattern is identical to the one introduced in [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent#workflow-function). For a complete implementation example — including how to set up an agent, format messages, and return structured output — please refer to that guide. +This pattern is identical to the one introduced in [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent#workflow-function). For a complete implementation example — including how to set up an agent, format messages, and return structured output — please refer to that guide. Your function must return `WorkflowOutput`. Do not define custom output classes. @@ -95,7 +95,7 @@ The judge function evaluates the output of the workflow and assigns a numerical - Compute a scalar `reward` (e.g., accuracy, BLEU score, or inverse latency) - Return a `JudgeOutput` object with `reward` and `metrics` -This follows the same contract described in [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent#judge-function). That guide provides a step-by-step example of building a correctness-based judge. +This follows the same contract described in [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent#judge-function). That guide provides a step-by-step example of building a correctness-based judge. ## Using Built-in Judges diff --git a/versions/1.0.21/en/tune-agent/model-weights-tuning.mdx b/agentscope/1.0.21/en/tune-agent/model-weights-tuning.mdx similarity index 98% rename from versions/1.0.21/en/tune-agent/model-weights-tuning.mdx rename to agentscope/1.0.21/en/tune-agent/model-weights-tuning.mdx index 80d0442..8575389 100644 --- a/versions/1.0.21/en/tune-agent/model-weights-tuning.mdx +++ b/agentscope/1.0.21/en/tune-agent/model-weights-tuning.mdx @@ -35,7 +35,7 @@ ray start --head ## Refine Workflow Function -Continuing from [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent.mdx), assume you have a task dataset and judge function ready. Now, refine your workflow function for model weights tuning: +Continuing from [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent.mdx), assume you have a task dataset and judge function ready. Now, refine your workflow function for model weights tuning: ```python async def example_workflow_function( diff --git a/versions/1.0.21/en/tune-agent/prompt-tuning.mdx b/agentscope/1.0.21/en/tune-agent/prompt-tuning.mdx similarity index 96% rename from versions/1.0.21/en/tune-agent/prompt-tuning.mdx rename to agentscope/1.0.21/en/tune-agent/prompt-tuning.mdx index d1a47c0..cc5df1c 100644 --- a/versions/1.0.21/en/tune-agent/prompt-tuning.mdx +++ b/agentscope/1.0.21/en/tune-agent/prompt-tuning.mdx @@ -31,7 +31,7 @@ Never commit your API key to version control. Use environment variables or a `.e ## Refine Workflow Function -Continuing from [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent#workflow-function), assume you have a task dataset and judge function ready. Now, refine your workflow function for prompt tuning: +Continuing from [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent#workflow-function), assume you have a task dataset and judge function ready. Now, refine your workflow function for prompt tuning: ```python async def workflow( diff --git a/versions/1.0.21/en/tune-agent/tune-multi-agents.mdx b/agentscope/1.0.21/en/tune-agent/tune-multi-agents.mdx similarity index 95% rename from versions/1.0.21/en/tune-agent/tune-multi-agents.mdx rename to agentscope/1.0.21/en/tune-agent/tune-multi-agents.mdx index c454b0f..c925ba9 100644 --- a/versions/1.0.21/en/tune-agent/tune-multi-agents.mdx +++ b/agentscope/1.0.21/en/tune-agent/tune-multi-agents.mdx @@ -6,7 +6,7 @@ icon: 'users' In many real-world applications, agents do not work in isolation — they interact, cooperate, or compete with each other in multi-agent systems. The `tuner` module supports tuning agents within such multi-agent settings, allowing you to optimize a subset of agents while other agents serve as the environment or opponents. -This tutorial builds on the concepts introduced in [Overview](/versions/1.0.21/en/tune-agent/tune-your-first-agent.mdx) and [Agent Reinforcement Learning](/versions/1.0.21/en/tune-agent/model-weights-tuning.mdx). Make sure you are familiar with the core components (Task Dataset, Workflow Function, Judge Function) and the basic tuning workflow before proceeding. +This tutorial builds on the concepts introduced in [Overview](/agentscope/1.0.21/en/tune-agent/tune-your-first-agent.mdx) and [Agent Reinforcement Learning](/agentscope/1.0.21/en/tune-agent/model-weights-tuning.mdx). Make sure you are familiar with the core components (Task Dataset, Workflow Function, Judge Function) and the basic tuning workflow before proceeding. We will use a simplified **werewolf game** as the running example throughout this tutorial. In this game, 7 players (2 werewolves, 3 villagers, 1 seer, 1 witch) interact over multiple rounds of discussion and voting. The goal is to train the werewolf players to improve their win rate. @@ -144,7 +144,7 @@ return WorkflowOutput( When you compute reward directly in the workflow, pass `judge_func=None` to the `tune()` function. -For multi-agent scenarios without clear win/loss outcomes, you can still use a separate judge function or LLM-as-a-Judge as described in [Agent Reinforcement Learning — LLM-as-a-Judge](/versions/1.0.21/en/tune-agent/model-weights-tuning.mdx#llm-as-a-judge). +For multi-agent scenarios without clear win/loss outcomes, you can still use a separate judge function or LLM-as-a-Judge as described in [Agent Reinforcement Learning — LLM-as-a-Judge](/agentscope/1.0.21/en/tune-agent/model-weights-tuning.mdx#llm-as-a-judge). @@ -302,7 +302,7 @@ Using a stronger model for auxiliary agents provides a more challenging and stab -Add the `logger` parameter to your workflow function (see [Agent Reinforcement Learning — Runtime Monitoring](/versions/1.0.21/en/tune-agent/model-weights-tuning#runtime-monitoring)) to debug multi-agent interactions during tuning. +Add the `logger` parameter to your workflow function (see [Agent Reinforcement Learning — Runtime Monitoring](/agentscope/1.0.21/en/tune-agent/model-weights-tuning#runtime-monitoring)) to debug multi-agent interactions during tuning. diff --git a/versions/1.0.21/en/tune-agent/tune-your-first-agent.mdx b/agentscope/1.0.21/en/tune-agent/tune-your-first-agent.mdx similarity index 100% rename from versions/1.0.21/en/tune-agent/tune-your-first-agent.mdx rename to agentscope/1.0.21/en/tune-agent/tune-your-first-agent.mdx diff --git a/versions/1.0.21/en/tutorial/tutorial_research_agent.mdx b/agentscope/1.0.21/en/tutorial/tutorial_research_agent.mdx similarity index 98% rename from versions/1.0.21/en/tutorial/tutorial_research_agent.mdx rename to agentscope/1.0.21/en/tutorial/tutorial_research_agent.mdx index 7927d4f..b42bb43 100644 --- a/versions/1.0.21/en/tutorial/tutorial_research_agent.mdx +++ b/agentscope/1.0.21/en/tutorial/tutorial_research_agent.mdx @@ -826,6 +826,6 @@ asyncio.run(demo_full_assistant()) Congratulations on completing this tutorial! You have mastered the core capabilities of an AgentScope single agent. Next, you can explore: -- [**Context and Memory**](/versions/1.0.21/en/building-blocks/context-and-memory) — Complete guide to short-term and long-term memory -- [**Tool Capabilities**](/versions/1.0.21/en/building-blocks/tool-capabilities) — Complete guide to tools and function calling -- [**Agent**](/versions/1.0.21/en/basic-concepts/agent) — Agent customization and advanced features +- [**Context and Memory**](/agentscope/1.0.21/en/building-blocks/context-and-memory) — Complete guide to short-term and long-term memory +- [**Tool Capabilities**](/agentscope/1.0.21/en/building-blocks/tool-capabilities) — Complete guide to tools and function calling +- [**Agent**](/agentscope/1.0.21/en/basic-concepts/agent) — Agent customization and advanced features diff --git a/versions/1.0.21/en/tutorial/tutorial_sales_agent.mdx b/agentscope/1.0.21/en/tutorial/tutorial_sales_agent.mdx similarity index 98% rename from versions/1.0.21/en/tutorial/tutorial_sales_agent.mdx rename to agentscope/1.0.21/en/tutorial/tutorial_sales_agent.mdx index 6aef9ba..c1f3e07 100644 --- a/versions/1.0.21/en/tutorial/tutorial_sales_agent.mdx +++ b/agentscope/1.0.21/en/tutorial/tutorial_sales_agent.mdx @@ -921,5 +921,5 @@ asyncio.run(main()) Congratulations on completing this tutorial! You have mastered AgentScope's multi-agent orchestration capabilities. Next, you can explore: -- [**Hooking Functions**](/versions/1.0.21/en/building-blocks/hooking-functions) — Detailed usage of agent hooks, including Human-in-the-Loop patterns -- [**Orchestration**](/versions/1.0.21/en/building-blocks/orchestration) — In-depth guide to routing strategies, MsgHub, and Orchestrator-Workers patterns +- [**Hooking Functions**](/agentscope/1.0.21/en/building-blocks/hooking-functions) — Detailed usage of agent hooks, including Human-in-the-Loop patterns +- [**Orchestration**](/agentscope/1.0.21/en/building-blocks/orchestration) — In-depth guide to routing strategies, MsgHub, and Orchestrator-Workers patterns diff --git a/versions/2.0.2/en/building-blocks/agent.mdx b/agentscope/2.0.2/en/building-blocks/agent.mdx similarity index 98% rename from versions/2.0.2/en/building-blocks/agent.mdx rename to agentscope/2.0.2/en/building-blocks/agent.mdx index cf64524..e14ee23 100644 --- a/versions/2.0.2/en/building-blocks/agent.mdx +++ b/agentscope/2.0.2/en/building-blocks/agent.mdx @@ -422,10 +422,10 @@ asyncio.run(main()) ## Further Reading - + Control which tools the agent can call and under what conditions. - + Intercept and modify agent behavior at reply, reasoning, acting, and model call hooks. diff --git a/versions/2.0.3/en/building-blocks/context.mdx b/agentscope/2.0.2/en/building-blocks/context.mdx similarity index 94% rename from versions/2.0.3/en/building-blocks/context.mdx rename to agentscope/2.0.2/en/building-blocks/context.mdx index b6eef16..ef7e957 100644 --- a/versions/2.0.3/en/building-blocks/context.mdx +++ b/agentscope/2.0.2/en/building-blocks/context.mdx @@ -27,7 +27,7 @@ Before each model call, the agent assembles a single API input from three layers How each layer is built: -1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/versions/2.0.3/en/building-blocks/middleware) hook in order. +1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/agentscope/2.0.2/en/building-blocks/middleware) hook in order. 2. **Summary** — the compressed digest of older messages, present only after a compression has occurred. 3. **Context** — the recent uncompressed messages (user inputs, assistant responses, tool calls, tool results). @@ -148,7 +148,7 @@ Offloading is wired through the `Offloader` protocol — a structural contract w | `offload_context(session_id, msgs)` | Persist compressed messages; returns a reference (e.g. a file path) to the persisted content | | `offload_tool_result(session_id, tool_result)` | Persist a truncated tool result; returns a reference to the persisted content | -Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/versions/2.0.3/en/building-blocks/workspace) module ships ready-made implementations: +Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/agentscope/2.0.2/en/building-blocks/workspace) module ships ready-made implementations: ```python from agentscope.agent import Agent @@ -236,16 +236,16 @@ Pass the instance into `Agent(offloader=...)` like any built-in workspace. ## Further Reading - + Built-in offloader implementations and the agent's working environment - + The ReAct loop and how context flows through reasoning steps - + Intercept model calls and system prompt composition with middleware hooks - + Tools that produce results subject to compression diff --git a/versions/2.0.2/en/building-blocks/message-and-event.mdx b/agentscope/2.0.2/en/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.2/en/building-blocks/message-and-event.mdx rename to agentscope/2.0.2/en/building-blocks/message-and-event.mdx index 7483bdf..e51a894 100644 --- a/versions/2.0.2/en/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.2/en/building-blocks/message-and-event.mdx @@ -513,10 +513,10 @@ async for event in agent.reply_stream(UserMsg("user", "Fix the bug")): ## Further Reading - + How the agent produces events and messages in the ReAct loop - + How messages are stored, compressed, and offloaded \ No newline at end of file diff --git a/versions/2.0.2/en/building-blocks/middleware.mdx b/agentscope/2.0.2/en/building-blocks/middleware.mdx similarity index 100% rename from versions/2.0.2/en/building-blocks/middleware.mdx rename to agentscope/2.0.2/en/building-blocks/middleware.mdx diff --git a/versions/2.0.2/en/building-blocks/model.mdx b/agentscope/2.0.2/en/building-blocks/model.mdx similarity index 99% rename from versions/2.0.2/en/building-blocks/model.mdx rename to agentscope/2.0.2/en/building-blocks/model.mdx index ff5e900..db9854e 100644 --- a/versions/2.0.2/en/building-blocks/model.mdx +++ b/agentscope/2.0.2/en/building-blocks/model.mdx @@ -595,7 +595,7 @@ asyncio.run(main()) ### Integrate with Agent -In the agent layer, TTS is integrated via [`TTSMiddleware`](/versions/2.0.2/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: +In the agent layer, TTS is integrated via [`TTSMiddleware`](/agentscope/2.0.2/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: ```python from agentscope.agent import Agent diff --git a/versions/2.0.2/en/building-blocks/permission-system.mdx b/agentscope/2.0.2/en/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.2/en/building-blocks/permission-system.mdx rename to agentscope/2.0.2/en/building-blocks/permission-system.mdx diff --git a/versions/2.0.2/en/building-blocks/tool.mdx b/agentscope/2.0.2/en/building-blocks/tool.mdx similarity index 96% rename from versions/2.0.2/en/building-blocks/tool.mdx rename to agentscope/2.0.2/en/building-blocks/tool.mdx index 010d886..bbadc81 100644 --- a/versions/2.0.2/en/building-blocks/tool.mdx +++ b/agentscope/2.0.2/en/building-blocks/tool.mdx @@ -125,7 +125,7 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the `check_permissions()` — `Write` and `Edit` share the same permission logic: -1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/versions/2.0.2/en/building-blocks/permission-system#safety-check-contract) for the full contract. +1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/agentscope/2.0.2/en/building-blocks/permission-system#safety-check-contract) for the full contract. 2. **ACCEPT_EDITS mode** — auto-allows operations on files within configured working directories 3. **PASSTHROUGH** — falls through to the permission engine for rule matching @@ -185,7 +185,7 @@ class WebSearch(ToolBase): Two extension hooks worth knowing about when writing custom tools with safety logic: - **`check_read_only(tool_input)`** — override when whether an invocation modifies state depends on the input (like `Bash`: `ls` is read-only, `rm` is not). Defaults to returning the static `is_read_only` attribute. The permission engine calls it before deciding EXPLORE / ACCEPT_EDITS auto-allow. -- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/versions/2.0.2/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. +- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/agentscope/2.0.2/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. ### Wrap Function as Tool @@ -226,7 +226,7 @@ Wrapped functions default to `ASK` permission behavior — the user must explici An external execution tool delegates its actual execution outside the agent runtime — typically to a human operator or an external system. When the agent calls one, it emits a `RequireExternalExecutionEvent` and pauses until the result is delivered via `ExternalExecutionResultEvent`. -This pattern underlies the [human-in-the-loop](/versions/2.0.2/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. +This pattern underlies the [human-in-the-loop](/agentscope/2.0.2/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. To create an external execution tool, set `is_external_tool = True`. There is no need to implement `__call__`: @@ -441,16 +441,16 @@ The meta tool input represents the **final state** of all groups, not incrementa ## Further Reading - + How agents orchestrate tool calls in the ReAct loop - + Fine-grained control over which tools can execute and when - + Intercept and transform tool calls with onion-style middleware - + External execution tools and human approval workflows diff --git a/versions/2.0.4/en/building-blocks/workspace.mdx b/agentscope/2.0.2/en/building-blocks/workspace.mdx similarity index 92% rename from versions/2.0.4/en/building-blocks/workspace.mdx rename to agentscope/2.0.2/en/building-blocks/workspace.mdx index 87fd0f7..48b3298 100644 --- a/versions/2.0.4/en/building-blocks/workspace.mdx +++ b/agentscope/2.0.2/en/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "The execution environment that supplies tools, skills, and context A workspace is the agent's execution environment. It supplies the agent with three categories of resources — **tools** (built-in tools and MCPs), **skills**, and **context offloading** for compressed messages and oversized tool results — and owns the lifecycle of the resources living inside it (MCP server processes, dynamically added skills, offloaded files). -AgentScope ships three workspace implementations — local filesystem, Docker container, and E2B cloud sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/versions/2.0.4/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. +AgentScope ships three workspace implementations — local filesystem, Docker container, and E2B cloud sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/agentscope/2.0.2/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. For Docker and E2B, MCP servers run *inside* the isolated environment; the host reaches them through an in-workspace gateway covered in [MCP Gateway](#mcp-gateway). @@ -177,7 +177,7 @@ toolkit = Toolkit( ## Workspace Manager -A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/versions/2.0.4/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. +A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/agentscope/2.0.2/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. A manager is responsible for: @@ -220,10 +220,10 @@ ws = await manager.get_workspace( ) ``` -To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/versions/2.0.4/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. +To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/agentscope/2.0.2/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. -In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/versions/2.0.4/en/deploy/agent-service) for the full integration. +In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/agentscope/2.0.2/en/deploy/agent-service) for the full integration. ## MCP Gateway @@ -255,16 +255,16 @@ This abstraction keeps the agent-side code identical across all three workspace ## Further Reading - + Agent abstraction, the ReAct loop, and offloader integration - + Built-in tools, MCP integration, and toolkit composition - + Multi-tenant service that drives the workspace manager - + Context compression and the offloading triggers diff --git a/versions/2.0.2/en/change-log.mdx b/agentscope/2.0.2/en/change-log.mdx similarity index 100% rename from versions/2.0.2/en/change-log.mdx rename to agentscope/2.0.2/en/change-log.mdx diff --git a/versions/2.0.2/en/deploy/agent-service.mdx b/agentscope/2.0.2/en/deploy/agent-service.mdx similarity index 96% rename from versions/2.0.2/en/deploy/agent-service.mdx rename to agentscope/2.0.2/en/deploy/agent-service.mdx index 1f2a8ab..c9206d2 100644 --- a/versions/2.0.2/en/deploy/agent-service.mdx +++ b/agentscope/2.0.2/en/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "Agent Service" description: "Host your agent as a multi-tenant, multi-session HTTP service" --- -Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/versions/2.0.2/en/building-blocks/agent) can serve production traffic without being rewritten. +Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/agentscope/2.0.2/en/building-blocks/agent) can serve production traffic without being rewritten. What sets it apart: @@ -16,7 +16,7 @@ What sets it apart: | Capability | Description | |------------|-------------| -| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/versions/2.0.2/en/deploy/agent-team) chapter. | +| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/agentscope/2.0.2/en/deploy/agent-team) chapter. | | Workspace management | Pluggable workspace isolation (built-in: per-agent; extensible to per-session or per-user) for the agent's filesystem, MCP clients, and skills. | | Background task offloading | Long-running tool calls move to background; their results are delivered back through the session's event stream when they finish. | | Cron scheduling | Time-based agent execution with stateful or stateless sessions; schedules persist across restarts. | @@ -200,7 +200,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) Async factory `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]` invoked once per agent assembly. Returned tools are merged into the toolkit's `"basic"` group alongside the workspace-derived tools, so tool availability can vary per caller (per-tenant integrations, user-specific credentials). - Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/versions/2.0.2/en/deploy/agent-team#custom-sub-agent-types) for details. + Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/agentscope/2.0.2/en/deploy/agent-team#custom-sub-agent-types) for details. OpenAPI title shown in the docs UI. @@ -241,7 +241,7 @@ Once the server is running, drive it through the resources defined in the resour ``` - Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/versions/2.0.2/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. + Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/agentscope/2.0.2/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. ```http POST /workspace/mcp @@ -352,7 +352,7 @@ The service is open at every infrastructure boundary. The sections below describ ### Agent chat protocol -The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/versions/2.0.2/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. +The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/agentscope/2.0.2/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. AgentScope ships with `AGUIProtocolMiddleware` for the [AG-UI](https://docs.ag-ui.com/) protocol. Install it via `extra_middlewares`: @@ -701,16 +701,16 @@ Routers receive application state through FastAPI's `Depends()`. The standard in ## Further Reading - + Core agent abstraction and the ReAct loop - + Event streaming and message reconstruction - + Built-in and custom tools including external execution - + Context compression and workspace offloading diff --git a/versions/2.0.2/en/deploy/agent-team.mdx b/agentscope/2.0.2/en/deploy/agent-team.mdx similarity index 87% rename from versions/2.0.2/en/deploy/agent-team.mdx rename to agentscope/2.0.2/en/deploy/agent-team.mdx index 7a5b131..648376d 100644 --- a/versions/2.0.2/en/deploy/agent-team.mdx +++ b/agentscope/2.0.2/en/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "Agent Team" description: "Leader agents that spawn and coordinate worker agents through built-in team tools" --- -Agent Team is the multi-agent layer built on top of [Agent Service](/versions/2.0.2/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. +Agent Team is the multi-agent layer built on top of [Agent Service](/agentscope/2.0.2/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. ## Quickstart -The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/versions/2.0.2/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. +The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/agentscope/2.0.2/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. Agent team coordination demo @@ -132,7 +132,7 @@ A leader session is automatically given these tools. Workers see only `TeamSay`. ### Coordination model -Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/versions/2.0.2/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. +Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/agentscope/2.0.2/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. Team communication reuses the same inbox + wakeup primitives the service uses for scheduled fires and background-tool completions: @@ -146,10 +146,10 @@ This means workers run *concurrently* on the same service — they are not neste ## See also - + The hosting layer that powers teams — sessions, message bus, workspace lifecycle. - + The agent abstraction each team member runs. diff --git a/versions/2.0.2/en/deploy/openapi.json b/agentscope/2.0.2/en/deploy/openapi.json similarity index 100% rename from versions/2.0.2/en/deploy/openapi.json rename to agentscope/2.0.2/en/deploy/openapi.json diff --git a/versions/2.0.2/en/index.mdx b/agentscope/2.0.2/en/index.mdx similarity index 76% rename from versions/2.0.2/en/index.mdx rename to agentscope/2.0.2/en/index.mdx index ab6e1c4..cb26a16 100644 --- a/versions/2.0.2/en/index.mdx +++ b/agentscope/2.0.2/en/index.mdx @@ -21,26 +21,26 @@ making it easier to build and run agents in production. - **Workspace System**: Move an agent from your laptop to a Docker host or an E2B sandbox by changing one line, with working directory, MCP clients and skills cleanly isolated per user, agent or session. - **Agent Service**: Host any agent over REST + SSE with multi-tenant, multi-session concurrency, resumable streams, durable sessions, scheduled runs and managed credentials — without writing the service plumbing yourself. -If you are still evaluating whether to migrate, check out the [Changelog](/versions/2.0.2/en/change-log) for a full breakdown of every change — it should give you everything you need to plan your migration to AgentScope 2.0. +If you are still evaluating whether to migrate, check out the [Changelog](/agentscope/2.0.2/en/change-log) for a full breakdown of every change — it should give you everything you need to plan your migration to AgentScope 2.0. - + Observe every step of the agent and stream it straight into your UI. - + Gate or sandbox dangerous tool calls before they touch the host. - + Let users review and edit tool arguments before execution, or delegate sensitive actions to your own backend entirely. - + Tool calls are auto-batched and run concurrently or sequentially based on each tool's properties. - + Swap Local, Docker or E2B without rewriting the agent. - + Ship agents over REST + SSE with multi-tenant, multi-session concurrency, sessions, schedules and credentials. \ No newline at end of file diff --git a/versions/2.0.3/en/others/faq.mdx b/agentscope/2.0.2/en/others/faq.mdx similarity index 87% rename from versions/2.0.3/en/others/faq.mdx rename to agentscope/2.0.2/en/others/faq.mdx index ef9110a..57a644a 100644 --- a/versions/2.0.3/en/others/faq.mdx +++ b/agentscope/2.0.2/en/others/faq.mdx @@ -14,14 +14,14 @@ description: "Frequently asked questions about AgentScope v2.0" Yes. The **workspace** abstraction is AgentScope's execution environment for agents and ships three implementations — `LocalWorkspace` (host filesystem), `DockerWorkspace` (container), and `E2BWorkspace` (E2B cloud sandbox) — sharing the same interface so the same agent code runs against any backend. Workspaces also own MCP server lifecycles, skill management, and context offloading. - See [Workspace](/versions/2.0.3/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. + See [Workspace](/agentscope/2.0.2/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. Yes, on two layers: - **TypeScript SDK** — install with `pnpm install @agentscope-ai/agentscope`. It mirrors the Python `Msg` and `Event` types so frontend code can consume agent streams without re-implementing the protocol. - - **Frontend UI** — a ready-to-use web app for [Agent Service](/versions/2.0.3/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. + - **Frontend UI** — a ready-to-use web app for [Agent Service](/agentscope/2.0.2/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. diff --git a/versions/2.0.2/en/quickstart.mdx b/agentscope/2.0.2/en/quickstart.mdx similarity index 100% rename from versions/2.0.2/en/quickstart.mdx rename to agentscope/2.0.2/en/quickstart.mdx diff --git a/versions/2.0.2/zh/building-blocks/agent.mdx b/agentscope/2.0.2/zh/building-blocks/agent.mdx similarity index 98% rename from versions/2.0.2/zh/building-blocks/agent.mdx rename to agentscope/2.0.2/zh/building-blocks/agent.mdx index 921a1b3..d40a4ef 100644 --- a/versions/2.0.2/zh/building-blocks/agent.mdx +++ b/agentscope/2.0.2/zh/building-blocks/agent.mdx @@ -422,10 +422,10 @@ asyncio.run(main()) ## 延伸阅读 - + 控制智能体可以调用哪些工具以及在什么条件下调用。 - + 在 reply、reasoning、acting 和 model call 钩子处拦截和修改智能体行为。 diff --git a/versions/2.0.2/zh/building-blocks/context.mdx b/agentscope/2.0.2/zh/building-blocks/context.mdx similarity index 94% rename from versions/2.0.2/zh/building-blocks/context.mdx rename to agentscope/2.0.2/zh/building-blocks/context.mdx index 0de28ac..57b251f 100644 --- a/versions/2.0.2/zh/building-blocks/context.mdx +++ b/agentscope/2.0.2/zh/building-blocks/context.mdx @@ -27,7 +27,7 @@ Context 是 agent 的工作记忆 —— LLM 在每一步推理时看到的全 每一层的构成方式： -1. **System prompt** —— 以创建 agent 时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [middleware](/versions/2.0.2/zh/building-blocks/middleware) 钩子。 +1. **System prompt** —— 以创建 agent 时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [middleware](/agentscope/2.0.2/zh/building-blocks/middleware) 钩子。 2. **Summary** —— 较早消息被压缩后的摘要；只有发生过压缩之后才存在。 3. **Context** —— 最近的、尚未压缩的消息（用户输入、assistant 回复、工具调用、工具结果）。 @@ -147,7 +147,7 @@ Offload 通过 `Offloader` 协议接入 —— 该协议是结构化的，仅有 | `offload_context(session_id, msgs)` | 持久化被压缩的消息；返回一个引用（例如文件路径） | | `offload_tool_result(session_id, tool_result)` | 持久化被截断的工具结果；返回一个引用 | -任何实现该协议的对象都可以传入 agent 的 `offloader` 参数。AgentScope 的 [`workspace`](/versions/2.0.2/zh/building-blocks/workspace) 模块提供了开箱即用的实现： +任何实现该协议的对象都可以传入 agent 的 `offloader` 参数。AgentScope 的 [`workspace`](/agentscope/2.0.2/zh/building-blocks/workspace) 模块提供了开箱即用的实现： ```python from agentscope.agent import Agent @@ -235,16 +235,16 @@ class S3Offloader: ## 延伸阅读 - + 内置的 offloader 实现，以及 agent 的工作环境 - + ReAct 循环以及上下文如何在推理步骤间流转 - + 通过 middleware 钩子拦截模型调用与 system prompt 组装 - + 会被压缩处理的工具结果来源 diff --git a/versions/2.0.2/zh/building-blocks/message-and-event.mdx b/agentscope/2.0.2/zh/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.2/zh/building-blocks/message-and-event.mdx rename to agentscope/2.0.2/zh/building-blocks/message-and-event.mdx index 4f3b9da..10bcddd 100644 --- a/versions/2.0.2/zh/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.2/zh/building-blocks/message-and-event.mdx @@ -511,10 +511,10 @@ async for event in agent.reply_stream(UserMsg("user", "帮我修复这个 bug")) ## 延伸阅读 - + 智能体如何在 ReAct 循环中产出事件和消息 - + 消息如何存储、压缩和卸载 diff --git a/versions/2.0.2/zh/building-blocks/middleware.mdx b/agentscope/2.0.2/zh/building-blocks/middleware.mdx similarity index 100% rename from versions/2.0.2/zh/building-blocks/middleware.mdx rename to agentscope/2.0.2/zh/building-blocks/middleware.mdx diff --git a/versions/2.0.2/zh/building-blocks/model.mdx b/agentscope/2.0.2/zh/building-blocks/model.mdx similarity index 99% rename from versions/2.0.2/zh/building-blocks/model.mdx rename to agentscope/2.0.2/zh/building-blocks/model.mdx index ae83e0f..6126ad7 100644 --- a/versions/2.0.2/zh/building-blocks/model.mdx +++ b/agentscope/2.0.2/zh/building-blocks/model.mdx @@ -586,7 +586,7 @@ asyncio.run(main()) ### 与 Agent 集成 -在 agent 层，TTS 通过 [`TTSMiddleware`](/versions/2.0.2/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： +在 agent 层，TTS 通过 [`TTSMiddleware`](/agentscope/2.0.2/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： ```python from agentscope.agent import Agent diff --git a/versions/2.0.2/zh/building-blocks/permission-system.mdx b/agentscope/2.0.2/zh/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.2/zh/building-blocks/permission-system.mdx rename to agentscope/2.0.2/zh/building-blocks/permission-system.mdx diff --git a/versions/2.0.2/zh/building-blocks/tool.mdx b/agentscope/2.0.2/zh/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.2/zh/building-blocks/tool.mdx rename to agentscope/2.0.2/zh/building-blocks/tool.mdx index fa37787..d67fd5e 100644 --- a/versions/2.0.2/zh/building-blocks/tool.mdx +++ b/agentscope/2.0.2/zh/building-blocks/tool.mdx @@ -125,7 +125,7 @@ bash = Bash( `check_permissions()` —— `Write` 与 `Edit` 共用同一权限逻辑： -1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/versions/2.0.2/zh/building-blocks/permission-system#safety-check-契约)。 +1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/agentscope/2.0.2/zh/building-blocks/permission-system#safety-check-契约)。 2. **ACCEPT_EDITS 模式** —— 自动放行配置工作目录内的文件操作 3. **PASSTHROUGH** —— 交给权限引擎做规则匹配 @@ -185,7 +185,7 @@ class WebSearch(ToolBase): 自定义 tool 写带安全语义的逻辑时，有两个扩展钩子值得了解： - **`check_read_only(tool_input)`** —— 当某次调用是否修改状态取决于输入时覆写（例如 `Bash`：`ls` 是只读，`rm` 不是）。默认返回 `is_read_only` 静态属性。权限引擎在判定 EXPLORE / ACCEPT_EDITS 是否自动放行时调用。 -- **`PermissionDecision(..., bypass_immune=True)`** —— 在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/versions/2.0.2/zh/building-blocks/permission-system#safety-check-契约)。 +- **`PermissionDecision(..., bypass_immune=True)`** —— 在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/agentscope/2.0.2/zh/building-blocks/permission-system#safety-check-契约)。 ### 把函数包装为 Tool @@ -226,7 +226,7 @@ toolkit = Toolkit(tools=[FunctionTool(get_weather)]) 外部执行 tool 把实际执行委派给 agent 运行时之外 —— 通常是人工操作员或外部系统。Agent 调用此类 tool 时会发出 `RequireExternalExecutionEvent` 并暂停，直到结果通过 `ExternalExecutionResultEvent` 回传。 -这种模式是 [human-in-the-loop](/versions/2.0.2/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 +这种模式是 [human-in-the-loop](/agentscope/2.0.2/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 创建外部执行 tool 只需把 `is_external_tool` 设为 `True`，不必实现 `__call__`： @@ -441,16 +441,16 @@ Meta tool 的输入表示所有 group 的**最终状态**而非增量。任何 ## 延伸阅读 - + Agent 如何在 ReAct 循环中编排 tool 调用 - + 精细控制哪个 tool 可以执行、何时执行 - + 用洋葱式 middleware 拦截并改写 tool 调用 - + 外部执行 tool 与人工审批工作流 diff --git a/versions/2.0.4/zh/building-blocks/workspace.mdx b/agentscope/2.0.2/zh/building-blocks/workspace.mdx similarity index 92% rename from versions/2.0.4/zh/building-blocks/workspace.mdx rename to agentscope/2.0.2/zh/building-blocks/workspace.mdx index b27b24c..05890ba 100644 --- a/versions/2.0.4/zh/building-blocks/workspace.mdx +++ b/agentscope/2.0.2/zh/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "为 agent 提供工具、skill 与上下文 offload 的执行环 Workspace 是 agent 的执行环境，向 agent 提供三类资源 —— **工具**（内置 tool 与 MCP）、**skill**，以及面向压缩消息与超大工具结果的**上下文 offload** —— 同时管理其中资源（MCP server 进程、动态加入的 skill、offload 文件）的生命周期。 -AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/versions/2.0.4/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 +AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/agentscope/2.0.2/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 对 Docker 与 E2B 而言，MCP server 跑在隔离环境*内部*；宿主侧通过 workspace 内的 gateway 访问它们，详见后文 [MCP Gateway](#mcp-gateway)。 @@ -177,7 +177,7 @@ toolkit = Toolkit( ## Workspace Manager -Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/versions/2.0.4/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 +Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/agentscope/2.0.2/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 Manager 的职责： @@ -220,10 +220,10 @@ ws = await manager.get_workspace( ) ``` -要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/versions/2.0.4/zh/deploy/agent-service#workspace-实现与隔离)。 +要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/agentscope/2.0.2/zh/deploy/agent-service#workspace-实现与隔离)。 -Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/versions/2.0.4/zh/deploy/agent-service)。 +Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/agentscope/2.0.2/zh/deploy/agent-service)。 ## MCP Gateway @@ -255,16 +255,16 @@ Gateway 暴露一组小型 REST 接口 —— `GET /health`、`GET/POST/DELETE / ## 延伸阅读 - + Agent 抽象、ReAct 循环与 offloader 集成 - + 内置 tool、MCP 集成与 toolkit 组装 - + 驱动 workspace manager 的多租户服务 - + 上下文压缩与 offload 触发条件 diff --git a/versions/2.0.2/zh/change-log.mdx b/agentscope/2.0.2/zh/change-log.mdx similarity index 100% rename from versions/2.0.2/zh/change-log.mdx rename to agentscope/2.0.2/zh/change-log.mdx diff --git a/versions/2.0.2/zh/deploy/agent-service.mdx b/agentscope/2.0.2/zh/deploy/agent-service.mdx similarity index 96% rename from versions/2.0.2/zh/deploy/agent-service.mdx rename to agentscope/2.0.2/zh/deploy/agent-service.mdx index 351d437..267ab3d 100644 --- a/versions/2.0.2/zh/deploy/agent-service.mdx +++ b/agentscope/2.0.2/zh/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "智能体服务" description: "把智能体部署为多租户、多会话的 HTTP 服务" --- -智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/versions/2.0.2/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 +智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/agentscope/2.0.2/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 它的特点： @@ -16,7 +16,7 @@ description: "把智能体部署为多租户、多会话的 HTTP 服务" | 能力 | 说明 | |---------------------------------------------------|-----------------------------------------------------------------------------------------| -| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/versions/2.0.2/zh/deploy/agent-team) 章节。 | +| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/agentscope/2.0.2/zh/deploy/agent-team) 章节。 | | 工作区管理 | 可插拔的工作区隔离策略（内置：智能体隔离；可扩展为按会话或用户隔离），管理智能体的文件系统、MCP client 与 skill。 | | 后台任务卸载（Background Task Offloading） | 长耗时工具调用切到后台执行，完成时通过会话事件流回送结果。 | | Cron 调度 | 按时间触发智能体执行，支持有状态或无状态会话；调度持久化保存，跨重启生效。 | @@ -199,7 +199,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) 异步工厂 `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]`，在每次组装智能体时被调用一次。返回的工具会与工作区派生的工具一起合并到 toolkit 的 `"basic"` 分组里，便于按调用者动态决定可用工具（例如按租户接入、按用户使用各自凭证的工具）。 - 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/versions/2.0.2/zh/deploy/agent-team#自定义子智能体类型)。 + 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/agentscope/2.0.2/zh/deploy/agent-team#自定义子智能体类型)。 OpenAPI 文档界面中显示的标题。 @@ -240,7 +240,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) ``` - 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/versions/2.0.2/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 + 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/agentscope/2.0.2/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 ```http POST /workspace/mcp @@ -351,7 +351,7 @@ flowchart TB ### 智能体聊天协议 -按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/versions/2.0.2/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 +按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/agentscope/2.0.2/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 AgentScope 内置 `AGUIProtocolMiddleware` 适配 [AG-UI](https://docs.ag-ui.com/) 协议。通过 `extra_middlewares` 装载： @@ -700,16 +700,16 @@ Router 通过 FastAPI 的 `Depends()` 拿到应用状态。标准注入项（位 ## 延伸阅读 - + 核心智能体抽象与 ReAct 循环 - + 事件流与消息重建 - + 内置与自定义工具，包括外部执行 - + 上下文压缩与工作区 offloading diff --git a/versions/2.0.2/zh/deploy/agent-team.mdx b/agentscope/2.0.2/zh/deploy/agent-team.mdx similarity index 85% rename from versions/2.0.2/zh/deploy/agent-team.mdx rename to agentscope/2.0.2/zh/deploy/agent-team.mdx index 02ce825..cc680f4 100644 --- a/versions/2.0.2/zh/deploy/agent-team.mdx +++ b/agentscope/2.0.2/zh/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "智能体团队" description: "Leader 智能体通过内置 team 工具派生并协调 worker 智能体" --- -智能体团队（Agent Team）是构建在[智能体服务](/versions/2.0.2/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 +智能体团队（Agent Team）是构建在[智能体服务](/agentscope/2.0.2/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 ## 快速上手 -随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/versions/2.0.2/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 +随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/agentscope/2.0.2/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 智能体团队协作演示 @@ -129,7 +129,7 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ### 协调模型 -智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/versions/2.0.2/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 +智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/agentscope/2.0.2/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 团队通信复用了服务用于调度触发与后台工具完成的同一组 inbox + wakeup 原语： @@ -143,10 +143,10 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ## 延伸阅读 - + 支撑团队的托管层 —— 会话、消息总线、工作区生命周期。 - + 每个团队成员所运行的智能体抽象。 diff --git a/versions/2.0.2/zh/index.mdx b/agentscope/2.0.2/zh/index.mdx similarity index 76% rename from versions/2.0.2/zh/index.mdx rename to agentscope/2.0.2/zh/index.mdx index 7195be8..24de0ff 100644 --- a/versions/2.0.2/zh/index.mdx +++ b/agentscope/2.0.2/zh/index.mdx @@ -18,25 +18,25 @@ AgentScope 2.0 是对框架的一次重大升级，核心目标是提升开发 - **工作区系统**：只需修改一行代码，就能将智能体从本地迁移到 Docker 或 E2B 沙箱，工作目录、MCP 客户端和技能集均按用户、智能体或会话独立隔离。 - **智能体服务**：通过 REST + SSE 托管任意智能体，支持多租户、多 Session 并发，内置可续传流、持久化会话、定时任务和凭据管理，无需自己搭建服务脚手架。 -对于正在评估是否进行迁移的开发者，可以查阅 [Changelog](/versions/2.0.2/zh/change-log) 了解每项变更的完整说明，帮助更好地规划迁移到 AgentScope 2.0 的计划。 +对于正在评估是否进行迁移的开发者，可以查阅 [Changelog](/agentscope/2.0.2/zh/change-log) 了解每项变更的完整说明，帮助更好地规划迁移到 AgentScope 2.0 的计划。 - + 观测智能体的每一步操作，直接流式推送到界面。 - + 在危险工具调用触达宿主机之前进行拦截或沙箱隔离。 - + 支持在执行前审核或修改工具参数，也可将敏感操作完全转交自定义后端处理。 - + 工具调用根据各工具的属性自动分批，并发或顺序执行——在保证正确性的前提下获得更高的吞吐效率。 - + 无需重写智能体即可在本地、Docker 或 E2B 之间自由切换。 - + 通过 REST + SSE 部署智能体，支持多租户、多 Session 并发，内置会话管理、定时任务和凭据管理。 diff --git a/versions/2.0.2/zh/others/faq.mdx b/agentscope/2.0.2/zh/others/faq.mdx similarity index 84% rename from versions/2.0.2/zh/others/faq.mdx rename to agentscope/2.0.2/zh/others/faq.mdx index 59ad264..1bdb50c 100644 --- a/versions/2.0.2/zh/others/faq.mdx +++ b/agentscope/2.0.2/zh/others/faq.mdx @@ -14,14 +14,14 @@ description: "AgentScope v2.0 常见问题" 支持。**Workspace** 是 AgentScope 为 agent 提供的执行环境抽象，内置三种实现 —— `LocalWorkspace`（宿主文件系统）、`DockerWorkspace`（容器）、`E2BWorkspace`（E2B 云沙箱），共享同一份接口，因此同一份 agent 代码可以无差别地在任意后端上运行。Workspace 同时负责管理 MCP server 生命周期、skill 与上下文 offload。 - 完整介绍见 [Workspace](/versions/2.0.2/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 + 完整介绍见 [Workspace](/agentscope/2.0.2/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 有，分两个层次： - **TypeScript SDK** —— 通过 `pnpm install @agentscope-ai/agentscope` 安装，对齐 Python 端的 `Msg` 与 `Event` 类型，前端无需重写协议即可消费 agent 的流式输出。 - - **前端 UI** —— 面向 [Agent Service](/versions/2.0.2/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 + - **前端 UI** —— 面向 [Agent Service](/agentscope/2.0.2/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 diff --git a/versions/2.0.2/zh/quickstart.mdx b/agentscope/2.0.2/zh/quickstart.mdx similarity index 100% rename from versions/2.0.2/zh/quickstart.mdx rename to agentscope/2.0.2/zh/quickstart.mdx diff --git a/versions/2.0.3/en/building-blocks/agent.mdx b/agentscope/2.0.3/en/building-blocks/agent.mdx similarity index 98% rename from versions/2.0.3/en/building-blocks/agent.mdx rename to agentscope/2.0.3/en/building-blocks/agent.mdx index 68045be..27a01e4 100644 --- a/versions/2.0.3/en/building-blocks/agent.mdx +++ b/agentscope/2.0.3/en/building-blocks/agent.mdx @@ -422,10 +422,10 @@ asyncio.run(main()) ## Further Reading - + Control which tools the agent can call and under what conditions. - + Intercept and modify agent behavior at reply, reasoning, acting, and model call hooks. diff --git a/versions/2.0.4/en/building-blocks/context.mdx b/agentscope/2.0.3/en/building-blocks/context.mdx similarity index 94% rename from versions/2.0.4/en/building-blocks/context.mdx rename to agentscope/2.0.3/en/building-blocks/context.mdx index 34d7509..e58cac5 100644 --- a/versions/2.0.4/en/building-blocks/context.mdx +++ b/agentscope/2.0.3/en/building-blocks/context.mdx @@ -27,7 +27,7 @@ Before each model call, the agent assembles a single API input from three layers How each layer is built: -1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/versions/2.0.4/en/building-blocks/middleware) hook in order. +1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/agentscope/2.0.3/en/building-blocks/middleware) hook in order. 2. **Summary** — the compressed digest of older messages, present only after a compression has occurred. 3. **Context** — the recent uncompressed messages (user inputs, assistant responses, tool calls, tool results). @@ -148,7 +148,7 @@ Offloading is wired through the `Offloader` protocol — a structural contract w | `offload_context(session_id, msgs)` | Persist compressed messages; returns a reference (e.g. a file path) to the persisted content | | `offload_tool_result(session_id, tool_result)` | Persist a truncated tool result; returns a reference to the persisted content | -Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/versions/2.0.4/en/building-blocks/workspace) module ships ready-made implementations: +Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/agentscope/2.0.3/en/building-blocks/workspace) module ships ready-made implementations: ```python from agentscope.agent import Agent @@ -236,16 +236,16 @@ Pass the instance into `Agent(offloader=...)` like any built-in workspace. ## Further Reading - + Built-in offloader implementations and the agent's working environment - + The ReAct loop and how context flows through reasoning steps - + Intercept model calls and system prompt composition with middleware hooks - + Tools that produce results subject to compression diff --git a/versions/2.0.3/en/building-blocks/long-term-memory.mdx b/agentscope/2.0.3/en/building-blocks/long-term-memory.mdx similarity index 97% rename from versions/2.0.3/en/building-blocks/long-term-memory.mdx rename to agentscope/2.0.3/en/building-blocks/long-term-memory.mdx index ec707ef..e176159 100644 --- a/versions/2.0.3/en/building-blocks/long-term-memory.mdx +++ b/agentscope/2.0.3/en/building-blocks/long-term-memory.mdx @@ -7,7 +7,7 @@ description: "Persist knowledge across sessions with middleware-based long-term **Long-term memory** lets an agent store and retrieve durable information across sessions — user preferences, past decisions, and knowledge that should persist beyond a single conversation. -In AgentScope, memory extraction and storage services (such as mem0 and ReMe) serve as long-term memory backends, integrated into agents as [middleware](/versions/2.0.3/en/building-blocks/middleware). Each memory middleware is a `MiddlewareBase` subclass that can hook into any position of the agent lifecycle as needed. For example: +In AgentScope, memory extraction and storage services (such as mem0 and ReMe) serve as long-term memory backends, integrated into agents as [middleware](/agentscope/2.0.3/en/building-blocks/middleware). Each memory middleware is a `MiddlewareBase` subclass that can hook into any position of the agent lifecycle as needed. For example: - `on_reply` — search the store before a reply and write the new exchange back afterward. - `on_system_prompt` — advertise memory tools to the model. diff --git a/versions/2.0.3/en/building-blocks/message-and-event.mdx b/agentscope/2.0.3/en/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.3/en/building-blocks/message-and-event.mdx rename to agentscope/2.0.3/en/building-blocks/message-and-event.mdx index 0a4e96d..d086b1b 100644 --- a/versions/2.0.3/en/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.3/en/building-blocks/message-and-event.mdx @@ -647,10 +647,10 @@ async for event in agent.reply_stream(UserMsg("user", "Fix the bug")): ## Further Reading - + How the agent produces events and messages in the ReAct loop - + How messages are stored, compressed, and offloaded \ No newline at end of file diff --git a/versions/2.0.3/en/building-blocks/middleware.mdx b/agentscope/2.0.3/en/building-blocks/middleware.mdx similarity index 98% rename from versions/2.0.3/en/building-blocks/middleware.mdx rename to agentscope/2.0.3/en/building-blocks/middleware.mdx index 3bcb3cc..3e48852 100644 --- a/versions/2.0.3/en/building-blocks/middleware.mdx +++ b/agentscope/2.0.3/en/building-blocks/middleware.mdx @@ -20,7 +20,7 @@ AgentScope exposes 6 hook positions plus a tool-provider hook, covering the full | `list_tools` | Tool source | Optional. Returns a `list[ToolBase]` that the middleware contributes. **Not invoked automatically** — the caller assembling the agent's toolkit decides whether to call it and how to merge the result. | -These hooks operate at the **agent** level. For per-tool onion hooks that fire on every invocation of a specific tool — regardless of whether it's called inside or outside an agent — see [Tool Middleware](/versions/2.0.3/en/building-blocks/tool#tool-middleware). +These hooks operate at the **agent** level. For per-tool onion hooks that fire on every invocation of a specific tool — regardless of whether it's called inside or outside an agent — see [Tool Middleware](/agentscope/2.0.3/en/building-blocks/tool#tool-middleware). The three types differ as follows: @@ -285,7 +285,7 @@ Each `DataBlockDeltaEvent.data` carries an incremental base64-encoded audio chun ### Long-Term Memory -AgentScope implements long-term memory as middleware, so an agent can persist and recall durable facts across sessions. A memory backend hooks `on_reply` (pre-reply search + post-reply write-back), `on_system_prompt` (advertise memory tools), and contributes agent-callable memory tools (such as `search_memory` / `add_memory`) via `list_tools`. The currently available backend is `Mem0Middleware`, powered by [mem0](https://github.com/mem0ai/mem0). See [Long-Term Memory](/versions/2.0.3/en/building-blocks/long-term-memory) for installation, control modes, and construction paths. +AgentScope implements long-term memory as middleware, so an agent can persist and recall durable facts across sessions. A memory backend hooks `on_reply` (pre-reply search + post-reply write-back), `on_system_prompt` (advertise memory tools), and contributes agent-callable memory tools (such as `search_memory` / `add_memory`) via `list_tools`. The currently available backend is `Mem0Middleware`, powered by [mem0](https://github.com/mem0ai/mem0). See [Long-Term Memory](/agentscope/2.0.3/en/building-blocks/long-term-memory) for installation, control modes, and construction paths. ## Custom Middleware diff --git a/versions/2.0.3/en/building-blocks/model.mdx b/agentscope/2.0.3/en/building-blocks/model.mdx similarity index 99% rename from versions/2.0.3/en/building-blocks/model.mdx rename to agentscope/2.0.3/en/building-blocks/model.mdx index 0682a52..cc6a364 100644 --- a/versions/2.0.3/en/building-blocks/model.mdx +++ b/agentscope/2.0.3/en/building-blocks/model.mdx @@ -610,7 +610,7 @@ asyncio.run(main()) ### Integrate with Agent -In the agent layer, TTS is integrated via [`TTSMiddleware`](/versions/2.0.3/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: +In the agent layer, TTS is integrated via [`TTSMiddleware`](/agentscope/2.0.3/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: ```python from agentscope.agent import Agent diff --git a/versions/2.0.3/en/building-blocks/permission-system.mdx b/agentscope/2.0.3/en/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.3/en/building-blocks/permission-system.mdx rename to agentscope/2.0.3/en/building-blocks/permission-system.mdx diff --git a/versions/2.0.3/en/building-blocks/plan.mdx b/agentscope/2.0.3/en/building-blocks/plan.mdx similarity index 97% rename from versions/2.0.3/en/building-blocks/plan.mdx rename to agentscope/2.0.3/en/building-blocks/plan.mdx index 93d2b02..8d2e30a 100644 --- a/versions/2.0.3/en/building-blocks/plan.mdx +++ b/agentscope/2.0.3/en/building-blocks/plan.mdx @@ -202,5 +202,5 @@ The next agent turn will see an empty plan and start over. ## Further Reading -- [Tool](/versions/2.0.3/en/building-blocks/tool) — the toolkit, the `ToolBase` interface, and how state-injected tools receive `AgentState`. -- [Agent](/versions/2.0.3/en/building-blocks/agent) — the agent lifecycle, including how `AgentState` is created, restored, and persisted. +- [Tool](/agentscope/2.0.3/en/building-blocks/tool) — the toolkit, the `ToolBase` interface, and how state-injected tools receive `AgentState`. +- [Agent](/agentscope/2.0.3/en/building-blocks/agent) — the agent lifecycle, including how `AgentState` is created, restored, and persisted. diff --git a/versions/2.0.3/en/building-blocks/rag.mdx b/agentscope/2.0.3/en/building-blocks/rag.mdx similarity index 97% rename from versions/2.0.3/en/building-blocks/rag.mdx rename to agentscope/2.0.3/en/building-blocks/rag.mdx index 258f911..6ea46d9 100644 --- a/versions/2.0.3/en/building-blocks/rag.mdx +++ b/agentscope/2.0.3/en/building-blocks/rag.mdx @@ -16,7 +16,7 @@ In AgentScope, RAG is composed of the following **independently replaceable** mo This chapter focuses on **using RAG in non-service scenarios** — indexing files, retrieving knowledge, and integrating with an agent. -For embedding models and how to configure them, see the [Embedding Model chapter](/versions/2.0.3/en/building-blocks/model); for the service version of RAG (with an HTTP service, file hosting, and distributed indexing), see [RAG Service](/versions/2.0.3/en/deploy/rag). +For embedding models and how to configure them, see the [Embedding Model chapter](/agentscope/2.0.3/en/building-blocks/model); for the service version of RAG (with an HTTP service, file hosting, and distributed indexing), see [RAG Service](/agentscope/2.0.3/en/deploy/rag). ## Existing Implementations @@ -46,7 +46,7 @@ The PDF and PPT parsers depend on additional third-party libraries; install them ### Embedding Model -See the [Embedding Model chapter](/versions/2.0.3/en/building-blocks/model). +See the [Embedding Model chapter](/agentscope/2.0.3/en/building-blocks/model). ### Vector Database @@ -521,13 +521,13 @@ Implementation notes: ## Further Reading - + A multi-tenant, distributed RAG service with HTTP API, file hosting, and managed vector databases. - + See how `RAGMiddleware` plugs into the reply / reasoning hooks. - + Available embedding models and their parameters. diff --git a/versions/2.0.3/en/building-blocks/tool.mdx b/agentscope/2.0.3/en/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.3/en/building-blocks/tool.mdx rename to agentscope/2.0.3/en/building-blocks/tool.mdx index fd20888..4405cc5 100644 --- a/versions/2.0.3/en/building-blocks/tool.mdx +++ b/agentscope/2.0.3/en/building-blocks/tool.mdx @@ -126,7 +126,7 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the `check_permissions()` — `Write` and `Edit` share the same permission logic: -1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/versions/2.0.3/en/building-blocks/permission-system#safety-check-contract) for the full contract. +1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/agentscope/2.0.3/en/building-blocks/permission-system#safety-check-contract) for the full contract. 2. **ACCEPT_EDITS mode** — auto-allows operations on files within configured working directories 3. **PASSTHROUGH** — falls through to the permission engine for rule matching @@ -146,7 +146,7 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the The plan tools give the agent a structured task list it can append to, query, and update through normal tool calls. They share a single store on `agent.state.tasks_context`, are state-injected, and always pass permission checks — the agent treats them as free-cost coordination primitives for breaking complex work into trackable steps. -See [Plan](/versions/2.0.3/en/building-blocks/plan) for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically. +See [Plan](/agentscope/2.0.3/en/building-blocks/plan) for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically. ### Create Custom Tool @@ -192,7 +192,7 @@ class WebSearch(ToolBase): Two extension hooks worth knowing about when writing custom tools with safety logic: - **`check_read_only(tool_input)`** — override when whether an invocation modifies state depends on the input (like `Bash`: `ls` is read-only, `rm` is not). Defaults to returning the static `is_read_only` attribute. The permission engine calls it before deciding EXPLORE / ACCEPT_EDITS auto-allow. -- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/versions/2.0.3/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. +- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/agentscope/2.0.3/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. ### Wrap Function as Tool @@ -233,7 +233,7 @@ Wrapped functions default to `ASK` permission behavior — the user must explici An external execution tool delegates its actual execution outside the agent runtime — typically to a human operator or an external system. When the agent calls one, it emits a `RequireExternalExecutionEvent` and pauses until the result is delivered via `ExternalExecutionResultEvent`. -This pattern underlies the [human-in-the-loop](/versions/2.0.3/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. +This pattern underlies the [human-in-the-loop](/agentscope/2.0.3/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. To create an external execution tool, set `is_external_tool = True`. There is no need to implement `call`: @@ -353,7 +353,7 @@ bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)]) ``` -**Tool middleware vs. agent middleware** — use `ToolMiddlewareBase` for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use `MiddlewareBase.on_acting` when you need access to the broader agent context — permission decisions, the tool-call event, or the surrounding ReAct round. See [Middleware](/versions/2.0.3/en/building-blocks/middleware) for the full agent-level hook reference. +**Tool middleware vs. agent middleware** — use `ToolMiddlewareBase` for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use `MiddlewareBase.on_acting` when you need access to the broader agent context — permission decisions, the tool-call event, or the surrounding ReAct round. See [Middleware](/agentscope/2.0.3/en/building-blocks/middleware) for the full agent-level hook reference. ## MCP @@ -537,16 +537,16 @@ The meta tool input represents the **final state** of all groups, not incrementa ## Further Reading - + How agents orchestrate tool calls in the ReAct loop - + Fine-grained control over which tools can execute and when - + Intercept agent lifecycle hooks — reply, reasoning, model calls, and more - + External execution tools and human approval workflows diff --git a/versions/2.0.3/en/building-blocks/workspace.mdx b/agentscope/2.0.3/en/building-blocks/workspace.mdx similarity index 92% rename from versions/2.0.3/en/building-blocks/workspace.mdx rename to agentscope/2.0.3/en/building-blocks/workspace.mdx index 28f4f8b..9568723 100644 --- a/versions/2.0.3/en/building-blocks/workspace.mdx +++ b/agentscope/2.0.3/en/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "The execution environment that supplies tools, skills, and context A workspace is the agent's execution environment. It supplies the agent with three categories of resources — **tools** (built-in tools and MCPs), **skills**, and **context offloading** for compressed messages and oversized tool results — and owns the lifecycle of the resources living inside it (MCP server processes, dynamically added skills, offloaded files). -AgentScope ships three workspace implementations — local filesystem, Docker container, and E2B cloud sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/versions/2.0.3/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. +AgentScope ships three workspace implementations — local filesystem, Docker container, and E2B cloud sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/agentscope/2.0.3/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. For Docker and E2B, MCP servers run *inside* the isolated environment; the host reaches them through an in-workspace gateway covered in [MCP Gateway](#mcp-gateway). @@ -177,7 +177,7 @@ toolkit = Toolkit( ## Workspace Manager -A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/versions/2.0.3/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. +A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/agentscope/2.0.3/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. A manager is responsible for: @@ -220,10 +220,10 @@ ws = await manager.get_workspace( ) ``` -To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/versions/2.0.3/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. +To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/agentscope/2.0.3/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. -In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/versions/2.0.3/en/deploy/agent-service) for the full integration. +In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/agentscope/2.0.3/en/deploy/agent-service) for the full integration. ## MCP Gateway @@ -255,16 +255,16 @@ This abstraction keeps the agent-side code identical across all three workspace ## Further Reading - + Agent abstraction, the ReAct loop, and offloader integration - + Built-in tools, MCP integration, and toolkit composition - + Multi-tenant service that drives the workspace manager - + Context compression and the offloading triggers diff --git a/versions/2.0.3/en/deploy/agent-service.mdx b/agentscope/2.0.3/en/deploy/agent-service.mdx similarity index 96% rename from versions/2.0.3/en/deploy/agent-service.mdx rename to agentscope/2.0.3/en/deploy/agent-service.mdx index 776bb6a..fdf967e 100644 --- a/versions/2.0.3/en/deploy/agent-service.mdx +++ b/agentscope/2.0.3/en/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "Architecture" description: "Host your agent as a multi-tenant, multi-session HTTP service" --- -Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/versions/2.0.3/en/building-blocks/agent) can serve production traffic without being rewritten. +Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/agentscope/2.0.3/en/building-blocks/agent) can serve production traffic without being rewritten. What sets it apart: @@ -16,7 +16,7 @@ What sets it apart: | Capability | Description | |------------|-------------| -| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/versions/2.0.3/en/deploy/agent-team) chapter. | +| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/agentscope/2.0.3/en/deploy/agent-team) chapter. | | Workspace management | Pluggable workspace isolation (built-in: per-agent; extensible to per-session or per-user) for the agent's filesystem, MCP clients, and skills. | | Background task offloading | Long-running tool calls move to background; their results are delivered back through the session's event stream when they finish. | | Cron scheduling | Time-based agent execution with stateful or stateless sessions; schedules persist across restarts. | @@ -200,7 +200,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) Async factory `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]` invoked once per agent assembly. Returned tools are merged into the toolkit's `"basic"` group alongside the workspace-derived tools, so tool availability can vary per caller (per-tenant integrations, user-specific credentials). - Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/versions/2.0.3/en/deploy/agent-team#custom-sub-agent-types) for details. + Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/agentscope/2.0.3/en/deploy/agent-team#custom-sub-agent-types) for details. OpenAPI title shown in the docs UI. @@ -241,7 +241,7 @@ Once the server is running, drive it through the resources defined in the resour ``` - Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/versions/2.0.3/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. + Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/agentscope/2.0.3/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. ```http POST /workspace/mcp @@ -352,7 +352,7 @@ The service is open at every infrastructure boundary. The sections below describ ### Agent chat protocol -The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/versions/2.0.3/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. +The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/agentscope/2.0.3/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. AgentScope ships with `AGUIProtocolMiddleware` for the [AG-UI](https://docs.ag-ui.com/) protocol. Install it via `extra_middlewares`: @@ -701,16 +701,16 @@ Routers receive application state through FastAPI's `Depends()`. The standard in ## Further Reading - + Core agent abstraction and the ReAct loop - + Event streaming and message reconstruction - + Built-in and custom tools including external execution - + Context compression and workspace offloading diff --git a/versions/2.0.3/en/deploy/agent-team.mdx b/agentscope/2.0.3/en/deploy/agent-team.mdx similarity index 87% rename from versions/2.0.3/en/deploy/agent-team.mdx rename to agentscope/2.0.3/en/deploy/agent-team.mdx index cdffdf9..b30e54c 100644 --- a/versions/2.0.3/en/deploy/agent-team.mdx +++ b/agentscope/2.0.3/en/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "Agent Team" description: "Leader agents that spawn and coordinate worker agents through built-in team tools" --- -Agent Team is the multi-agent layer built on top of [Agent Service](/versions/2.0.3/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. +Agent Team is the multi-agent layer built on top of [Agent Service](/agentscope/2.0.3/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. ## Quickstart -The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/versions/2.0.3/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. +The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/agentscope/2.0.3/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. Agent team coordination demo @@ -132,7 +132,7 @@ A leader session is automatically given these tools. Workers see only `TeamSay`. ### Coordination model -Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/versions/2.0.3/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. +Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/agentscope/2.0.3/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. Team communication reuses the same inbox + wakeup primitives the service uses for scheduled fires and background-tool completions: @@ -146,10 +146,10 @@ This means workers run *concurrently* on the same service — they are not neste ## See also - + The hosting layer that powers teams — sessions, message bus, workspace lifecycle. - + The agent abstraction each team member runs. diff --git a/versions/2.0.3/en/deploy/openapi.json b/agentscope/2.0.3/en/deploy/openapi.json similarity index 100% rename from versions/2.0.3/en/deploy/openapi.json rename to agentscope/2.0.3/en/deploy/openapi.json diff --git a/versions/2.0.4/en/deploy/rag.mdx b/agentscope/2.0.3/en/deploy/rag.mdx similarity index 96% rename from versions/2.0.4/en/deploy/rag.mdx rename to agentscope/2.0.3/en/deploy/rag.mdx index 8271ba8..4ee1076 100644 --- a/versions/2.0.4/en/deploy/rag.mdx +++ b/agentscope/2.0.3/en/deploy/rag.mdx @@ -3,7 +3,7 @@ title: "RAG Service" description: "A one-click multi-tenant, distributed RAG service" --- -The [RAG](/versions/2.0.4/en/building-blocks/rag) chapter covers the extension points and library-mode usage of AgentScope's RAG module. This chapter introduces the **multi-tenant, distribution-ready** RAG service layer included in the Agent Service. Building on top of those building blocks, the service layer provides the following capabilities around "multi-tenancy", "distribution", and "easy onboarding": +The [RAG](/agentscope/2.0.3/en/building-blocks/rag) chapter covers the extension points and library-mode usage of AgentScope's RAG module. This chapter introduces the **multi-tenant, distribution-ready** RAG service layer included in the Agent Service. Building on top of those building blocks, the service layer provides the following capabilities around "multi-tenancy", "distribution", and "easy onboarding": | Capability | Description | |------|------| @@ -424,16 +424,16 @@ Upload and search both go through the **same** knowledge base handle — the ser ## Further Reading - + Learn the atomic interfaces of parser / chunker / vector store / middleware and their library-mode usage. - + `create_app`'s global parameters, lifespan, dependency injection, and ASGI middleware layer. - + Which hooks `RAGMiddleware` uses to inject retrieval results. - + Embedding-model cards and dimension constraints decide which models a knowledge base can pick. diff --git a/versions/2.0.4/en/index.mdx b/agentscope/2.0.3/en/index.mdx similarity index 76% rename from versions/2.0.4/en/index.mdx rename to agentscope/2.0.3/en/index.mdx index 03d5c5c..f11a62a 100644 --- a/versions/2.0.4/en/index.mdx +++ b/agentscope/2.0.3/en/index.mdx @@ -20,19 +20,19 @@ AgentScope 2.0 is a production-ready agent framework built for security, efficie From reasoning agent to enterprise deployment, AgentScope covers the full agent development lifecycle. - + Autonomous agent with ReAct reasoning and tool execution. Built-in human-in-the-loop oversight and efficient tool orchestration. - + Agent self-managed tool system with Python functions, MCP and skills integration. - + Compression, offload and agentic retrieval for context management and long-term memory. Third-party integration with Mem0, ReMe and other vector databases. - + Tool execution in isolated environments (local filesystem, Docker, E2B, K8s, etc.) with multi-granularity isolation at user, agent, and session levels. - + One-click start of a production-ready backend with multi-tenant, multi-session management and distributed deployment, plus a frontend UI and development SDK. \ No newline at end of file diff --git a/versions/2.0.3/en/others/change-log.mdx b/agentscope/2.0.3/en/others/change-log.mdx similarity index 100% rename from versions/2.0.3/en/others/change-log.mdx rename to agentscope/2.0.3/en/others/change-log.mdx diff --git a/versions/2.0.4/en/others/faq.mdx b/agentscope/2.0.3/en/others/faq.mdx similarity index 87% rename from versions/2.0.4/en/others/faq.mdx rename to agentscope/2.0.3/en/others/faq.mdx index af7f909..00db127 100644 --- a/versions/2.0.4/en/others/faq.mdx +++ b/agentscope/2.0.3/en/others/faq.mdx @@ -14,14 +14,14 @@ description: "Frequently asked questions about AgentScope v2.0" Yes. The **workspace** abstraction is AgentScope's execution environment for agents and ships three implementations — `LocalWorkspace` (host filesystem), `DockerWorkspace` (container), and `E2BWorkspace` (E2B cloud sandbox) — sharing the same interface so the same agent code runs against any backend. Workspaces also own MCP server lifecycles, skill management, and context offloading. - See [Workspace](/versions/2.0.4/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. + See [Workspace](/agentscope/2.0.3/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. Yes, on two layers: - **TypeScript SDK** — install with `pnpm install @agentscope-ai/agentscope`. It mirrors the Python `Msg` and `Event` types so frontend code can consume agent streams without re-implementing the protocol. - - **Frontend UI** — a ready-to-use web app for [Agent Service](/versions/2.0.4/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. + - **Frontend UI** — a ready-to-use web app for [Agent Service](/agentscope/2.0.3/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. diff --git a/versions/2.0.3/en/quickstart.mdx b/agentscope/2.0.3/en/quickstart.mdx similarity index 100% rename from versions/2.0.3/en/quickstart.mdx rename to agentscope/2.0.3/en/quickstart.mdx diff --git a/versions/2.0.3/en/release-notes.mdx b/agentscope/2.0.3/en/release-notes.mdx similarity index 99% rename from versions/2.0.3/en/release-notes.mdx rename to agentscope/2.0.3/en/release-notes.mdx index f340b8d..81d76af 100644 --- a/versions/2.0.3/en/release-notes.mdx +++ b/agentscope/2.0.3/en/release-notes.mdx @@ -280,7 +280,7 @@ For the full commit-level history and contributor list, see the [GitHub releases **Tool** - **Built-in tools rebuilt on `ToolBase`**: brand-new `_bash`, `_edit`, `_glob`, `_grep`, `_read`, and `_write` implementations, plus `_meta` and `_constants`, all sharing the new tool base class. ([#1502](https://github.com/agentscope-ai/agentscope/pull/1502)) -- **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/versions/2.0.3/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) +- **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/agentscope/2.0.3/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) - **Tool + Workspace integration**: the toolkit and the workspace module are now wired into the `Agent` class so file/shell tools execute inside the agent's workspace. ([#1642](https://github.com/agentscope-ai/agentscope/pull/1642)) **Workspace** diff --git a/versions/2.0.3/zh/building-blocks/agent.mdx b/agentscope/2.0.3/zh/building-blocks/agent.mdx similarity index 98% rename from versions/2.0.3/zh/building-blocks/agent.mdx rename to agentscope/2.0.3/zh/building-blocks/agent.mdx index 7b7cc62..a732e09 100644 --- a/versions/2.0.3/zh/building-blocks/agent.mdx +++ b/agentscope/2.0.3/zh/building-blocks/agent.mdx @@ -436,10 +436,10 @@ asyncio.run(main()) ## 延伸阅读 - + 控制智能体可以调用哪些工具以及在什么条件下调用。 - + 在 reply、reasoning、acting 和 model call 钩子处拦截和修改智能体行为。 diff --git a/versions/2.0.3/zh/building-blocks/context.mdx b/agentscope/2.0.3/zh/building-blocks/context.mdx similarity index 94% rename from versions/2.0.3/zh/building-blocks/context.mdx rename to agentscope/2.0.3/zh/building-blocks/context.mdx index 365b41b..5cae843 100644 --- a/versions/2.0.3/zh/building-blocks/context.mdx +++ b/agentscope/2.0.3/zh/building-blocks/context.mdx @@ -27,7 +27,7 @@ Context 是 agent 的工作记忆 —— LLM 在每一步推理时看到的全 每一层的构成方式： -1. **System prompt** —— 以创建 agent 时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [middleware](/versions/2.0.3/zh/building-blocks/middleware) 钩子。 +1. **System prompt** —— 以创建 agent 时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [middleware](/agentscope/2.0.3/zh/building-blocks/middleware) 钩子。 2. **Summary** —— 较早消息被压缩后的摘要；只有发生过压缩之后才存在。 3. **Context** —— 最近的、尚未压缩的消息（用户输入、assistant 回复、工具调用、工具结果）。 @@ -147,7 +147,7 @@ Offload 通过 `Offloader` 协议接入 —— 该协议是结构化的，仅有 | `offload_context(session_id, msgs)` | 持久化被压缩的消息；返回一个引用（例如文件路径） | | `offload_tool_result(session_id, tool_result)` | 持久化被截断的工具结果；返回一个引用 | -任何实现该协议的对象都可以传入 agent 的 `offloader` 参数。AgentScope 的 [`workspace`](/versions/2.0.3/zh/building-blocks/workspace) 模块提供了开箱即用的实现： +任何实现该协议的对象都可以传入 agent 的 `offloader` 参数。AgentScope 的 [`workspace`](/agentscope/2.0.3/zh/building-blocks/workspace) 模块提供了开箱即用的实现： ```python from agentscope.agent import Agent @@ -235,16 +235,16 @@ class S3Offloader: ## 延伸阅读 - + 内置的 offloader 实现，以及 agent 的工作环境 - + ReAct 循环以及上下文如何在推理步骤间流转 - + 通过 middleware 钩子拦截模型调用与 system prompt 组装 - + 会被压缩处理的工具结果来源 diff --git a/versions/2.0.3/zh/building-blocks/long-term-memory.mdx b/agentscope/2.0.3/zh/building-blocks/long-term-memory.mdx similarity index 96% rename from versions/2.0.3/zh/building-blocks/long-term-memory.mdx rename to agentscope/2.0.3/zh/building-blocks/long-term-memory.mdx index 78f05d7..5f11991 100644 --- a/versions/2.0.3/zh/building-blocks/long-term-memory.mdx +++ b/agentscope/2.0.3/zh/building-blocks/long-term-memory.mdx @@ -7,7 +7,7 @@ description: "通过基于中间件的长期记忆后端，让知识在多个会 **长期记忆**让 agent 在多次会话之间保留并检索可持久化的信息，例如用户偏好、历史决策，以及需要在后续对话中反复使用的知识。 -在 AgentScope 中，记忆提取和存储服务（如 mem0、ReMe）作为长期记忆后端，以[中间件](/versions/2.0.3/zh/building-blocks/middleware)的形式集成到 agent 中。每个记忆中间件是一个 `MiddlewareBase` 子类，可以按需挂接到 agent 生命周期的 hook 位置。例如： +在 AgentScope 中，记忆提取和存储服务（如 mem0、ReMe）作为长期记忆后端，以[中间件](/agentscope/2.0.3/zh/building-blocks/middleware)的形式集成到 agent 中。每个记忆中间件是一个 `MiddlewareBase` 子类，可以按需挂接到 agent 生命周期的 hook 位置。例如： - `on_reply` —— 在 reply 前检索记忆，在 reply 后把新的对话写回。 - `on_system_prompt` —— 向模型声明记忆工具。 diff --git a/versions/2.0.3/zh/building-blocks/message-and-event.mdx b/agentscope/2.0.3/zh/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.3/zh/building-blocks/message-and-event.mdx rename to agentscope/2.0.3/zh/building-blocks/message-and-event.mdx index 26f7b27..3c436b7 100644 --- a/versions/2.0.3/zh/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.3/zh/building-blocks/message-and-event.mdx @@ -646,10 +646,10 @@ async for event in agent.reply_stream(UserMsg("user", "帮我修复这个 bug")) ## 延伸阅读 - + 智能体如何在 ReAct 循环中产出事件和消息 - + 消息如何存储、压缩和卸载 diff --git a/versions/2.0.3/zh/building-blocks/middleware.mdx b/agentscope/2.0.3/zh/building-blocks/middleware.mdx similarity index 98% rename from versions/2.0.3/zh/building-blocks/middleware.mdx rename to agentscope/2.0.3/zh/building-blocks/middleware.mdx index 19204f8..f32c0e5 100644 --- a/versions/2.0.3/zh/building-blocks/middleware.mdx +++ b/agentscope/2.0.3/zh/building-blocks/middleware.mdx @@ -20,7 +20,7 @@ AgentScope 暴露了 6 个 hook 位置外加一个 tool-provider hook，覆盖 | `list_tools` | Tool source | 可选。返回 middleware 贡献的 `list[ToolBase]`。**不会被自动调用** —— 由组装 agent toolkit 的调用方决定是否调用以及如何合并结果。 | -以上 hook 均作用于 **agent** 层面。若需要在单个工具实例上挂钩 —— 无论该工具是在 agent 内部还是外部被调用 —— 请参见[工具中间件](/versions/2.0.3/zh/building-blocks/tool#tool-middleware)。 +以上 hook 均作用于 **agent** 层面。若需要在单个工具实例上挂钩 —— 无论该工具是在 agent 内部还是外部被调用 —— 请参见[工具中间件](/agentscope/2.0.3/zh/building-blocks/tool#tool-middleware)。 三种类型的差别： @@ -286,7 +286,7 @@ DataBlockEndEvent ### 长期记忆中间件 -AgentScope 以中间件的形式实现长期记忆，让 agent 能够在多个会话间持久保存并调取信息。记忆后端挂接 `on_reply`（reply 前检索 + reply 后写回）、`on_system_prompt`（声明记忆工具），并通过 `list_tools` 提供供 agent 调用的 memory 相关工具（例如 `search_memory` / `add_memory`）。当前可用的后端为 `Mem0Middleware`，由 [mem0](https://github.com/mem0ai/mem0) 驱动。安装方式、控制模式与构造方式详见[长期记忆](/versions/2.0.3/zh/building-blocks/long-term-memory)。 +AgentScope 以中间件的形式实现长期记忆，让 agent 能够在多个会话间持久保存并调取信息。记忆后端挂接 `on_reply`（reply 前检索 + reply 后写回）、`on_system_prompt`（声明记忆工具），并通过 `list_tools` 提供供 agent 调用的 memory 相关工具（例如 `search_memory` / `add_memory`）。当前可用的后端为 `Mem0Middleware`，由 [mem0](https://github.com/mem0ai/mem0) 驱动。安装方式、控制模式与构造方式详见[长期记忆](/agentscope/2.0.3/zh/building-blocks/long-term-memory)。 ## 自定义中间件 diff --git a/versions/2.0.3/zh/building-blocks/model.mdx b/agentscope/2.0.3/zh/building-blocks/model.mdx similarity index 99% rename from versions/2.0.3/zh/building-blocks/model.mdx rename to agentscope/2.0.3/zh/building-blocks/model.mdx index b0e806b..ce71d81 100644 --- a/versions/2.0.3/zh/building-blocks/model.mdx +++ b/agentscope/2.0.3/zh/building-blocks/model.mdx @@ -601,7 +601,7 @@ asyncio.run(main()) ### 与 Agent 集成 -在 agent 层，TTS 通过 [`TTSMiddleware`](/versions/2.0.3/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： +在 agent 层，TTS 通过 [`TTSMiddleware`](/agentscope/2.0.3/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： ```python from agentscope.agent import Agent diff --git a/versions/2.0.3/zh/building-blocks/permission-system.mdx b/agentscope/2.0.3/zh/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.3/zh/building-blocks/permission-system.mdx rename to agentscope/2.0.3/zh/building-blocks/permission-system.mdx diff --git a/versions/2.0.3/zh/building-blocks/plan.mdx b/agentscope/2.0.3/zh/building-blocks/plan.mdx similarity index 97% rename from versions/2.0.3/zh/building-blocks/plan.mdx rename to agentscope/2.0.3/zh/building-blocks/plan.mdx index b7ff59a..cf75448 100644 --- a/versions/2.0.3/zh/building-blocks/plan.mdx +++ b/agentscope/2.0.3/zh/building-blocks/plan.mdx @@ -202,5 +202,5 @@ agent 下一轮就会看到一个空计划并从头开始。 ## 延伸阅读 -- [Tool](/versions/2.0.3/zh/building-blocks/tool) —— toolkit、`ToolBase` 接口，以及状态注入式工具如何拿到 `AgentState`。 -- [Agent](/versions/2.0.3/zh/building-blocks/agent) —— agent 生命周期，包括 `AgentState` 的创建、恢复与持久化。 +- [Tool](/agentscope/2.0.3/zh/building-blocks/tool) —— toolkit、`ToolBase` 接口，以及状态注入式工具如何拿到 `AgentState`。 +- [Agent](/agentscope/2.0.3/zh/building-blocks/agent) —— agent 生命周期，包括 `AgentState` 的创建、恢复与持久化。 diff --git a/versions/2.0.3/zh/building-blocks/rag.mdx b/agentscope/2.0.3/zh/building-blocks/rag.mdx similarity index 97% rename from versions/2.0.3/zh/building-blocks/rag.mdx rename to agentscope/2.0.3/zh/building-blocks/rag.mdx index 9df1410..b6a34e1 100644 --- a/versions/2.0.3/zh/building-blocks/rag.mdx +++ b/agentscope/2.0.3/zh/building-blocks/rag.mdx @@ -16,7 +16,7 @@ AgentScope 中的 RAG 由如下**可独立替换**的功能模块组成： 本章主要介绍**在非服务化场景下**使用 RAG 功能，包括索引文件、检索知识、集成到智能体等。 -嵌入模型的介绍和配置方式请见[嵌入模型章节](/versions/2.0.3/zh/building-blocks/model)；服务化版本的 RAG（带 HTTP 服务、文件托管、分布式索引）请见 [RAG 服务](/versions/2.0.3/zh/deploy/rag)。 +嵌入模型的介绍和配置方式请见[嵌入模型章节](/agentscope/2.0.3/zh/building-blocks/model)；服务化版本的 RAG（带 HTTP 服务、文件托管、分布式索引）请见 [RAG 服务](/agentscope/2.0.3/zh/deploy/rag)。 ## 现有实现 @@ -46,7 +46,7 @@ PDF 与 PPT 解析依赖额外的第三方库，可以通过 `pip install agents ### 嵌入模型 -请见[嵌入模型章节](/versions/2.0.3/zh/building-blocks/model)。 +请见[嵌入模型章节](/agentscope/2.0.3/zh/building-blocks/model)。 ### 向量数据库 @@ -520,13 +520,13 @@ class MyVectorStore(VectorStoreBase): ## 延伸阅读 - + 多租户、分布式的 RAG 服务，支持 HTTP API、文件托管、向量数据库托管。 - + 了解 `RAGMiddleware` 是如何嵌入 reply / reasoning 钩子的。 - + 可用的嵌入模型及其参数。 diff --git a/versions/2.0.3/zh/building-blocks/tool.mdx b/agentscope/2.0.3/zh/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.3/zh/building-blocks/tool.mdx rename to agentscope/2.0.3/zh/building-blocks/tool.mdx index acfc452..274b79b 100644 --- a/versions/2.0.3/zh/building-blocks/tool.mdx +++ b/agentscope/2.0.3/zh/building-blocks/tool.mdx @@ -126,7 +126,7 @@ bash = Bash( `check_permissions()` —— `Write` 与 `Edit` 共用同一权限逻辑： -1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/versions/2.0.3/zh/building-blocks/permission-system#safety-check-契约)。 +1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/agentscope/2.0.3/zh/building-blocks/permission-system#safety-check-契约)。 2. **ACCEPT_EDITS 模式** —— 自动放行配置工作目录内的文件操作 3. **PASSTHROUGH** —— 交给权限引擎做规则匹配 @@ -146,7 +146,7 @@ bash = Bash( Plan 类工具为 agent 提供一份结构化的任务清单 —— 通过普通的工具调用即可追加、查询与更新任务。它们共享 `agent.state.tasks_context` 这一份存储，全部为状态注入式工具，且权限检查恒为放行 —— agent 把它们视作零成本的协调原语，用于把复杂工作拆解成可追踪的步骤。 -完整的任务生命周期、存储模型，以及如何以编程方式预置或自定义任务，请参见 [Plan](/versions/2.0.3/zh/building-blocks/plan)。 +完整的任务生命周期、存储模型，以及如何以编程方式预置或自定义任务，请参见 [Plan](/agentscope/2.0.3/zh/building-blocks/plan)。 ### 自定义 Tool @@ -192,7 +192,7 @@ class WebSearch(ToolBase): 自定义 tool 写带安全语义的逻辑时，有两个扩展钩子值得了解： - **`check_read_only(tool_input)`** —— 当某次调用是否修改状态取决于输入时覆写（例如 `Bash`：`ls` 是只读，`rm` 不是）。默认返回 `is_read_only` 静态属性。权限引擎在判定 EXPLORE / ACCEPT_EDITS 是否自动放行时调用。 -- **`PermissionDecision(..., bypass_immune=True)`** —— 在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/versions/2.0.3/zh/building-blocks/permission-system#safety-check-契约)。 +- **`PermissionDecision(..., bypass_immune=True)`** —— 在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/agentscope/2.0.3/zh/building-blocks/permission-system#safety-check-契约)。 ### 把函数包装为 Tool @@ -233,7 +233,7 @@ toolkit = Toolkit(tools=[FunctionTool(get_weather)]) 外部执行 tool 把实际执行委派给 agent 运行时之外 —— 通常是人工操作员或外部系统。Agent 调用此类 tool 时会发出 `RequireExternalExecutionEvent` 并暂停，直到结果通过 `ExternalExecutionResultEvent` 回传。 -这种模式是 [human-in-the-loop](/versions/2.0.3/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 +这种模式是 [human-in-the-loop](/agentscope/2.0.3/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 创建外部执行 tool 只需把 `is_external_tool` 设为 `True`，不必实现 `call`： @@ -353,7 +353,7 @@ bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)]) ``` -**Tool middleware vs. agent middleware** —— 对属于工具本身的横切关注点（日志、metrics、重试），使用 `ToolMiddlewareBase`。若需要访问更广泛的 agent 上下文 —— 权限决策、tool-call 事件或所在的 ReAct 轮次 —— 请使用 `MiddlewareBase.on_acting`。完整的 agent 级钩子参考见 [Middleware](/versions/2.0.3/zh/building-blocks/middleware)。 +**Tool middleware vs. agent middleware** —— 对属于工具本身的横切关注点（日志、metrics、重试），使用 `ToolMiddlewareBase`。若需要访问更广泛的 agent 上下文 —— 权限决策、tool-call 事件或所在的 ReAct 轮次 —— 请使用 `MiddlewareBase.on_acting`。完整的 agent 级钩子参考见 [Middleware](/agentscope/2.0.3/zh/building-blocks/middleware)。 ## MCP @@ -537,16 +537,16 @@ Meta tool 的输入表示所有 group 的**最终状态**而非增量。任何 ## 延伸阅读 - + Agent 如何在 ReAct 循环中编排 tool 调用 - + 精细控制哪个 tool 可以执行、何时执行 - + 拦截 agent 生命周期钩子 —— reply、reasoning、model 调用等 - + 外部执行 tool 与人工审批工作流 diff --git a/versions/2.0.3/zh/building-blocks/workspace.mdx b/agentscope/2.0.3/zh/building-blocks/workspace.mdx similarity index 92% rename from versions/2.0.3/zh/building-blocks/workspace.mdx rename to agentscope/2.0.3/zh/building-blocks/workspace.mdx index c09e5bf..1e08364 100644 --- a/versions/2.0.3/zh/building-blocks/workspace.mdx +++ b/agentscope/2.0.3/zh/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "为 agent 提供工具、skill 与上下文 offload 的执行环 Workspace 是 agent 的执行环境，向 agent 提供三类资源 —— **工具**（内置 tool 与 MCP）、**skill**，以及面向压缩消息与超大工具结果的**上下文 offload** —— 同时管理其中资源（MCP server 进程、动态加入的 skill、offload 文件）的生命周期。 -AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/versions/2.0.3/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 +AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/agentscope/2.0.3/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 对 Docker 与 E2B 而言，MCP server 跑在隔离环境*内部*；宿主侧通过 workspace 内的 gateway 访问它们，详见后文 [MCP Gateway](#mcp-gateway)。 @@ -177,7 +177,7 @@ toolkit = Toolkit( ## Workspace Manager -Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/versions/2.0.3/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 +Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/agentscope/2.0.3/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 Manager 的职责： @@ -220,10 +220,10 @@ ws = await manager.get_workspace( ) ``` -要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/versions/2.0.3/zh/deploy/agent-service#workspace-实现与隔离)。 +要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/agentscope/2.0.3/zh/deploy/agent-service#workspace-实现与隔离)。 -Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/versions/2.0.3/zh/deploy/agent-service)。 +Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/agentscope/2.0.3/zh/deploy/agent-service)。 ## MCP Gateway @@ -255,16 +255,16 @@ Gateway 暴露一组小型 REST 接口 —— `GET /health`、`GET/POST/DELETE / ## 延伸阅读 - + Agent 抽象、ReAct 循环与 offloader 集成 - + 内置 tool、MCP 集成与 toolkit 组装 - + 驱动 workspace manager 的多租户服务 - + 上下文压缩与 offload 触发条件 diff --git a/versions/2.0.3/zh/deploy/agent-service.mdx b/agentscope/2.0.3/zh/deploy/agent-service.mdx similarity index 96% rename from versions/2.0.3/zh/deploy/agent-service.mdx rename to agentscope/2.0.3/zh/deploy/agent-service.mdx index c3a102b..d51798c 100644 --- a/versions/2.0.3/zh/deploy/agent-service.mdx +++ b/agentscope/2.0.3/zh/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "架构" description: "把智能体部署为多租户、多会话的 HTTP 服务" --- -智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/versions/2.0.3/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 +智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/agentscope/2.0.3/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 它的特点： @@ -16,7 +16,7 @@ description: "把智能体部署为多租户、多会话的 HTTP 服务" | 能力 | 说明 | |---------------------------------------------------|-----------------------------------------------------------------------------------------| -| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/versions/2.0.3/zh/deploy/agent-team) 章节。 | +| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/agentscope/2.0.3/zh/deploy/agent-team) 章节。 | | 工作区管理 | 可插拔的工作区隔离策略（内置：智能体隔离；可扩展为按会话或用户隔离），管理智能体的文件系统、MCP client 与 skill。 | | 后台任务卸载（Background Task Offloading） | 长耗时工具调用切到后台执行，完成时通过会话事件流回送结果。 | | Cron 调度 | 按时间触发智能体执行，支持有状态或无状态会话；调度持久化保存，跨重启生效。 | @@ -199,7 +199,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) 异步工厂 `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]`，在每次组装智能体时被调用一次。返回的工具会与工作区派生的工具一起合并到 toolkit 的 `"basic"` 分组里，便于按调用者动态决定可用工具（例如按租户接入、按用户使用各自凭证的工具）。 - 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/versions/2.0.3/zh/deploy/agent-team#自定义子智能体类型)。 + 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/agentscope/2.0.3/zh/deploy/agent-team#自定义子智能体类型)。 OpenAPI 文档界面中显示的标题。 @@ -240,7 +240,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) ``` - 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/versions/2.0.3/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 + 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/agentscope/2.0.3/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 ```http POST /workspace/mcp @@ -351,7 +351,7 @@ flowchart TB ### 智能体聊天协议 -按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/versions/2.0.3/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 +按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/agentscope/2.0.3/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 AgentScope 内置 `AGUIProtocolMiddleware` 适配 [AG-UI](https://docs.ag-ui.com/) 协议。通过 `extra_middlewares` 装载： @@ -700,16 +700,16 @@ Router 通过 FastAPI 的 `Depends()` 拿到应用状态。标准注入项（位 ## 延伸阅读 - + 核心智能体抽象与 ReAct 循环 - + 事件流与消息重建 - + 内置与自定义工具，包括外部执行 - + 上下文压缩与工作区 offloading diff --git a/versions/2.0.3/zh/deploy/agent-team.mdx b/agentscope/2.0.3/zh/deploy/agent-team.mdx similarity index 85% rename from versions/2.0.3/zh/deploy/agent-team.mdx rename to agentscope/2.0.3/zh/deploy/agent-team.mdx index f0da099..2e8c5fc 100644 --- a/versions/2.0.3/zh/deploy/agent-team.mdx +++ b/agentscope/2.0.3/zh/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "智能体团队" description: "Leader 智能体通过内置 team 工具派生并协调 worker 智能体" --- -智能体团队（Agent Team）是构建在[智能体服务](/versions/2.0.3/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 +智能体团队（Agent Team）是构建在[智能体服务](/agentscope/2.0.3/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 ## 快速上手 -随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/versions/2.0.3/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 +随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/agentscope/2.0.3/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 智能体团队协作演示 @@ -129,7 +129,7 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ### 协调模型 -智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/versions/2.0.3/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 +智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/agentscope/2.0.3/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 团队通信复用了服务用于调度触发与后台工具完成的同一组 inbox + wakeup 原语： @@ -143,10 +143,10 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ## 延伸阅读 - + 支撑团队的托管层 —— 会话、消息总线、工作区生命周期。 - + 每个团队成员所运行的智能体抽象。 diff --git a/versions/2.0.4/zh/deploy/rag.mdx b/agentscope/2.0.3/zh/deploy/rag.mdx similarity index 96% rename from versions/2.0.4/zh/deploy/rag.mdx rename to agentscope/2.0.3/zh/deploy/rag.mdx index ba8feff..baecaad 100644 --- a/versions/2.0.4/zh/deploy/rag.mdx +++ b/agentscope/2.0.3/zh/deploy/rag.mdx @@ -3,7 +3,7 @@ title: "RAG 服务" description: "一键式启动的多租户、分布式 RAG 服务" --- -[RAG](/versions/2.0.4/zh/building-blocks/rag) 章节中介绍了 AgentScope 中的 RAG 模块的拓展和使用方法。本章介绍智能体服务（Agent service）中提供的**多租户、可分布式部署**的 RAG 服务层。服务层在 building blocks 的基础上，围绕「多租户」「分布式」「易接入」提供以下能力： +[RAG](/agentscope/2.0.3/zh/building-blocks/rag) 章节中介绍了 AgentScope 中的 RAG 模块的拓展和使用方法。本章介绍智能体服务（Agent service）中提供的**多租户、可分布式部署**的 RAG 服务层。服务层在 building blocks 的基础上，围绕「多租户」「分布式」「易接入」提供以下能力： | 能力 | 说明 | |------|------| @@ -424,16 +424,16 @@ parser 默认在事件循环线程内运行。如果引入 PDF / Office 等 CPU ## 延伸阅读 - + 了解 parser / chunker / vector store / middleware 的原子接口与 library 模式用法。 - + `create_app` 的全局参数、lifespan、依赖注入与 ASGI 中间件层。 - + `RAGMiddleware` 借助哪些钩子注入检索结果。 - + 嵌入模型卡 / 维度约束，决定知识库可选哪些模型。 diff --git a/versions/2.0.4/zh/index.mdx b/agentscope/2.0.3/zh/index.mdx similarity index 77% rename from versions/2.0.4/zh/index.mdx rename to agentscope/2.0.3/zh/index.mdx index 17acac9..a814320 100644 --- a/versions/2.0.4/zh/index.mdx +++ b/agentscope/2.0.3/zh/index.mdx @@ -19,19 +19,19 @@ AgentScope 2.0 是一款安全、高效、灵活且完备的生产级智能体 从单智能体推理到复杂企业级应用，AgentScope 为开发者提供覆盖其完整生命周期的全栈支持。 - + 具备自主 ReAct 推理和多工具协同执行能力的智能体，内置人机协作审核与高并发工具调度机制。 - + 智能体自主管理的工具栈体系，支持原生 Python 函数、MCP（模型上下文协议）和多种外部技能（Skill）的无缝拼装。 - + 精细化的上下文剪裁、卸载与智能体主动检索，深度融合了 Mem0、ReMe 等第三方记忆实现。 - + 支持在物理隔离的安全环境（如本地隔离沙箱、Docker、E2B、Kubernetes 等）中安全执行外部代码，支持用户、智能体、会话三级精细隔离。 - + 一键部署的生产级后端，自带可视化前端与开发 SDK，多租户多会话并发与分布式集群调度触手可得。 diff --git a/versions/2.0.3/zh/others/change-log.mdx b/agentscope/2.0.3/zh/others/change-log.mdx similarity index 100% rename from versions/2.0.3/zh/others/change-log.mdx rename to agentscope/2.0.3/zh/others/change-log.mdx diff --git a/versions/2.0.4/zh/others/faq.mdx b/agentscope/2.0.3/zh/others/faq.mdx similarity index 84% rename from versions/2.0.4/zh/others/faq.mdx rename to agentscope/2.0.3/zh/others/faq.mdx index b572803..b1c560a 100644 --- a/versions/2.0.4/zh/others/faq.mdx +++ b/agentscope/2.0.3/zh/others/faq.mdx @@ -14,14 +14,14 @@ description: "AgentScope 2.0 常见问题" 支持。**Workspace** 是 AgentScope 为 agent 提供的执行环境抽象，内置三种实现 —— `LocalWorkspace`（宿主文件系统）、`DockerWorkspace`（容器）、`E2BWorkspace`（E2B 云沙箱），共享同一份接口，因此同一份 agent 代码可以无差别地在任意后端上运行。Workspace 同时负责管理 MCP server 生命周期、skill 与上下文 offload。 - 完整介绍见 [Workspace](/versions/2.0.4/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 + 完整介绍见 [Workspace](/agentscope/2.0.3/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 有，分两个层次： - **TypeScript SDK** —— 通过 `pnpm install @agentscope-ai/agentscope` 安装，对齐 Python 端的 `Msg` 与 `Event` 类型，前端无需重写协议即可消费 agent 的流式输出。 - - **前端 UI** —— 面向 [Agent Service](/versions/2.0.4/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 + - **前端 UI** —— 面向 [Agent Service](/agentscope/2.0.3/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 diff --git a/versions/2.0.3/zh/quickstart.mdx b/agentscope/2.0.3/zh/quickstart.mdx similarity index 100% rename from versions/2.0.3/zh/quickstart.mdx rename to agentscope/2.0.3/zh/quickstart.mdx diff --git a/versions/2.0.3/zh/release-notes.mdx b/agentscope/2.0.3/zh/release-notes.mdx similarity index 99% rename from versions/2.0.3/zh/release-notes.mdx rename to agentscope/2.0.3/zh/release-notes.mdx index d23e0cf..9b7304e 100644 --- a/versions/2.0.3/zh/release-notes.mdx +++ b/agentscope/2.0.3/zh/release-notes.mdx @@ -280,7 +280,7 @@ description: "AgentScope 版本改动和更新日志。" **Tool** - **基于 `ToolBase` 重建内置工具**：全新的 `_bash`、`_edit`、`_glob`、`_grep`、`_read`、`_write` 实现，以及共享的 `_meta` 与 `_constants`，全部基于新的工具基类。([#1502](https://github.com/agentscope-ai/agentscope/pull/1502)) -- **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/versions/2.0.3/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) +- **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/agentscope/2.0.3/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) - **Tool 与 Workspace 集成**：工具包与 Workspace 模块被打通进 `Agent` 类，文件/Shell 工具现在统一在 Agent 的 Workspace 中执行。([#1642](https://github.com/agentscope-ai/agentscope/pull/1642)) **Workspace** diff --git a/versions/2.0.4/en/building-blocks/agent.mdx b/agentscope/2.0.4/en/building-blocks/agent.mdx similarity index 99% rename from versions/2.0.4/en/building-blocks/agent.mdx rename to agentscope/2.0.4/en/building-blocks/agent.mdx index 6dd91ce..59a0ceb 100644 --- a/versions/2.0.4/en/building-blocks/agent.mdx +++ b/agentscope/2.0.4/en/building-blocks/agent.mdx @@ -478,10 +478,10 @@ asyncio.run(main()) ## Further Reading - + Control which tools the agent can call and under what conditions. - + Intercept and modify agent behavior at reply, reasoning, acting, and model call hooks. diff --git a/versions/2.0.2/en/building-blocks/context.mdx b/agentscope/2.0.4/en/building-blocks/context.mdx similarity index 94% rename from versions/2.0.2/en/building-blocks/context.mdx rename to agentscope/2.0.4/en/building-blocks/context.mdx index 6aa3a26..3bec5b8 100644 --- a/versions/2.0.2/en/building-blocks/context.mdx +++ b/agentscope/2.0.4/en/building-blocks/context.mdx @@ -27,7 +27,7 @@ Before each model call, the agent assembles a single API input from three layers How each layer is built: -1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/versions/2.0.2/en/building-blocks/middleware) hook in order. +1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/agentscope/2.0.4/en/building-blocks/middleware) hook in order. 2. **Summary** — the compressed digest of older messages, present only after a compression has occurred. 3. **Context** — the recent uncompressed messages (user inputs, assistant responses, tool calls, tool results). @@ -148,7 +148,7 @@ Offloading is wired through the `Offloader` protocol — a structural contract w | `offload_context(session_id, msgs)` | Persist compressed messages; returns a reference (e.g. a file path) to the persisted content | | `offload_tool_result(session_id, tool_result)` | Persist a truncated tool result; returns a reference to the persisted content | -Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/versions/2.0.2/en/building-blocks/workspace) module ships ready-made implementations: +Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/agentscope/2.0.4/en/building-blocks/workspace) module ships ready-made implementations: ```python from agentscope.agent import Agent @@ -236,16 +236,16 @@ Pass the instance into `Agent(offloader=...)` like any built-in workspace. ## Further Reading - + Built-in offloader implementations and the agent's working environment - + The ReAct loop and how context flows through reasoning steps - + Intercept model calls and system prompt composition with middleware hooks - + Tools that produce results subject to compression diff --git a/versions/2.0.4/en/building-blocks/long-term-memory.mdx b/agentscope/2.0.4/en/building-blocks/long-term-memory.mdx similarity index 98% rename from versions/2.0.4/en/building-blocks/long-term-memory.mdx rename to agentscope/2.0.4/en/building-blocks/long-term-memory.mdx index 8072309..21f931e 100644 --- a/versions/2.0.4/en/building-blocks/long-term-memory.mdx +++ b/agentscope/2.0.4/en/building-blocks/long-term-memory.mdx @@ -5,7 +5,7 @@ description: "Cross-session long-term memory implemented with agent middleware" **Long-term memory** is an agent's ability to retain information across sessions, including user preferences, past decisions, and knowledge or rules summarized from conversations. -AgentScope implements different long-term memory capabilities as [agent middleware](/versions/2.0.4/en/building-blocks/middleware). Each long-term memory implementation is a `MiddlewareBase` subclass that non-invasively handles memory injection, retrieval, and write-back. +AgentScope implements different long-term memory capabilities as [agent middleware](/agentscope/2.0.4/en/building-blocks/middleware). Each long-term memory implementation is a `MiddlewareBase` subclass that non-invasively handles memory injection, retrieval, and write-back. AgentScope currently supports the following long-term memory implementations, with more under development: diff --git a/versions/2.0.4/en/building-blocks/message-and-event.mdx b/agentscope/2.0.4/en/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.4/en/building-blocks/message-and-event.mdx rename to agentscope/2.0.4/en/building-blocks/message-and-event.mdx index eb12b59..ddb2574 100644 --- a/versions/2.0.4/en/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.4/en/building-blocks/message-and-event.mdx @@ -647,10 +647,10 @@ async for event in agent.reply_stream(UserMsg("user", "Fix the bug")): ## Further Reading - + How the agent produces events and messages in the ReAct loop - + How messages are stored, compressed, and offloaded \ No newline at end of file diff --git a/versions/2.0.4/en/building-blocks/middleware.mdx b/agentscope/2.0.4/en/building-blocks/middleware.mdx similarity index 98% rename from versions/2.0.4/en/building-blocks/middleware.mdx rename to agentscope/2.0.4/en/building-blocks/middleware.mdx index b9606ed..db7727a 100644 --- a/versions/2.0.4/en/building-blocks/middleware.mdx +++ b/agentscope/2.0.4/en/building-blocks/middleware.mdx @@ -20,7 +20,7 @@ AgentScope exposes 6 hook positions plus a tool-provider hook, covering the full | `list_tools` | Tool source | Optional. Returns a `list[ToolBase]` that the middleware contributes. **Not invoked automatically** — the caller assembling the agent's toolkit decides whether to call it and how to merge the result. | -These hooks operate at the **agent** level. For per-tool onion hooks that fire on every invocation of a specific tool — regardless of whether it's called inside or outside an agent — see [Tool Middleware](/versions/2.0.4/en/building-blocks/tool#tool-middleware). +These hooks operate at the **agent** level. For per-tool onion hooks that fire on every invocation of a specific tool — regardless of whether it's called inside or outside an agent — see [Tool Middleware](/agentscope/2.0.4/en/building-blocks/tool#tool-middleware). The three types differ as follows: @@ -295,11 +295,11 @@ Each `DataBlockDeltaEvent.data` carries an incremental base64-encoded audio chun ### Long-Term Memory -AgentScope supports long-term memory as middleware, so agents can persist and recall information across sessions. See [Long-Term Memory](/versions/2.0.4/en/building-blocks/long-term-memory) for details. +AgentScope supports long-term memory as middleware, so agents can persist and recall information across sessions. See [Long-Term Memory](/agentscope/2.0.4/en/building-blocks/long-term-memory) for details. ### RAG -AgentScope also provides knowledge-base access through middleware, allowing agents to access external knowledge bases during reasoning. See [RAG](/versions/2.0.4/en/building-blocks/rag) for details. +AgentScope also provides knowledge-base access through middleware, allowing agents to access external knowledge bases during reasoning. See [RAG](/agentscope/2.0.4/en/building-blocks/rag) for details. ## Custom Middleware diff --git a/versions/2.0.4/en/building-blocks/model.mdx b/agentscope/2.0.4/en/building-blocks/model.mdx similarity index 99% rename from versions/2.0.4/en/building-blocks/model.mdx rename to agentscope/2.0.4/en/building-blocks/model.mdx index 6b209b6..3a3c51c 100644 --- a/versions/2.0.4/en/building-blocks/model.mdx +++ b/agentscope/2.0.4/en/building-blocks/model.mdx @@ -672,7 +672,7 @@ asyncio.run(main()) ### Integrate with Agent -In the agent layer, TTS is integrated via [`TTSMiddleware`](/versions/2.0.4/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: +In the agent layer, TTS is integrated via [`TTSMiddleware`](/agentscope/2.0.4/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: ```python from agentscope.agent import Agent diff --git a/versions/2.0.4/en/building-blocks/permission-system.mdx b/agentscope/2.0.4/en/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.4/en/building-blocks/permission-system.mdx rename to agentscope/2.0.4/en/building-blocks/permission-system.mdx diff --git a/versions/2.0.4/en/building-blocks/plan.mdx b/agentscope/2.0.4/en/building-blocks/plan.mdx similarity index 96% rename from versions/2.0.4/en/building-blocks/plan.mdx rename to agentscope/2.0.4/en/building-blocks/plan.mdx index 82e4253..9b96d58 100644 --- a/versions/2.0.4/en/building-blocks/plan.mdx +++ b/agentscope/2.0.4/en/building-blocks/plan.mdx @@ -198,5 +198,5 @@ The next agent turn will see an empty plan and start over. ## Further Reading -- [Tool](/versions/2.0.4/en/building-blocks/tool) — the toolkit, the `ToolBase` interface, and how state-injected tools receive `AgentState`. -- [Agent](/versions/2.0.4/en/building-blocks/agent) — the agent lifecycle, including how `AgentState` is created, restored, and persisted. +- [Tool](/agentscope/2.0.4/en/building-blocks/tool) — the toolkit, the `ToolBase` interface, and how state-injected tools receive `AgentState`. +- [Agent](/agentscope/2.0.4/en/building-blocks/agent) — the agent lifecycle, including how `AgentState` is created, restored, and persisted. diff --git a/versions/2.0.4/en/building-blocks/rag.mdx b/agentscope/2.0.4/en/building-blocks/rag.mdx similarity index 97% rename from versions/2.0.4/en/building-blocks/rag.mdx rename to agentscope/2.0.4/en/building-blocks/rag.mdx index a30fe8d..ffd6012 100644 --- a/versions/2.0.4/en/building-blocks/rag.mdx +++ b/agentscope/2.0.4/en/building-blocks/rag.mdx @@ -16,7 +16,7 @@ In AgentScope, RAG is composed of the following **independently replaceable** mo This chapter focuses on **using RAG in non-service scenarios** — indexing files, retrieving knowledge, and integrating with an agent. -For embedding models and how to configure them, see the [Embedding Model chapter](/versions/2.0.4/en/building-blocks/model); for the service version of RAG (with an HTTP service, file hosting, and distributed indexing), see [RAG Service](/versions/2.0.4/en/deploy/rag). +For embedding models and how to configure them, see the [Embedding Model chapter](/agentscope/2.0.4/en/building-blocks/model); for the service version of RAG (with an HTTP service, file hosting, and distributed indexing), see [RAG Service](/agentscope/2.0.4/en/deploy/rag). ## Existing Implementations @@ -46,7 +46,7 @@ The PDF and PPT parsers depend on additional third-party libraries; install them ### Embedding Model -See the [Embedding Model chapter](/versions/2.0.4/en/building-blocks/model). +See the [Embedding Model chapter](/agentscope/2.0.4/en/building-blocks/model). ### Vector Database @@ -534,13 +534,13 @@ Implementation notes: ## Further Reading - + A multi-tenant, distributed RAG service with HTTP API, file hosting, and managed vector databases. - + See how `RAGMiddleware` plugs into the reply / reasoning hooks. - + Available embedding models and their parameters. diff --git a/versions/2.0.4/en/building-blocks/tool.mdx b/agentscope/2.0.4/en/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.4/en/building-blocks/tool.mdx rename to agentscope/2.0.4/en/building-blocks/tool.mdx index 98d3834..66697b7 100644 --- a/versions/2.0.4/en/building-blocks/tool.mdx +++ b/agentscope/2.0.4/en/building-blocks/tool.mdx @@ -126,7 +126,7 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the `check_permissions()` — `Write` and `Edit` share the same permission logic: -1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/versions/2.0.4/en/building-blocks/permission-system#safety-check-contract) for the full contract. +1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/agentscope/2.0.4/en/building-blocks/permission-system#safety-check-contract) for the full contract. 2. **ACCEPT_EDITS mode** — auto-allows operations on files within configured working directories 3. **PASSTHROUGH** — falls through to the permission engine for rule matching @@ -146,14 +146,14 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the The plan tools give the agent a structured task list it can append to, query, and update through normal tool calls. They share a single store on `agent.state.tasks_context`, are state-injected, and always pass permission checks — the agent treats them as free-cost coordination primitives for breaking complex work into trackable steps. -See [Plan](/versions/2.0.4/en/building-blocks/plan) for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically. +See [Plan](/agentscope/2.0.4/en/building-blocks/plan) for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically. ### Switch Tool Backend The `Bash`, `Grep`, `Glob`, `Read`, `Write`, and `Edit` tools in AgentScope support backend switching — delegating their execution to different runtime environments such as the local filesystem, a Docker container, an E2B sandbox, and so on. -A backend is selected via the `backend` argument. Backend instances are obtained from a `Workspace`, which defaults to the local environment. See [Workspace](/versions/2.0.4/en/building-blocks/workspace) for more details. +A backend is selected via the `backend` argument. Backend instances are obtained from a `Workspace`, which defaults to the local environment. See [Workspace](/agentscope/2.0.4/en/building-blocks/workspace) for more details. ```python title="Switch to Docker backend" @@ -238,7 +238,7 @@ class WebSearch(ToolBase): Two extension hooks worth knowing about when writing custom tools with safety logic: - **`check_read_only(tool_input)`** — override when whether an invocation modifies state depends on the input (like `Bash`: `ls` is read-only, `rm` is not). Defaults to returning the static `is_read_only` attribute. The permission engine calls it before deciding EXPLORE / ACCEPT_EDITS auto-allow. -- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/versions/2.0.4/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. +- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/agentscope/2.0.4/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. ### Wrap Function as Tool @@ -279,7 +279,7 @@ Wrapped functions default to `ASK` permission behavior — the user must explici An external execution tool delegates its actual execution outside the agent runtime — typically to a human operator or an external system. When the agent calls one, it emits a `RequireExternalExecutionEvent` and pauses until the result is delivered via `ExternalExecutionResultEvent`. -This pattern underlies the [human-in-the-loop](/versions/2.0.4/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. +This pattern underlies the [human-in-the-loop](/agentscope/2.0.4/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. To create an external execution tool, set `is_external_tool = True`. There is no need to implement `call`: @@ -399,7 +399,7 @@ bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)]) ``` -**Tool middleware vs. agent middleware** — use `ToolMiddlewareBase` for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use `MiddlewareBase.on_acting` when you need access to the broader agent context — permission decisions, the tool-call event, or the surrounding ReAct round. See [Middleware](/versions/2.0.4/en/building-blocks/middleware) for the full agent-level hook reference. +**Tool middleware vs. agent middleware** — use `ToolMiddlewareBase` for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use `MiddlewareBase.on_acting` when you need access to the broader agent context — permission decisions, the tool-call event, or the surrounding ReAct round. See [Middleware](/agentscope/2.0.4/en/building-blocks/middleware) for the full agent-level hook reference. ## MCP @@ -583,16 +583,16 @@ The meta tool input represents the **final state** of all groups, not incrementa ## Further Reading - + How agents orchestrate tool calls in the ReAct loop - + Fine-grained control over which tools can execute and when - + Intercept agent lifecycle hooks — reply, reasoning, model calls, and more - + External execution tools and human approval workflows diff --git a/versions/2.0.2/en/building-blocks/workspace.mdx b/agentscope/2.0.4/en/building-blocks/workspace.mdx similarity index 92% rename from versions/2.0.2/en/building-blocks/workspace.mdx rename to agentscope/2.0.4/en/building-blocks/workspace.mdx index 752d93d..340a875 100644 --- a/versions/2.0.2/en/building-blocks/workspace.mdx +++ b/agentscope/2.0.4/en/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "The execution environment that supplies tools, skills, and context A workspace is the agent's execution environment. It supplies the agent with three categories of resources — **tools** (built-in tools and MCPs), **skills**, and **context offloading** for compressed messages and oversized tool results — and owns the lifecycle of the resources living inside it (MCP server processes, dynamically added skills, offloaded files). -AgentScope ships three workspace implementations — local filesystem, Docker container, and E2B cloud sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/versions/2.0.2/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. +AgentScope ships three workspace implementations — local filesystem, Docker container, and E2B cloud sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/agentscope/2.0.4/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. For Docker and E2B, MCP servers run *inside* the isolated environment; the host reaches them through an in-workspace gateway covered in [MCP Gateway](#mcp-gateway). @@ -177,7 +177,7 @@ toolkit = Toolkit( ## Workspace Manager -A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/versions/2.0.2/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. +A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/agentscope/2.0.4/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. A manager is responsible for: @@ -220,10 +220,10 @@ ws = await manager.get_workspace( ) ``` -To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/versions/2.0.2/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. +To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/agentscope/2.0.4/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. -In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/versions/2.0.2/en/deploy/agent-service) for the full integration. +In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/agentscope/2.0.4/en/deploy/agent-service) for the full integration. ## MCP Gateway @@ -255,16 +255,16 @@ This abstraction keeps the agent-side code identical across all three workspace ## Further Reading - + Agent abstraction, the ReAct loop, and offloader integration - + Built-in tools, MCP integration, and toolkit composition - + Multi-tenant service that drives the workspace manager - + Context compression and the offloading triggers diff --git a/versions/2.0.4/en/deploy/agent-service.mdx b/agentscope/2.0.4/en/deploy/agent-service.mdx similarity index 97% rename from versions/2.0.4/en/deploy/agent-service.mdx rename to agentscope/2.0.4/en/deploy/agent-service.mdx index b9d78bb..b410e59 100644 --- a/versions/2.0.4/en/deploy/agent-service.mdx +++ b/agentscope/2.0.4/en/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "Architecture" description: "Host your agent as a multi-tenant, multi-session HTTP service" --- -Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/versions/2.0.4/en/building-blocks/agent) can serve production traffic without being rewritten. +Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/agentscope/2.0.4/en/building-blocks/agent) can serve production traffic without being rewritten. What sets it apart: @@ -16,7 +16,7 @@ What sets it apart: | Capability | Description | |------------|-------------| -| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/versions/2.0.4/en/deploy/agent-team) chapter. | +| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/agentscope/2.0.4/en/deploy/agent-team) chapter. | | Workspace management | Configurable workspace isolation — `per_agent` (default), `per_session`, or `per_user` — for the agent's filesystem, MCP clients, and skills. | | Knowledge bases (RAG) | Optional built-in knowledge base service with document ingestion, chunking, embedding, and natural-language search — enabled by passing a `knowledge_base_manager` to `create_app`. | | Background task offloading | Long-running tool calls move to background; their results are delivered back through the session's event stream when they finish. | @@ -217,7 +217,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) Async factory `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]` invoked once per agent assembly. Returned tools are merged into the toolkit's `"basic"` group alongside the workspace-derived tools, so tool availability can vary per caller (per-tenant integrations, user-specific credentials). - Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/versions/2.0.4/en/deploy/agent-team#custom-sub-agent-types) for details. + Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/agentscope/2.0.4/en/deploy/agent-team#custom-sub-agent-types) for details. A custom `Agent` subclass to instantiate on every chat turn instead of the built-in `Agent`. Use this to swap in an agent implementation with different reasoning behaviour while keeping the rest of the service unchanged. @@ -261,7 +261,7 @@ Once the server is running, drive it through the resources defined in the resour ``` - Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/versions/2.0.4/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. + Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/agentscope/2.0.4/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. ```http POST /workspace/mcp @@ -386,7 +386,7 @@ The service is open at every infrastructure boundary. The sections below describ ### Agent chat protocol -The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/versions/2.0.4/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. +The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/agentscope/2.0.4/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. AgentScope ships with `AGUIProtocolMiddleware` for the [AG-UI](https://docs.ag-ui.com/) protocol. Install it via `extra_middlewares`: @@ -742,16 +742,16 @@ Routers receive application state through FastAPI's `Depends()`. The standard in ## Further Reading - + Core agent abstraction and the ReAct loop - + Event streaming and message reconstruction - + Built-in and custom tools including external execution - + Context compression and workspace offloading diff --git a/versions/2.0.4/en/deploy/agent-team.mdx b/agentscope/2.0.4/en/deploy/agent-team.mdx similarity index 88% rename from versions/2.0.4/en/deploy/agent-team.mdx rename to agentscope/2.0.4/en/deploy/agent-team.mdx index 2b87c20..fd4e1c1 100644 --- a/versions/2.0.4/en/deploy/agent-team.mdx +++ b/agentscope/2.0.4/en/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "Agent Team" description: "Leader agents that spawn and coordinate worker agents through built-in team tools" --- -Agent Team is the multi-agent layer built on top of [Agent Service](/versions/2.0.4/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. +Agent Team is the multi-agent layer built on top of [Agent Service](/agentscope/2.0.4/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. ## Quickstart -The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/versions/2.0.4/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. +The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/agentscope/2.0.4/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. Agent team coordination demo @@ -147,7 +147,7 @@ A leader session is automatically given these tools. Workers see only `TeamSay`. ### Coordination model -Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/versions/2.0.4/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. +Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/agentscope/2.0.4/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. Team communication reuses the same inbox + wakeup primitives the service uses for scheduled fires and background-tool completions: @@ -161,10 +161,10 @@ This means workers run *concurrently* on the same service — they are not neste ## See also - + The hosting layer that powers teams — sessions, message bus, workspace lifecycle. - + The agent abstraction each team member runs. diff --git a/versions/2.0.4/en/deploy/openapi.json b/agentscope/2.0.4/en/deploy/openapi.json similarity index 100% rename from versions/2.0.4/en/deploy/openapi.json rename to agentscope/2.0.4/en/deploy/openapi.json diff --git a/versions/2.0.3/en/deploy/rag.mdx b/agentscope/2.0.4/en/deploy/rag.mdx similarity index 96% rename from versions/2.0.3/en/deploy/rag.mdx rename to agentscope/2.0.4/en/deploy/rag.mdx index 83f06cd..535f334 100644 --- a/versions/2.0.3/en/deploy/rag.mdx +++ b/agentscope/2.0.4/en/deploy/rag.mdx @@ -3,7 +3,7 @@ title: "RAG Service" description: "A one-click multi-tenant, distributed RAG service" --- -The [RAG](/versions/2.0.3/en/building-blocks/rag) chapter covers the extension points and library-mode usage of AgentScope's RAG module. This chapter introduces the **multi-tenant, distribution-ready** RAG service layer included in the Agent Service. Building on top of those building blocks, the service layer provides the following capabilities around "multi-tenancy", "distribution", and "easy onboarding": +The [RAG](/agentscope/2.0.4/en/building-blocks/rag) chapter covers the extension points and library-mode usage of AgentScope's RAG module. This chapter introduces the **multi-tenant, distribution-ready** RAG service layer included in the Agent Service. Building on top of those building blocks, the service layer provides the following capabilities around "multi-tenancy", "distribution", and "easy onboarding": | Capability | Description | |------|------| @@ -424,16 +424,16 @@ Upload and search both go through the **same** knowledge base handle — the ser ## Further Reading - + Learn the atomic interfaces of parser / chunker / vector store / middleware and their library-mode usage. - + `create_app`'s global parameters, lifespan, dependency injection, and ASGI middleware layer. - + Which hooks `RAGMiddleware` uses to inject retrieval results. - + Embedding-model cards and dimension constraints decide which models a knowledge base can pick. diff --git a/versions/2.0.3/en/index.mdx b/agentscope/2.0.4/en/index.mdx similarity index 76% rename from versions/2.0.3/en/index.mdx rename to agentscope/2.0.4/en/index.mdx index 9f488ec..caa6a4f 100644 --- a/versions/2.0.3/en/index.mdx +++ b/agentscope/2.0.4/en/index.mdx @@ -20,19 +20,19 @@ AgentScope 2.0 is a production-ready agent framework built for security, efficie From reasoning agent to enterprise deployment, AgentScope covers the full agent development lifecycle. - + Autonomous agent with ReAct reasoning and tool execution. Built-in human-in-the-loop oversight and efficient tool orchestration. - + Agent self-managed tool system with Python functions, MCP and skills integration. - + Compression, offload and agentic retrieval for context management and long-term memory. Third-party integration with Mem0, ReMe and other vector databases. - + Tool execution in isolated environments (local filesystem, Docker, E2B, K8s, etc.) with multi-granularity isolation at user, agent, and session levels. - + One-click start of a production-ready backend with multi-tenant, multi-session management and distributed deployment, plus a frontend UI and development SDK. \ No newline at end of file diff --git a/versions/2.0.4/en/others/change-log.mdx b/agentscope/2.0.4/en/others/change-log.mdx similarity index 100% rename from versions/2.0.4/en/others/change-log.mdx rename to agentscope/2.0.4/en/others/change-log.mdx diff --git a/versions/2.0.2/en/others/faq.mdx b/agentscope/2.0.4/en/others/faq.mdx similarity index 87% rename from versions/2.0.2/en/others/faq.mdx rename to agentscope/2.0.4/en/others/faq.mdx index ddd57b8..97cbe65 100644 --- a/versions/2.0.2/en/others/faq.mdx +++ b/agentscope/2.0.4/en/others/faq.mdx @@ -14,14 +14,14 @@ description: "Frequently asked questions about AgentScope v2.0" Yes. The **workspace** abstraction is AgentScope's execution environment for agents and ships three implementations — `LocalWorkspace` (host filesystem), `DockerWorkspace` (container), and `E2BWorkspace` (E2B cloud sandbox) — sharing the same interface so the same agent code runs against any backend. Workspaces also own MCP server lifecycles, skill management, and context offloading. - See [Workspace](/versions/2.0.2/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. + See [Workspace](/agentscope/2.0.4/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. Yes, on two layers: - **TypeScript SDK** — install with `pnpm install @agentscope-ai/agentscope`. It mirrors the Python `Msg` and `Event` types so frontend code can consume agent streams without re-implementing the protocol. - - **Frontend UI** — a ready-to-use web app for [Agent Service](/versions/2.0.2/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. + - **Frontend UI** — a ready-to-use web app for [Agent Service](/agentscope/2.0.4/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. diff --git a/versions/2.0.4/en/quickstart.mdx b/agentscope/2.0.4/en/quickstart.mdx similarity index 100% rename from versions/2.0.4/en/quickstart.mdx rename to agentscope/2.0.4/en/quickstart.mdx diff --git a/versions/2.0.4/en/release-notes.mdx b/agentscope/2.0.4/en/release-notes.mdx similarity index 99% rename from versions/2.0.4/en/release-notes.mdx rename to agentscope/2.0.4/en/release-notes.mdx index 2d37f91..6d4e55e 100644 --- a/versions/2.0.4/en/release-notes.mdx +++ b/agentscope/2.0.4/en/release-notes.mdx @@ -355,7 +355,7 @@ For the full commit-level history and contributor list, see the [GitHub releases **Tool** - **Built-in tools rebuilt on `ToolBase`**: brand-new `_bash`, `_edit`, `_glob`, `_grep`, `_read`, and `_write` implementations, plus `_meta` and `_constants`, all sharing the new tool base class. ([#1502](https://github.com/agentscope-ai/agentscope/pull/1502)) -- **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/versions/2.0.4/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) +- **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/agentscope/2.0.4/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) - **Tool + Workspace integration**: the toolkit and the workspace module are now wired into the `Agent` class so file/shell tools execute inside the agent's workspace. ([#1642](https://github.com/agentscope-ai/agentscope/pull/1642)) **Workspace** diff --git a/versions/2.0.4/zh/building-blocks/agent.mdx b/agentscope/2.0.4/zh/building-blocks/agent.mdx similarity index 99% rename from versions/2.0.4/zh/building-blocks/agent.mdx rename to agentscope/2.0.4/zh/building-blocks/agent.mdx index 4b89379..678dbb5 100644 --- a/versions/2.0.4/zh/building-blocks/agent.mdx +++ b/agentscope/2.0.4/zh/building-blocks/agent.mdx @@ -492,10 +492,10 @@ asyncio.run(main()) ## 延伸阅读 - + 控制智能体可以调用哪些工具以及在什么条件下调用。 - + 在 reply、reasoning、acting 和 model call 钩子处拦截和修改智能体行为。 diff --git a/versions/2.0.4/zh/building-blocks/context.mdx b/agentscope/2.0.4/zh/building-blocks/context.mdx similarity index 94% rename from versions/2.0.4/zh/building-blocks/context.mdx rename to agentscope/2.0.4/zh/building-blocks/context.mdx index d119fd1..62d3aaf 100644 --- a/versions/2.0.4/zh/building-blocks/context.mdx +++ b/agentscope/2.0.4/zh/building-blocks/context.mdx @@ -27,7 +27,7 @@ description: "管理智能体的上下文窗口，让长任务稳定运行" 每一层的构成方式： -1. **System prompt** —— 以创建智能体时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [中间件](/versions/2.0.4/zh/building-blocks/middleware) 钩子。 +1. **System prompt** —— 以创建智能体时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [中间件](/agentscope/2.0.4/zh/building-blocks/middleware) 钩子。 2. **Summary** —— 较早消息被压缩后的摘要；只有发生过压缩之后才存在。 3. **Context** —— 最近的、尚未压缩的消息（用户输入、assistant 回复、工具调用、工具结果）。 @@ -147,7 +147,7 @@ Offload 通过 `Offloader` 协议接入 —— 该协议是结构化的，仅有 | `offload_context(session_id, msgs)` | 持久化被压缩的消息；返回一个引用（例如文件路径） | | `offload_tool_result(session_id, tool_result)` | 持久化被截断的工具结果；返回一个引用 | -任何实现该协议的对象都可以传入智能体的 `offloader` 参数。AgentScope 的 [`workspace`](/versions/2.0.4/zh/building-blocks/workspace) 模块提供了开箱即用的实现： +任何实现该协议的对象都可以传入智能体的 `offloader` 参数。AgentScope 的 [`workspace`](/agentscope/2.0.4/zh/building-blocks/workspace) 模块提供了开箱即用的实现： ```python from agentscope.agent import Agent @@ -235,16 +235,16 @@ class S3Offloader: ## 延伸阅读 - + 内置的 offloader 实现，以及智能体的工作环境 - + ReAct 循环以及上下文如何在推理步骤间流转 - + 通过中间件钩子拦截模型调用与 system prompt 组装 - + 会被压缩处理的工具结果来源 diff --git a/versions/2.0.4/zh/building-blocks/long-term-memory.mdx b/agentscope/2.0.4/zh/building-blocks/long-term-memory.mdx similarity index 98% rename from versions/2.0.4/zh/building-blocks/long-term-memory.mdx rename to agentscope/2.0.4/zh/building-blocks/long-term-memory.mdx index 0f3a933..e378d3c 100644 --- a/versions/2.0.4/zh/building-blocks/long-term-memory.mdx +++ b/agentscope/2.0.4/zh/building-blocks/long-term-memory.mdx @@ -5,7 +5,7 @@ description: "基于智能体中间件实现的，跨会话长期记忆" **长期记忆** 是智能体跨会话保留信息的能力，包括用户偏好、历史决策，以及在会话中总结、凝练的知识或规则。 -AgentScope 通过 [智能体中间件](/versions/2.0.4/zh/building-blocks/middleware) 的形式实现不同长期记忆能力。每个长期记忆实现都是一个 `MiddlewareBase` 的子类，以非侵入式的方式完成记忆的注入、检索和写回。 +AgentScope 通过 [智能体中间件](/agentscope/2.0.4/zh/building-blocks/middleware) 的形式实现不同长期记忆能力。每个长期记忆实现都是一个 `MiddlewareBase` 的子类，以非侵入式的方式完成记忆的注入、检索和写回。 AgentScope 目前支持以下长期记忆，更多实现正在开发中： diff --git a/versions/2.0.4/zh/building-blocks/message-and-event.mdx b/agentscope/2.0.4/zh/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.4/zh/building-blocks/message-and-event.mdx rename to agentscope/2.0.4/zh/building-blocks/message-and-event.mdx index 8e79d31..04592cc 100644 --- a/versions/2.0.4/zh/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.4/zh/building-blocks/message-and-event.mdx @@ -646,10 +646,10 @@ async for event in agent.reply_stream(UserMsg("user", "帮我修复这个 bug")) ## 延伸阅读 - + 智能体如何在 ReAct 循环中产出事件和消息 - + 消息如何存储、压缩和卸载 diff --git a/versions/2.0.4/zh/building-blocks/middleware.mdx b/agentscope/2.0.4/zh/building-blocks/middleware.mdx similarity index 98% rename from versions/2.0.4/zh/building-blocks/middleware.mdx rename to agentscope/2.0.4/zh/building-blocks/middleware.mdx index 4bca871..bf3cdd9 100644 --- a/versions/2.0.4/zh/building-blocks/middleware.mdx +++ b/agentscope/2.0.4/zh/building-blocks/middleware.mdx @@ -20,7 +20,7 @@ AgentScope 暴露了 6 个 hook 位置外加一个工具提供 hook，覆盖了 | `list_tools` | Tool source | 可选。返回中间件贡献的 `list[ToolBase]`。**不会被自动调用** —— 由组装智能体 toolkit 的调用方决定是否调用以及如何合并结果。 | -以上 hook 均作用于**智能体**层面。若需要在单个工具实例上挂钩 —— 无论该工具是在智能体内部还是外部被调用 —— 请参见[工具中间件](/versions/2.0.4/zh/building-blocks/tool#工具中间件)。 +以上 hook 均作用于**智能体**层面。若需要在单个工具实例上挂钩 —— 无论该工具是在智能体内部还是外部被调用 —— 请参见[工具中间件](/agentscope/2.0.4/zh/building-blocks/tool#工具中间件)。 三种类型的差别： @@ -296,11 +296,11 @@ DataBlockEndEvent ### 长期记忆 -AgentScope 以中间件的形式支持长期记忆，让智能体能够在多个会话间持久保存并调取信息。详见 [长期记忆](/versions/2.0.4/zh/building-blocks/long-term-memory) 章节。 +AgentScope 以中间件的形式支持长期记忆，让智能体能够在多个会话间持久保存并调取信息。详见 [长期记忆](/agentscope/2.0.4/zh/building-blocks/long-term-memory) 章节。 ### RAG -AgentScope 中知识库同样以中间件形式提供，允许智能体在推理时访问外部知识库。详见 [RAG](/versions/2.0.4/zh/building-blocks/rag) 章节。 +AgentScope 中知识库同样以中间件形式提供，允许智能体在推理时访问外部知识库。详见 [RAG](/agentscope/2.0.4/zh/building-blocks/rag) 章节。 ## 自定义中间件 diff --git a/versions/2.0.4/zh/building-blocks/model.mdx b/agentscope/2.0.4/zh/building-blocks/model.mdx similarity index 99% rename from versions/2.0.4/zh/building-blocks/model.mdx rename to agentscope/2.0.4/zh/building-blocks/model.mdx index a5d9969..59b06e8 100644 --- a/versions/2.0.4/zh/building-blocks/model.mdx +++ b/agentscope/2.0.4/zh/building-blocks/model.mdx @@ -663,7 +663,7 @@ asyncio.run(main()) ### 与 Agent 集成 -在 agent 层，TTS 通过 [`TTSMiddleware`](/versions/2.0.4/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： +在 agent 层，TTS 通过 [`TTSMiddleware`](/agentscope/2.0.4/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： ```python from agentscope.agent import Agent diff --git a/versions/2.0.4/zh/building-blocks/permission-system.mdx b/agentscope/2.0.4/zh/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.4/zh/building-blocks/permission-system.mdx rename to agentscope/2.0.4/zh/building-blocks/permission-system.mdx diff --git a/versions/2.0.4/zh/building-blocks/plan.mdx b/agentscope/2.0.4/zh/building-blocks/plan.mdx similarity index 96% rename from versions/2.0.4/zh/building-blocks/plan.mdx rename to agentscope/2.0.4/zh/building-blocks/plan.mdx index d205864..7ff88f3 100644 --- a/versions/2.0.4/zh/building-blocks/plan.mdx +++ b/agentscope/2.0.4/zh/building-blocks/plan.mdx @@ -198,5 +198,5 @@ agent.state.tasks_context.tasks.clear() ## 延伸阅读 -- [Tool](/versions/2.0.4/zh/building-blocks/tool) —— toolkit、`ToolBase` 接口，以及状态注入式工具如何拿到 `AgentState`。 -- [Agent](/versions/2.0.4/zh/building-blocks/agent) —— 智能体生命周期，包括 `AgentState` 的创建、恢复与持久化。 +- [Tool](/agentscope/2.0.4/zh/building-blocks/tool) —— toolkit、`ToolBase` 接口，以及状态注入式工具如何拿到 `AgentState`。 +- [Agent](/agentscope/2.0.4/zh/building-blocks/agent) —— 智能体生命周期，包括 `AgentState` 的创建、恢复与持久化。 diff --git a/versions/2.0.4/zh/building-blocks/rag.mdx b/agentscope/2.0.4/zh/building-blocks/rag.mdx similarity index 97% rename from versions/2.0.4/zh/building-blocks/rag.mdx rename to agentscope/2.0.4/zh/building-blocks/rag.mdx index 258b2a0..04381eb 100644 --- a/versions/2.0.4/zh/building-blocks/rag.mdx +++ b/agentscope/2.0.4/zh/building-blocks/rag.mdx @@ -16,7 +16,7 @@ AgentScope 中的 RAG 由如下**可独立替换**的功能模块组成： 本章主要介绍**在非服务化场景下**使用 RAG 功能，包括索引文件、检索知识、集成到智能体等。 -嵌入模型的介绍和配置方式请见[嵌入模型章节](/versions/2.0.4/zh/building-blocks/model)；服务化版本的 RAG（带 HTTP 服务、文件托管、分布式索引）请见 [RAG 服务](/versions/2.0.4/zh/deploy/rag)。 +嵌入模型的介绍和配置方式请见[嵌入模型章节](/agentscope/2.0.4/zh/building-blocks/model)；服务化版本的 RAG（带 HTTP 服务、文件托管、分布式索引）请见 [RAG 服务](/agentscope/2.0.4/zh/deploy/rag)。 ## 现有实现 @@ -46,7 +46,7 @@ PDF 与 PPT 解析依赖额外的第三方库，可以通过 `pip install agents ### 嵌入模型 -请见[嵌入模型章节](/versions/2.0.4/zh/building-blocks/model)。 +请见[嵌入模型章节](/agentscope/2.0.4/zh/building-blocks/model)。 ### 向量数据库 @@ -533,13 +533,13 @@ class MyVectorStore(VectorStoreBase): ## 延伸阅读 - + 多租户、分布式的 RAG 服务，支持 HTTP API、文件托管、向量数据库托管。 - + 了解 `RAGMiddleware` 是如何嵌入 reply / reasoning 钩子的。 - + 可用的嵌入模型及其参数。 diff --git a/versions/2.0.4/zh/building-blocks/tool.mdx b/agentscope/2.0.4/zh/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.4/zh/building-blocks/tool.mdx rename to agentscope/2.0.4/zh/building-blocks/tool.mdx index 9520692..a356ab6 100644 --- a/versions/2.0.4/zh/building-blocks/tool.mdx +++ b/agentscope/2.0.4/zh/building-blocks/tool.mdx @@ -126,7 +126,7 @@ bash = Bash( `check_permissions()` —— `Write` 与 `Edit` 共用同一权限逻辑： -1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/versions/2.0.4/zh/building-blocks/permission-system#safety-check-契约)。 +1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/agentscope/2.0.4/zh/building-blocks/permission-system#safety-check-契约)。 2. **ACCEPT_EDITS 模式** —— 自动放行配置工作目录内的文件操作 3. **PASSTHROUGH** —— 交给权限引擎做规则匹配 @@ -146,14 +146,14 @@ bash = Bash( 计划工具让智能体能够显式地维护一份结构化的任务清单，智能体可以通过工具调用来创建、查询和更新任务。计划相关的数据会被存储在智能体实例的 `agent.state.tasks_context` 中，所有计划相关的工具通过操作这个共享的状态来实现任务的管理。同时，所有计划相关的工具在权限检查中被默认放行。 -完整的任务生命周期、存储模型，以及如何以编程方式预置或自定义任务，请参见 [计划模式](/versions/2.0.4/zh/building-blocks/plan)。 +完整的任务生命周期、存储模型，以及如何以编程方式预置或自定义任务，请参见 [计划模式](/agentscope/2.0.4/zh/building-blocks/plan)。 ### 切换工具后端 AgentScope 中的 `Bash`，`Grep`，`Glob`，`Read`，`Write`，`Edit` 工具支持后端切换，即将运行逻辑委派到不同的执行环境中，例如本地文件系统，Docker 容器，E2B 沙箱等。 -通过指定 `backend` 参数即可切换后端，而 `backend` 实例可以通过 `Workspace` 实例获取，默认为本地环境。关于 `Workspace` 的更多信息，请参见 [工作空间](/versions/2.0.4/zh/building-blocks/workspace) 章节。 +通过指定 `backend` 参数即可切换后端，而 `backend` 实例可以通过 `Workspace` 实例获取，默认为本地环境。关于 `Workspace` 的更多信息，请参见 [工作空间](/agentscope/2.0.4/zh/building-blocks/workspace) 章节。 ```python title="切换到 Docker 后端" @@ -238,7 +238,7 @@ class WebSearch(ToolBase): 自定义工具时，有两个权限审查相关的逻辑需要注意： - **`check_read_only(tool_input)`**：当某次调用是否是只读取决于输入时，需要重新该函数（例如 `Bash`：`ls` 是只读，`rm` 不是）。该函数默认返回 `is_read_only` 静态属性。权限引擎在判定 EXPLORE / ACCEPT_EDITS 是否自动放行时调用。 -- **`PermissionDecision(..., bypass_immune=True)`**：在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/versions/2.0.4/zh/building-blocks/permission-system#safety-check-契约)。 +- **`PermissionDecision(..., bypass_immune=True)`**：在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/agentscope/2.0.4/zh/building-blocks/permission-system#safety-check-契约)。 ### 将函数包装为工具 @@ -279,7 +279,7 @@ toolkit = Toolkit(tools=[FunctionTool(get_weather)]) 外部执行工具把实际执行委派给智能体运行时之外 —— 通常是人工操作员或外部系统。智能体调用此类工具时会发出 `RequireExternalExecutionEvent` 事件并退出 `reply` / `reply_stream` 函数，直到结果通过 `ExternalExecutionResultEvent` 回传。 -这种模式是 [human-in-the-loop](/versions/2.0.4/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 +这种模式是 [human-in-the-loop](/agentscope/2.0.4/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 创建外部执行工具只需把 `is_external_tool` 设为 `True`，不必实现 `call` 函数： @@ -399,7 +399,7 @@ bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)]) ``` -**工具中间件 vs. 智能体中间件** —— 对属于工具本身的横切关注点（日志、metrics、重试），使用 `ToolMiddlewareBase`。若需要访问更广泛的智能体上下文 —— 权限决策、tool-call 事件或所在的 ReAct 轮次 —— 请使用 `MiddlewareBase.on_acting`。完整的智能体级钩子参考见 [Middleware](/versions/2.0.4/zh/building-blocks/middleware)。 +**工具中间件 vs. 智能体中间件** —— 对属于工具本身的横切关注点（日志、metrics、重试），使用 `ToolMiddlewareBase`。若需要访问更广泛的智能体上下文 —— 权限决策、tool-call 事件或所在的 ReAct 轮次 —— 请使用 `MiddlewareBase.on_acting`。完整的智能体级钩子参考见 [Middleware](/agentscope/2.0.4/zh/building-blocks/middleware)。 ## MCP @@ -583,16 +583,16 @@ toolkit = Toolkit( ## 延伸阅读 - + 智能体如何在 ReAct 循环中编排工具调用 - + 精细控制哪个工具可以执行、何时执行 - + 拦截智能体生命周期钩子 —— reply、reasoning、model 调用等 - + 外部执行工具与人工审批工作流 diff --git a/versions/2.0.2/zh/building-blocks/workspace.mdx b/agentscope/2.0.4/zh/building-blocks/workspace.mdx similarity index 92% rename from versions/2.0.2/zh/building-blocks/workspace.mdx rename to agentscope/2.0.4/zh/building-blocks/workspace.mdx index 6ee4507..1137c6d 100644 --- a/versions/2.0.2/zh/building-blocks/workspace.mdx +++ b/agentscope/2.0.4/zh/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "为 agent 提供工具、skill 与上下文 offload 的执行环 Workspace 是 agent 的执行环境，向 agent 提供三类资源 —— **工具**（内置 tool 与 MCP）、**skill**，以及面向压缩消息与超大工具结果的**上下文 offload** —— 同时管理其中资源（MCP server 进程、动态加入的 skill、offload 文件）的生命周期。 -AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/versions/2.0.2/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 +AgentScope 提供三种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/agentscope/2.0.4/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 对 Docker 与 E2B 而言，MCP server 跑在隔离环境*内部*；宿主侧通过 workspace 内的 gateway 访问它们，详见后文 [MCP Gateway](#mcp-gateway)。 @@ -177,7 +177,7 @@ toolkit = Toolkit( ## Workspace Manager -Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/versions/2.0.2/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 +Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/agentscope/2.0.4/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 Manager 的职责： @@ -220,10 +220,10 @@ ws = await manager.get_workspace( ) ``` -要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/versions/2.0.2/zh/deploy/agent-service#workspace-实现与隔离)。 +要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/agentscope/2.0.4/zh/deploy/agent-service#workspace-实现与隔离)。 -Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/versions/2.0.2/zh/deploy/agent-service)。 +Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/agentscope/2.0.4/zh/deploy/agent-service)。 ## MCP Gateway @@ -255,16 +255,16 @@ Gateway 暴露一组小型 REST 接口 —— `GET /health`、`GET/POST/DELETE / ## 延伸阅读 - + Agent 抽象、ReAct 循环与 offloader 集成 - + 内置 tool、MCP 集成与 toolkit 组装 - + 驱动 workspace manager 的多租户服务 - + 上下文压缩与 offload 触发条件 diff --git a/versions/2.0.4/zh/deploy/agent-service.mdx b/agentscope/2.0.4/zh/deploy/agent-service.mdx similarity index 97% rename from versions/2.0.4/zh/deploy/agent-service.mdx rename to agentscope/2.0.4/zh/deploy/agent-service.mdx index dc84c61..02be065 100644 --- a/versions/2.0.4/zh/deploy/agent-service.mdx +++ b/agentscope/2.0.4/zh/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "架构" description: "把智能体部署为多租户、多会话的 HTTP 服务" --- -智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/versions/2.0.4/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 +智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/agentscope/2.0.4/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 它的特点： @@ -16,7 +16,7 @@ description: "把智能体部署为多租户、多会话的 HTTP 服务" | 能力 | 说明 | |---------------------------------------------------|-----------------------------------------------------------------------------------------| -| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/versions/2.0.4/zh/deploy/agent-team) 章节。 | +| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/agentscope/2.0.4/zh/deploy/agent-team) 章节。 | | 工作区管理 | 可配置的工作区隔离粒度 —— `per_agent`（默认）、`per_session` 或 `per_user` —— 管理智能体的文件系统、MCP client 与 skill。 | | 知识库（RAG） | 可选的内置知识库服务，支持文档摄取、切片、embedding 与自然语言检索 —— 向 `create_app` 传入 `knowledge_base_manager` 即可启用。 | | 后台任务卸载（Background Task Offloading） | 长耗时工具调用切到后台执行，完成时通过会话事件流回送结果。 | @@ -216,7 +216,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) 异步工厂 `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]`，在每次组装智能体时被调用一次。返回的工具会与工作区派生的工具一起合并到 toolkit 的 `"basic"` 分组里，便于按调用者动态决定可用工具（例如按租户接入、按用户使用各自凭证的工具）。 - 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/versions/2.0.4/zh/deploy/agent-team#自定义子智能体类型)。 + 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/agentscope/2.0.4/zh/deploy/agent-team#自定义子智能体类型)。 自定义的 `Agent` 子类，用于替代内置 `Agent` 在每轮 chat 中被实例化。适合在保留其他服务组件不变的前提下换用具有不同推理行为的智能体实现。 @@ -260,7 +260,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) ``` - 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/versions/2.0.4/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 + 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/agentscope/2.0.4/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 ```http POST /workspace/mcp @@ -385,7 +385,7 @@ flowchart TB ### 智能体聊天协议 -按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/versions/2.0.4/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 +按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/agentscope/2.0.4/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 AgentScope 内置 `AGUIProtocolMiddleware` 适配 [AG-UI](https://docs.ag-ui.com/) 协议。通过 `extra_middlewares` 装载： @@ -741,16 +741,16 @@ Router 通过 FastAPI 的 `Depends()` 拿到应用状态。标准注入项（位 ## 延伸阅读 - + 核心智能体抽象与 ReAct 循环 - + 事件流与消息重建 - + 内置与自定义工具，包括外部执行 - + 上下文压缩与工作区 offloading diff --git a/versions/2.0.4/zh/deploy/agent-team.mdx b/agentscope/2.0.4/zh/deploy/agent-team.mdx similarity index 87% rename from versions/2.0.4/zh/deploy/agent-team.mdx rename to agentscope/2.0.4/zh/deploy/agent-team.mdx index 2e493fe..b1ec683 100644 --- a/versions/2.0.4/zh/deploy/agent-team.mdx +++ b/agentscope/2.0.4/zh/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "智能体团队" description: "Leader 智能体通过内置 team 工具派生并协调 worker 智能体" --- -智能体团队（Agent Team）是构建在[智能体服务](/versions/2.0.4/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 +智能体团队（Agent Team）是构建在[智能体服务](/agentscope/2.0.4/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 ## 快速上手 -随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/versions/2.0.4/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 +随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/agentscope/2.0.4/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 智能体团队协作演示 @@ -144,7 +144,7 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ### 协调模型 -智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/versions/2.0.4/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 +智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/agentscope/2.0.4/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 团队通信复用了服务用于调度触发与后台工具完成的同一组 inbox + wakeup 原语： @@ -158,10 +158,10 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ## 延伸阅读 - + 支撑团队的托管层 —— 会话、消息总线、工作区生命周期。 - + 每个团队成员所运行的智能体抽象。 diff --git a/versions/2.0.3/zh/deploy/rag.mdx b/agentscope/2.0.4/zh/deploy/rag.mdx similarity index 96% rename from versions/2.0.3/zh/deploy/rag.mdx rename to agentscope/2.0.4/zh/deploy/rag.mdx index ef06847..2ab9db8 100644 --- a/versions/2.0.3/zh/deploy/rag.mdx +++ b/agentscope/2.0.4/zh/deploy/rag.mdx @@ -3,7 +3,7 @@ title: "RAG 服务" description: "一键式启动的多租户、分布式 RAG 服务" --- -[RAG](/versions/2.0.3/zh/building-blocks/rag) 章节中介绍了 AgentScope 中的 RAG 模块的拓展和使用方法。本章介绍智能体服务（Agent service）中提供的**多租户、可分布式部署**的 RAG 服务层。服务层在 building blocks 的基础上，围绕「多租户」「分布式」「易接入」提供以下能力： +[RAG](/agentscope/2.0.4/zh/building-blocks/rag) 章节中介绍了 AgentScope 中的 RAG 模块的拓展和使用方法。本章介绍智能体服务（Agent service）中提供的**多租户、可分布式部署**的 RAG 服务层。服务层在 building blocks 的基础上，围绕「多租户」「分布式」「易接入」提供以下能力： | 能力 | 说明 | |------|------| @@ -424,16 +424,16 @@ parser 默认在事件循环线程内运行。如果引入 PDF / Office 等 CPU ## 延伸阅读 - + 了解 parser / chunker / vector store / middleware 的原子接口与 library 模式用法。 - + `create_app` 的全局参数、lifespan、依赖注入与 ASGI 中间件层。 - + `RAGMiddleware` 借助哪些钩子注入检索结果。 - + 嵌入模型卡 / 维度约束，决定知识库可选哪些模型。 diff --git a/versions/2.0.3/zh/index.mdx b/agentscope/2.0.4/zh/index.mdx similarity index 77% rename from versions/2.0.3/zh/index.mdx rename to agentscope/2.0.4/zh/index.mdx index a37c23d..599f85b 100644 --- a/versions/2.0.3/zh/index.mdx +++ b/agentscope/2.0.4/zh/index.mdx @@ -19,19 +19,19 @@ AgentScope 2.0 是一款安全、高效、灵活且完备的生产级智能体 从单智能体推理到复杂企业级应用，AgentScope 为开发者提供覆盖其完整生命周期的全栈支持。 - + 具备自主 ReAct 推理和多工具协同执行能力的智能体，内置人机协作审核与高并发工具调度机制。 - + 智能体自主管理的工具栈体系，支持原生 Python 函数、MCP（模型上下文协议）和多种外部技能（Skill）的无缝拼装。 - + 精细化的上下文剪裁、卸载与智能体主动检索，深度融合了 Mem0、ReMe 等第三方记忆实现。 - + 支持在物理隔离的安全环境（如本地隔离沙箱、Docker、E2B、Kubernetes 等）中安全执行外部代码，支持用户、智能体、会话三级精细隔离。 - + 一键部署的生产级后端，自带可视化前端与开发 SDK，多租户多会话并发与分布式集群调度触手可得。 diff --git a/versions/2.0.4/zh/others/change-log.mdx b/agentscope/2.0.4/zh/others/change-log.mdx similarity index 100% rename from versions/2.0.4/zh/others/change-log.mdx rename to agentscope/2.0.4/zh/others/change-log.mdx diff --git a/versions/2.0.3/zh/others/faq.mdx b/agentscope/2.0.4/zh/others/faq.mdx similarity index 84% rename from versions/2.0.3/zh/others/faq.mdx rename to agentscope/2.0.4/zh/others/faq.mdx index a8ee217..b2b0896 100644 --- a/versions/2.0.3/zh/others/faq.mdx +++ b/agentscope/2.0.4/zh/others/faq.mdx @@ -14,14 +14,14 @@ description: "AgentScope 2.0 常见问题" 支持。**Workspace** 是 AgentScope 为 agent 提供的执行环境抽象，内置三种实现 —— `LocalWorkspace`（宿主文件系统）、`DockerWorkspace`（容器）、`E2BWorkspace`（E2B 云沙箱），共享同一份接口，因此同一份 agent 代码可以无差别地在任意后端上运行。Workspace 同时负责管理 MCP server 生命周期、skill 与上下文 offload。 - 完整介绍见 [Workspace](/versions/2.0.3/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 + 完整介绍见 [Workspace](/agentscope/2.0.4/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 有，分两个层次： - **TypeScript SDK** —— 通过 `pnpm install @agentscope-ai/agentscope` 安装，对齐 Python 端的 `Msg` 与 `Event` 类型，前端无需重写协议即可消费 agent 的流式输出。 - - **前端 UI** —— 面向 [Agent Service](/versions/2.0.3/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 + - **前端 UI** —— 面向 [Agent Service](/agentscope/2.0.4/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 diff --git a/versions/2.0.4/zh/quickstart.mdx b/agentscope/2.0.4/zh/quickstart.mdx similarity index 100% rename from versions/2.0.4/zh/quickstart.mdx rename to agentscope/2.0.4/zh/quickstart.mdx diff --git a/versions/2.0.4/zh/release-notes.mdx b/agentscope/2.0.4/zh/release-notes.mdx similarity index 99% rename from versions/2.0.4/zh/release-notes.mdx rename to agentscope/2.0.4/zh/release-notes.mdx index 0970edb..cee8c53 100644 --- a/versions/2.0.4/zh/release-notes.mdx +++ b/agentscope/2.0.4/zh/release-notes.mdx @@ -355,7 +355,7 @@ description: "AgentScope 版本改动和更新日志。" **Tool** - **基于 `ToolBase` 重建内置工具**：全新的 `_bash`、`_edit`、`_glob`、`_grep`、`_read`、`_write` 实现，以及共享的 `_meta` 与 `_constants`，全部基于新的工具基类。([#1502](https://github.com/agentscope-ai/agentscope/pull/1502)) -- **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/versions/2.0.4/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) +- **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/agentscope/2.0.4/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) - **工具与 Workspace 集成**：工具包与 Workspace 模块被打通进 `Agent` 类，文件/Shell 工具现在统一在智能体的 Workspace 中执行。([#1642](https://github.com/agentscope-ai/agentscope/pull/1642)) **Workspace** diff --git a/versions/2.0.5dev/en/building-blocks/agent.mdx b/agentscope/2.0.5dev/en/building-blocks/agent.mdx similarity index 99% rename from versions/2.0.5dev/en/building-blocks/agent.mdx rename to agentscope/2.0.5dev/en/building-blocks/agent.mdx index 319e967..a1f3c7a 100644 --- a/versions/2.0.5dev/en/building-blocks/agent.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/agent.mdx @@ -478,10 +478,10 @@ asyncio.run(main()) ## Further Reading - + Control which tools the agent can call and under what conditions. - + Intercept and modify agent behavior at reply, reasoning, acting, and model call hooks. diff --git a/versions/2.0.5dev/en/building-blocks/context.mdx b/agentscope/2.0.5dev/en/building-blocks/context.mdx similarity index 94% rename from versions/2.0.5dev/en/building-blocks/context.mdx rename to agentscope/2.0.5dev/en/building-blocks/context.mdx index 0f7327e..f919e69 100644 --- a/versions/2.0.5dev/en/building-blocks/context.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/context.mdx @@ -27,7 +27,7 @@ Before each model call, the agent assembles a single API input from three layers How each layer is built: -1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/versions/2.0.5dev/en/building-blocks/middleware) hook in order. +1. **System prompt** — starts from the `system_prompt` passed at agent creation, then appends skill instructions (each skill's name and description, sourced from the toolkit), then runs every `on_system_prompt` [middleware](/agentscope/2.0.5dev/en/building-blocks/middleware) hook in order. 2. **Summary** — the compressed digest of older messages, present only after a compression has occurred. 3. **Context** — the recent uncompressed messages (user inputs, assistant responses, tool calls, tool results). @@ -148,7 +148,7 @@ Offloading is wired through the `Offloader` protocol — a structural contract w | `offload_context(session_id, msgs)` | Persist compressed messages; returns a reference (e.g. a file path) to the persisted content | | `offload_tool_result(session_id, tool_result)` | Persist a truncated tool result; returns a reference to the persisted content | -Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/versions/2.0.5dev/en/building-blocks/workspace) module ships ready-made implementations: +Pass any object satisfying this protocol to the agent's `offloader` argument. AgentScope's [`workspace`](/agentscope/2.0.5dev/en/building-blocks/workspace) module ships ready-made implementations: ```python from agentscope.agent import Agent @@ -236,16 +236,16 @@ Pass the instance into `Agent(offloader=...)` like any built-in workspace. ## Further Reading - + Built-in offloader implementations and the agent's working environment - + The ReAct loop and how context flows through reasoning steps - + Intercept model calls and system prompt composition with middleware hooks - + Tools that produce results subject to compression diff --git a/versions/2.0.5dev/en/building-blocks/long-term-memory.mdx b/agentscope/2.0.5dev/en/building-blocks/long-term-memory.mdx similarity index 98% rename from versions/2.0.5dev/en/building-blocks/long-term-memory.mdx rename to agentscope/2.0.5dev/en/building-blocks/long-term-memory.mdx index 2aaa0d4..14bea1a 100644 --- a/versions/2.0.5dev/en/building-blocks/long-term-memory.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/long-term-memory.mdx @@ -5,7 +5,7 @@ description: "Cross-session long-term memory implemented with agent middleware" **Long-term memory** is an agent's ability to retain information across sessions, including user preferences, past decisions, and knowledge or rules summarized from conversations. -AgentScope implements different long-term memory capabilities as [agent middleware](/versions/2.0.5dev/en/building-blocks/middleware). Each long-term memory implementation is a `MiddlewareBase` subclass that non-invasively handles memory injection, retrieval, and write-back. +AgentScope implements different long-term memory capabilities as [agent middleware](/agentscope/2.0.5dev/en/building-blocks/middleware). Each long-term memory implementation is a `MiddlewareBase` subclass that non-invasively handles memory injection, retrieval, and write-back. AgentScope currently supports the following long-term memory implementations, with more under development: diff --git a/versions/2.0.5dev/en/building-blocks/message-and-event.mdx b/agentscope/2.0.5dev/en/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.5dev/en/building-blocks/message-and-event.mdx rename to agentscope/2.0.5dev/en/building-blocks/message-and-event.mdx index adb4175..7cf78e4 100644 --- a/versions/2.0.5dev/en/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/message-and-event.mdx @@ -647,10 +647,10 @@ async for event in agent.reply_stream(UserMsg("user", "Fix the bug")): ## Further Reading - + How the agent produces events and messages in the ReAct loop - + How messages are stored, compressed, and offloaded \ No newline at end of file diff --git a/versions/2.0.5dev/en/building-blocks/middleware.mdx b/agentscope/2.0.5dev/en/building-blocks/middleware.mdx similarity index 98% rename from versions/2.0.5dev/en/building-blocks/middleware.mdx rename to agentscope/2.0.5dev/en/building-blocks/middleware.mdx index 9af20c1..bb3e638 100644 --- a/versions/2.0.5dev/en/building-blocks/middleware.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/middleware.mdx @@ -20,7 +20,7 @@ AgentScope exposes 6 hook positions plus a tool-provider hook, covering the full | `list_tools` | Tool source | Optional. Returns a `list[ToolBase]` that the middleware contributes. **Not invoked automatically** — the caller assembling the agent's toolkit decides whether to call it and how to merge the result. | -These hooks operate at the **agent** level. For per-tool onion hooks that fire on every invocation of a specific tool — regardless of whether it's called inside or outside an agent — see [Tool Middleware](/versions/2.0.5dev/en/building-blocks/tool#tool-middleware). +These hooks operate at the **agent** level. For per-tool onion hooks that fire on every invocation of a specific tool — regardless of whether it's called inside or outside an agent — see [Tool Middleware](/agentscope/2.0.5dev/en/building-blocks/tool#tool-middleware). The three types differ as follows: @@ -295,11 +295,11 @@ Each `DataBlockDeltaEvent.data` carries an incremental base64-encoded audio chun ### Long-Term Memory -AgentScope supports long-term memory as middleware, so agents can persist and recall information across sessions. See [Long-Term Memory](/versions/2.0.5dev/en/building-blocks/long-term-memory) for details. +AgentScope supports long-term memory as middleware, so agents can persist and recall information across sessions. See [Long-Term Memory](/agentscope/2.0.5dev/en/building-blocks/long-term-memory) for details. ### RAG -AgentScope also provides knowledge-base access through middleware, allowing agents to access external knowledge bases during reasoning. See [RAG](/versions/2.0.5dev/en/building-blocks/rag) for details. +AgentScope also provides knowledge-base access through middleware, allowing agents to access external knowledge bases during reasoning. See [RAG](/agentscope/2.0.5dev/en/building-blocks/rag) for details. ## Custom Middleware diff --git a/versions/2.0.5dev/en/building-blocks/model.mdx b/agentscope/2.0.5dev/en/building-blocks/model.mdx similarity index 99% rename from versions/2.0.5dev/en/building-blocks/model.mdx rename to agentscope/2.0.5dev/en/building-blocks/model.mdx index d41953e..0c79d32 100644 --- a/versions/2.0.5dev/en/building-blocks/model.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/model.mdx @@ -672,7 +672,7 @@ asyncio.run(main()) ### Integrate with Agent -In the agent layer, TTS is integrated via [`TTSMiddleware`](/versions/2.0.5dev/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: +In the agent layer, TTS is integrated via [`TTSMiddleware`](/agentscope/2.0.5dev/en/building-blocks/middleware#ttsmiddleware) — it intercepts the agent's text output and synthesizes speech automatically: ```python from agentscope.agent import Agent diff --git a/versions/2.0.5dev/en/building-blocks/permission-system.mdx b/agentscope/2.0.5dev/en/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.5dev/en/building-blocks/permission-system.mdx rename to agentscope/2.0.5dev/en/building-blocks/permission-system.mdx diff --git a/versions/2.0.5dev/en/building-blocks/plan.mdx b/agentscope/2.0.5dev/en/building-blocks/plan.mdx similarity index 96% rename from versions/2.0.5dev/en/building-blocks/plan.mdx rename to agentscope/2.0.5dev/en/building-blocks/plan.mdx index 15a6ee0..9938e5f 100644 --- a/versions/2.0.5dev/en/building-blocks/plan.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/plan.mdx @@ -198,5 +198,5 @@ The next agent turn will see an empty plan and start over. ## Further Reading -- [Tool](/versions/2.0.5dev/en/building-blocks/tool) — the toolkit, the `ToolBase` interface, and how state-injected tools receive `AgentState`. -- [Agent](/versions/2.0.5dev/en/building-blocks/agent) — the agent lifecycle, including how `AgentState` is created, restored, and persisted. +- [Tool](/agentscope/2.0.5dev/en/building-blocks/tool) — the toolkit, the `ToolBase` interface, and how state-injected tools receive `AgentState`. +- [Agent](/agentscope/2.0.5dev/en/building-blocks/agent) — the agent lifecycle, including how `AgentState` is created, restored, and persisted. diff --git a/versions/2.0.5dev/en/building-blocks/rag.mdx b/agentscope/2.0.5dev/en/building-blocks/rag.mdx similarity index 97% rename from versions/2.0.5dev/en/building-blocks/rag.mdx rename to agentscope/2.0.5dev/en/building-blocks/rag.mdx index e04ee1a..5486fef 100644 --- a/versions/2.0.5dev/en/building-blocks/rag.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/rag.mdx @@ -16,7 +16,7 @@ In AgentScope, RAG is composed of the following **independently replaceable** mo This chapter focuses on **using RAG in non-service scenarios** — indexing files, retrieving knowledge, and integrating with an agent. -For embedding models and how to configure them, see the [Embedding Model chapter](/versions/2.0.5dev/en/building-blocks/model); for the service version of RAG (with an HTTP service, file hosting, and distributed indexing), see [RAG Service](/versions/2.0.5dev/en/deploy/rag). +For embedding models and how to configure them, see the [Embedding Model chapter](/agentscope/2.0.5dev/en/building-blocks/model); for the service version of RAG (with an HTTP service, file hosting, and distributed indexing), see [RAG Service](/agentscope/2.0.5dev/en/deploy/rag). ## Existing Implementations @@ -46,7 +46,7 @@ The PDF and PPT parsers depend on additional third-party libraries; install them ### Embedding Model -See the [Embedding Model chapter](/versions/2.0.5dev/en/building-blocks/model). +See the [Embedding Model chapter](/agentscope/2.0.5dev/en/building-blocks/model). ### Vector Database @@ -534,13 +534,13 @@ Implementation notes: ## Further Reading - + A multi-tenant, distributed RAG service with HTTP API, file hosting, and managed vector databases. - + See how `RAGMiddleware` plugs into the reply / reasoning hooks. - + Available embedding models and their parameters. diff --git a/versions/2.0.5dev/en/building-blocks/tool.mdx b/agentscope/2.0.5dev/en/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.5dev/en/building-blocks/tool.mdx rename to agentscope/2.0.5dev/en/building-blocks/tool.mdx index abf91f5..87c8271 100644 --- a/versions/2.0.5dev/en/building-blocks/tool.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/tool.mdx @@ -126,7 +126,7 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the `check_permissions()` — `Write` and `Edit` share the same permission logic: -1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/versions/2.0.5dev/en/building-blocks/permission-system#safety-check-contract) for the full contract. +1. **Dangerous path protection** — operations on sensitive files (`.bashrc`, `.env`, `.ssh/`) return a bypass-immune ASK (`bypass_immune=True`), so allow rules cannot silently authorize them. The ASK is still skipped in `BYPASS` mode (which opts out of safety prompts by design) and converted to DENY in `DONT_ASK` mode. See the [permission system docs](/agentscope/2.0.5dev/en/building-blocks/permission-system#safety-check-contract) for the full contract. 2. **ACCEPT_EDITS mode** — auto-allows operations on files within configured working directories 3. **PASSTHROUGH** — falls through to the permission engine for rule matching @@ -146,14 +146,14 @@ The file tools enforce a read-before-write rule: `Write` and `Edit` require the The plan tools give the agent a structured task list it can append to, query, and update through normal tool calls. They share a single store on `agent.state.tasks_context`, are state-injected, and always pass permission checks — the agent treats them as free-cost coordination primitives for breaking complex work into trackable steps. -See [Plan](/versions/2.0.5dev/en/building-blocks/plan) for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically. +See [Plan](/agentscope/2.0.5dev/en/building-blocks/plan) for the full task lifecycle, the storage model, and how to seed or customize tasks programmatically. ### Switch Tool Backend The `Bash`, `Grep`, `Glob`, `Read`, `Write`, and `Edit` tools in AgentScope support backend switching — delegating their execution to different runtime environments such as the local filesystem, a Docker container, an E2B sandbox, and so on. -A backend is selected via the `backend` argument. Backend instances are obtained from a `Workspace`, which defaults to the local environment. See [Workspace](/versions/2.0.5dev/en/building-blocks/workspace) for more details. +A backend is selected via the `backend` argument. Backend instances are obtained from a `Workspace`, which defaults to the local environment. See [Workspace](/agentscope/2.0.5dev/en/building-blocks/workspace) for more details. ```python title="Switch to Docker backend" @@ -238,7 +238,7 @@ class WebSearch(ToolBase): Two extension hooks worth knowing about when writing custom tools with safety logic: - **`check_read_only(tool_input)`** — override when whether an invocation modifies state depends on the input (like `Bash`: `ls` is read-only, `rm` is not). Defaults to returning the static `is_read_only` attribute. The permission engine calls it before deciding EXPLORE / ACCEPT_EDITS auto-allow. -- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/versions/2.0.5dev/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. +- **`PermissionDecision(..., bypass_immune=True)`** — set on a returned ASK to mark it as a safety check that allow rules cannot silence (e.g. a `DeployTool` flagging `prod-*` targets). See the [safety check contract](/agentscope/2.0.5dev/en/building-blocks/permission-system#safety-check-contract) for per-mode handling. ### Wrap Function as Tool @@ -279,7 +279,7 @@ Wrapped functions default to `ASK` permission behavior — the user must explici An external execution tool delegates its actual execution outside the agent runtime — typically to a human operator or an external system. When the agent calls one, it emits a `RequireExternalExecutionEvent` and pauses until the result is delivered via `ExternalExecutionResultEvent`. -This pattern underlies the [human-in-the-loop](/versions/2.0.5dev/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. +This pattern underlies the [human-in-the-loop](/agentscope/2.0.5dev/en/building-blocks/agent) workflow, where certain actions require human approval or manual execution. To create an external execution tool, set `is_external_tool = True`. There is no need to implement `call`: @@ -399,7 +399,7 @@ bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)]) ``` -**Tool middleware vs. agent middleware** — use `ToolMiddlewareBase` for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use `MiddlewareBase.on_acting` when you need access to the broader agent context — permission decisions, the tool-call event, or the surrounding ReAct round. See [Middleware](/versions/2.0.5dev/en/building-blocks/middleware) for the full agent-level hook reference. +**Tool middleware vs. agent middleware** — use `ToolMiddlewareBase` for cross-cutting concerns that belong to the tool itself (logging, metrics, retry). Use `MiddlewareBase.on_acting` when you need access to the broader agent context — permission decisions, the tool-call event, or the surrounding ReAct round. See [Middleware](/agentscope/2.0.5dev/en/building-blocks/middleware) for the full agent-level hook reference. ## MCP @@ -583,16 +583,16 @@ The meta tool input represents the **final state** of all groups, not incrementa ## Further Reading - + How agents orchestrate tool calls in the ReAct loop - + Fine-grained control over which tools can execute and when - + Intercept agent lifecycle hooks — reply, reasoning, model calls, and more - + External execution tools and human approval workflows diff --git a/versions/2.0.5dev/en/building-blocks/workspace.mdx b/agentscope/2.0.5dev/en/building-blocks/workspace.mdx similarity index 93% rename from versions/2.0.5dev/en/building-blocks/workspace.mdx rename to agentscope/2.0.5dev/en/building-blocks/workspace.mdx index 99d48b4..5777421 100644 --- a/versions/2.0.5dev/en/building-blocks/workspace.mdx +++ b/agentscope/2.0.5dev/en/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "The execution environment that supplies tools, skills, and context A workspace is the agent's execution environment. It supplies the agent with three categories of resources — **tools** (built-in tools and MCPs), **skills**, and **context offloading** for compressed messages and oversized tool results — and owns the lifecycle of the resources living inside it (MCP server processes, dynamically added skills, offloaded files). -AgentScope ships four workspace implementations — local filesystem, Docker container, E2B cloud sandbox, and OpenSandbox sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/versions/2.0.5dev/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. +AgentScope ships four workspace implementations — local filesystem, Docker container, E2B cloud sandbox, and OpenSandbox sandbox — plus a **workspace manager** that allocates and tracks workspaces in [Agent Service](/agentscope/2.0.5dev/en/deploy/agent-service) so that multi-tenant deployments can map workspaces to users, agents, or sessions without rewriting the agent code. For Docker, E2B, and OpenSandbox, MCP servers run *inside* the isolated environment; the host reaches them through an in-workspace gateway covered in [MCP Gateway](#mcp-gateway). @@ -208,7 +208,7 @@ toolkit = Toolkit( ## Workspace Manager -A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/versions/2.0.5dev/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. +A workspace manager is the allocator and lifecycle owner for workspaces in a multi-tenant service. It is used by [Agent Service](/agentscope/2.0.5dev/en/deploy/agent-service) to map incoming requests to the right workspace instance and to release them on shutdown. A manager is responsible for: @@ -252,10 +252,10 @@ ws = await manager.get_workspace( ) ``` -To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/versions/2.0.5dev/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. +To plug a different isolation policy (per-user, per-session, or hybrid), subclass `WorkspaceManagerBase` and override `get_workspace` / `create_workspace` with your own keying — see [Agent Service · Workspace implementation and isolation](/agentscope/2.0.5dev/en/deploy/agent-service#workspace-implementation-and-isolation) for how the service wires a manager into the request lifecycle. -In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/versions/2.0.5dev/en/deploy/agent-service) for the full integration. +In the agent service, the workspace manager is bound to the FastAPI app state during the lifespan and shared across all requests; routers acquire workspaces through `get_workspace_manager` dependency injection. See [Agent Service](/agentscope/2.0.5dev/en/deploy/agent-service) for the full integration. ## MCP Gateway @@ -291,16 +291,16 @@ The gateway is **not** published on a host-reachable network port. Each host-to- ## Further Reading - + Agent abstraction, the ReAct loop, and offloader integration - + Built-in tools, MCP integration, and toolkit composition - + Multi-tenant service that drives the workspace manager - + Context compression and the offloading triggers diff --git a/versions/2.0.5dev/en/deploy/agent-service.mdx b/agentscope/2.0.5dev/en/deploy/agent-service.mdx similarity index 97% rename from versions/2.0.5dev/en/deploy/agent-service.mdx rename to agentscope/2.0.5dev/en/deploy/agent-service.mdx index 212913b..3098d76 100644 --- a/versions/2.0.5dev/en/deploy/agent-service.mdx +++ b/agentscope/2.0.5dev/en/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "Architecture" description: "Host your agent as a multi-tenant, multi-session HTTP service" --- -Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/versions/2.0.5dev/en/building-blocks/agent) can serve production traffic without being rewritten. +Agent Service is the FastAPI-based hosting layer that turns AgentScope agents into a **multi-tenant, multi-session HTTP service**. It owns everything *around* the agent — request routing, per-user resource lifecycle, session state, persistence, scheduling, and tool offloading — so that the agent code you wrote against [`Agent`](/agentscope/2.0.5dev/en/building-blocks/agent) can serve production traffic without being rewritten. What sets it apart: @@ -16,7 +16,7 @@ What sets it apart: | Capability | Description | |------------|-------------| -| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/versions/2.0.5dev/en/deploy/agent-team) chapter. | +| Agent teams | A leader agent spawns worker agents and coordinates them through built-in team tools; see the [Agent Team](/agentscope/2.0.5dev/en/deploy/agent-team) chapter. | | Workspace management | Configurable workspace isolation — `per_agent` (default), `per_session`, or `per_user` — for the agent's filesystem, MCP clients, and skills. | | Knowledge bases (RAG) | Optional built-in knowledge base service with document ingestion, chunking, embedding, and natural-language search — enabled by passing a `knowledge_base_manager` to `create_app`. | | Background task offloading | Long-running tool calls move to background; their results are delivered back through the session's event stream when they finish. | @@ -217,7 +217,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) Async factory `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]` invoked once per agent assembly. Returned tools are merged into the toolkit's `"basic"` group alongside the workspace-derived tools, so tool availability can vary per caller (per-tenant integrations, user-specific credentials). - Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/versions/2.0.5dev/en/deploy/agent-team#custom-sub-agent-types) for details. + Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. `"researcher"`, `"coder"`) with pre-configured system prompt, permission context, and task context. When registered, the `AgentCreate` tool exposes a `subagent_type` parameter so the leader agent can route to the appropriate template. See [Custom sub-agent types](/agentscope/2.0.5dev/en/deploy/agent-team#custom-sub-agent-types) for details. A custom `Agent` subclass to instantiate on every chat turn instead of the built-in `Agent`. Use this to swap in an agent implementation with different reasoning behaviour while keeping the rest of the service unchanged. @@ -261,7 +261,7 @@ Once the server is running, drive it through the resources defined in the resour ``` - Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/versions/2.0.5dev/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. + Attach MCP clients and skills to the session's workspace if the agent needs tools beyond its built-ins. Out of the box, every agent already has access to the workspace's built-in tools (filesystem, shell, search, …), task-planning tools, schedule and background-task controls, and — when the session is a team leader or member — the team coordination tools described in [Agent Team](/agentscope/2.0.5dev/en/deploy/agent-team). Anything you pass via `extra_agent_tools` in `create_app` is merged in alongside. ```http POST /workspace/mcp @@ -317,7 +317,7 @@ curl -X POST -H "X-User-ID: alice" \ ## Resource Model -Every operation in Agent Service is scoped to a `user_id` resolved from the request. Below that boundary, the service manages seven resource types — six persisted (left half of the diagram) plus the message bus that ties their runtime behavior together (right half). To let credentials, agents, or knowledge bases cross this boundary between users, see [Resource Sharing](/versions/2.0.5dev/en/deploy/sharing). +Every operation in Agent Service is scoped to a `user_id` resolved from the request. Below that boundary, the service manages seven resource types — six persisted (left half of the diagram) plus the message bus that ties their runtime behavior together (right half). To let credentials, agents, or knowledge bases cross this boundary between users, see [Resource Sharing](/agentscope/2.0.5dev/en/deploy/sharing). ```mermaid flowchart TB @@ -386,7 +386,7 @@ The service is open at every infrastructure boundary. The sections below describ ### Agent chat protocol -The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/versions/2.0.5dev/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. +The per-session stream endpoint (`GET /sessions/{id}/stream`) emits AgentScope's native [`AgentEvent`](/agentscope/2.0.5dev/en/building-blocks/message-and-event) stream over SSE. To serve the same agent under a different frontend protocol, install a protocol middleware that intercepts the SSE stream and rewrites each frame. AgentScope ships with `AGUIProtocolMiddleware` for the [AG-UI](https://docs.ag-ui.com/) protocol. Install it via `extra_middlewares`: @@ -742,16 +742,16 @@ Routers receive application state through FastAPI's `Depends()`. The standard in ## Further Reading - + Core agent abstraction and the ReAct loop - + Event streaming and message reconstruction - + Built-in and custom tools including external execution - + Context compression and workspace offloading diff --git a/versions/2.0.5dev/en/deploy/agent-team.mdx b/agentscope/2.0.5dev/en/deploy/agent-team.mdx similarity index 88% rename from versions/2.0.5dev/en/deploy/agent-team.mdx rename to agentscope/2.0.5dev/en/deploy/agent-team.mdx index 2ea8c6f..2e6e0b8 100644 --- a/versions/2.0.5dev/en/deploy/agent-team.mdx +++ b/agentscope/2.0.5dev/en/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "Agent Team" description: "Leader agents that spawn and coordinate worker agents through built-in team tools" --- -Agent Team is the multi-agent layer built on top of [Agent Service](/versions/2.0.5dev/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. +Agent Team is the multi-agent layer built on top of [Agent Service](/agentscope/2.0.5dev/en/deploy/agent-service). A leader agent — the session the user talks to — can spawn worker agents on demand and exchange messages with them, while every member is just another session with its own state, workspace binding, and event stream. The whole coordination story is expressed through four built-in tools rather than a separate orchestration framework. ## Quickstart -The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/versions/2.0.5dev/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. +The bundled [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) backend ships with the team tools enabled, and the matching [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) frontend renders team membership and per-worker streams out of the box. Follow the [Agent Service quickstart](/agentscope/2.0.5dev/en/deploy/agent-service#try-the-bundled-example) to boot both — once they are running, ask the leader agent to assemble a team and you will see it call `TeamCreate` / `AgentCreate` automatically, watch workers come online, and observe them exchange messages in the UI. Agent team coordination demo @@ -147,7 +147,7 @@ A leader session is automatically given these tools. Workers see only `TeamSay`. ### Coordination model -Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/versions/2.0.5dev/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. +Agent Team is designed for distributed deployments by default. All inter-member communication is mediated by the [message bus](/agentscope/2.0.5dev/en/deploy/agent-service#resource-model) — a Redis-backed abstraction — so leader and worker sessions can live in different processes or different nodes without any code change. The sender writes to the recipient's inbox; any wakeup dispatcher in the cluster can then claim the wakeup signal and drive that session on its own process. This is the same mechanism that powers scheduled fires and background-tool completions, which is why the team feature scales out the same way the rest of the service does. Team communication reuses the same inbox + wakeup primitives the service uses for scheduled fires and background-tool completions: @@ -161,10 +161,10 @@ This means workers run *concurrently* on the same service — they are not neste ## See also - + The hosting layer that powers teams — sessions, message bus, workspace lifecycle. - + The agent abstraction each team member runs. diff --git a/versions/2.0.5dev/en/deploy/openapi.json b/agentscope/2.0.5dev/en/deploy/openapi.json similarity index 100% rename from versions/2.0.5dev/en/deploy/openapi.json rename to agentscope/2.0.5dev/en/deploy/openapi.json diff --git a/versions/2.0.5dev/en/deploy/rag.mdx b/agentscope/2.0.5dev/en/deploy/rag.mdx similarity index 96% rename from versions/2.0.5dev/en/deploy/rag.mdx rename to agentscope/2.0.5dev/en/deploy/rag.mdx index 5d8f7dd..17081c1 100644 --- a/versions/2.0.5dev/en/deploy/rag.mdx +++ b/agentscope/2.0.5dev/en/deploy/rag.mdx @@ -3,7 +3,7 @@ title: "RAG Service" description: "A one-click multi-tenant, distributed RAG service" --- -The [RAG](/versions/2.0.5dev/en/building-blocks/rag) chapter covers the extension points and library-mode usage of AgentScope's RAG module. This chapter introduces the **multi-tenant, distribution-ready** RAG service layer included in the Agent Service. Building on top of those building blocks, the service layer provides the following capabilities around "multi-tenancy", "distribution", and "easy onboarding": +The [RAG](/agentscope/2.0.5dev/en/building-blocks/rag) chapter covers the extension points and library-mode usage of AgentScope's RAG module. This chapter introduces the **multi-tenant, distribution-ready** RAG service layer included in the Agent Service. Building on top of those building blocks, the service layer provides the following capabilities around "multi-tenancy", "distribution", and "easy onboarding": | Capability | Description | |------|------| @@ -424,16 +424,16 @@ Upload and search both go through the **same** knowledge base handle — the ser ## Further Reading - + Learn the atomic interfaces of parser / chunker / vector store / middleware and their library-mode usage. - + `create_app`'s global parameters, lifespan, dependency injection, and ASGI middleware layer. - + Which hooks `RAGMiddleware` uses to inject retrieval results. - + Embedding-model cards and dimension constraints decide which models a knowledge base can pick. diff --git a/versions/2.0.5dev/en/deploy/sharing.mdx b/agentscope/2.0.5dev/en/deploy/sharing.mdx similarity index 95% rename from versions/2.0.5dev/en/deploy/sharing.mdx rename to agentscope/2.0.5dev/en/deploy/sharing.mdx index 5d33573..88c0264 100644 --- a/versions/2.0.5dev/en/deploy/sharing.mdx +++ b/agentscope/2.0.5dev/en/deploy/sharing.mdx @@ -6,7 +6,7 @@ tag: "NEW" Resource sharing makes one user's **credentials**, **agents**, and **knowledge bases** visible (usable) or editable to other users. -By default, the Agent Service in AgentScope is strictly isolated per tenant — no user can see another user's records (see [Resource Model](/versions/2.0.5dev/en/deploy/agent-service#resource-model)). Resource sharing is the sanctioned way to share resources while keeping data secure. +By default, the Agent Service in AgentScope is strictly isolated per tenant — no user can see another user's records (see [Resource Model](/agentscope/2.0.5dev/en/deploy/agent-service#resource-model)). Resource sharing is the sanctioned way to share resources while keeping data secure. Typical scenarios include: @@ -195,7 +195,7 @@ Views returned to a viewer carry an `editable` flag computed from the ref's perm -Sharing an agent shares its **configuration** — display name, system prompt, and context / ReAct settings — but **not its workspace content**. MCP client setups, skills, and accumulated memory (`MEMORY.md`) live in the per-user [workspace](/versions/2.0.5dev/en/deploy/workspace-manager), which is provisioned fresh per viewer, so a shared agent starts from a clean workspace for each user rather than inheriting the owner's tools and memory. +Sharing an agent shares its **configuration** — display name, system prompt, and context / ReAct settings — but **not its workspace content**. MCP client setups, skills, and accumulated memory (`MEMORY.md`) live in the per-user [workspace](/agentscope/2.0.5dev/en/deploy/workspace-manager), which is provisioned fresh per viewer, so a shared agent starts from a clean workspace for each user rather than inheriting the owner's tools and memory. Sharing this workspace-resident state is a known gap we are actively working on; follow the tracking issue on GitHub for progress. diff --git a/versions/2.0.5dev/en/deploy/workspace-manager.mdx b/agentscope/2.0.5dev/en/deploy/workspace-manager.mdx similarity index 95% rename from versions/2.0.5dev/en/deploy/workspace-manager.mdx rename to agentscope/2.0.5dev/en/deploy/workspace-manager.mdx index 60278ca..462f69b 100644 --- a/versions/2.0.5dev/en/deploy/workspace-manager.mdx +++ b/agentscope/2.0.5dev/en/deploy/workspace-manager.mdx @@ -4,7 +4,7 @@ description: "Manage the lifecycle of agent harness workspace" tag: "NEW" --- -The **workspace manager** owns the isolation policy and lifecycle of the [`Workspace`](/versions/2.0.5dev/en/building-blocks/workspace) instances the Agent Service hands to each agent. It is the service-side counterpart of the `agentscope.workspace` module: for every workspace subclass there is one matching manager class that provisions, caches, and evicts it. +The **workspace manager** owns the isolation policy and lifecycle of the [`Workspace`](/agentscope/2.0.5dev/en/building-blocks/workspace) instances the Agent Service hands to each agent. It is the service-side counterpart of the `agentscope.workspace` module: for every workspace subclass there is one matching manager class that provisions, caches, and evicts it. Highlights: @@ -22,7 +22,7 @@ Highlights: | `K8sWorkspaceManager` | One Pod + PVC per workspace on a Kubernetes cluster. Fits production clusters where you already run other workloads. | -For an in-depth look at what a workspace *is* (filesystem layout, gateway, MCP wiring, builtin tools), see the [Workspace](/versions/2.0.5dev/en/building-blocks/workspace) building-block chapter. +For an in-depth look at what a workspace *is* (filesystem layout, gateway, MCP wiring, builtin tools), see the [Workspace](/agentscope/2.0.5dev/en/building-blocks/workspace) building-block chapter. ## Integrate with Agent Service @@ -262,7 +262,7 @@ Every manager implements the following contract from `WorkspaceManagerBase`. Cus ## Custom manager -Any workspace class you build against [`WorkspaceBase`](/versions/2.0.5dev/en/building-blocks/workspace) can be surfaced to the Agent Service by pairing it with a `WorkspaceManagerBase` subclass. In most cases you only need to fill in a small provisioning + cache scaffold — the isolation policy is inherited. +Any workspace class you build against [`WorkspaceBase`](/agentscope/2.0.5dev/en/building-blocks/workspace) can be surfaced to the Agent Service by pairing it with a `WorkspaceManagerBase` subclass. In most cases you only need to fill in a small provisioning + cache scaffold — the isolation policy is inherited. ```python Custom manager import asyncio diff --git a/versions/2.0.5dev/en/index.mdx b/agentscope/2.0.5dev/en/index.mdx similarity index 75% rename from versions/2.0.5dev/en/index.mdx rename to agentscope/2.0.5dev/en/index.mdx index 4833a9a..bfaaca8 100644 --- a/versions/2.0.5dev/en/index.mdx +++ b/agentscope/2.0.5dev/en/index.mdx @@ -20,19 +20,19 @@ AgentScope 2.0 is a production-ready agent framework built for security, efficie From reasoning agent to enterprise deployment, AgentScope covers the full agent development lifecycle. - + Autonomous agent with ReAct reasoning and tool execution. Built-in human-in-the-loop oversight and efficient tool orchestration. - + Agent self-managed tool system with Python functions, MCP and skills integration. - + Compression, offload and agentic retrieval for context management and long-term memory. Third-party integration with Mem0, ReMe and other vector databases. - + Tool execution in isolated environments (local filesystem, Docker, E2B, K8s, etc.) with multi-granularity isolation at user, agent, and session levels. - + One-click start of a production-ready backend with multi-tenant, multi-session management and distributed deployment, plus a frontend UI and development SDK. \ No newline at end of file diff --git a/versions/2.0.5dev/en/others/change-log.mdx b/agentscope/2.0.5dev/en/others/change-log.mdx similarity index 100% rename from versions/2.0.5dev/en/others/change-log.mdx rename to agentscope/2.0.5dev/en/others/change-log.mdx diff --git a/versions/2.0.5dev/en/others/faq.mdx b/agentscope/2.0.5dev/en/others/faq.mdx similarity index 87% rename from versions/2.0.5dev/en/others/faq.mdx rename to agentscope/2.0.5dev/en/others/faq.mdx index d143d88..f7f2ffa 100644 --- a/versions/2.0.5dev/en/others/faq.mdx +++ b/agentscope/2.0.5dev/en/others/faq.mdx @@ -14,14 +14,14 @@ description: "Frequently asked questions about AgentScope v2.0" Yes. The **workspace** abstraction is AgentScope's execution environment for agents and ships three implementations — `LocalWorkspace` (host filesystem), `DockerWorkspace` (container), and `E2BWorkspace` (E2B cloud sandbox) — sharing the same interface so the same agent code runs against any backend. Workspaces also own MCP server lifecycles, skill management, and context offloading. - See [Workspace](/versions/2.0.5dev/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. + See [Workspace](/agentscope/2.0.5dev/en/building-blocks/workspace) for the full overview, including how to plug a workspace into an `Agent` and the multi-tenant `WorkspaceManager`. Yes, on two layers: - **TypeScript SDK** — install with `pnpm install @agentscope-ai/agentscope`. It mirrors the Python `Msg` and `Event` types so frontend code can consume agent streams without re-implementing the protocol. - - **Frontend UI** — a ready-to-use web app for [Agent Service](/versions/2.0.5dev/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. + - **Frontend UI** — a ready-to-use web app for [Agent Service](/agentscope/2.0.5dev/en/deploy/agent-service), letting developers exercise their deployed agents without writing any UI code. diff --git a/versions/2.0.5dev/en/quickstart.mdx b/agentscope/2.0.5dev/en/quickstart.mdx similarity index 100% rename from versions/2.0.5dev/en/quickstart.mdx rename to agentscope/2.0.5dev/en/quickstart.mdx diff --git a/versions/2.0.5dev/en/release-notes.mdx b/agentscope/2.0.5dev/en/release-notes.mdx similarity index 99% rename from versions/2.0.5dev/en/release-notes.mdx rename to agentscope/2.0.5dev/en/release-notes.mdx index 9470bf2..dff6f87 100644 --- a/versions/2.0.5dev/en/release-notes.mdx +++ b/agentscope/2.0.5dev/en/release-notes.mdx @@ -355,7 +355,7 @@ For the full commit-level history and contributor list, see the [GitHub releases **Tool** - **Built-in tools rebuilt on `ToolBase`**: brand-new `_bash`, `_edit`, `_glob`, `_grep`, `_read`, and `_write` implementations, plus `_meta` and `_constants`, all sharing the new tool base class. ([#1502](https://github.com/agentscope-ai/agentscope/pull/1502)) -- **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/versions/2.0.5dev/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) +- **Task tools** added: `TaskCreate`, `TaskGet`, `TaskList`, and `TaskUpdate` (see the [Plan](/agentscope/2.0.5dev/en/building-blocks/plan) page). ([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) - **Tool + Workspace integration**: the toolkit and the workspace module are now wired into the `Agent` class so file/shell tools execute inside the agent's workspace. ([#1642](https://github.com/agentscope-ai/agentscope/pull/1642)) **Workspace** diff --git a/versions/2.0.5dev/zh/building-blocks/agent.mdx b/agentscope/2.0.5dev/zh/building-blocks/agent.mdx similarity index 99% rename from versions/2.0.5dev/zh/building-blocks/agent.mdx rename to agentscope/2.0.5dev/zh/building-blocks/agent.mdx index 2ce1557..cd40a55 100644 --- a/versions/2.0.5dev/zh/building-blocks/agent.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/agent.mdx @@ -492,10 +492,10 @@ asyncio.run(main()) ## 延伸阅读 - + 控制智能体可以调用哪些工具以及在什么条件下调用。 - + 在 reply、reasoning、acting 和 model call 钩子处拦截和修改智能体行为。 diff --git a/versions/2.0.5dev/zh/building-blocks/context.mdx b/agentscope/2.0.5dev/zh/building-blocks/context.mdx similarity index 94% rename from versions/2.0.5dev/zh/building-blocks/context.mdx rename to agentscope/2.0.5dev/zh/building-blocks/context.mdx index f50078c..d354407 100644 --- a/versions/2.0.5dev/zh/building-blocks/context.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/context.mdx @@ -27,7 +27,7 @@ description: "管理智能体的上下文窗口，让长任务稳定运行" 每一层的构成方式： -1. **System prompt** —— 以创建智能体时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [中间件](/versions/2.0.5dev/zh/building-blocks/middleware) 钩子。 +1. **System prompt** —— 以创建智能体时传入的 `system_prompt` 为起点，拼接 skill 指令（每个 skill 的名称与描述，来自 toolkit），再依次执行所有 `on_system_prompt` [中间件](/agentscope/2.0.5dev/zh/building-blocks/middleware) 钩子。 2. **Summary** —— 较早消息被压缩后的摘要；只有发生过压缩之后才存在。 3. **Context** —— 最近的、尚未压缩的消息（用户输入、assistant 回复、工具调用、工具结果）。 @@ -147,7 +147,7 @@ Offload 通过 `Offloader` 协议接入 —— 该协议是结构化的，仅有 | `offload_context(session_id, msgs)` | 持久化被压缩的消息；返回一个引用（例如文件路径） | | `offload_tool_result(session_id, tool_result)` | 持久化被截断的工具结果；返回一个引用 | -任何实现该协议的对象都可以传入智能体的 `offloader` 参数。AgentScope 的 [`workspace`](/versions/2.0.5dev/zh/building-blocks/workspace) 模块提供了开箱即用的实现： +任何实现该协议的对象都可以传入智能体的 `offloader` 参数。AgentScope 的 [`workspace`](/agentscope/2.0.5dev/zh/building-blocks/workspace) 模块提供了开箱即用的实现： ```python from agentscope.agent import Agent @@ -235,16 +235,16 @@ class S3Offloader: ## 延伸阅读 - + 内置的 offloader 实现，以及智能体的工作环境 - + ReAct 循环以及上下文如何在推理步骤间流转 - + 通过中间件钩子拦截模型调用与 system prompt 组装 - + 会被压缩处理的工具结果来源 diff --git a/versions/2.0.5dev/zh/building-blocks/long-term-memory.mdx b/agentscope/2.0.5dev/zh/building-blocks/long-term-memory.mdx similarity index 98% rename from versions/2.0.5dev/zh/building-blocks/long-term-memory.mdx rename to agentscope/2.0.5dev/zh/building-blocks/long-term-memory.mdx index 6f2f088..f722c72 100644 --- a/versions/2.0.5dev/zh/building-blocks/long-term-memory.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/long-term-memory.mdx @@ -5,7 +5,7 @@ description: "基于智能体中间件实现的，跨会话长期记忆" **长期记忆** 是智能体跨会话保留信息的能力，包括用户偏好、历史决策，以及在会话中总结、凝练的知识或规则。 -AgentScope 通过 [智能体中间件](/versions/2.0.5dev/zh/building-blocks/middleware) 的形式实现不同长期记忆能力。每个长期记忆实现都是一个 `MiddlewareBase` 的子类，以非侵入式的方式完成记忆的注入、检索和写回。 +AgentScope 通过 [智能体中间件](/agentscope/2.0.5dev/zh/building-blocks/middleware) 的形式实现不同长期记忆能力。每个长期记忆实现都是一个 `MiddlewareBase` 的子类，以非侵入式的方式完成记忆的注入、检索和写回。 AgentScope 目前支持以下长期记忆，更多实现正在开发中： diff --git a/versions/2.0.5dev/zh/building-blocks/message-and-event.mdx b/agentscope/2.0.5dev/zh/building-blocks/message-and-event.mdx similarity index 99% rename from versions/2.0.5dev/zh/building-blocks/message-and-event.mdx rename to agentscope/2.0.5dev/zh/building-blocks/message-and-event.mdx index ebb687a..93ca3e9 100644 --- a/versions/2.0.5dev/zh/building-blocks/message-and-event.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/message-and-event.mdx @@ -646,10 +646,10 @@ async for event in agent.reply_stream(UserMsg("user", "帮我修复这个 bug")) ## 延伸阅读 - + 智能体如何在 ReAct 循环中产出事件和消息 - + 消息如何存储、压缩和卸载 diff --git a/versions/2.0.5dev/zh/building-blocks/middleware.mdx b/agentscope/2.0.5dev/zh/building-blocks/middleware.mdx similarity index 98% rename from versions/2.0.5dev/zh/building-blocks/middleware.mdx rename to agentscope/2.0.5dev/zh/building-blocks/middleware.mdx index 4b5f797..11e16fa 100644 --- a/versions/2.0.5dev/zh/building-blocks/middleware.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/middleware.mdx @@ -20,7 +20,7 @@ AgentScope 暴露了 6 个 hook 位置外加一个工具提供 hook，覆盖了 | `list_tools` | Tool source | 可选。返回中间件贡献的 `list[ToolBase]`。**不会被自动调用** —— 由组装智能体 toolkit 的调用方决定是否调用以及如何合并结果。 | -以上 hook 均作用于**智能体**层面。若需要在单个工具实例上挂钩 —— 无论该工具是在智能体内部还是外部被调用 —— 请参见[工具中间件](/versions/2.0.5dev/zh/building-blocks/tool#工具中间件)。 +以上 hook 均作用于**智能体**层面。若需要在单个工具实例上挂钩 —— 无论该工具是在智能体内部还是外部被调用 —— 请参见[工具中间件](/agentscope/2.0.5dev/zh/building-blocks/tool#工具中间件)。 三种类型的差别： @@ -296,11 +296,11 @@ DataBlockEndEvent ### 长期记忆 -AgentScope 以中间件的形式支持长期记忆，让智能体能够在多个会话间持久保存并调取信息。详见 [长期记忆](/versions/2.0.5dev/zh/building-blocks/long-term-memory) 章节。 +AgentScope 以中间件的形式支持长期记忆，让智能体能够在多个会话间持久保存并调取信息。详见 [长期记忆](/agentscope/2.0.5dev/zh/building-blocks/long-term-memory) 章节。 ### RAG -AgentScope 中知识库同样以中间件形式提供，允许智能体在推理时访问外部知识库。详见 [RAG](/versions/2.0.5dev/zh/building-blocks/rag) 章节。 +AgentScope 中知识库同样以中间件形式提供，允许智能体在推理时访问外部知识库。详见 [RAG](/agentscope/2.0.5dev/zh/building-blocks/rag) 章节。 ## 自定义中间件 diff --git a/versions/2.0.5dev/zh/building-blocks/model.mdx b/agentscope/2.0.5dev/zh/building-blocks/model.mdx similarity index 99% rename from versions/2.0.5dev/zh/building-blocks/model.mdx rename to agentscope/2.0.5dev/zh/building-blocks/model.mdx index 0800211..c80c25f 100644 --- a/versions/2.0.5dev/zh/building-blocks/model.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/model.mdx @@ -663,7 +663,7 @@ asyncio.run(main()) ### 与 Agent 集成 -在 agent 层，TTS 通过 [`TTSMiddleware`](/versions/2.0.5dev/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： +在 agent 层，TTS 通过 [`TTSMiddleware`](/agentscope/2.0.5dev/zh/building-blocks/middleware#ttsmiddleware) 集成 —— 自动拦截 agent 的文本输出并合成语音： ```python from agentscope.agent import Agent diff --git a/versions/2.0.5dev/zh/building-blocks/permission-system.mdx b/agentscope/2.0.5dev/zh/building-blocks/permission-system.mdx similarity index 100% rename from versions/2.0.5dev/zh/building-blocks/permission-system.mdx rename to agentscope/2.0.5dev/zh/building-blocks/permission-system.mdx diff --git a/versions/2.0.5dev/zh/building-blocks/plan.mdx b/agentscope/2.0.5dev/zh/building-blocks/plan.mdx similarity index 96% rename from versions/2.0.5dev/zh/building-blocks/plan.mdx rename to agentscope/2.0.5dev/zh/building-blocks/plan.mdx index d4036ce..ae3027b 100644 --- a/versions/2.0.5dev/zh/building-blocks/plan.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/plan.mdx @@ -198,5 +198,5 @@ agent.state.tasks_context.tasks.clear() ## 延伸阅读 -- [Tool](/versions/2.0.5dev/zh/building-blocks/tool) —— toolkit、`ToolBase` 接口，以及状态注入式工具如何拿到 `AgentState`。 -- [Agent](/versions/2.0.5dev/zh/building-blocks/agent) —— 智能体生命周期，包括 `AgentState` 的创建、恢复与持久化。 +- [Tool](/agentscope/2.0.5dev/zh/building-blocks/tool) —— toolkit、`ToolBase` 接口，以及状态注入式工具如何拿到 `AgentState`。 +- [Agent](/agentscope/2.0.5dev/zh/building-blocks/agent) —— 智能体生命周期，包括 `AgentState` 的创建、恢复与持久化。 diff --git a/versions/2.0.5dev/zh/building-blocks/rag.mdx b/agentscope/2.0.5dev/zh/building-blocks/rag.mdx similarity index 97% rename from versions/2.0.5dev/zh/building-blocks/rag.mdx rename to agentscope/2.0.5dev/zh/building-blocks/rag.mdx index dcf3547..05fb3f6 100644 --- a/versions/2.0.5dev/zh/building-blocks/rag.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/rag.mdx @@ -16,7 +16,7 @@ AgentScope 中的 RAG 由如下**可独立替换**的功能模块组成： 本章主要介绍**在非服务化场景下**使用 RAG 功能，包括索引文件、检索知识、集成到智能体等。 -嵌入模型的介绍和配置方式请见[嵌入模型章节](/versions/2.0.5dev/zh/building-blocks/model)；服务化版本的 RAG（带 HTTP 服务、文件托管、分布式索引）请见 [RAG 服务](/versions/2.0.5dev/zh/deploy/rag)。 +嵌入模型的介绍和配置方式请见[嵌入模型章节](/agentscope/2.0.5dev/zh/building-blocks/model)；服务化版本的 RAG（带 HTTP 服务、文件托管、分布式索引）请见 [RAG 服务](/agentscope/2.0.5dev/zh/deploy/rag)。 ## 现有实现 @@ -46,7 +46,7 @@ PDF 与 PPT 解析依赖额外的第三方库，可以通过 `pip install agents ### 嵌入模型 -请见[嵌入模型章节](/versions/2.0.5dev/zh/building-blocks/model)。 +请见[嵌入模型章节](/agentscope/2.0.5dev/zh/building-blocks/model)。 ### 向量数据库 @@ -533,13 +533,13 @@ class MyVectorStore(VectorStoreBase): ## 延伸阅读 - + 多租户、分布式的 RAG 服务，支持 HTTP API、文件托管、向量数据库托管。 - + 了解 `RAGMiddleware` 是如何嵌入 reply / reasoning 钩子的。 - + 可用的嵌入模型及其参数。 diff --git a/versions/2.0.5dev/zh/building-blocks/tool.mdx b/agentscope/2.0.5dev/zh/building-blocks/tool.mdx similarity index 95% rename from versions/2.0.5dev/zh/building-blocks/tool.mdx rename to agentscope/2.0.5dev/zh/building-blocks/tool.mdx index 83fff59..e2d551e 100644 --- a/versions/2.0.5dev/zh/building-blocks/tool.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/tool.mdx @@ -126,7 +126,7 @@ bash = Bash( `check_permissions()` —— `Write` 与 `Edit` 共用同一权限逻辑： -1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/versions/2.0.5dev/zh/building-blocks/permission-system#safety-check-契约)。 +1. **危险路径保护** —— 操作敏感文件（`.bashrc`、`.env`、`.ssh/`）返回带 `bypass_immune=True` 的 ASK，allow 规则无法静默授权。`BYPASS` 模式下该 ASK 仍然被跳过（BYPASS 明确选择放弃 safety 提示），`DONT_ASK` 下被转为 DENY。完整契约见[权限系统文档](/agentscope/2.0.5dev/zh/building-blocks/permission-system#safety-check-契约)。 2. **ACCEPT_EDITS 模式** —— 自动放行配置工作目录内的文件操作 3. **PASSTHROUGH** —— 交给权限引擎做规则匹配 @@ -146,14 +146,14 @@ bash = Bash( 计划工具让智能体能够显式地维护一份结构化的任务清单，智能体可以通过工具调用来创建、查询和更新任务。计划相关的数据会被存储在智能体实例的 `agent.state.tasks_context` 中，所有计划相关的工具通过操作这个共享的状态来实现任务的管理。同时，所有计划相关的工具在权限检查中被默认放行。 -完整的任务生命周期、存储模型，以及如何以编程方式预置或自定义任务，请参见 [计划模式](/versions/2.0.5dev/zh/building-blocks/plan)。 +完整的任务生命周期、存储模型，以及如何以编程方式预置或自定义任务，请参见 [计划模式](/agentscope/2.0.5dev/zh/building-blocks/plan)。 ### 切换工具后端 AgentScope 中的 `Bash`，`Grep`，`Glob`，`Read`，`Write`，`Edit` 工具支持后端切换，即将运行逻辑委派到不同的执行环境中，例如本地文件系统，Docker 容器，E2B 沙箱等。 -通过指定 `backend` 参数即可切换后端，而 `backend` 实例可以通过 `Workspace` 实例获取，默认为本地环境。关于 `Workspace` 的更多信息，请参见 [工作空间](/versions/2.0.5dev/zh/building-blocks/workspace) 章节。 +通过指定 `backend` 参数即可切换后端，而 `backend` 实例可以通过 `Workspace` 实例获取，默认为本地环境。关于 `Workspace` 的更多信息，请参见 [工作空间](/agentscope/2.0.5dev/zh/building-blocks/workspace) 章节。 ```python title="切换到 Docker 后端" @@ -238,7 +238,7 @@ class WebSearch(ToolBase): 自定义工具时，有两个权限审查相关的逻辑需要注意： - **`check_read_only(tool_input)`**：当某次调用是否是只读取决于输入时，需要重新该函数（例如 `Bash`：`ls` 是只读，`rm` 不是）。该函数默认返回 `is_read_only` 静态属性。权限引擎在判定 EXPLORE / ACCEPT_EDITS 是否自动放行时调用。 -- **`PermissionDecision(..., bypass_immune=True)`**：在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/versions/2.0.5dev/zh/building-blocks/permission-system#safety-check-契约)。 +- **`PermissionDecision(..., bypass_immune=True)`**：在返回的 ASK 上设置，把它标记为 allow 规则无法静默的 safety check（例如 `DeployTool` 标记 `prod-*` 目标）。各 mode 下的具体处理见 [safety check 契约](/agentscope/2.0.5dev/zh/building-blocks/permission-system#safety-check-契约)。 ### 将函数包装为工具 @@ -279,7 +279,7 @@ toolkit = Toolkit(tools=[FunctionTool(get_weather)]) 外部执行工具把实际执行委派给智能体运行时之外 —— 通常是人工操作员或外部系统。智能体调用此类工具时会发出 `RequireExternalExecutionEvent` 事件并退出 `reply` / `reply_stream` 函数，直到结果通过 `ExternalExecutionResultEvent` 回传。 -这种模式是 [human-in-the-loop](/versions/2.0.5dev/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 +这种模式是 [human-in-the-loop](/agentscope/2.0.5dev/zh/building-blocks/agent#人机交互) 工作流的基础 —— 某些动作需要人工确认或人工执行。 创建外部执行工具只需把 `is_external_tool` 设为 `True`，不必实现 `call` 函数： @@ -399,7 +399,7 @@ bash = Bash(middlewares=[LoggingMiddleware(), RetryMiddleware(max_attempts=3)]) ``` -**工具中间件 vs. 智能体中间件** —— 对属于工具本身的横切关注点（日志、metrics、重试），使用 `ToolMiddlewareBase`。若需要访问更广泛的智能体上下文 —— 权限决策、tool-call 事件或所在的 ReAct 轮次 —— 请使用 `MiddlewareBase.on_acting`。完整的智能体级钩子参考见 [Middleware](/versions/2.0.5dev/zh/building-blocks/middleware)。 +**工具中间件 vs. 智能体中间件** —— 对属于工具本身的横切关注点（日志、metrics、重试），使用 `ToolMiddlewareBase`。若需要访问更广泛的智能体上下文 —— 权限决策、tool-call 事件或所在的 ReAct 轮次 —— 请使用 `MiddlewareBase.on_acting`。完整的智能体级钩子参考见 [Middleware](/agentscope/2.0.5dev/zh/building-blocks/middleware)。 ## MCP @@ -583,16 +583,16 @@ toolkit = Toolkit( ## 延伸阅读 - + 智能体如何在 ReAct 循环中编排工具调用 - + 精细控制哪个工具可以执行、何时执行 - + 拦截智能体生命周期钩子 —— reply、reasoning、model 调用等 - + 外部执行工具与人工审批工作流 diff --git a/versions/2.0.5dev/zh/building-blocks/workspace.mdx b/agentscope/2.0.5dev/zh/building-blocks/workspace.mdx similarity index 93% rename from versions/2.0.5dev/zh/building-blocks/workspace.mdx rename to agentscope/2.0.5dev/zh/building-blocks/workspace.mdx index 67f05e7..3549c9b 100644 --- a/versions/2.0.5dev/zh/building-blocks/workspace.mdx +++ b/agentscope/2.0.5dev/zh/building-blocks/workspace.mdx @@ -7,7 +7,7 @@ description: "为 agent 提供工具、skill 与上下文 offload 的执行环 Workspace 是 agent 的执行环境，向 agent 提供三类资源 —— **工具**（内置 tool 与 MCP）、**skill**，以及面向压缩消息与超大工具结果的**上下文 offload** —— 同时管理其中资源（MCP server 进程、动态加入的 skill、offload 文件）的生命周期。 -AgentScope 提供四种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱、OpenSandbox 沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/versions/2.0.5dev/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 +AgentScope 提供四种 workspace 实现 —— 本地文件系统、Docker 容器、E2B 云沙箱、OpenSandbox 沙箱 —— 以及一个 **workspace manager**，在 [Agent Service](/agentscope/2.0.5dev/zh/deploy/agent-service) 中负责分配和追踪 workspace，让多租户部署可以把 workspace 按 user、agent 或 session 维度映射，无需改写 agent 代码。 对 Docker、E2B 与 OpenSandbox 而言，MCP server 跑在隔离环境*内部*；宿主侧通过 workspace 内的 gateway 访问它们，详见后文 [MCP Gateway](#mcp-gateway)。 @@ -208,7 +208,7 @@ toolkit = Toolkit( ## Workspace Manager -Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/versions/2.0.5dev/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 +Workspace manager 是多租户服务中 workspace 的分配器与生命周期持有者，由 [Agent Service](/agentscope/2.0.5dev/zh/deploy/agent-service) 使用，负责把请求路由到正确的 workspace 实例并在关闭时回收。 Manager 的职责： @@ -252,10 +252,10 @@ ws = await manager.get_workspace( ) ``` -要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/versions/2.0.5dev/zh/deploy/agent-service#workspace-实现与隔离)。 +要换用其他隔离策略（按 user、按 session 或混合），继承 `WorkspaceManagerBase` 并按自己的键重写 `get_workspace` / `create_workspace` —— 关于 manager 如何接入服务请求生命周期，详见 [Agent Service · Workspace 实现与隔离](/agentscope/2.0.5dev/zh/deploy/agent-service#workspace-实现与隔离)。 -Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/versions/2.0.5dev/zh/deploy/agent-service)。 +Agent Service 在 lifespan 期间把 workspace manager 绑定到 FastAPI 应用状态上，所有请求共享；router 通过 `get_workspace_manager` 依赖注入获取 workspace。完整集成方式见 [Agent Service](/agentscope/2.0.5dev/zh/deploy/agent-service)。 ## MCP Gateway @@ -291,16 +291,16 @@ Gateway 暴露一组小型 REST 接口 —— `GET /health`、`GET/POST/DELETE / ## 延伸阅读 - + Agent 抽象、ReAct 循环与 offloader 集成 - + 内置 tool、MCP 集成与 toolkit 组装 - + 驱动 workspace manager 的多租户服务 - + 上下文压缩与 offload 触发条件 diff --git a/versions/2.0.5dev/zh/deploy/agent-service.mdx b/agentscope/2.0.5dev/zh/deploy/agent-service.mdx similarity index 97% rename from versions/2.0.5dev/zh/deploy/agent-service.mdx rename to agentscope/2.0.5dev/zh/deploy/agent-service.mdx index ddfde2c..d844cd3 100644 --- a/versions/2.0.5dev/zh/deploy/agent-service.mdx +++ b/agentscope/2.0.5dev/zh/deploy/agent-service.mdx @@ -3,7 +3,7 @@ title: "架构" description: "把智能体部署为多租户、多会话的 HTTP 服务" --- -智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/versions/2.0.5dev/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 +智能体服务（Agent Service）是基于 FastAPI 把 AgentScope 的智能体转化为**多租户（Multi-tenant）、多会话（Multi-session）的 HTTP 服务**。它接管智能体*外围*的全部职责 —— 请求路由、按用户的资源生命周期、会话（Session）状态、持久化、调度（Schedule），以及工具调用的卸载，让基于 [`Agent`](/agentscope/2.0.5dev/zh/building-blocks/agent) 编写的代码无需重写即可承接生产流量。 它的特点： @@ -16,7 +16,7 @@ description: "把智能体部署为多租户、多会话的 HTTP 服务" | 能力 | 说明 | |---------------------------------------------------|-----------------------------------------------------------------------------------------| -| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/versions/2.0.5dev/zh/deploy/agent-team) 章节。 | +| 智能体团队（Agent Team） | Leader 智能体派生 worker 智能体，并通过内置 team 工具协调它们；详见 [Agent Team](/agentscope/2.0.5dev/zh/deploy/agent-team) 章节。 | | 工作区管理 | 可配置的工作区隔离粒度 —— `per_agent`（默认）、`per_session` 或 `per_user` —— 管理智能体的文件系统、MCP client 与 skill。 | | 知识库（RAG） | 可选的内置知识库服务，支持文档摄取、切片、embedding 与自然语言检索 —— 向 `create_app` 传入 `knowledge_base_manager` 即可启用。 | | 后台任务卸载（Background Task Offloading） | 长耗时工具调用切到后台执行，完成时通过会话事件流回送结果。 | @@ -216,7 +216,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) 异步工厂 `(user_id, agent_id, session_id) -> Awaitable[list[ToolBase]]`，在每次组装智能体时被调用一次。返回的工具会与工作区派生的工具一起合并到 toolkit 的 `"basic"` 分组里，便于按调用者动态决定可用工具（例如按租户接入、按用户使用各自凭证的工具）。 - 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/versions/2.0.5dev/zh/deploy/agent-team#自定义子智能体类型)。 + 团队中子智能体创建的可复用蓝图。每个模板定义了一个子智能体*类型*（例如 `"researcher"`、`"coder"`），预设了系统提示词、权限上下文与任务上下文。注册后，`AgentCreate` 工具会暴露 `subagent_type` 参数，使 leader 智能体可以路由到相应的模板。详见[自定义子智能体类型](/agentscope/2.0.5dev/zh/deploy/agent-team#自定义子智能体类型)。 自定义的 `Agent` 子类，用于替代内置 `Agent` 在每轮 chat 中被实例化。适合在保留其他服务组件不变的前提下换用具有不同推理行为的智能体实现。 @@ -260,7 +260,7 @@ uvicorn.run(app, host="0.0.0.0", port=8000) ``` - 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/versions/2.0.5dev/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 + 若智能体需要超出内置范围的工具，向会话的工作区附加 MCP client 与 skill。开箱即用的情况下，每个智能体已经能访问工作区的内置工具（文件系统、shell、搜索……）、任务规划工具、调度与后台任务控制工具，以及 —— 当会话是团队 leader 或成员时 —— [Agent Team](/agentscope/2.0.5dev/zh/deploy/agent-team) 中描述的团队协调工具。通过 `create_app` 的 `extra_agent_tools` 传入的工具也会一并合入。 ```http POST /workspace/mcp @@ -316,7 +316,7 @@ curl -X POST -H "X-User-ID: alice" \ ## 资源模型 -智能体服务中的每次操作都归属于从请求中解析出的 `user_id`。在该边界之下，服务管理七类资源 —— 六类持久化资源（图左侧）加把它们运行时行为串起来的消息总线（图右侧）。若要让凭证、智能体或知识库跨越用户之间的这条边界，见[资源共享](/versions/2.0.5dev/zh/deploy/sharing)。 +智能体服务中的每次操作都归属于从请求中解析出的 `user_id`。在该边界之下，服务管理七类资源 —— 六类持久化资源（图左侧）加把它们运行时行为串起来的消息总线（图右侧）。若要让凭证、智能体或知识库跨越用户之间的这条边界，见[资源共享](/agentscope/2.0.5dev/zh/deploy/sharing)。 ```mermaid flowchart TB @@ -385,7 +385,7 @@ flowchart TB ### 智能体聊天协议 -按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/versions/2.0.5dev/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 +按会话流端点（`GET /sessions/{id}/stream`）通过 SSE 输出 AgentScope 原生的 [`AgentEvent`](/agentscope/2.0.5dev/zh/building-blocks/message-and-event) 流。要让同一智能体服务于不同前端协议，安装协议中间件拦截 SSE 流并改写每帧。 AgentScope 内置 `AGUIProtocolMiddleware` 适配 [AG-UI](https://docs.ag-ui.com/) 协议。通过 `extra_middlewares` 装载： @@ -741,16 +741,16 @@ Router 通过 FastAPI 的 `Depends()` 拿到应用状态。标准注入项（位 ## 延伸阅读 - + 核心智能体抽象与 ReAct 循环 - + 事件流与消息重建 - + 内置与自定义工具，包括外部执行 - + 上下文压缩与工作区 offloading diff --git a/versions/2.0.5dev/zh/deploy/agent-team.mdx b/agentscope/2.0.5dev/zh/deploy/agent-team.mdx similarity index 86% rename from versions/2.0.5dev/zh/deploy/agent-team.mdx rename to agentscope/2.0.5dev/zh/deploy/agent-team.mdx index b1dfb9d..06e9f57 100644 --- a/versions/2.0.5dev/zh/deploy/agent-team.mdx +++ b/agentscope/2.0.5dev/zh/deploy/agent-team.mdx @@ -3,11 +3,11 @@ title: "智能体团队" description: "Leader 智能体通过内置 team 工具派生并协调 worker 智能体" --- -智能体团队（Agent Team）是构建在[智能体服务](/versions/2.0.5dev/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 +智能体团队（Agent Team）是构建在[智能体服务](/agentscope/2.0.5dev/zh/deploy/agent-service)之上的多智能体层。Leader 智能体 —— 即用户对话的那个会话 —— 可以按需派生 worker 智能体并与之交换消息，而每个成员都只是另一个拥有独立状态、工作区绑定与事件流的会话。整套协调能力通过四个内置工具表达，而非借助一套独立的编排框架。 ## 快速上手 -随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/versions/2.0.5dev/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 +随仓库附带的 [`examples/agent_service`](https://github.com/agentscope-ai/agentscope/tree/main/examples/agent_service) 后端默认启用了 team 工具，配套的 [`examples/web_ui`](https://github.com/agentscope-ai/agentscope/tree/main/examples/web_ui) 前端开箱即可渲染团队成员关系与各 worker 的事件流。按照[智能体服务快速上手](/agentscope/2.0.5dev/zh/deploy/agent-service#试用示例)启动两者 —— 跑起来后让 leader 智能体组建一个团队，你会看到它自动调用 `TeamCreate` / `AgentCreate`，观察 worker 上线，并在 UI 中看到它们互相交换消息。 智能体团队协作演示 @@ -144,7 +144,7 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ### 协调模型 -智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/versions/2.0.5dev/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 +智能体团队天然为分布式部署而设计。所有成员间的通信都由[消息总线](/agentscope/2.0.5dev/zh/deploy/agent-service#资源模型)居中转发 —— 一个由 Redis 支撑的抽象 —— 因此 leader 与 worker 会话可以位于不同进程或不同节点，无需任何代码改动。发送方将消息写入接收方的收件箱；集群中任意 wakeup dispatcher 都可以认领该唤醒信号，并在自己的进程上驱动该会话运行。这与支撑调度触发、后台工具完成的机制是同一套，也是为什么团队功能能与服务的其他部分一样横向扩展。 团队通信复用了服务用于调度触发与后台工具完成的同一组 inbox + wakeup 原语： @@ -158,10 +158,10 @@ Leader 会话自动获得下列工具。Worker 只能看到 `TeamSay`。 ## 延伸阅读 - + 支撑团队的托管层 —— 会话、消息总线、工作区生命周期。 - + 每个团队成员所运行的智能体抽象。 diff --git a/versions/2.0.5dev/zh/deploy/rag.mdx b/agentscope/2.0.5dev/zh/deploy/rag.mdx similarity index 96% rename from versions/2.0.5dev/zh/deploy/rag.mdx rename to agentscope/2.0.5dev/zh/deploy/rag.mdx index 1e80681..a751ac2 100644 --- a/versions/2.0.5dev/zh/deploy/rag.mdx +++ b/agentscope/2.0.5dev/zh/deploy/rag.mdx @@ -3,7 +3,7 @@ title: "RAG 服务" description: "一键式启动的多租户、分布式 RAG 服务" --- -[RAG](/versions/2.0.5dev/zh/building-blocks/rag) 章节中介绍了 AgentScope 中的 RAG 模块的拓展和使用方法。本章介绍智能体服务（Agent service）中提供的**多租户、可分布式部署**的 RAG 服务层。服务层在 building blocks 的基础上，围绕「多租户」「分布式」「易接入」提供以下能力： +[RAG](/agentscope/2.0.5dev/zh/building-blocks/rag) 章节中介绍了 AgentScope 中的 RAG 模块的拓展和使用方法。本章介绍智能体服务（Agent service）中提供的**多租户、可分布式部署**的 RAG 服务层。服务层在 building blocks 的基础上，围绕「多租户」「分布式」「易接入」提供以下能力： | 能力 | 说明 | |------|------| @@ -424,16 +424,16 @@ parser 默认在事件循环线程内运行。如果引入 PDF / Office 等 CPU ## 延伸阅读 - + 了解 parser / chunker / vector store / middleware 的原子接口与 library 模式用法。 - + `create_app` 的全局参数、lifespan、依赖注入与 ASGI 中间件层。 - + `RAGMiddleware` 借助哪些钩子注入检索结果。 - + 嵌入模型卡 / 维度约束，决定知识库可选哪些模型。 diff --git a/versions/2.0.5dev/zh/deploy/sharing.mdx b/agentscope/2.0.5dev/zh/deploy/sharing.mdx similarity index 96% rename from versions/2.0.5dev/zh/deploy/sharing.mdx rename to agentscope/2.0.5dev/zh/deploy/sharing.mdx index b5974e3..805d96d 100644 --- a/versions/2.0.5dev/zh/deploy/sharing.mdx +++ b/agentscope/2.0.5dev/zh/deploy/sharing.mdx @@ -6,7 +6,7 @@ tag: "NEW" 资源共享是指让一个用户的 **凭证**、**智能体** 和 **知识库** 对其他用户变得可见（可使用）或可编辑。 -默认情况下，AgentScope 中智能体服务默认是按照租户严格隔离的，任何用户都看不到别人的记录（见[资源模型](/versions/2.0.5dev/zh/deploy/agent-service#资源模型)）。 +默认情况下，AgentScope 中智能体服务默认是按照租户严格隔离的，任何用户都看不到别人的记录（见[资源模型](/agentscope/2.0.5dev/zh/deploy/agent-service#资源模型)）。 资源共享是在确保数据安全的前提下合法实现资源共享的途径。 适用的典型场景包括： @@ -196,7 +196,7 @@ app = create_app( -共享一个智能体，共享的是它的**配置** —— 显示名、系统提示词，以及 context / ReAct 设置 —— 而**不包括它的 workspace 内容**。MCP 客户端配置、skills 以及累积的记忆（`MEMORY.md`）都存放在按用户隔离的 [workspace](/versions/2.0.5dev/zh/deploy/workspace-manager) 中，它会为每个访问者重新初始化，因此共享的智能体对每个用户都是从一个干净的 workspace 起步，而非继承属主的工具与记忆。 +共享一个智能体，共享的是它的**配置** —— 显示名、系统提示词，以及 context / ReAct 设置 —— 而**不包括它的 workspace 内容**。MCP 客户端配置、skills 以及累积的记忆（`MEMORY.md`）都存放在按用户隔离的 [workspace](/agentscope/2.0.5dev/zh/deploy/workspace-manager) 中，它会为每个访问者重新初始化，因此共享的智能体对每个用户都是从一个干净的 workspace 起步，而非继承属主的工具与记忆。 共享这部分驻留在 workspace 中的状态是一个已知的缺口，我们正在积极解决；进展请关注 GitHub 上的跟踪 issue。 diff --git a/versions/2.0.5dev/zh/deploy/workspace-manager.mdx b/agentscope/2.0.5dev/zh/deploy/workspace-manager.mdx similarity index 95% rename from versions/2.0.5dev/zh/deploy/workspace-manager.mdx rename to agentscope/2.0.5dev/zh/deploy/workspace-manager.mdx index 4e2048f..1b7dd1e 100644 --- a/versions/2.0.5dev/zh/deploy/workspace-manager.mdx +++ b/agentscope/2.0.5dev/zh/deploy/workspace-manager.mdx @@ -4,7 +4,7 @@ description: "在服务中分配、管理智能体的运行环境（Workspace） tag: "NEW" --- -**工作区管理器**（Workspace Manager）持有隔离策略，并管理智能体服务中每个智能体的 [`Workspace`](/versions/2.0.5dev/zh/building-blocks/workspace) 实例的生命周期。它是 `agentscope.workspace` 模块在服务侧的对应实现 —— 每一种 `WorkspaceBase` 子类都有一个配套的 `WorkspaceManagerBase` 的子类来负责创建、缓存与删除。 +**工作区管理器**（Workspace Manager）持有隔离策略，并管理智能体服务中每个智能体的 [`Workspace`](/agentscope/2.0.5dev/zh/building-blocks/workspace) 实例的生命周期。它是 `agentscope.workspace` 模块在服务侧的对应实现 —— 每一种 `WorkspaceBase` 子类都有一个配套的 `WorkspaceManagerBase` 的子类来负责创建、缓存与删除。 它的特点： @@ -22,7 +22,7 @@ tag: "NEW" | `K8sWorkspaceManager` | 在 Kubernetes 集群上为每个 workspace 起一个 Pod + PVC。适合已经在跑其他负载的生产集群。 | -想深入了解 workspace *究竟是什么*（文件系统布局、gateway、MCP 接线、内置工具），请看 [Workspace](/versions/2.0.5dev/zh/building-blocks/workspace) 章节。 +想深入了解 workspace *究竟是什么*（文件系统布局、gateway、MCP 接线、内置工具），请看 [Workspace](/agentscope/2.0.5dev/zh/building-blocks/workspace) 章节。 ## 接入智能体服务 @@ -261,7 +261,7 @@ async with AsyncExitStack() as stack: ## 自定义 Manager -任何基于 [`WorkspaceBase`](/versions/2.0.5dev/zh/building-blocks/workspace) 构建的 workspace 类，都可以通过配一个 `WorkspaceManagerBase` 子类的方式接到智能体服务里。大多数情况下只需要写一小段准备 + 缓存的样板代码 —— 隔离策略由基类自动继承。 +任何基于 [`WorkspaceBase`](/agentscope/2.0.5dev/zh/building-blocks/workspace) 构建的 workspace 类，都可以通过配一个 `WorkspaceManagerBase` 子类的方式接到智能体服务里。大多数情况下只需要写一小段准备 + 缓存的样板代码 —— 隔离策略由基类自动继承。 ```python 自定义 Manager import asyncio diff --git a/versions/2.0.5dev/zh/index.mdx b/agentscope/2.0.5dev/zh/index.mdx similarity index 76% rename from versions/2.0.5dev/zh/index.mdx rename to agentscope/2.0.5dev/zh/index.mdx index 5de9655..ee18a3b 100644 --- a/versions/2.0.5dev/zh/index.mdx +++ b/agentscope/2.0.5dev/zh/index.mdx @@ -19,19 +19,19 @@ AgentScope 2.0 是一款安全、高效、灵活且完备的生产级智能体 从单智能体推理到复杂企业级应用，AgentScope 为开发者提供覆盖其完整生命周期的全栈支持。 - + 具备自主 ReAct 推理和多工具协同执行能力的智能体，内置人机协作审核与高并发工具调度机制。 - + 智能体自主管理的工具栈体系，支持原生 Python 函数、MCP（模型上下文协议）和多种外部技能（Skill）的无缝拼装。 - + 精细化的上下文剪裁、卸载与智能体主动检索，深度融合了 Mem0、ReMe 等第三方记忆实现。 - + 支持在物理隔离的安全环境（如本地隔离沙箱、Docker、E2B、Kubernetes 等）中安全执行外部代码，支持用户、智能体、会话三级精细隔离。 - + 一键部署的生产级后端，自带可视化前端与开发 SDK，多租户多会话并发与分布式集群调度触手可得。 diff --git a/versions/2.0.5dev/zh/others/change-log.mdx b/agentscope/2.0.5dev/zh/others/change-log.mdx similarity index 100% rename from versions/2.0.5dev/zh/others/change-log.mdx rename to agentscope/2.0.5dev/zh/others/change-log.mdx diff --git a/versions/2.0.5dev/zh/others/faq.mdx b/agentscope/2.0.5dev/zh/others/faq.mdx similarity index 84% rename from versions/2.0.5dev/zh/others/faq.mdx rename to agentscope/2.0.5dev/zh/others/faq.mdx index 8b34b4b..f3d1397 100644 --- a/versions/2.0.5dev/zh/others/faq.mdx +++ b/agentscope/2.0.5dev/zh/others/faq.mdx @@ -14,14 +14,14 @@ description: "AgentScope 2.0 常见问题" 支持。**Workspace** 是 AgentScope 为 agent 提供的执行环境抽象，内置三种实现 —— `LocalWorkspace`（宿主文件系统）、`DockerWorkspace`（容器）、`E2BWorkspace`（E2B 云沙箱），共享同一份接口，因此同一份 agent 代码可以无差别地在任意后端上运行。Workspace 同时负责管理 MCP server 生命周期、skill 与上下文 offload。 - 完整介绍见 [Workspace](/versions/2.0.5dev/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 + 完整介绍见 [Workspace](/agentscope/2.0.5dev/zh/building-blocks/workspace)，包括如何把 workspace 接入 `Agent`，以及多租户场景下的 `WorkspaceManager`。 有，分两个层次： - **TypeScript SDK** —— 通过 `pnpm install @agentscope-ai/agentscope` 安装，对齐 Python 端的 `Msg` 与 `Event` 类型，前端无需重写协议即可消费 agent 的流式输出。 - - **前端 UI** —— 面向 [Agent Service](/versions/2.0.5dev/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 + - **前端 UI** —— 面向 [Agent Service](/agentscope/2.0.5dev/zh/deploy/agent-service) 的开箱即用 Web 应用，开发者无需自行编写 UI 即可直接体验已部署的 agent。 diff --git a/versions/2.0.5dev/zh/quickstart.mdx b/agentscope/2.0.5dev/zh/quickstart.mdx similarity index 100% rename from versions/2.0.5dev/zh/quickstart.mdx rename to agentscope/2.0.5dev/zh/quickstart.mdx diff --git a/versions/2.0.5dev/zh/release-notes.mdx b/agentscope/2.0.5dev/zh/release-notes.mdx similarity index 99% rename from versions/2.0.5dev/zh/release-notes.mdx rename to agentscope/2.0.5dev/zh/release-notes.mdx index 5450162..808bb2d 100644 --- a/versions/2.0.5dev/zh/release-notes.mdx +++ b/agentscope/2.0.5dev/zh/release-notes.mdx @@ -355,7 +355,7 @@ description: "AgentScope 版本改动和更新日志。" **Tool** - **基于 `ToolBase` 重建内置工具**：全新的 `_bash`、`_edit`、`_glob`、`_grep`、`_read`、`_write` 实现，以及共享的 `_meta` 与 `_constants`，全部基于新的工具基类。([#1502](https://github.com/agentscope-ai/agentscope/pull/1502)) -- **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/versions/2.0.5dev/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) +- **Task 工具**：新增 `TaskCreate`、`TaskGet`、`TaskList`、`TaskUpdate`（详见 [Plan](/agentscope/2.0.5dev/zh/building-blocks/plan) 页面）。([#1549](https://github.com/agentscope-ai/agentscope/pull/1549)) - **工具与 Workspace 集成**：工具包与 Workspace 模块被打通进 `Agent` 类，文件/Shell 工具现在统一在智能体的 Workspace 中执行。([#1642](https://github.com/agentscope-ai/agentscope/pull/1642)) **Workspace** diff --git a/docs.json b/docs.json index a7e03bb..4a342fa 100644 --- a/docs.json +++ b/docs.json @@ -13,301 +13,316 @@ { "language": "en", "default": true, - "versions": [ + "tabs": [ { - "version": "2.0.5dev", - "tabs": [ + "tab": "AgentScope", + "versions": [ { - "tab": "Guides", + "version": "2.0.5dev", "groups": [ { "group": "Get Started", "pages": [ - "versions/2.0.5dev/en/index", - "versions/2.0.5dev/en/quickstart", - "versions/2.0.5dev/en/release-notes" + "agentscope/2.0.5dev/en/index", + "agentscope/2.0.5dev/en/quickstart", + "agentscope/2.0.5dev/en/release-notes" ] }, { "group": "Building Blocks", "pages": [ - "versions/2.0.5dev/en/building-blocks/message-and-event", - "versions/2.0.5dev/en/building-blocks/agent", - "versions/2.0.5dev/en/building-blocks/model", - "versions/2.0.5dev/en/building-blocks/context", - "versions/2.0.5dev/en/building-blocks/tool", - "versions/2.0.5dev/en/building-blocks/plan", - "versions/2.0.5dev/en/building-blocks/permission-system", - "versions/2.0.5dev/en/building-blocks/middleware", - "versions/2.0.5dev/en/building-blocks/rag", - "versions/2.0.5dev/en/building-blocks/long-term-memory", - "versions/2.0.5dev/en/building-blocks/workspace" + "agentscope/2.0.5dev/en/building-blocks/message-and-event", + "agentscope/2.0.5dev/en/building-blocks/agent", + "agentscope/2.0.5dev/en/building-blocks/model", + "agentscope/2.0.5dev/en/building-blocks/context", + "agentscope/2.0.5dev/en/building-blocks/tool", + "agentscope/2.0.5dev/en/building-blocks/plan", + "agentscope/2.0.5dev/en/building-blocks/permission-system", + "agentscope/2.0.5dev/en/building-blocks/middleware", + "agentscope/2.0.5dev/en/building-blocks/rag", + "agentscope/2.0.5dev/en/building-blocks/long-term-memory", + "agentscope/2.0.5dev/en/building-blocks/workspace" ] }, { "group": "Agent as Service", "pages": [ - "versions/2.0.5dev/en/deploy/agent-service", - "versions/2.0.5dev/en/deploy/agent-team", - "versions/2.0.5dev/en/deploy/sharing", - "versions/2.0.5dev/en/deploy/rag", - "versions/2.0.5dev/en/deploy/workspace-manager", + "agentscope/2.0.5dev/en/deploy/agent-service", + "agentscope/2.0.5dev/en/deploy/agent-team", + "agentscope/2.0.5dev/en/deploy/sharing", + "agentscope/2.0.5dev/en/deploy/rag", + "agentscope/2.0.5dev/en/deploy/workspace-manager", { "group": "API", - "openapi": "versions/2.0.5dev/en/deploy/openapi.json" + "openapi": "agentscope/2.0.5dev/en/deploy/openapi.json" } ] }, { "group": "Others", "pages": [ - "versions/2.0.5dev/en/others/faq", - "versions/2.0.5dev/en/others/change-log" + "agentscope/2.0.5dev/en/others/faq", + "agentscope/2.0.5dev/en/others/change-log" ] } ] - } - ] - }, - { - "version": "2.0.4", - "tabs": [ + }, { - "tab": "Guides", + "version": "2.0.4", "groups": [ { "group": "Get Started", "pages": [ - "versions/2.0.4/en/index", - "versions/2.0.4/en/quickstart", - "versions/2.0.4/en/release-notes" + "agentscope/2.0.4/en/index", + "agentscope/2.0.4/en/quickstart", + "agentscope/2.0.4/en/release-notes" ] }, { "group": "Building Blocks", "pages": [ - "versions/2.0.4/en/building-blocks/message-and-event", - "versions/2.0.4/en/building-blocks/agent", - "versions/2.0.4/en/building-blocks/model", - "versions/2.0.4/en/building-blocks/context", - "versions/2.0.4/en/building-blocks/tool", - "versions/2.0.4/en/building-blocks/plan", - "versions/2.0.4/en/building-blocks/permission-system", - "versions/2.0.4/en/building-blocks/middleware", - "versions/2.0.4/en/building-blocks/rag", - "versions/2.0.4/en/building-blocks/long-term-memory", - "versions/2.0.4/en/building-blocks/workspace" + "agentscope/2.0.4/en/building-blocks/message-and-event", + "agentscope/2.0.4/en/building-blocks/agent", + "agentscope/2.0.4/en/building-blocks/model", + "agentscope/2.0.4/en/building-blocks/context", + "agentscope/2.0.4/en/building-blocks/tool", + "agentscope/2.0.4/en/building-blocks/plan", + "agentscope/2.0.4/en/building-blocks/permission-system", + "agentscope/2.0.4/en/building-blocks/middleware", + "agentscope/2.0.4/en/building-blocks/rag", + "agentscope/2.0.4/en/building-blocks/long-term-memory", + "agentscope/2.0.4/en/building-blocks/workspace" ] }, { "group": "Agent as Service", "pages": [ - "versions/2.0.4/en/deploy/agent-service", - "versions/2.0.4/en/deploy/agent-team", - "versions/2.0.4/en/deploy/rag", + "agentscope/2.0.4/en/deploy/agent-service", + "agentscope/2.0.4/en/deploy/agent-team", + "agentscope/2.0.4/en/deploy/rag", { "group": "API", - "openapi": "versions/2.0.4/en/deploy/openapi.json" + "openapi": "agentscope/2.0.4/en/deploy/openapi.json" } ] }, { "group": "Others", "pages": [ - "versions/2.0.4/en/others/faq", - "versions/2.0.4/en/others/change-log" + "agentscope/2.0.4/en/others/faq", + "agentscope/2.0.4/en/others/change-log" ] } ] - } - ] - }, - { - "version": "2.0.3", - "tabs": [ + }, { - "tab": "Guides", + "version": "2.0.3", "groups": [ { "group": "Get Started", "pages": [ - "versions/2.0.3/en/index", - "versions/2.0.3/en/quickstart", - "versions/2.0.3/en/release-notes" + "agentscope/2.0.3/en/index", + "agentscope/2.0.3/en/quickstart", + "agentscope/2.0.3/en/release-notes" ] }, { "group": "Building Blocks", "pages": [ - "versions/2.0.3/en/building-blocks/message-and-event", - "versions/2.0.3/en/building-blocks/agent", - "versions/2.0.3/en/building-blocks/model", - "versions/2.0.3/en/building-blocks/context", - "versions/2.0.3/en/building-blocks/tool", - "versions/2.0.3/en/building-blocks/plan", - "versions/2.0.3/en/building-blocks/permission-system", - "versions/2.0.3/en/building-blocks/middleware", - "versions/2.0.3/en/building-blocks/rag", - "versions/2.0.3/en/building-blocks/long-term-memory", - "versions/2.0.3/en/building-blocks/workspace" + "agentscope/2.0.3/en/building-blocks/message-and-event", + "agentscope/2.0.3/en/building-blocks/agent", + "agentscope/2.0.3/en/building-blocks/model", + "agentscope/2.0.3/en/building-blocks/context", + "agentscope/2.0.3/en/building-blocks/tool", + "agentscope/2.0.3/en/building-blocks/plan", + "agentscope/2.0.3/en/building-blocks/permission-system", + "agentscope/2.0.3/en/building-blocks/middleware", + "agentscope/2.0.3/en/building-blocks/rag", + "agentscope/2.0.3/en/building-blocks/long-term-memory", + "agentscope/2.0.3/en/building-blocks/workspace" ] }, { "group": "Agent as Service", "pages": [ - "versions/2.0.3/en/deploy/agent-service", - "versions/2.0.3/en/deploy/agent-team", - "versions/2.0.3/en/deploy/rag", + "agentscope/2.0.3/en/deploy/agent-service", + "agentscope/2.0.3/en/deploy/agent-team", + "agentscope/2.0.3/en/deploy/rag", { "group": "API", - "openapi": "versions/2.0.3/en/deploy/openapi.json" + "openapi": "agentscope/2.0.3/en/deploy/openapi.json" } ] }, { "group": "Others", "pages": [ - "versions/2.0.3/en/others/faq", - "versions/2.0.3/en/others/change-log" + "agentscope/2.0.3/en/others/faq", + "agentscope/2.0.3/en/others/change-log" ] } ] - } - ] - }, - { - "version": "2.0.2", - "tabs": [ + }, { - "tab": "Guides", + "version": "2.0.2", "groups": [ { "group": "Get Started", "pages": [ - "versions/2.0.2/en/index", - "versions/2.0.2/en/quickstart", - "versions/2.0.2/en/change-log" + "agentscope/2.0.2/en/index", + "agentscope/2.0.2/en/quickstart", + "agentscope/2.0.2/en/change-log" ] }, { "group": "Building Blocks", "pages": [ - "versions/2.0.2/en/building-blocks/message-and-event", - "versions/2.0.2/en/building-blocks/agent", - "versions/2.0.2/en/building-blocks/model", - "versions/2.0.2/en/building-blocks/context", - "versions/2.0.2/en/building-blocks/tool", - "versions/2.0.2/en/building-blocks/permission-system", - "versions/2.0.2/en/building-blocks/middleware", - "versions/2.0.2/en/building-blocks/workspace" + "agentscope/2.0.2/en/building-blocks/message-and-event", + "agentscope/2.0.2/en/building-blocks/agent", + "agentscope/2.0.2/en/building-blocks/model", + "agentscope/2.0.2/en/building-blocks/context", + "agentscope/2.0.2/en/building-blocks/tool", + "agentscope/2.0.2/en/building-blocks/permission-system", + "agentscope/2.0.2/en/building-blocks/middleware", + "agentscope/2.0.2/en/building-blocks/workspace" ] }, { "group": "Deploy", "pages": [ - "versions/2.0.2/en/deploy/agent-service", - "versions/2.0.2/en/deploy/agent-team", + "agentscope/2.0.2/en/deploy/agent-service", + "agentscope/2.0.2/en/deploy/agent-team", { "group": "API", - "openapi": "versions/2.0.2/en/deploy/openapi.json" + "openapi": "agentscope/2.0.2/en/deploy/openapi.json" } ] }, { "group": "Others", "pages": [ - "versions/2.0.2/en/others/faq" + "agentscope/2.0.2/en/others/faq" ] } ] - } - ] - }, - { - "version": "1.0.21", - "tabs": [ + }, { - "tab": "Guides", + "version": "1.0.21", "groups": [ { "group": "Get Started", "pages": [ - "versions/1.0.21/en/index", - "versions/1.0.21/en/quickstart" + "agentscope/1.0.21/en/index", + "agentscope/1.0.21/en/quickstart" ] }, { "group": "Tutorial", "pages": [ - "versions/1.0.21/en/tutorial/tutorial_research_agent", - "versions/1.0.21/en/tutorial/tutorial_sales_agent" + "agentscope/1.0.21/en/tutorial/tutorial_research_agent", + "agentscope/1.0.21/en/tutorial/tutorial_sales_agent" ] }, { "group": "Out-of-box Agents", "pages": [ - "versions/1.0.21/en/out-of-box-agents/alias", - "versions/1.0.21/en/out-of-box-agents/browser-use", - "versions/1.0.21/en/out-of-box-agents/deep-research", - "versions/1.0.21/en/out-of-box-agents/alias-finance", - "versions/1.0.21/en/out-of-box-agents/data-science", - "versions/1.0.21/en/out-of-box-agents/datajuicer-agent", - "versions/1.0.21/en/out-of-box-agents/evo-trader" + "agentscope/1.0.21/en/out-of-box-agents/alias", + "agentscope/1.0.21/en/out-of-box-agents/browser-use", + "agentscope/1.0.21/en/out-of-box-agents/deep-research", + "agentscope/1.0.21/en/out-of-box-agents/alias-finance", + "agentscope/1.0.21/en/out-of-box-agents/data-science", + "agentscope/1.0.21/en/out-of-box-agents/datajuicer-agent", + "agentscope/1.0.21/en/out-of-box-agents/evo-trader" ] }, { "group": "Basic Concepts", "pages": [ - "versions/1.0.21/en/basic-concepts/msg", - "versions/1.0.21/en/basic-concepts/agent", - "versions/1.0.21/en/basic-concepts/model", - "versions/1.0.21/en/basic-concepts/context-and-memory", - "versions/1.0.21/en/basic-concepts/tool" + "agentscope/1.0.21/en/basic-concepts/msg", + "agentscope/1.0.21/en/basic-concepts/agent", + "agentscope/1.0.21/en/basic-concepts/model", + "agentscope/1.0.21/en/basic-concepts/context-and-memory", + "agentscope/1.0.21/en/basic-concepts/tool" ] }, { "group": "Building Blocks", "pages": [ - "versions/1.0.21/en/building-blocks/agent", - "versions/1.0.21/en/building-blocks/models", - "versions/1.0.21/en/building-blocks/context-and-memory", - "versions/1.0.21/en/building-blocks/rag", - "versions/1.0.21/en/building-blocks/tool-capabilities", - "versions/1.0.21/en/building-blocks/hooking-functions", - "versions/1.0.21/en/building-blocks/orchestration" + "agentscope/1.0.21/en/building-blocks/agent", + "agentscope/1.0.21/en/building-blocks/models", + "agentscope/1.0.21/en/building-blocks/context-and-memory", + "agentscope/1.0.21/en/building-blocks/rag", + "agentscope/1.0.21/en/building-blocks/tool-capabilities", + "agentscope/1.0.21/en/building-blocks/hooking-functions", + "agentscope/1.0.21/en/building-blocks/orchestration" ] }, { "group": "Observe & Evaluate", "pages": [ - "versions/1.0.21/en/observe-and-evaluate/observability", - "versions/1.0.21/en/observe-and-evaluate/evaluation" + "agentscope/1.0.21/en/observe-and-evaluate/observability", + "agentscope/1.0.21/en/observe-and-evaluate/evaluation" ] }, { "group": "Tune Agent", "pages": [ - "versions/1.0.21/en/tune-agent/tune-your-first-agent", - "versions/1.0.21/en/tune-agent/model-selection-tuning", - "versions/1.0.21/en/tune-agent/prompt-tuning", - "versions/1.0.21/en/tune-agent/model-weights-tuning", - "versions/1.0.21/en/tune-agent/tune-multi-agents" + "agentscope/1.0.21/en/tune-agent/tune-your-first-agent", + "agentscope/1.0.21/en/tune-agent/model-selection-tuning", + "agentscope/1.0.21/en/tune-agent/prompt-tuning", + "agentscope/1.0.21/en/tune-agent/model-weights-tuning", + "agentscope/1.0.21/en/tune-agent/tune-multi-agents" ] }, { "group": "Deploy & Serve", "pages": [ - "versions/1.0.21/en/deploy-and-serve/agent-as-service", + "agentscope/1.0.21/en/deploy-and-serve/agent-as-service", { "group": "API", - "openapi": "versions/2.0.2/en/deploy/openapi.json" + "openapi": "agentscope/2.0.2/en/deploy/openapi.json" } ] }, { "group": "Others", "pages": [ - "versions/1.0.21/en/others/faq" + "agentscope/1.0.21/en/others/faq" + ] + } + ] + } + ] + }, + { + "tab": "ReMe", + "versions": [ + { + "version": "0.4.0.6", + "groups": [ + { + "group": "Get Started", + "pages": [ + "reme/0.4.0.6/en/index", + "reme/0.4.0.6/en/overview", + "reme/0.4.0.6/en/quickstart", + "reme/0.4.0.6/en/concepts" + ] + }, + { + "group": "Integrate", + "pages": [ + "reme/0.4.0.6/en/guides/index", + "reme/0.4.0.6/en/guides/claude-code", + "reme/0.4.0.6/en/guides/qwenpaw" + ] + }, + { + "group": "Reference & Contribute", + "pages": [ + "reme/0.4.0.6/en/reference", + "reme/0.4.0.6/en/support", + "reme/0.4.0.6/en/contributing" ] } ] @@ -318,210 +333,230 @@ }, { "language": "zh", - "versions": [ + "tabs": [ { - "version": "2.0.5dev", - "tabs": [ + "tab": "AgentScope", + "versions": [ { - "tab": "指南", + "version": "2.0.5dev", "groups": [ { "group": "快速开始", "pages": [ - "versions/2.0.5dev/zh/index", - "versions/2.0.5dev/zh/quickstart", - "versions/2.0.5dev/zh/release-notes" + "agentscope/2.0.5dev/zh/index", + "agentscope/2.0.5dev/zh/quickstart", + "agentscope/2.0.5dev/zh/release-notes" ] }, { "group": "核心模块", "pages": [ - "versions/2.0.5dev/zh/building-blocks/message-and-event", - "versions/2.0.5dev/zh/building-blocks/agent", - "versions/2.0.5dev/zh/building-blocks/model", - "versions/2.0.5dev/zh/building-blocks/context", - "versions/2.0.5dev/zh/building-blocks/tool", - "versions/2.0.5dev/zh/building-blocks/plan", - "versions/2.0.5dev/zh/building-blocks/permission-system", - "versions/2.0.5dev/zh/building-blocks/middleware", - "versions/2.0.5dev/zh/building-blocks/rag", - "versions/2.0.5dev/zh/building-blocks/long-term-memory", - "versions/2.0.5dev/zh/building-blocks/workspace" + "agentscope/2.0.5dev/zh/building-blocks/message-and-event", + "agentscope/2.0.5dev/zh/building-blocks/agent", + "agentscope/2.0.5dev/zh/building-blocks/model", + "agentscope/2.0.5dev/zh/building-blocks/context", + "agentscope/2.0.5dev/zh/building-blocks/tool", + "agentscope/2.0.5dev/zh/building-blocks/plan", + "agentscope/2.0.5dev/zh/building-blocks/permission-system", + "agentscope/2.0.5dev/zh/building-blocks/middleware", + "agentscope/2.0.5dev/zh/building-blocks/rag", + "agentscope/2.0.5dev/zh/building-blocks/long-term-memory", + "agentscope/2.0.5dev/zh/building-blocks/workspace" ] }, { "group": "智能体即服务", "pages": [ - "versions/2.0.5dev/zh/deploy/agent-service", - "versions/2.0.5dev/zh/deploy/agent-team", - "versions/2.0.5dev/zh/deploy/sharing", - "versions/2.0.5dev/zh/deploy/rag", - "versions/2.0.5dev/zh/deploy/workspace-manager", + "agentscope/2.0.5dev/zh/deploy/agent-service", + "agentscope/2.0.5dev/zh/deploy/agent-team", + "agentscope/2.0.5dev/zh/deploy/sharing", + "agentscope/2.0.5dev/zh/deploy/rag", + "agentscope/2.0.5dev/zh/deploy/workspace-manager", { "group": "API", - "openapi": "versions/2.0.5dev/en/deploy/openapi.json" + "openapi": "agentscope/2.0.5dev/en/deploy/openapi.json" } ] }, { "group": "其他", "pages": [ - "versions/2.0.5dev/zh/others/faq", - "versions/2.0.5dev/zh/others/change-log" + "agentscope/2.0.5dev/zh/others/faq", + "agentscope/2.0.5dev/zh/others/change-log" ] } ] - } - ] - }, - { - "version": "2.0.4", - "tabs": [ + }, { - "tab": "指南", + "version": "2.0.4", "groups": [ { "group": "快速开始", "pages": [ - "versions/2.0.4/zh/index", - "versions/2.0.4/zh/quickstart", - "versions/2.0.4/zh/release-notes" + "agentscope/2.0.4/zh/index", + "agentscope/2.0.4/zh/quickstart", + "agentscope/2.0.4/zh/release-notes" ] }, { "group": "核心模块", "pages": [ - "versions/2.0.4/zh/building-blocks/message-and-event", - "versions/2.0.4/zh/building-blocks/agent", - "versions/2.0.4/zh/building-blocks/model", - "versions/2.0.4/zh/building-blocks/context", - "versions/2.0.4/zh/building-blocks/tool", - "versions/2.0.4/zh/building-blocks/plan", - "versions/2.0.4/zh/building-blocks/permission-system", - "versions/2.0.4/zh/building-blocks/middleware", - "versions/2.0.4/zh/building-blocks/rag", - "versions/2.0.4/zh/building-blocks/long-term-memory", - "versions/2.0.4/zh/building-blocks/workspace" + "agentscope/2.0.4/zh/building-blocks/message-and-event", + "agentscope/2.0.4/zh/building-blocks/agent", + "agentscope/2.0.4/zh/building-blocks/model", + "agentscope/2.0.4/zh/building-blocks/context", + "agentscope/2.0.4/zh/building-blocks/tool", + "agentscope/2.0.4/zh/building-blocks/plan", + "agentscope/2.0.4/zh/building-blocks/permission-system", + "agentscope/2.0.4/zh/building-blocks/middleware", + "agentscope/2.0.4/zh/building-blocks/rag", + "agentscope/2.0.4/zh/building-blocks/long-term-memory", + "agentscope/2.0.4/zh/building-blocks/workspace" ] }, { "group": "智能体即服务", "pages": [ - "versions/2.0.4/zh/deploy/agent-service", - "versions/2.0.4/zh/deploy/agent-team", - "versions/2.0.4/zh/deploy/rag", + "agentscope/2.0.4/zh/deploy/agent-service", + "agentscope/2.0.4/zh/deploy/agent-team", + "agentscope/2.0.4/zh/deploy/rag", { "group": "API", - "openapi": "versions/2.0.4/en/deploy/openapi.json" + "openapi": "agentscope/2.0.4/en/deploy/openapi.json" } ] }, { "group": "其他", "pages": [ - "versions/2.0.4/zh/others/faq", - "versions/2.0.4/zh/others/change-log" + "agentscope/2.0.4/zh/others/faq", + "agentscope/2.0.4/zh/others/change-log" ] } ] - } - ] - }, - { - "version": "2.0.3", - "tabs": [ + }, { - "tab": "指南", + "version": "2.0.3", "groups": [ { "group": "快速开始", "pages": [ - "versions/2.0.3/zh/index", - "versions/2.0.3/zh/quickstart", - "versions/2.0.3/zh/release-notes" + "agentscope/2.0.3/zh/index", + "agentscope/2.0.3/zh/quickstart", + "agentscope/2.0.3/zh/release-notes" ] }, { "group": "核心模块", "pages": [ - "versions/2.0.3/zh/building-blocks/message-and-event", - "versions/2.0.3/zh/building-blocks/agent", - "versions/2.0.3/zh/building-blocks/model", - "versions/2.0.3/zh/building-blocks/context", - "versions/2.0.3/zh/building-blocks/tool", - "versions/2.0.3/zh/building-blocks/plan", - "versions/2.0.3/zh/building-blocks/permission-system", - "versions/2.0.3/zh/building-blocks/middleware", - "versions/2.0.3/zh/building-blocks/rag", - "versions/2.0.3/zh/building-blocks/long-term-memory", - "versions/2.0.3/zh/building-blocks/workspace" + "agentscope/2.0.3/zh/building-blocks/message-and-event", + "agentscope/2.0.3/zh/building-blocks/agent", + "agentscope/2.0.3/zh/building-blocks/model", + "agentscope/2.0.3/zh/building-blocks/context", + "agentscope/2.0.3/zh/building-blocks/tool", + "agentscope/2.0.3/zh/building-blocks/plan", + "agentscope/2.0.3/zh/building-blocks/permission-system", + "agentscope/2.0.3/zh/building-blocks/middleware", + "agentscope/2.0.3/zh/building-blocks/rag", + "agentscope/2.0.3/zh/building-blocks/long-term-memory", + "agentscope/2.0.3/zh/building-blocks/workspace" ] }, { "group": "智能体即服务", "pages": [ - "versions/2.0.3/zh/deploy/agent-service", - "versions/2.0.3/zh/deploy/agent-team", - "versions/2.0.3/zh/deploy/rag", + "agentscope/2.0.3/zh/deploy/agent-service", + "agentscope/2.0.3/zh/deploy/agent-team", + "agentscope/2.0.3/zh/deploy/rag", { "group": "API", - "openapi": "versions/2.0.3/en/deploy/openapi.json" + "openapi": "agentscope/2.0.3/en/deploy/openapi.json" } ] }, { "group": "其他", "pages": [ - "versions/2.0.3/zh/others/faq", - "versions/2.0.3/zh/others/change-log" + "agentscope/2.0.3/zh/others/faq", + "agentscope/2.0.3/zh/others/change-log" ] } ] - } - ] - }, - { - "version": "2.0.2", - "tabs": [ + }, { - "tab": "指南", + "version": "2.0.2", "groups": [ { "group": "快速开始", "pages": [ - "versions/2.0.2/zh/index", - "versions/2.0.2/zh/quickstart", - "versions/2.0.2/zh/change-log" + "agentscope/2.0.2/zh/index", + "agentscope/2.0.2/zh/quickstart", + "agentscope/2.0.2/zh/change-log" ] }, { "group": "核心模块", "pages": [ - "versions/2.0.2/zh/building-blocks/message-and-event", - "versions/2.0.2/zh/building-blocks/agent", - "versions/2.0.2/zh/building-blocks/model", - "versions/2.0.2/zh/building-blocks/context", - "versions/2.0.2/zh/building-blocks/tool", - "versions/2.0.2/zh/building-blocks/permission-system", - "versions/2.0.2/zh/building-blocks/middleware", - "versions/2.0.2/zh/building-blocks/workspace" + "agentscope/2.0.2/zh/building-blocks/message-and-event", + "agentscope/2.0.2/zh/building-blocks/agent", + "agentscope/2.0.2/zh/building-blocks/model", + "agentscope/2.0.2/zh/building-blocks/context", + "agentscope/2.0.2/zh/building-blocks/tool", + "agentscope/2.0.2/zh/building-blocks/permission-system", + "agentscope/2.0.2/zh/building-blocks/middleware", + "agentscope/2.0.2/zh/building-blocks/workspace" ] }, { "group": "部署", "pages": [ - "versions/2.0.2/zh/deploy/agent-service", - "versions/2.0.2/zh/deploy/agent-team", + "agentscope/2.0.2/zh/deploy/agent-service", + "agentscope/2.0.2/zh/deploy/agent-team", { "group": "API", - "openapi": "versions/2.0.2/en/deploy/openapi.json" + "openapi": "agentscope/2.0.2/en/deploy/openapi.json" } ] }, { "group": "其他", "pages": [ - "versions/2.0.2/zh/others/faq" + "agentscope/2.0.2/zh/others/faq" + ] + } + ] + } + ] + }, + { + "tab": "ReMe", + "versions": [ + { + "version": "0.4.0.6", + "groups": [ + { + "group": "快速开始", + "pages": [ + "reme/0.4.0.6/zh/index", + "reme/0.4.0.6/zh/overview", + "reme/0.4.0.6/zh/quickstart", + "reme/0.4.0.6/zh/concepts" + ] + }, + { + "group": "接入", + "pages": [ + "reme/0.4.0.6/zh/guides/index", + "reme/0.4.0.6/zh/guides/claude-code", + "reme/0.4.0.6/zh/guides/qwenpaw" + ] + }, + { + "group": "查阅与参与", + "pages": [ + "reme/0.4.0.6/zh/reference", + "reme/0.4.0.6/zh/support", + "reme/0.4.0.6/zh/contributing" ] } ] @@ -564,13 +599,25 @@ ] }, "redirects": [ + { + "source": "/versions/:slug*", + "destination": "/agentscope/:slug*" + }, { "source": "/latest/:slug*", - "destination": "/versions/2.0.5dev/:slug*" + "destination": "/agentscope/2.0.5dev/:slug*" }, { "source": "/stable/:slug*", - "destination": "/versions/2.0.4/:slug*" + "destination": "/agentscope/2.0.4/:slug*" + }, + { + "source": "/reme/latest/:slug*", + "destination": "/reme/0.4.0.6/:slug*" + }, + { + "source": "/reme/stable/:slug*", + "destination": "/reme/0.4.0.6/:slug*" } ], "footer": { diff --git a/images/reme/auto-dream-and-proactive.svg b/images/reme/auto-dream-and-proactive.svg new file mode 100644 index 0000000..0206f49 --- /dev/null +++ b/images/reme/auto-dream-and-proactive.svg @@ -0,0 +1,129 @@ + + ReMe auto dream and proactive flow + A left-to-right flow from changed daily notes to digest integration, interest topic writing, catalog checkpointing, and proactive reads. + + + + + + + + + + + + Auto Dream and Proactive + Scan changed daily memory, integrate reusable units into digest, then expose proactive topics. + + + + 1 + Extract + dream_extract_step + + refresh index + daily/<date>.md + + compare catalog + changed daily + + LLM extract + units + topics + + + + 2 + Integrate + dream_integrate_step + + node_search + recall digest + + auto link + dedup + links + + write digest + create / update + + + + 3 + Topics + dream_topics_step + + merge topics + same day kept + + avoid repeats + last 7 days + + write YAML + interests.yaml + + + + 4 + Finish + dream_finish_step + + checkpoint + skip failures + + persist catalog + file_catalog + + return summary + counts + errors + + + + 5 + Proactive + proactive_step + + read YAML + interests.yaml + + return topics + metadata + + agent decides + whether to notify + + + + + + + + Inputs + daily/<date>.md and daily/<date>/**/*.md + + Long-term memory + digest/procedure, digest/personal, digest/wiki + + Proactive material + daily/<date>/interests.yaml + + Boundary + Read only; caller decides + + + proactive reads interests.yaml after auto_dream writes it + diff --git a/images/reme/auto-index-and-memory-search.svg b/images/reme/auto-index-and-memory-search.svg new file mode 100644 index 0000000..ae44f88 --- /dev/null +++ b/images/reme/auto-index-and-memory-search.svg @@ -0,0 +1,98 @@ + + ReMe auto index and memory search flow + A concise left-to-right flow from automatic workspace indexing to memory search and progressive link expansion. + + + + + + + + + + + + Auto Index and Memory Search + Keep workspace indexes fresh, recall relevant chunks, then expand nearby wikilink context. + + + + 1 + Watch memory + index_update_loop + + daily / digest / resource + md and jsonl files + + init + watch changes + added / modified / deleted + + + + 2 + Build index + update_index_step + + chunk file + FileNode + FileChunk[] + + store structures + BM25 + graph + chunks + + + + 3 + Recall chunks + search_step + + BM25 search + keyword-ranked chunks + + optional vector search + RRF fusion when enabled + + + + 4 + Expand context + expand_links + + top chunks + path + line range + + outlinks + inlinks + name, description, via + + + + + + + Default path + BM25 first, vector optional. + + BM25 is enabled by default + embedding_store is empty unless configured. + + Results stay compact first + Use read or traverse for deeper expansion. + + + link expansion is contextual, not a full-workspace dump + diff --git a/images/reme/auto-memory-resource.svg b/images/reme/auto-memory-resource.svg new file mode 100644 index 0000000..4fa22dc --- /dev/null +++ b/images/reme/auto-memory-resource.svg @@ -0,0 +1,91 @@ + + ReMe auto memory and auto resource flow + A concise flow where auto memory and auto resource both create daily cards, which are indexed in the daily memory layer and then used by dream and search. + + + + + + + + + + + + Auto Memory & Auto Resource + Two ingestion paths create daily cards, then share one daily index and downstream memory flow. + + + + 1 + Inputs + memory + resource + + Auto Memory + conversation -> session daily card + + Auto Resource + dated file -> resource daily card + + original sources remain verifiable + + + + 2 + Daily Memory Layer + daily/<date>/ + + daily cards + facts, context, actions + + day index + daily/<date>.md links cards + + one readable daily memory stream + + + + 3 + Downstream + dream + search + + Auto Dream + daily material -> digest memory + + Memory Search + retrieve daily and digest nodes + + daily is the shared ingestion layer + + + + + + Conversation source + session/dialog/<session_id>.jsonl + + Resource source + resource/<date>/<resource_file> + + Daily output + daily cards plus daily/<date>.md + + + downstream flows read the same daily memory layer + diff --git a/images/reme/cc-auto-dream.gif b/images/reme/cc-auto-dream.gif new file mode 100644 index 0000000..8106b0c Binary files /dev/null and b/images/reme/cc-auto-dream.gif differ diff --git a/images/reme/cc-auto-memory.gif b/images/reme/cc-auto-memory.gif new file mode 100644 index 0000000..efc4088 Binary files /dev/null and b/images/reme/cc-auto-memory.gif differ diff --git a/images/reme/design-philosophy.svg b/images/reme/design-philosophy.svg new file mode 100644 index 0000000..2369290 --- /dev/null +++ b/images/reme/design-philosophy.svg @@ -0,0 +1,97 @@ + + ReMe design philosophy + A simple diagram showing ReMe's design philosophy: file-native memory, progressive abstraction, and explicit relationship graph for agents. + + + + + + + + + + + + ReMe Design Philosophy + File-native memory, progressive abstraction, and explicit links for reusable agent context. + + + Foundation: Memory as File + Readable, editable knowledge assets + + + + + + + Markdown + + YAML/JSONL + + Human-readable. Agent-operable. + + + Core: Progressive Abstraction + From raw material to durable memory + + + Raw + + Daily + + Digest + + + + session/ + resource/ -> daily/ -> digest/ + Continuous consolidation, not one-shot summary. + + + Innovation: Link Graph + Explicit links expand context + + + + + + + + + + [[ ]] + Node + Src + Risk + Dep + + Beyond similarity: source, cause, dependency, risk. + Wikilinks guide expansion across nodes. + + + + + + One shared file tree acts as both memory store and operating surface. + capture -> refine -> link -> retrieve -> expand + + + + diff --git a/images/reme/framework-structure.svg b/images/reme/framework-structure.svg new file mode 100644 index 0000000..e35ec4f --- /dev/null +++ b/images/reme/framework-structure.svg @@ -0,0 +1,158 @@ + + ReMe framework structure + An architectural map of ReMe from file-backed workspace storage through knowledge kernel, workflows, application wiring, and external service surfaces. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ReMe Framework Structure + File-backed memory, searchable knowledge kernel, composable jobs, app wiring, and public service surfaces. + + + + + + Service + Public interfaces + + + HTTP API + server routes + + MCP Tools + agent actions + + CLI Client + local access + + + + + + + Application + Config, wiring, lifecycle + + + Context + + Wiring + + Lifecycle + + Job APIs + + + + + + + Steps / Jobs + Composable workflows + + + Jobs + base · stream · background · cron + + Step Modules + file_io · index · evolve · transfer · channel · common + + + + + + + Knowledge Kernel + Index, watch, schema + + + Index Stores + file_store · keyword_index + embedding_store · file_graph + + File Watcher + scanner · chunker + catalog + + Memory + FileNode + FileChunk · FileLink + + + + + + + Workspace Layout + File-backed memory + + + daily/ + working notes + + digest/ + long-term + + resource/ + resources + + metadata/ + state + + + EXTERNAL SURFACES + PERSISTENT MEMORY BASE + Structure reads bottom-up during boot and top-down during use. + Workspace files feed the kernel; workflows compose operations; application wiring exposes stable service entry points. + diff --git a/images/reme/memory-as-file.svg b/images/reme/memory-as-file.svg new file mode 100644 index 0000000..2dee7b5 --- /dev/null +++ b/images/reme/memory-as-file.svg @@ -0,0 +1,110 @@ + + ReMe memory as file model + A diagram showing ReMe workspace files as both a human readable memory interface and an agent operable memory graph, flowing from raw input to daily notes, digest nodes, and metadata indexes. + + + + + + + + + + + + Memory as File + Workspace files are the readable memory surface and the operable graph/index substrate. + + + + Human + Read and edit files + Markdown, YAML, JSONL, resources + + open, revise, move, delete + + + Workspace directory + the shared memory interface + + Memory as File + + File as Memory + + + + Agent + Parse and operate graph + frontmatter, chunks, wikilinks + + search, link, rewrite, index + + + + + people and agents see the same file tree, so edits and evidence links stay inspectable + + + + 1 + Raw input + keep the original scene + + session/ + resource/ + + + + 2 + Daily + shallow working memory + + daily/YYYY-MM-DD/*.md + + + + 3 + Digest + long-term reusable nodes + + personal / procedure / wiki + + + + 4 + Metadata + system state and indexes + + catalog + chunks + links + + + + + + + + + Stable paths + + workspace-relative wikilinks + + derived_from evidence edges + + search expands structure and links + diff --git a/images/reme/qwenpaw-auto-dream.gif b/images/reme/qwenpaw-auto-dream.gif new file mode 100644 index 0000000..79cd9b7 Binary files /dev/null and b/images/reme/qwenpaw-auto-dream.gif differ diff --git a/images/reme/qwenpaw-auto-memory.gif b/images/reme/qwenpaw-auto-memory.gif new file mode 100644 index 0000000..0ca2f4e Binary files /dev/null and b/images/reme/qwenpaw-auto-memory.gif differ diff --git a/images/reme/reme-overview.svg b/images/reme/reme-overview.svg new file mode 100644 index 0000000..6b96431 --- /dev/null +++ b/images/reme/reme-overview.svg @@ -0,0 +1,204 @@ + + ReMe overview + A hand-drawn style overview of ReMe, showing Auto Memory plus Auto Resource, Auto Dream plus Proactive, Auto Index plus Memory Search, and Memory as File. + + + + + + + + + + + + ReMe + A file-native memory loop: capture, consolidate, link, search, and proactively surface what matters. + + + + + Auto Memory + Auto Resource + Capture sessions and resources into daily cards. + + + + Auto + Memory + + + Capture + chat + + + Write + daily + + + + + + + Auto + Resource + + + Read + source + + + Write + daily + + + + + + + + Auto Dream + Proactive + Consolidate notes, link knowledge, surface interests. + + + Extract + changed files + + + Auto Link + dedupe + edges + + + Integrate + write digest + + + Proactive + interests.yaml + + + + + + + + + + Auto Index + Memory Search + Keep indexes fresh, recall chunks, then follow links. + + + + Auto Index + + + Watch + changes + + + Build + index + + + + + + + Memory Search + + + Recall + BM25 + vec + + + Expand + links + + + + + + + + + + + + Memory as File + Every memory is readable, editable, indexable, linkable, and auditable as files. + + + + + + + .json + + + session/ + raw session logs + + + + + + + + .md + + + resource/ + raw material with source + + + + + + + + .md + + + daily/ + working memory cards + + + + + + + + .md + + + digest/ + long-term knowledge nodes + + + + + + diff --git a/images/reme/reme_logo.png b/images/reme/reme_logo.png new file mode 100644 index 0000000..5fcf03b Binary files /dev/null and b/images/reme/reme_logo.png differ diff --git a/reme/0.4.0.6/en/concepts.mdx b/reme/0.4.0.6/en/concepts.mdx new file mode 100644 index 0000000..0d4901f --- /dev/null +++ b/reme/0.4.0.6/en/concepts.mdx @@ -0,0 +1,77 @@ +--- +title: "Memory Should Belong to the User" +description: "The principles and trade-offs behind ReMe's file-native agent memory." +--- + +ReMe is not defined by one retrieval algorithm or pipeline. It starts from a set of judgments about long-term agent memory: users should own it, it should grow from experience, and people and agents should be able to understand and correct it together. + +## Design Philosophy + +ReMe is not a stack of features but a derivation grounded in cognitive science: a hierarchical file pipeline derived from complementary learning systems and event-construction theory, biomimetic links motivated by spreading activation theory, and a shared extended mind between human and agent. + +### Brain-Inspired Multi-Level Processing + +Human memory is not a single container but a multi-level processing system. Complementary learning systems (CLS) theory holds that the hippocampus rapidly binds new experience while the neocortex slowly consolidates general knowledge—each requiring its own representational space and a time-extended transfer process. ReMe translates this into a four-layer processing cascade: + +- `resource/`: early preprocessing of cross-modal materials +- `session/`: event-structured records of interactions +- `daily/`: episodic cards retaining spatiotemporal context +- `digest/`: long-term semantic knowledge untethered from time + +This layering lets memory grow from raw experience while progressively refining reusable understanding, rather than accumulating conflicts and stale information in flat storage. + +### Biomimetic Links and the Extended Mind + +Spreading activation theory calls for explicit, traversable semantic associations. ReMe replaces traditional foreign keys with Wikilinks, organizing four file layers into a readable and editable semantic network. Each link not only points to a concrete file but also externalizes an associative path, making the network topology itself part of the cognitive process. + +The extended-mind hypothesis holds that external tools can become part of a cognitive system. Markdown serves as a cognitive prosthesis: users can edit files directly, and editing itself is a form of generative re-encoding. ReMe treats memory as a knowledge garden co-built by human and agent—readability and editability are central to cognitive quality, not peripheral. + +These theoretical judgments lead to concrete engineering choices: memory should exist as files, be refined from experience rather than naively stored, support joint human-agent understanding and correction, and maintain traceable associative structure. + +## Memory as File + +Long-term memory should not exist only as internal database rows or temporary prompt text. ReMe stores memory as local files that users can read, search, edit, move, delete, back up, and version with ordinary tools. + +Files do not exclude indexes. ReMe can build keyword, embedding, and link indexes over Markdown, but those indexes are rebuildable derived state. User-owned files remain the source of truth. + +This makes memory: + +- **transparent**: users can see what the agent remembers; +- **controllable**: incorrect, stale, or sensitive memory can be corrected or removed; +- **portable**: memory is not locked to one database, model, or agent framework. + +## Memory from Experience + +Saving every message is not the same as remembering. Raw conversations are valuable evidence but poor durable understanding; endlessly appended summaries become repetitive, contradictory, and stale. + +ReMe separates sources, daily notes, and durable memory. It preserves what happened, then refines facts, preferences, procedures, and knowledge worth reusing. New experience can extend, merge, or correct older understanding. + +A memory system therefore needs refinement and forgetting as well as writing. Its value comes from helping future action, not from the number of files or tokens stored. + +## Human-Agent Shared Memory + +Markdown is the shared surface between people and agents. Agents can refine, link, and recall automatically; users can always inspect and make the final correction. + +That collaboration requires boundaries: + +- do not store sensitive information merely because it might be useful; +- preserve relevant sources and context when changing a conclusion; +- do not treat retrieval output as unquestionable truth; +- let the host agent decide when and how to act on memory. + +## Connected and Traceable + +Isolated fragments rarely explain how a decision formed. Links express both source and related context, allowing an agent to expand a useful hit and a user to verify durable conclusions against original material. + +Traceability does not mean retaining everything. It means keeping enough evidence for important understanding, and allowing memories to change when sources disappear, judgments evolve, or a user asks to forget. + +## Trade-offs + +ReMe deliberately favors: + +- file transparency over fully opaque automation; +- user control over unbounded collection; +- correctable understanding over lossless retention of all context; +- open integration contracts over commitment to one agent framework. + +Auto Memory, Auto Resource, Auto Dream, BM25, embeddings, and wikilinks are current implementation choices—not the philosophy itself. Read `reme/`, `reme/config/default.yaml`, and `tests/` for the current mechanics. diff --git a/reme/0.4.0.6/en/contributing.mdx b/reme/0.4.0.6/en/contributing.mdx new file mode 100644 index 0000000..bb384cb --- /dev/null +++ b/reme/0.4.0.6/en/contributing.mdx @@ -0,0 +1,77 @@ +--- +title: "Contributing" +description: "Set up ReMe development, run tests, and prepare a pull request." +--- + +ReMe welcomes bug fixes, tests, documentation, and features. Before a substantial change, search or open a [GitHub Issue](https://github.com/agentscope-ai/ReMe/issues) to align on user behavior, compatibility, and test scope. + +## Development Setup + +ReMe requires Python 3.11 or newer: + +```bash +git clone https://github.com/agentscope-ai/ReMe.git +cd ReMe +python -m venv .venv +source .venv/bin/activate +pip install -e ".[full]" +pre-commit install +``` + +## Code Map + +```text +reme/ +├── reme.py CLI entrypoint +├── application.py application assembly and lifecycle +├── config/ defaults and configuration parsing +├── components/ services, clients, stores, and reusable components +├── steps/ atomic steps behind actions and background flows +├── schema/ configuration, request, response, and persistent models +└── utils/ shared utilities + +tests/ +├── unit/ fast, isolated behavior tests +└── integration/ cross-component and external-dependency tests +``` + +Source and tests are the authoritative architecture and extension guide. Before adding a capability, find adjacent implementations, abstract bases, registration paths, and tests instead of copying a pattern from a static architecture manual. + +## Local Checks + +Before submitting, run at least: + +```bash +pre-commit run --all-files +pytest +``` + +During development, run focused tests first: + +```bash +pytest tests/unit/test_reme_cli.py +pytest tests/unit -q +``` + +Tests using an LLM, embeddings, or an external service may need extra environment variables. If they cannot run locally, state why and describe substitute validation in the PR. + +## Change Requirements + +- Include a reproducing regression test with a bug fix. +- Update job schemas and entrypoint tests when changing an action. +- Keep the default configuration launchable and test merge and compatibility behavior. +- Consider existing workspaces when changing files, indexes, wikilinks, or persistent schemas. +- Update the relevant page when user-visible installation, integration, stable contracts, or troubleshooting behavior changes. +- Keep implementation details in code comments and tests; do not create a manual page for every class or step. + +## Pull Requests + +A PR should explain: + +1. the user-observable problem and change; +2. why this implementation was chosen; +3. tests that were run; +4. configuration, data, and compatibility impact; +5. remaining limitations. + +Use a concise Conventional Commit-style title such as `fix(search): rebuild stale link index`. Keep roadmap and design discussion in Issues / Project, and publish version changes through [GitHub Releases](https://github.com/agentscope-ai/ReMe/releases). diff --git a/reme/0.4.0.6/en/guides/claude-code.mdx b/reme/0.4.0.6/en/guides/claude-code.mdx new file mode 100644 index 0000000..2f55d46 --- /dev/null +++ b/reme/0.4.0.6/en/guides/claude-code.mdx @@ -0,0 +1,77 @@ +--- +title: "Integrate Claude Code" +description: "Add ReMe recall and automatic session recording to Claude Code." +--- + +The ReMe Claude Code plugin provides two paths: MCP tools recall memory, while a Stop hook records the transcript asynchronously after a session ends. + +## Prerequisites + +Install ReMe through [Quick Start](/reme/0.4.0.6/en/quickstart). Automatic session refinement also requires `LLM_API_KEY` and `LLM_BASE_URL` in the launch environment. + +## 1. Start the MCP Service + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +The default endpoint is `http://127.0.0.1:2333/mcp`. Keep this shared service running; multiple Claude Code windows can use it. + +## 2. Install the Plugin + +In Claude Code, add this repository's `plugins` directory as a marketplace and install ReMe: + +```text +/plugin marketplace add ./plugins +/plugin install reme@reme-marketplace +``` + +Restart Claude Code and run `/mcp`. Confirm that the `reme` server and tools are connected. + +The plugin contains: + +```text +plugins/reme/ +├── .mcp.json MCP service URL +├── hooks/auto_memory.py Stop hook +└── skills/reme-memory/SKILL.md recall behavior +``` + +Replace the marketplace path when the repository is elsewhere. See [`plugins/README.md`](https://github.com/agentscope-ai/ReMe/blob/main/plugins/README.md) for package details. + +## 3. Verify Recall + +Write a distinctive memory from a terminal: + +```bash +reme write \ + path=digest/wiki/claude-code-check \ + name="Claude Code Check" \ + description="Claude Code integration check" \ + content="Project rule: run pytest before submitting changes." +``` + +Ask Claude Code, "What should I run before submitting changes in this project?" It should call ReMe `search` / `read` before answering. + +## 4. Verify Automatic Recording + +Have a conversation containing durable information, then end the session. The Stop hook calls `auto_memory_cc` in the background. After a short delay, search for a distinctive phrase: + +```bash +reme search query="" limit=5 +``` + +A successful run creates a card under `daily//`. The Stop hook is best-effort: an unavailable service does not block Claude Code and only produces a log entry. + +## Ports and Logs + +The service URL lives in `plugins/reme/.mcp.json`. If ReMe uses another port, update the URL too. `REME_HOST` and `REME_PORT` can override the hook connection. + +The hook log defaults to `plugins/reme/logs/auto_memory_hook.log`. For connection failures, start with: + +```bash +reme find_reme +reme health_check +``` + +See [Support](/reme/0.4.0.6/en/support) for more connection checks. diff --git a/reme/0.4.0.6/en/guides/index.mdx b/reme/0.4.0.6/en/guides/index.mdx new file mode 100644 index 0000000..c7270a2 --- /dev/null +++ b/reme/0.4.0.6/en/guides/index.mdx @@ -0,0 +1,66 @@ +--- +title: "Integrate ReMe" +description: "Choose among Skill, CLI, MCP, HTTP, and Python integration paths." +--- + +ReMe runs as a local memory service. Every integration method shares the same workspace; the difference is how an agent triggers search, file operations, and memory refinement. + +## Choose a Method + +| Method | Best for | Characteristics | +|---|---|---| +| Skill + CLI | Agents that execute commands and read `SKILL.md` | Lightest option, visible behavior rules, easy to debug | +| MCP | Agents with native MCP support | Automatic tool-schema discovery; a natural fit for Claude Code | +| HTTP | Custom applications and non-Python runtimes | Ordinary JSON calls across languages | +| Python | Deep, in-process integration | Reuses app lifecycle and model configuration at higher coupling | + +Start with Skill + CLI when unsure. Use MCP when the host supports it natively. Choose Python only when the host application needs to own the full lifecycle. + +## Shared Integration Contract + +Whichever protocol you use, the host agent should follow the same memory behavior: + +1. Before answering about earlier conversations, preferences, decisions, or project history, call `search`, then `read` relevant files. +2. Record only durable facts, preferences, decisions, and lessons. Do not store secrets or sensitive information by default. +3. Call `auto_memory` after a useful session or stable fact appears, using a stable `session_id`. +4. Let ReMe's cron run `auto_dream`, or trigger it from the host lifecycle. +5. ReMe returns memory; the host agent decides whether, when, and how to use it. + +The repository's [`skills/reme_memory/SKILL.md`](https://github.com/agentscope-ai/ReMe/blob/main/skills/reme_memory/SKILL.md) contains this contract. Install the complete `skills/reme_memory/` directory in an agent's skill directory to reuse it. + +## MCP + +Start a shared MCP service: + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +The default endpoint is `http://127.0.0.1:2333/mcp`. Add that URL to the MCP client, which discovers the tools exposed by the running version. Keep client and server ports aligned. + +MCP lets the model choose tools. Session recording and consolidation still belong in the host agent's hooks or lifecycle. + +## HTTP + +The default launch mode provides HTTP: + +```bash +reme start +``` + +Each served job maps to `POST /{action}` with a JSON body: + +```bash +curl -s http://127.0.0.1:2333/search \ + -H 'Content-Type: application/json' \ + -d '{"query":"project decisions","limit":5}' +``` + +Use `/docs` or `/openapi.json` on the running service for a schema that matches the installed version. + +## Maintained Integrations + +- [Claude Code](/reme/0.4.0.6/en/guides/claude-code): official plugin, MCP recall, and automatic recording through a Stop hook. +- [QwenPaw](/reme/0.4.0.6/en/guides/qwenpaw): ReMe skill integration with recording controlled by the application lifecycle. + +Before debugging an agent, run the write and search flow in [Quick Start](/reme/0.4.0.6/en/quickstart) to verify ReMe itself. diff --git a/reme/0.4.0.6/en/guides/qwenpaw.mdx b/reme/0.4.0.6/en/guides/qwenpaw.mdx new file mode 100644 index 0000000..245b324 --- /dev/null +++ b/reme/0.4.0.6/en/guides/qwenpaw.mdx @@ -0,0 +1,57 @@ +--- +title: "Integrate QwenPaw" +description: "Use the ReMe skill and QwenPaw lifecycle with file-native long-term memory." +--- + +QwenPaw can use ReMe through a skill that teaches the agent when to search, read, and record. ReMe handles persistence, indexing, and refinement behind that behavior contract. + +## 1. Start ReMe + +Complete [Quick Start](/reme/0.4.0.6/en/quickstart), then keep the default HTTP service running: + +```bash +reme start +``` + +Automatic conversation refinement and consolidation also require LLM environment variables. + +## 2. Install the ReMe Skill + +Install the repository's complete [`skills/reme_memory/`](https://github.com/agentscope-ai/ReMe/tree/main/skills/reme_memory) directory as a QwenPaw skill. The exact skill location and loading mechanism depend on the installed QwenPaw version; preserve `SKILL.md` and its behavior rules rather than copying only the example commands. + +Once loaded, QwenPaw should: + +- run `reme search`, then `reme read`, before answering about past conversations, preferences, decisions, or project history; +- call `reme auto_memory` for information with durable value; +- obtain explicit consent before storing sensitive information; +- supply a stable `session_id` from the QwenPaw session lifecycle. + + +The repository's `skills/qwenpaw_memory` is a separate convention that edits `MEMORY.md` and `memory/*.md` directly; it does not call the ReMe service. Use `skills/reme_memory` to integrate ReMe. + + +## 3. Verify + +Write a test memory in a terminal: + +```bash +reme write \ + path=digest/personal/qwenpaw-check \ + name="QwenPaw Check" \ + description="QwenPaw integration check" \ + content="User preference: lead with the conclusion when explaining technical topics." +``` + +Ask QwenPaw, "How do I prefer technical explanations?" Confirm that it searches ReMe and reads the file before answering. + +Next, tell QwenPaw one durable fact. After the session ends, run: + +```bash +reme search query="" limit=5 +``` + +If the installed QwenPaw version has no session-end hook, let the application call `auto_memory` explicitly or enable recall only. Do not have the model invent a missing complete message history. + +## Deep Integration + +An application that must reuse QwenPaw model configuration, message objects, and scheduling can call ReMe's Python objects or HTTP actions from its lifecycle. Those internals evolve with the code; use `reme/application.py`, `reme/schema/`, and current tests instead of a copied internal API manual. diff --git a/reme/0.4.0.6/en/index.mdx b/reme/0.4.0.6/en/index.mdx new file mode 100644 index 0000000..2a79cec --- /dev/null +++ b/reme/0.4.0.6/en/index.mdx @@ -0,0 +1,37 @@ +--- +title: "ReMe" +description: "A local-first, file-native memory layer for AI agents." +--- + +ReMe is a local-first memory layer for AI agents. It turns conversations and resources into readable, editable, and searchable Markdown, so users own their memory and can carry it across agents and sessions. + +![ReMe design philosophy](/images/reme/design-philosophy.svg) + + + + See what ReMe solves and where it does—or does not—fit. + + + Install, start, write, search, and inspect your first memory file. + + + Choose among Skill, CLI, MCP, HTTP, and Python integration. + + + +## Core Ideas + +- **Memory as File**: memory is a user-owned file, not hidden database state. +- **Memory from Experience**: long-term memory is refined and corrected, not an endless context dump. +- **Human-Agent Shared Memory**: people and agents work on the same visible, portable Markdown. +- **Connected and Traceable**: links provide context and trace durable conclusions back to sources. + +Read [Concepts](/reme/0.4.0.6/en/concepts) for the full philosophy and trade-offs. + +## Other Entrypoints + + + Workspace, configuration, and self-describing interfaces. + Common questions and troubleshooting. + Development setup, tests, and contribution flow. + diff --git a/reme/0.4.0.6/en/overview.mdx b/reme/0.4.0.6/en/overview.mdx new file mode 100644 index 0000000..5f5a0bf --- /dev/null +++ b/reme/0.4.0.6/en/overview.mdx @@ -0,0 +1,48 @@ +--- +title: "Overview" +description: "Understand what ReMe solves, where it fits, and how its memory model works." +--- + +ReMe gives agents a visible, user-controlled long-term memory layer. Its durable state is ordinary Markdown, JSONL, YAML, and resource files—not records that only the system can inspect. + +## What ReMe Solves + +Agent context usually disappears when a session ends. Even with a vector database, users may not know what was remembered, where a conclusion came from, or how to correct and move that memory. + +ReMe places memory in a local workspace: + +- raw conversations and resources remain available as sources; +- durable information is refined into Markdown memories; +- files are indexed, linked, and recalled when needed; +- users can read, edit, delete, back up, or version the result directly. + +Memory becomes shared knowledge owned by the user instead of opaque agent state. + +## Where It Fits + +- **Personal assistants** that retain preferences, background, plans, and important events. +- **Coding agents** that carry project decisions, conventions, and debugging experience across sessions. +- **Personal knowledge bases** built from conversations, notes, and linked resources. +- **Experience-driven agents** that preserve reusable procedures and lessons learned. + +ReMe may need another system alongside it when you need strict transactions, complex authorization, or very large-scale online retrieval. It is also a memory layer—not a complete agent product—and it deliberately avoids invisible, unbounded collection. + +## How Memory Flows + +```text +conversations / resources -> sources -> daily notes -> durable memory + | +current agent task <-------- search and links -----+ +``` + +The current implementation uses Auto Memory, Auto Resource, and Auto Dream for refinement, plus keyword, embedding, and wikilink retrieval. Those names can change. The durable promise is that sources remain traceable, memories remain correctable, and results remain in user-accessible files. + +## Offline Use + +File operations, keyword search, and wikilink traversal do not require an LLM. Conversation refinement, resource interpretation, and long-term consolidation need a compatible LLM. Semantic search additionally needs an embedding service. + +## Next + +- Validate the workflow in [Quick Start](/reme/0.4.0.6/en/quickstart). +- Understand the trade-offs in [Concepts](/reme/0.4.0.6/en/concepts). +- Connect an agent with the [Integration Guide](/reme/0.4.0.6/en/guides). diff --git a/reme/0.4.0.6/en/quickstart.mdx b/reme/0.4.0.6/en/quickstart.mdx new file mode 100644 index 0000000..8aa6e36 --- /dev/null +++ b/reme/0.4.0.6/en/quickstart.mdx @@ -0,0 +1,96 @@ +--- +title: "Quick Start" +description: "Install ReMe and complete a verifiable write, index, search, and read loop." +--- + +This page uses ReMe's model-free capabilities to complete a verifiable write → index → search → read loop. + +## 1. Install + +ReMe requires Python 3.11 or newer: + +```bash +pip install "reme-ai[core]" +``` + +For source development: + +```bash +git clone https://github.com/agentscope-ai/ReMe.git +cd ReMe +pip install -e ".[core]" +``` + +## 2. Start the Service + +In one terminal, run: + +```bash +reme start +``` + +The default workspace is `.reme/` under the launch directory, and the service listens on `127.0.0.1:2333`. In another terminal, check it: + +```bash +reme health_check +``` + +Use another port when necessary: + +```bash +reme start service.port=8181 +``` + +## 3. Write a Memory + +```bash +reme write \ + path=digest/wiki/quick-start-demo \ + name="Quick Start Demo" \ + description="My first ReMe memory" \ + content="# Quick Start Demo + +ReMe stores agent memory as user-readable Markdown." +``` + +ReMe adds the `.md` suffix and writes frontmatter plus content to `.reme/digest/wiki/quick-start-demo.md`. + +## 4. Search and Read + +The background index normally discovers the file automatically. If it does not appear immediately, wait briefly or run `reme reindex` once. + +```bash +reme search query="agent memory Markdown" limit=5 +reme read path=digest/wiki/quick-start-demo.md +``` + +Open the file in the workspace too. Matching CLI output and disk content confirm that the minimum loop works. + +```text +.reme/ +├── metadata/ derived indexes, graph, and runtime state +├── session/ raw sessions +├── resource/ source resources +├── daily/ daily refinement +└── digest/ durable memory +``` + +## 5. Enable Memory Refinement When Needed + +Conversation refinement, resource interpretation, and consolidation require an LLM. Semantic search also requires embeddings. Add a `.env` in the launch directory when you need them: + +```bash +LLM_API_KEY=sk-xxx +LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 + +EMBEDDING_API_KEY=sk-xxx +EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +``` + +Model names and embedding-store activation are configuration choices. The authoritative defaults are in `reme/config/default.yaml`. Never commit secrets from `.env`. + +## Next + +- Connect ReMe to an agent with [Guides](/reme/0.4.0.6/en/guides). +- Find workspace, configuration, and interface details in [Reference](/reme/0.4.0.6/en/reference). +- Use [Support](/reme/0.4.0.6/en/support) for connection or indexing problems. diff --git a/reme/0.4.0.6/en/reference.mdx b/reme/0.4.0.6/en/reference.mdx new file mode 100644 index 0000000..31d4333 --- /dev/null +++ b/reme/0.4.0.6/en/reference.mdx @@ -0,0 +1,115 @@ +--- +title: "Reference" +description: "Stable workspace, configuration, CLI, HTTP, and MCP contracts for ReMe." +--- + +This page records stable user-facing semantics and points to authoritative interfaces for the installed version. Exact parameters belong to runtime schemas and source code. + +## Workspace + +The default workspace is `.reme/` under the launch directory. Override it at startup: + +```bash +reme start workspace_dir=/path/to/workspace +``` + +| Directory | Meaning | User editing | +|---|---|---| +| `session/` | Raw conversations and agent sessions | Usually read-only | +| `resource/` | Imported source material | Add, replace, or delete as needed | +| `daily/` | Date-based notes and lightly refined output | Inspect and correct | +| `digest/` | Durable personal facts, procedures, and knowledge | Primary manual editing surface | +| `metadata/` | Derived indexes, graph, and catalogs | Do not edit manually | + +`metadata/` can be rebuilt and must not be the only copy of memory. Backups should retain at least `session/`, `resource/`, `daily/`, and `digest/`. + +## Markdown Memory + +Memory files are ordinary Markdown with optional YAML frontmatter: + +```markdown +--- +name: Build checks +description: Checks required before submitting code +--- + +# Build checks + +Run pytest before submitting. Context: [[daily/2026-07-13/session-42.md]]. +``` + +- Paths are workspace-relative and file actions cannot escape the workspace. +- ReMe can add a missing `.md` suffix where appropriate. +- `[[path/to/file.md]]` is a workspace wikilink. +- `name` and `description` are common summary fields. Treat other metadata as stable only when covered by the current schema. +- Prefer ReMe `move` / `delete` actions for linked files so related links can be checked. + +## Configuration + +ReMe starts with the built-in `default` configuration, then merges a config file and dot-notation overrides: + +```bash +reme start config=/path/to/config.yaml service.port=8181 +``` + +Common top-level groups include: + +| Setting | Meaning | +|---|---| +| `workspace_dir` | Workspace root | +| `timezone` | Timezone for daily notes and scheduled jobs | +| `service.backend` | `http` or `mcp` | +| `service.host` / `service.port` | Listen address | +| `service.transport` | MCP transport | +| `jobs` | Background, scheduled, and served actions | +| `components` | LLM, embedding, storage, and graph implementations | + +`${VAR}` and `${VAR:-default}` in string values expand from the environment. Never commit configuration or `.env` files containing secrets. + +Authoritative sources: + +- [`reme/config/default.yaml`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/default.yaml) for default jobs, components, and parameters; +- [`reme/schema/application_config.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/schema/application_config.py) for the top-level model; +- [`reme/config/config_parser.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/config_parser.py) for merge, override, and environment rules. + +## CLI + +The CLI has one uniform form: + +```text +reme key=value nested.key=value +``` + +Common entrypoints: + +```bash +reme help # actions served by the current service +reme version # installed version +reme health_check # component status +reme find_reme # locate a running ReMe process +reme reindex # clear and rebuild the file index +``` + +Actions other than `start` connect to the running service. Runtime `reme help` and `reme/config/default.yaml` are the authoritative action and parameter lists. + +## HTTP and MCP + +The default HTTP service exposes served jobs as `POST /{action}`. While it is running, use: + +- `/docs` for interactive OpenAPI documentation; +- `/openapi.json` for the machine-readable schema. + +Start MCP with: + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +The default MCP URL is `http://127.0.0.1:2333/mcp`. MCP clients discover the current tool list on connection. + +## Compatibility and Changes + +- Python and dependency ranges: [`pyproject.toml`](https://github.com/agentscope-ai/ReMe/blob/main/pyproject.toml) +- Request, response, and persistent structures: [`reme/schema/`](https://github.com/agentscope-ai/ReMe/tree/main/reme/schema) +- Behavioral boundaries: [`tests/`](https://github.com/agentscope-ai/ReMe/tree/main/tests) +- Version changes: [GitHub Releases](https://github.com/agentscope-ai/ReMe/releases) diff --git a/reme/0.4.0.6/en/support.mdx b/reme/0.4.0.6/en/support.mdx new file mode 100644 index 0000000..e900a27 --- /dev/null +++ b/reme/0.4.0.6/en/support.mdx @@ -0,0 +1,109 @@ +--- +title: "Support" +description: "Answers and troubleshooting steps for common ReMe problems." +--- + +Start by checking the running service: + +```bash +reme find_reme +reme health_check +reme version +``` + +## Common Questions + +### Does every feature need an LLM? + +No. File operations, keyword search, and wikilink traversal work without one. The main Auto Memory, Auto Resource, and Auto Dream refinement stages need an LLM. Vector semantic search needs embeddings. + +### Where is memory stored? + +By default, under `.reme/` in the launch directory. Use `workspace_dir=` to choose another location. The durable state is ordinary files suitable for git or file backup; `metadata/` is rebuildable derived state. + +### Can I edit memory directly? + +Yes. Markdown in `daily/` and `digest/` is the user interface. Preserve source links when changing durable conclusions, and prefer ReMe actions when moving or deleting linked files. + +### HTTP or MCP? + +Use the default HTTP service for CLI, scripts, and ordinary applications. Use MCP for agents with native MCP support. Both expose the same jobs and share the workspace. See [Guides](/reme/0.4.0.6/en/guides). + +## Troubleshooting + +### The service cannot start or the port is occupied + +The default port is `2333`. Locate an existing process or choose another port: + +```bash +reme find_reme +reme start service.port=8181 +``` + +After changing it, update every agent, MCP, and manual-request URL too. + +### `reme search` and other actions cannot connect + +Normal actions connect to the running service. Confirm that it exists, and do not manually specify a conflicting backend, transport, host, or port: + +```bash +reme find_reme +reme search query="check" host=127.0.0.1 port=8181 +``` + +An MCP service and its client must use the same backend and transport. + +### An MCP client cannot connect + +Use streamable HTTP unless the client requires something else: + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +The default URL is `http://127.0.0.1:2333/mcp`. Check for an SSE URL, wrong port, or HTTP backend in the client configuration. + +### Auto Memory or Auto Dream reports a model error + +Confirm that `.env` exists in the launch directory or that the variables are exported: + +```bash +LLM_API_KEY=sk-xxx +LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +``` + +Use the current `reme/config/default.yaml` for model names, provider parameters, and required components. + +### Embedding dimensions do not match + +The configured dimension must match the selected embedding model. Vectors from another model or dimension cannot be reused. Correct the configuration and rebuild: + +```bash +reme reindex +``` + +### A new file does not appear in search + +Confirm that: + +1. the ReMe service is running; +2. the file is under `daily/`, `digest/`, or `resource/`; +3. its suffix is supported by the relevant watcher; +4. the background watcher had a moment to process the write. + +Run `reme reindex` when necessary. Files outside watched locations do not update the index automatically. + +### Claude Code did not record a session + +Confirm that the ReMe MCP service is running, the plugin `.mcp.json` URL is correct, and inspect `plugins/reme/logs/auto_memory_hook.log`. The Stop hook is asynchronous and best-effort, so an unavailable service never blocks Claude Code. + +## Report an Issue + +If the problem remains, open a [GitHub Issue](https://github.com/agentscope-ai/ReMe/issues) with: + +- ReMe version and operating system; +- launch command and actual backend / transport; +- a minimal reproduction and complete error; +- whether LLM, embeddings, or custom configuration are enabled. + +Remove secrets, personal information, and sensitive workspace content first. diff --git a/reme/0.4.0.6/zh/concepts.mdx b/reme/0.4.0.6/zh/concepts.mdx new file mode 100644 index 0000000..b86af8e --- /dev/null +++ b/reme/0.4.0.6/zh/concepts.mdx @@ -0,0 +1,77 @@ +--- +title: "记忆应当属于用户" +description: "理解 ReMe 文件化 Agent 记忆背后的理念与取舍。" +--- + +ReMe 的核心不是某一种检索算法或流水线，而是对 Agent 长期记忆的一组判断：记忆应由用户拥有，从经验中成长，并且能被人和 Agent 共同理解与修正。 + +## 设计哲学 + +ReMe 的设计不是功能模块的堆砌，而是一条基于认知科学理论的推导链：从互补学习系统与事件建构理论出发确立层级文件管线，以扩散激活理论引入仿生联结机制，最终达成人机共享的延展心智。 + +### 仿人脑记忆的多级加工 + +人脑记忆不是单一容器，而是多级加工系统。互补学习系统（CLS）理论表明，海马体负责快速绑定新经验，新皮层负责缓慢整合通用知识，两者需要独立的表征空间和有时间跨度的巩固过程。基于这一判断，ReMe 将存储扩展为四层加工级联： + +- `resource/`：跨模态材料的早期预加工 +- `session/`：交互过程中的事件化记录 +- `daily/`：保留时空上下文的情景卡片 +- `digest/`：脱离时间绑定的长期语义知识 + +这种分层让记忆既能从原始经验中成长，又能逐步提炼为可复用的认识，而不是在扁平存储中累积冲突和过时信息。 + +### 仿生联结与延展心智 + +扩散激活理论要求显式、可遍历的语义关联。ReMe 以 Wikilink 替代传统外键，将四层文件组织为可读、可编辑的语义网络。每个链接不仅指向具体文件，还外化了联想路径，使网络拓扑本身成为认知过程的一部分。 + +延展心智假说认为，外部工具可以成为认知系统的一部分。Markdown 作为认知假体，让用户可以直接编辑文件，编辑本身即是生成性再编码。ReMe 将记忆视为人机共建的知识花园，可读性与可编辑性本身就是认知质量的核心。 + +基于这些理论判断，ReMe 在具体设计中做出了以下工程选择：记忆应以文件形式存在，从经验中提炼而非简单保存，支持人与 Agent 共同理解与修正，并保持可追溯的关联结构。 + +## Memory as File + +长期记忆不应该只存在于数据库的内部记录或临时 prompt 中。ReMe 将记忆保存为本地文件，让用户可以用普通工具阅读、搜索、编辑、移动、删除、备份和版本管理。 + +"文件"不是拒绝索引。ReMe 可以为 Markdown 构建关键词、向量和链接索引，但索引是可重建的派生状态，用户拥有的文件才是事实来源。 + +这带来三个直接结果： + +- **透明**：用户知道 Agent 记住了什么。 +- **可控**：错误、过时或敏感的记忆可以被修正和删除。 +- **可迁移**：记忆不被锁在特定数据库、模型或 Agent 框架中。 + +## Memory from Experience + +保存全部历史不等于拥有记忆。原始对话适合追溯，却不适合直接承担长期理解；无限追加摘要也会积累重复、冲突和过时信息。 + +ReMe 区分来源、当日记录和长期记忆：先保留发生过什么，再提炼哪些事实、偏好、方法和知识值得长期复用。新经验可以补充、合并或修正旧认识。 + +因此，记忆系统需要的不只是"写入"，还包括整理和遗忘。长期记忆的价值取决于它是否能帮助未来行动，而不是文件或 token 的数量。 + +## Human-Agent Shared Memory + +Markdown 是人和 Agent 的共享界面。Agent 可以自动整理、建立链接和召回；用户始终可以检查结果并作出最终修正。 + +这种协作要求 Agent 遵守与人相同的边界： + +- 不因"可能有用"而默认保存敏感信息； +- 修改结论时保留必要的来源和上下文； +- 不把索引结果当作不可质疑的事实； +- 宿主 Agent 决定何时使用记忆，ReMe 不替它决定如何回答或主动行动。 + +## Connected and Traceable + +孤立片段很难解释一项决定如何形成。ReMe 使用链接表达来源和相关关系，让 Agent 可以从一个命中结果继续展开上下文，也让用户能够回到原始材料核对结论。 + +可追溯不意味着保存一切，而是让重要的长期认识具有足够的证据链。来源消失、判断变化或用户要求遗忘时，相关记忆也应该能够更新。 + +## 设计取舍 + +ReMe 有意选择： + +- 文件透明性优先于完全黑盒的自动化； +- 用户控制优先于无边界采集； +- 可修正的长期认识优先于无损保存全部上下文； +- 开放的接入契约优先于绑定某一个 Agent 框架。 + +Auto Memory、Auto Resource、Auto Dream、BM25、embedding 和 wikilink 是当前实现这些理念的方式，而不是理念本身。需要了解具体调用链时，请直接查看 `reme/`、`reme/config/default.yaml` 和 `tests/`。 diff --git a/reme/0.4.0.6/zh/contributing.mdx b/reme/0.4.0.6/zh/contributing.mdx new file mode 100644 index 0000000..fe6e33f --- /dev/null +++ b/reme/0.4.0.6/zh/contributing.mdx @@ -0,0 +1,77 @@ +--- +title: "参与贡献" +description: "配置 ReMe 开发环境、运行测试并准备 Pull Request。" +--- + +ReMe 欢迎 Bug 修复、测试、文档和功能贡献。大改动开始前，请先搜索或创建 [GitHub Issue](https://github.com/agentscope-ai/ReMe/issues)，对齐用户行为、兼容性和测试范围。 + +## 开发环境 + +ReMe 需要 Python 3.11 或更高版本： + +```bash +git clone https://github.com/agentscope-ai/ReMe.git +cd ReMe +python -m venv .venv +source .venv/bin/activate +pip install -e ".[full]" +pre-commit install +``` + +## 代码地图 + +```text +reme/ +├── reme.py CLI 入口 +├── application.py 应用装配与生命周期 +├── config/ 默认配置和解析 +├── components/ 服务、客户端、存储和其他可复用组件 +├── steps/ 用户 action 与后台流程的原子步骤 +├── schema/ 配置、请求、响应和持久化结构 +└── utils/ 通用工具 + +tests/ +├── unit/ 快速、隔离的行为测试 +└── integration/ 跨组件或外部依赖测试 +``` + +源码和测试是架构与扩展方式的权威说明。新增能力前先搜索相邻实现、抽象基类、注册逻辑和对应测试，不要依据一份静态架构手册复制旧模式。 + +## 本地检查 + +提交前至少运行： + +```bash +pre-commit run --all-files +pytest +``` + +开发时可以先运行相关用例： + +```bash +pytest tests/unit/test_reme_cli.py +pytest tests/unit -q +``` + +依赖 LLM、embedding 或外部服务的测试可能需要额外环境变量。无法运行时，在 PR 中明确说明原因和替代验证。 + +## 变更要求 + +- Bug 修复应包含能复现问题的回归测试。 +- 新增或修改 action 时，同步更新 job schema 和入口测试。 +- 修改配置时保持默认配置可启动，并覆盖合并与兼容行为。 +- 修改文件、索引、wikilink 或持久化结构时，考虑已有 workspace 的兼容性。 +- 用户可见的安装、接入、稳定契约或排障行为发生变化时，更新对应文档。 +- 实现细节只更新代码注释和测试，不为每个类或 Step 新建手册页。 + +## Pull Request + +PR 应说明： + +1. 用户可观察到的问题和变化； +2. 选择该实现的原因； +3. 已运行的测试； +4. 配置、数据或兼容性影响； +5. 未解决的限制。 + +提交和 PR 标题建议使用简短的 Conventional Commit 形式，例如 `fix(search): rebuild stale link index`。路线图与设计讨论使用 Issues / Project，版本变化使用 [GitHub Releases](https://github.com/agentscope-ai/ReMe/releases)。 diff --git a/reme/0.4.0.6/zh/guides/claude-code.mdx b/reme/0.4.0.6/zh/guides/claude-code.mdx new file mode 100644 index 0000000..708c326 --- /dev/null +++ b/reme/0.4.0.6/zh/guides/claude-code.mdx @@ -0,0 +1,77 @@ +--- +title: "接入 Claude Code" +description: "为 Claude Code 添加 ReMe 召回与会话自动记录。" +--- + +ReMe 的 Claude Code plugin 提供两条链路：MCP 工具负责召回，Stop hook 在会话结束后异步记录 transcript。 + +## 前置条件 + +先按 [快速开始](/reme/0.4.0.6/zh/quickstart) 安装 ReMe。自动整理会话需要 LLM，因此还需在启动目录配置 `LLM_API_KEY` 和 `LLM_BASE_URL`。 + +## 1. 启动 MCP 服务 + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +默认 MCP 端点为 `http://127.0.0.1:2333/mcp`。该服务应保持运行，多个 Claude Code 窗口可以共享它。 + +## 2. 安装 plugin + +在 Claude Code 中，将本仓库的 `plugins` 目录添加为 marketplace 并安装： + +```text +/plugin marketplace add ./plugins +/plugin install reme@reme-marketplace +``` + +重启 Claude Code，再运行 `/mcp`，确认名为 `reme` 的 server 和工具已经连接。 + +plugin 包含： + +```text +plugins/reme/ +├── .mcp.json MCP 服务地址 +├── hooks/auto_memory.py Stop hook +└── skills/reme-memory/SKILL.md 召回规则 +``` + +如果仓库不在当前目录，请将 `/plugin marketplace add` 的参数替换为实际的本地路径。完整安装说明见仓库中的 [`plugins/README.md`](https://github.com/agentscope-ai/ReMe/blob/main/plugins/README.md)。 + +## 3. 验证召回 + +先在终端写入一条容易识别的记忆： + +```bash +reme write \ + path=digest/wiki/claude-code-check \ + name="Claude Code Check" \ + description="Claude Code 接入验证" \ + content="项目约定：提交前先运行 pytest。" +``` + +随后让 Claude Code 回答“这个项目提交前要做什么？”。它应先调用 ReMe 的 `search` / `read` 工具，再根据记忆回答。 + +## 4. 验证自动记录 + +与 Claude Code 进行一段包含长期信息的对话并结束会话。Stop hook 会在后台调用 `auto_memory_cc`；稍后搜索刚才的关键词： + +```bash +reme search query="<刚才对话中的关键词>" limit=5 +``` + +记录成功后，workspace 的 `daily//` 下会出现对应会话卡片。Stop hook 是 best-effort：服务不可达时不会阻塞 Claude Code，只会写日志。 + +## 端口与日志 + +plugin 的服务地址位于 `plugins/reme/.mcp.json`。如果 ReMe 使用其他端口，必须同步修改其中的 URL。也可以用 `REME_HOST` 和 `REME_PORT` 覆盖 hook 的连接地址。 + +hook 日志默认位于 `plugins/reme/logs/auto_memory_hook.log`。连接失败时先运行： + +```bash +reme find_reme +reme health_check +``` + +更多连接问题见 [Support](/reme/0.4.0.6/zh/support)。 diff --git a/reme/0.4.0.6/zh/guides/index.mdx b/reme/0.4.0.6/zh/guides/index.mdx new file mode 100644 index 0000000..0de3114 --- /dev/null +++ b/reme/0.4.0.6/zh/guides/index.mdx @@ -0,0 +1,66 @@ +--- +title: "接入 ReMe" +description: "在 Skill、CLI、MCP、HTTP 和 Python 接入方式中做出选择。" +--- + +ReMe 作为本地记忆服务运行。所有接入方式共享同一个 workspace，区别只是 Agent 通过什么方式触发搜索、读写和记忆整理。 + +## 选择接入方式 + +| 方式 | 适合场景 | 特点 | +|---|---|---| +| Skill + CLI | 能执行命令并读取 `SKILL.md` 的 Agent | 最轻量，行为规则可见，易于调试 | +| MCP | 原生支持 MCP 的 Agent | 工具 schema 自动发现，适合 Claude Code 等客户端 | +| HTTP | 自研应用或非 Python 运行时 | 普通 JSON 接口，跨语言调用 | +| Python | 与 ReMe 同进程的深度集成 | 可复用应用生命周期和模型配置，但耦合更高 | + +不确定时优先使用 Skill + CLI；Agent 已原生支持 MCP 时使用 MCP。只有宿主应用需要掌控完整生命周期时才做 Python 深度集成。 + +## 通用接入契约 + +无论选择哪一种协议，宿主 Agent 都应遵循相同的记忆行为： + +1. 回答过往对话、偏好、决定或项目历史前，先 `search`，再 `read` 命中的相关文件； +2. 只记录具有长期价值的事实、偏好、决定和经验，不默认保存密钥或敏感信息； +3. 会话结束或出现稳定信息时调用 `auto_memory`，并使用稳定的 `session_id`； +4. 将 `auto_dream` 交给 ReMe 定时任务，或由宿主应用按自己的生命周期触发； +5. ReMe 返回记忆，宿主 Agent 负责判断是否、何时以及如何使用。 + +仓库中的 [`skills/reme_memory/SKILL.md`](https://github.com/agentscope-ai/ReMe/blob/main/skills/reme_memory/SKILL.md) 已包含这套契约。将整个 `skills/reme_memory/` 目录安装到 Agent 的 skill 目录即可复用。 + +## MCP + +启动共享的 MCP 服务： + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +默认端点是 `http://127.0.0.1:2333/mcp`。在 MCP 客户端中添加该 URL 后，客户端会自动发现当前服务暴露的工具。修改端口时，服务端和客户端配置必须保持一致。 + +MCP 适合让模型直接选择工具；会话结束时是否记录、何时整理长期记忆，仍应由宿主 Agent 的 hook 或生命周期负责。 + +## HTTP + +默认启动方式提供 HTTP 服务： + +```bash +reme start +``` + +每个已公开 job 对应 `POST /{action}`，请求体使用 JSON。例如： + +```bash +curl -s http://127.0.0.1:2333/search \ + -H 'Content-Type: application/json' \ + -d '{"query":"project decisions","limit":5}' +``` + +运行服务后访问 `/docs` 或 `/openapi.json` 获取与当前版本一致的接口 schema，不要在集成代码中依赖文档里复制的旧参数表。 + +## 已维护的集成 + +- [Claude Code](/reme/0.4.0.6/zh/guides/claude-code)：官方 plugin、MCP recall 与 Stop hook 自动记录。 +- [QwenPaw](/reme/0.4.0.6/zh/guides/qwenpaw)：通过 ReMe skill 接入，并由应用生命周期决定记录与整理时机。 + +接入后先运行 [快速开始](/reme/0.4.0.6/zh/quickstart) 中的写入与检索命令，确认 ReMe 自身正常，再排查 Agent 侧配置。 diff --git a/reme/0.4.0.6/zh/guides/qwenpaw.mdx b/reme/0.4.0.6/zh/guides/qwenpaw.mdx new file mode 100644 index 0000000..2d684a9 --- /dev/null +++ b/reme/0.4.0.6/zh/guides/qwenpaw.mdx @@ -0,0 +1,57 @@ +--- +title: "接入 QwenPaw" +description: "通过 ReMe skill 和 QwenPaw 生命周期使用文件化长期记忆。" +--- + +QwenPaw 可以通过 ReMe skill 使用本地、文件化的长期记忆。skill 负责告诉 Agent 何时搜索、读取和记录；ReMe 服务负责持久化、索引和整理。 + +## 1. 启动 ReMe + +先完成 [快速开始](/reme/0.4.0.6/zh/quickstart)，并保持默认 HTTP 服务运行： + +```bash +reme start +``` + +如果需要自动提炼会话和整理长期记忆，还需配置 LLM 环境变量。 + +## 2. 安装 ReMe skill + +将仓库中的 [`skills/reme_memory/`](https://github.com/agentscope-ai/ReMe/tree/main/skills/reme_memory) 作为一个完整 skill 安装到 QwenPaw。skill 的具体安装位置和加载方式以所用 QwenPaw 版本为准；不要只复制其中的示例命令而丢失 `SKILL.md` 的行为约束。 + +加载后，QwenPaw 应遵循以下规则： + +- 涉及过去对话、偏好、决定和项目历史时，先执行 `reme search`，需要时再 `reme read`； +- 出现值得长期保留的信息时调用 `reme auto_memory`； +- 写入敏感信息前取得用户明确同意； +- 由 QwenPaw 的会话生命周期提供稳定的 `session_id`。 + + +仓库中的 `skills/qwenpaw_memory` 是一套直接维护 `MEMORY.md` / `memory/*.md` 的文件约定，不会调用 ReMe 服务。要接入 ReMe，请使用 `skills/reme_memory`。 + + +## 3. 验证 + +先在终端写入验证记忆： + +```bash +reme write \ + path=digest/personal/qwenpaw-check \ + name="QwenPaw Check" \ + description="QwenPaw 接入验证" \ + content="用户偏好：解释技术问题时先给结论。" +``` + +然后让 QwenPaw 回答“我偏好怎样的技术解释？”。确认它先搜索 ReMe，并能读到刚写入的文件。 + +再告诉 QwenPaw 一条明确需要长期保留的信息，结束当前会话后运行： + +```bash +reme search query="<刚才的信息关键词>" limit=5 +``` + +如果 QwenPaw 版本没有会话结束 hook，可以由应用层显式调用 `auto_memory`，或先仅启用召回。不要让模型自行猜测缺失的完整消息历史。 + +## 深度集成 + +需要复用 QwenPaw 自身模型配置、消息对象和调度器时，可在应用生命周期中直接调用 ReMe 的 Python 对象或 HTTP action。该接口会随代码演进，集成时以 `reme/application.py`、`reme/schema/` 和现有测试为准，不在本文复制内部 API。 diff --git a/reme/0.4.0.6/zh/index.mdx b/reme/0.4.0.6/zh/index.mdx new file mode 100644 index 0000000..d4de874 --- /dev/null +++ b/reme/0.4.0.6/zh/index.mdx @@ -0,0 +1,37 @@ +--- +title: "ReMe" +description: "面向 AI Agent 的本地优先、文件化长期记忆层。" +--- + +ReMe 是面向 AI Agent 的 local-first 记忆层。它把对话和资料转化为可读、可编辑、可检索的 Markdown，让记忆由用户拥有，并能在不同 Agent 和会话之间延续。 + +![ReMe 设计理念](/images/reme/design-philosophy.svg) + + + + 了解 ReMe 解决什么问题，以及它适合和不适合哪些场景。 + + + 安装、启动，完成第一次写入、检索和文件检查。 + + + 在 Skill、CLI、MCP、HTTP 和 Python 中选择合适的接入方式。 + + + +## 核心理念 + +- **Memory as File**：记忆首先是用户拥有的文件，而不是数据库里的隐藏状态。 +- **Memory from Experience**：长期记忆来自经验的提炼、修正与合并，不是无限堆积上下文。 +- **Human-Agent Shared Memory**：人和 Agent 读写同一份 Markdown，知识始终可见、可控、可迁移。 +- **Connected and Traceable**：记忆通过链接形成关系，长期结论可以追溯到来源。 + +完整的理念与取舍见 [Concepts](/reme/0.4.0.6/zh/concepts)。 + +## 其他入口 + + + Workspace、配置和运行时自描述接口。 + 常见问题与故障排查。 + 开发环境、测试和贡献流程。 + diff --git a/reme/0.4.0.6/zh/overview.mdx b/reme/0.4.0.6/zh/overview.mdx new file mode 100644 index 0000000..50acdf7 --- /dev/null +++ b/reme/0.4.0.6/zh/overview.mdx @@ -0,0 +1,53 @@ +--- +title: "概览" +description: "了解 ReMe 解决什么问题、适用场景和记忆模型。" +--- + +ReMe 为 Agent 提供一个用户可见、可控制的长期记忆层。它保存的不是只能由系统读取的记录，而是普通的 Markdown、JSONL、YAML 和资源文件。 + +## ReMe 解决什么问题 + +Agent 的上下文通常随会话结束而消失。即使接入向量数据库，用户也很难知道系统记住了什么、依据是什么，以及如何修正或迁移这些记忆。 + +ReMe 将记忆放进本地 workspace： + +- 原始对话和资料保留为可追溯的来源； +- 有长期价值的信息被整理成 Markdown 记忆； +- 文件被索引、链接，并在需要时召回； +- 用户可以直接阅读、编辑、删除、备份或版本管理。 + +ReMe 由此把记忆从 Agent 的内部状态，变成用户和 Agent 共同维护的知识资产。 + +## 适合哪些场景 + +- **个人助理**：跨会话保留偏好、背景、计划和重要经历。 +- **Coding Agent**：延续项目决策、代码约定、排障经验和工作流。 +- **个人知识库**：将对话、笔记与资料整理成相互链接的 Markdown。 +- **经验驱动的 Agent**：把成功路径、失败教训和可复用流程沉淀下来。 + +以下场景可能需要其他系统配合： + +- 只需要一次性的会话上下文，不需要长期维护； +- 需要严格事务、复杂权限或超大规模在线检索； +- 希望系统在用户不可见的情况下无边界收集信息； +- 需要完整 Agent 产品，而不是可嵌入的记忆层。 + +## 记忆如何流动 + +```text +对话 / 资料 ──> 原始来源 ──> 当日记录 ──> 长期记忆 + │ +Agent 当前任务 <──── 搜索、链接与来源展开 ─────┘ +``` + +ReMe 当前通过 Auto Memory、Auto Resource 和 Auto Dream 完成整理，通过关键词、向量与 wikilink 完成召回。这些名称属于实现；对用户更重要的承诺是：来源被保留，记忆可以修正，结果始终落在用户可访问的文件中。 + +## 能否离线使用 + +文件读写、关键词检索和 wikilink 遍历不需要 LLM。对话提炼、资料理解和长期整合需要配置兼容的 LLM；语义检索需要 embedding 服务。可以先使用本地文件能力，再按需启用模型。 + +## 下一步 + +- 想先验证效果：进入 [快速开始](/reme/0.4.0.6/zh/quickstart)。 +- 想理解设计取舍：阅读 [Concepts](/reme/0.4.0.6/zh/concepts)。 +- 准备接入 Agent：查看 [接入指南](/reme/0.4.0.6/zh/guides)。 diff --git a/reme/0.4.0.6/zh/quickstart.mdx b/reme/0.4.0.6/zh/quickstart.mdx new file mode 100644 index 0000000..8d6fedb --- /dev/null +++ b/reme/0.4.0.6/zh/quickstart.mdx @@ -0,0 +1,96 @@ +--- +title: "快速开始" +description: "安装 ReMe，并跑通可验证的写入、索引、检索和读取流程。" +--- + +本页使用不依赖 LLM 的基础能力，完成一次可验证的“写入 → 索引 → 检索 → 读取”。 + +## 1. 安装 + +ReMe 需要 Python 3.11 或更高版本： + +```bash +pip install "reme-ai[core]" +``` + +从源码开发时使用： + +```bash +git clone https://github.com/agentscope-ai/ReMe.git +cd ReMe +pip install -e ".[core]" +``` + +## 2. 启动服务 + +在一个终端中运行： + +```bash +reme start +``` + +默认 workspace 是启动目录下的 `.reme/`，服务监听 `127.0.0.1:2333`。另开一个终端检查状态： + +```bash +reme health_check +``` + +端口冲突时可以改用： + +```bash +reme start service.port=8181 +``` + +## 3. 写入第一条记忆 + +```bash +reme write \ + path=digest/wiki/quick-start-demo \ + name="Quick Start Demo" \ + description="第一条 ReMe 记忆" \ + content="# Quick Start Demo + +ReMe 将 Agent 记忆保存为用户可读的 Markdown。" +``` + +ReMe 会补全 `.md` 后缀，并在 `.reme/digest/wiki/quick-start-demo.md` 中写入正文与 frontmatter。 + +## 4. 检索并读取 + +后台索引通常会自动发现新文件。如果没有立即命中，等待片刻或运行一次 `reme reindex`。 + +```bash +reme search query="Agent 记忆 Markdown" limit=5 +reme read path=digest/wiki/quick-start-demo.md +``` + +同时直接打开 workspace 中的文件。命令结果和磁盘文件一致，说明最小闭环已经跑通。 + +```text +.reme/ +├── metadata/ 索引、图谱和运行状态 +├── session/ 原始会话 +├── resource/ 原始资料 +├── daily/ 当日整理结果 +└── digest/ 长期记忆 +``` + +## 5. 按需启用记忆演化 + +对话提炼、资料理解和长期整合需要 LLM。语义检索还需要 embedding。准备使用这些能力时，在启动目录创建 `.env`： + +```bash +LLM_API_KEY=sk-xxx +LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 + +EMBEDDING_API_KEY=sk-xxx +EMBEDDING_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +``` + +模型名和 embedding store 是否启用由配置决定，权威默认值见 `reme/config/default.yaml`。不要提交包含密钥的 `.env`。 + +## 下一步 + +- 用 [接入指南](/reme/0.4.0.6/zh/guides) 将 ReMe 交给 Agent 使用。 +- 用 [Reference](/reme/0.4.0.6/zh/reference) 查 workspace、配置和接口入口。 +- 遇到连接或索引问题时查看 [Support](/reme/0.4.0.6/zh/support)。 diff --git a/reme/0.4.0.6/zh/reference.mdx b/reme/0.4.0.6/zh/reference.mdx new file mode 100644 index 0000000..4e164e4 --- /dev/null +++ b/reme/0.4.0.6/zh/reference.mdx @@ -0,0 +1,115 @@ +--- +title: "参考" +description: "ReMe 稳定的 workspace、配置、CLI、HTTP 和 MCP 契约。" +--- + +本页只记录用户可以依赖的稳定语义，并指向当前版本的权威接口。具体参数以运行时 schema 和源码为准。 + +## Workspace + +默认 workspace 是启动目录下的 `.reme/`，可在启动时覆盖： + +```bash +reme start workspace_dir=/path/to/workspace +``` + +| 目录 | 语义 | 用户是否应编辑 | +|---|---|---| +| `session/` | 原始对话和 Agent session | 通常只读 | +| `resource/` | 导入的原始资料 | 可以添加、替换或删除 | +| `daily/` | 按日期组织的当日记录和浅加工结果 | 可以检查和修正 | +| `digest/` | 可长期复用的个人事实、流程与知识 | 主要人工编辑入口 | +| `metadata/` | 索引、图谱、catalog 等派生状态 | 不应手工编辑 | + +`metadata/` 可以从用户文件重建，不应被当作唯一记忆来源。备份时至少保留 `session/`、`resource/`、`daily/` 和 `digest/`。 + +## Markdown 记忆 + +记忆文件使用普通 Markdown，可带 YAML frontmatter： + +```markdown +--- +name: Build checks +description: 提交代码前的检查约定 +--- + +# Build checks + +提交前运行 pytest。相关背景见 [[daily/2026-07-13/session-42.md]]。 +``` + +- 路径始终相对于 workspace；读写命令只接受 workspace 内路径。 +- `.md` 可以省略，ReMe 会在需要时补全。 +- `[[path/to/file.md]]` 表示 workspace 内的 wikilink。 +- frontmatter 的 `name` 和 `description` 是常用摘要字段；其他元数据是否稳定，应以 schema 和实际写入工具为准。 +- 移动或删除带链接的文件时优先使用 ReMe 的 `move` / `delete` action，以便检查相关链接。 + +## 配置 + +ReMe 从内置 `default` 配置开始，再合并配置文件和命令行点号覆盖： + +```bash +reme start config=/path/to/config.yaml service.port=8181 +``` + +常用顶层配置包括： + +| 配置 | 含义 | +|---|---| +| `workspace_dir` | workspace 根目录 | +| `timezone` | daily 和定时任务使用的时区 | +| `service.backend` | `http` 或 `mcp` | +| `service.host` / `service.port` | 服务监听地址 | +| `service.transport` | MCP transport | +| `jobs` | 后台、定时和公开 action | +| `components` | LLM、embedding、存储和图谱实现 | + +字符串中的 `${VAR}` 和 `${VAR:-default}` 会从环境变量展开。包含密钥的配置和 `.env` 不应提交到版本库。 + +权威配置来源： + +- [`reme/config/default.yaml`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/default.yaml)：默认 job、组件和参数； +- [`reme/schema/application_config.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/schema/application_config.py)：顶层配置结构； +- [`reme/config/config_parser.py`](https://github.com/agentscope-ai/ReMe/blob/main/reme/config/config_parser.py)：合并、点号覆盖和环境变量规则。 + +## CLI + +CLI 形式统一为： + +```text +reme key=value nested.key=value +``` + +常用入口： + +```bash +reme help # 当前服务公开的 action +reme version # 版本 +reme health_check # 组件状态 +reme find_reme # 定位运行中的 ReMe 进程 +reme reindex # 清理并重建文件索引 +``` + +`start` 之外的 action 会连接正在运行的服务。运行时 `reme help` 和 `reme/config/default.yaml` 是 action 与参数的权威清单。 + +## HTTP 与 MCP + +默认 HTTP 服务将公开 job 暴露为 `POST /{action}`。服务运行后访问： + +- `/docs`：交互式 OpenAPI 页面； +- `/openapi.json`：机器可读 schema。 + +MCP 服务通过以下方式启动： + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +默认 MCP URL 为 `http://127.0.0.1:2333/mcp`。工具清单由 MCP 客户端在连接时自动发现。 + +## 兼容性与变更 + +- Python 要求和依赖范围以 [`pyproject.toml`](https://github.com/agentscope-ai/ReMe/blob/main/pyproject.toml) 为准。 +- 请求、响应和持久化结构以 [`reme/schema/`](https://github.com/agentscope-ai/ReMe/tree/main/reme/schema) 为准。 +- 行为边界以 [`tests/`](https://github.com/agentscope-ai/ReMe/tree/main/tests) 为准。 +- 版本变化见 [GitHub Releases](https://github.com/agentscope-ai/ReMe/releases)。 diff --git a/reme/0.4.0.6/zh/support.mdx b/reme/0.4.0.6/zh/support.mdx new file mode 100644 index 0000000..4ab9923 --- /dev/null +++ b/reme/0.4.0.6/zh/support.mdx @@ -0,0 +1,109 @@ +--- +title: "支持与排障" +description: "解决 ReMe 安装、连接、模型和索引的常见问题。" +--- + +先运行以下命令确认服务状态： + +```bash +reme find_reme +reme health_check +reme version +``` + +## 常见问题 + +### 所有能力都需要 LLM 吗？ + +不需要。文件读写、关键词检索和 wikilink 遍历可以直接使用；Auto Memory、Auto Resource 和 Auto Dream 的主要整理阶段需要 LLM；向量语义检索需要 embedding。 + +### 记忆存在哪里？ + +默认在启动目录的 `.reme/`。用 `workspace_dir=` 可以指定其他位置。记忆主体是普通文件，可以用 git 或文件同步工具备份；`metadata/` 是可重建的派生状态。 + +### 可以直接编辑记忆吗？ + +可以。`daily/` 和 `digest/` 中的 Markdown 就是用户界面。编辑长期结论时尽量保留来源链接；移动和删除文件时优先使用 ReMe action，避免留下悬空链接。 + +### HTTP 和 MCP 怎么选？ + +CLI、脚本和普通应用使用默认 HTTP；原生支持 MCP 的 Agent 使用 MCP。两种服务暴露同一组 job，并共享 workspace。接入建议见 [Guides](/reme/0.4.0.6/zh/guides)。 + +## 故障排查 + +### 服务无法启动或端口被占用 + +默认端口是 `2333`。先定位已有进程，或换端口： + +```bash +reme find_reme +reme start service.port=8181 +``` + +使用自定义端口后，Agent、MCP 配置和手工请求中的端口也必须同步修改。 + +### `reme search` 等命令连接失败 + +普通 action 会连接运行中的服务。确认服务存在，并避免手工指定与服务不一致的 backend、transport、host 或 port： + +```bash +reme find_reme +reme search query="check" host=127.0.0.1 port=8181 +``` + +如果服务以 MCP 启动，客户端也必须使用相同 backend 和 transport。 + +### MCP 客户端无法连接 + +推荐使用 streamable HTTP： + +```bash +reme start service.backend=mcp service.transport=streamable-http +``` + +默认 URL 是 `http://127.0.0.1:2333/mcp`。检查客户端没有使用 SSE URL、错误端口或 HTTP backend。 + +### Auto Memory / Auto Dream 报模型错误 + +确认启动 ReMe 的目录中存在 `.env`，或环境变量已导出： + +```bash +LLM_API_KEY=sk-xxx +LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 +``` + +模型名称、provider 参数和所需组件以当前 `reme/config/default.yaml` 为准。 + +### 开启 embedding 后维度不匹配 + +embedding 模型的输出维度必须与配置一致。更换模型或维度后，旧向量不能复用，修正配置并重建索引： + +```bash +reme reindex +``` + +### 新文件搜索不到 + +确认： + +1. ReMe 服务正在运行； +2. 文件位于 `daily/`、`digest/` 或 `resource/`； +3. 文件类型在 watcher 支持范围内； +4. 写入后已给后台 watcher 短暂处理时间。 + +必要时运行 `reme reindex`。若直接修改了服务未监听的文件，索引不会自动更新。 + +### Claude Code 会话没有自动记录 + +确认 ReMe MCP 服务仍在运行、plugin 的 `.mcp.json` 地址正确，并查看 `plugins/reme/logs/auto_memory_hook.log`。Stop hook 是异步 best-effort，服务不可达时不会阻塞 Claude Code。 + +## 反馈问题 + +仍无法解决时，请在 [GitHub Issues](https://github.com/agentscope-ai/ReMe/issues) 提供： + +- ReMe 版本和操作系统； +- 启动命令与实际 backend / transport； +- 最小复现步骤和完整错误； +- 是否启用了 LLM、embedding 或自定义配置。 + +提交前请删除密钥、个人信息和 workspace 中的敏感内容。 diff --git a/reme/README.md b/reme/README.md new file mode 100644 index 0000000..6d572b1 --- /dev/null +++ b/reme/README.md @@ -0,0 +1,9 @@ +# ReMe documentation + +ReMe documentation is part of the unified Mintlify site in this repository. + +- Version directories such as `0.4.0.6/` contain the published `en/` and `zh/` MDX pages. +- Shared ReMe media lives in `images/reme/`. +- Navigation is defined by the `ReMe` tab for each language in `docs.json`. + +Keep the documentation focused on product philosophy, verified user workflows, and stable contracts. Implementation details belong in the ReMe source, schemas, tests, and runtime help. diff --git a/scripts/create-version.sh b/scripts/create-version.sh index e6a54db..fac76f1 100755 --- a/scripts/create-version.sh +++ b/scripts/create-version.sh @@ -18,22 +18,22 @@ fi SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" DOCS_ROOT="$(dirname "$SCRIPT_DIR")" -VERSIONS_DIR="$DOCS_ROOT/versions" +AGENTSCOPE_DIR="$DOCS_ROOT/agentscope" DOCS_JSON="$DOCS_ROOT/docs.json" # If source version not specified, find the latest version if [ -z "$SOURCE_VERSION" ]; then # Get all version directories, sort by version number (descending), take the first - SOURCE_VERSION=$(ls -1 "$VERSIONS_DIR" | sort -V -r | head -1) + SOURCE_VERSION=$(ls -1 "$AGENTSCOPE_DIR" | sort -V -r | head -1) if [ -z "$SOURCE_VERSION" ]; then - echo "Error: No existing versions found in $VERSIONS_DIR" + echo "Error: No existing versions found in $AGENTSCOPE_DIR" exit 1 fi fi -SOURCE_DIR="$VERSIONS_DIR/$SOURCE_VERSION" -TARGET_DIR="$VERSIONS_DIR/$NEW_VERSION" +SOURCE_DIR="$AGENTSCOPE_DIR/$SOURCE_VERSION" +TARGET_DIR="$AGENTSCOPE_DIR/$NEW_VERSION" if [ ! -d "$SOURCE_DIR" ]; then echo "Error: Source version directory not found: $SOURCE_DIR" @@ -57,10 +57,10 @@ cp -r "$SOURCE_DIR" "$TARGET_DIR" # Replace version references in all mdx files echo "Updating internal links in mdx files..." -find "$TARGET_DIR" -name "*.mdx" -exec sed -i '' "s|/versions/$SOURCE_VERSION/|/versions/$NEW_VERSION/|g" {} \; +find "$TARGET_DIR" -name "*.mdx" -exec sed -i '' "s|/agentscope/$SOURCE_VERSION/|/agentscope/$NEW_VERSION/|g" {} \; # Count modified files -MODIFIED_COUNT=$(grep -r "/versions/$NEW_VERSION/" "$TARGET_DIR" --include="*.mdx" -l 2>/dev/null | wc -l | tr -d ' ') +MODIFIED_COUNT=$(grep -r "/agentscope/$NEW_VERSION/" "$TARGET_DIR" --include="*.mdx" -l 2>/dev/null | wc -l | tr -d ' ') # Update docs.json: clone navigation entry per language + update redirects echo "Updating docs.json (navigation + redirects)..." @@ -78,9 +78,9 @@ with open(docs_json_path, "r", encoding="utf-8") as f: def update_paths(obj): - """Recursively rewrite any 'versions//' substring.""" - src = f"versions/{source_version}/" - dst = f"versions/{new_version}/" + """Recursively rewrite any 'agentscope//' substring.""" + src = f"agentscope/{source_version}/" + dst = f"agentscope/{new_version}/" if isinstance(obj, str): return obj.replace(src, dst) if isinstance(obj, list): @@ -95,7 +95,15 @@ skipped = [] languages = data.get("navigation", {}).get("languages", []) or [] for lang_entry in languages: lang = lang_entry.get("language", "?") - versions = lang_entry.get("versions", []) or [] + project_tab = next( + (tab for tab in lang_entry.get("tabs", []) if tab.get("tab") == "AgentScope"), + None, + ) + if project_tab is None: + skipped.append(f"{lang}(AgentScope tab not found)") + continue + + versions = project_tab.get("versions", []) or [] # Skip if the new version already exists for this language if any(v.get("version") == new_version for v in versions): @@ -118,7 +126,7 @@ for lang_entry in languages: # Insert right BEFORE the source version so newer versions appear higher versions.insert(source_idx, new_entry) - lang_entry["versions"] = versions + project_tab["versions"] = versions added.append(lang) # Update redirects (/latest/ for dev, /stable/ for release) @@ -127,8 +135,8 @@ target_source = "/latest/:slug*" if is_dev else "/stable/:slug*" redirect_updated = "" for redirect in data.get("redirects", []) or []: if redirect.get("source") == target_source: - redirect["destination"] = f"/versions/{new_version}/:slug*" - redirect_updated = f"{target_source} -> /versions/{new_version}/:slug*" + redirect["destination"] = f"/agentscope/{new_version}/:slug*" + redirect_updated = f"{target_source} -> /agentscope/{new_version}/:slug*" break with open(docs_json_path, "w", encoding="utf-8") as f: