agentscope-skill

AgentScope 2.0

AgentScope 是一个开源框架，用于构建和提供由大模型驱动的 Agent 应用，涵盖从使用单个工具的 Agent 到协同多 Agent 系统。它提供应用编排和服务基础设施；模型推理由已配置的提供方负责，工具则通过已配置的本地或沙箱后端执行。它由两层组成：

• Agent SDK： Agent 应用的构建模块，包括 Agent、模型、消息、工具、上下文和状态管理、中间件、记忆、RAG、多 Agent 编排和工作区。
• 服务： 基于 SDK 构建的服务层，提供用于 Agent 和会话管理、持久化、团队、调度、通道及资源管理的 API，并提供 Web UI 示例。

此技能支持 AgentScope 2.x，基于 2.0.8。API 签名和行为应遵循用户环境中实际安装的 SDK 版本。agentscope-runtime 和 agentscope-studio 与 2.x 不兼容；请改用内置的服务和工作区功能。

安装

需要 Python 3.11 或更高版本。

pip install agentscope
# or
uv pip install agentscope

核心概念和基本示例

• Agent 负责推理/行动循环。使用 reply() 获取最终的 Msg，或使用 reply_stream() 获取事件。launch_console() 负责终端交互、工具确认和中断处理。
• 使用凭证对象和 model=... 构造提供方模型。格式化器仍然存在，但配置在模型上；提供方会选择默认格式化器。它们不会传递给 Agent。
• Toolkit 接受工具对象、MCP 客户端和技能路径/加载器。使用 FunctionTool 封装 Python 函数；自定义工具类则使用 ToolBase。
• Msg 包含类型化内容块。UserMsg、AssistantMsg 和 SystemMsg 是便捷工厂，也接受文本字符串。二进制媒体使用带有 URLSource 或 Base64Source 的 DataBlock，包括 media_type。
• 事件： 类型化事件向应用暴露 Agent 执行过程：回复和模型调用生命周期、流式内容、工具调用/结果，以及确认请求或外部执行请求。通过 reply_stream() 消费这些事件；发送交互结果事件以恢复 Agent。Msg 表示对话内容，而事件描述执行和交互过程。
• AgentState 保存对话和执行状态。Agent 配置使用 ContextConfig、InjectionConfig、ModelConfig 和 ReActConfig。中间件可添加记忆、RAG、跟踪和其他钩子。

以下示例展示如何组合 Agent、模型和 Python 函数工具：

import asyncio
import os

from agentscope.agent import Agent
from agentscope.console import launch_console
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
from agentscope.tool import FunctionTool, Toolkit


def add(a: int, b: int) -> str:
    """Add two integers.

    Args:
        a: First integer.
        b: Second integer.
    """
    return str(a + b)


async def main() -> None:
    agent = Agent(
        name="Friday",
        system_prompt="You are a helpful assistant named Friday.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
                api_key=os.environ["DASHSCOPE_API_KEY"],
            ),
            model=os.environ.get("DASHSCOPE_MODEL", "qwen3.6-plus"),
        ),
        toolkit=Toolkit(tools=[FunctionTool(add)]),
    )
    await launch_console(agent)


if __name__ == "__main__":
    asyncio.run(main())

如需以编程方式交互，请在包含现有 agent 的异步函数中使用以下代码：

from agentscope.message import UserMsg

result = await agent.reply(UserMsg(name="user", content="Hello!"))
print(result.get_text_content())

reply() 会消费流式事件。如果工具需要确认或外部执行，自定义 UI 应消费 reply_stream()，并将相应的 UserConfirmResultEvent 或 ExternalExecutionResultEvent 反馈回来以恢复执行。流可能会在等待该输入时结束；不要将每次流结束都视为成功完成。请参考控制台实现和事件架构，了解此生命周期。FunctionTool 默认会请求权限。

如需多模态输入，请使用支持所提供媒体类型的模型：

from agentscope.message import DataBlock, TextBlock, URLSource, UserMsg

message = UserMsg(
    name="user",
    content=[
        TextBlock(text="Describe this image."),
        DataBlock(
            source=URLSource(
                url="https://example.com/image.png",
                media_type="image/png",
            ),
        ),
    ],
)

使用仓库

编写应用代码前，请复用现有的 AgentScope 检出副本，或克隆仓库以检查其中的示例和实现：

git clone --branch main https://github.com/agentscope-ai/agentscope.git
# Inspect local changes before updating an existing checkout.
git -C agentscope status --short
git -C agentscope pull --ff-only origin main

仓库结构

agentscope/
├── src/agentscope/
│   ├── agent/          # Agents and their configuration
│   ├── model/          # Chat model providers
│   ├── credential/     # Provider credentials
│   ├── console/        # Terminal interaction and event rendering
│   ├── formatter/      # Provider-specific message formatting
│   ├── message/        # Messages and typed content blocks
│   ├── tool/           # Toolkit, adapters, and built-in tools
│   ├── mcp/            # MCP clients and configuration
│   ├── skill/          # Skill loading
│   ├── state/          # Agent conversation and execution state
│   ├── middleware/     # Hooks, memory, RAG, tracing, and budgets
│   ├── event/          # Streaming and interaction events
│   ├── permission/     # Tool permissions and human confirmation
│   ├── pipeline/       # Multi-agent workflow abstractions
│   ├── workspace/      # Local and sandboxed execution backends
│   ├── rag/            # Retrieval building blocks
│   ├── embedding/      # Embedding model providers
│   ├── realtime/       # Realtime model interfaces
│   ├── tts/            # Text-to-speech models
│   └── app/            # Service APIs, storage, teams, channels, and hubs
├── examples/
│   ├── console/        # Terminal agent composition
│   ├── agent_service/  # Service configuration
│   ├── web_ui/         # Service frontend
│   ├── pipeline/       # Executor/verifier workflow
│   ├── a2a/            # Remote agent communication
│   ├── long_term_memory/
│   ├── rag/
│   ├── realtime/
│   └── workspace/
├── docs/               # News, roadmap, and changelog
└── tests/              # SDK and service behavior tests

浏览检出副本时，请确认实际的目录布局。从与任务匹配的示例类别开始，阅读其 README 和代码，然后沿着导入路径查看 src/agentscope/。在这些目录中搜索所需的类或功能。优先使用现有框架功能，而不是重新实现；添加自定义行为前，请检查基类及继承的方法。

资源

官方文档

• AgentScope 文档：SDK 和服务层的概念、API 用法及指南。

GitHub 资源

• 主仓库：源代码、示例和测试。
• 示例：按功能整理的参考实现。
• 路线图：开发方向。
• 项目看板：开发任务跟踪。
• 讨论区：社区提问、想法和框架设计讨论。

参考资料

需要了解更多细节时，请阅读以下本地参考资料：

• 多 Agent 编排：直接消息传递、将工作者用作工具、GoalPipeline、Agent Team 和 A2A。
• 部署指南：内置服务、存储、消息总线、工作区和沙箱后端。

脚本

• view_module_signature.py：检查当前 Python 环境中的模块、类和方法，包括继承的 API 和源码位置。
• view_pypi_latest_version.sh：查询最新发布的 AgentScope 版本。

示例查询：

python /path/to/agentscope-skill/scripts/view_module_signature.py --module agentscope
python /path/to/agentscope-skill/scripts/view_module_signature.py --module agentscope.agent.Agent
python /path/to/agentscope-skill/scripts/view_module_signature.py --module agentscope.agent.Agent.reply_stream
python /path/to/agentscope-skill/scripts/view_module_signature.py --module agentscope.app.storage
bash /path/to/agentscope-skill/scripts/view_pypi_latest_version.sh

模块发现不会导入所有可选集成。系统会报告缺失的可选导入；请使用目标 pyproject.toml，仅安装任务所需的额外依赖（例如 service、model-gemini 或 model-ollama）。 PyPI 助手仅报告发行版元数据，不报告已安装的版本。

交付代码前，请检查公开导出项、构造函数/方法签名、继承的方法以及清理要求。使用目标版本验证示例；离线行为检查请使用虚假模型，并将此类检查与实际的服务提供商、Redis、容器或部署运行区分开来。