AIStoreHub Package Vault: Agentscope
Package Slug: agentscope
Archetype: agent
Upstream Repository: https://github.com/agentscope-ai/agentscope
Workspace Files & Specifications (67 files)
- aistorehub.json (431 bytes)
{ "name": "Agentscope", "slug": "agentscope", "version": "1.0.0", "type": "agent", "description": "Build and run agents you can see, understand and trust.", "owner": "community", "repository": "catalog", "github_repo_url": "https://github.com/agentscope-ai/agentscope", "tags": [ "trending", "agentscope-ai", "python", "github", "open-source" ], "imported_at": "2026-11-21T23:56:28.707Z" } - CONTRIBUTING_zh.md (14593 bytes)
# 为 AgentScope 做贡献 感谢大家对 AgentScope 的关注! 作为一个开源项目,我们欢迎并鼓励来自社区的贡献。无论是修复 bug、新增功能、完善文档,还是分享想法,每一份贡献都让 AgentScope 变得更好。 ## 1. 开发路线图与参与方式 为了支持 AgentScope 开源社区的长期健康发展,我们将公开、透明地维护 AgentScope 的开发计划。 **路线图公开**。AgentScope 的开发计划会发布在 [GitHub Projects 页面](https://github.com/orgs/agentscope-ai/projects/2),并持续更新。路线图会反映 AgentScope 的技术发展方向,由核心开发团队对 AgentScope 的整体设计与质量负责。 **社区可认领的任务**。Projects 页面 / Issues 中标有 `help wanted` 的条目对所有人开放。如果你有兴趣参与某一项: - 请在对应 issue 下评论,告知准备认领 - 这样可以避免重复劳动,也方便我们尽早协作 **成为核心开发者**。我们欢迎想要更深入参与、共同塑造 AgentScope 的开发者。我们会在合适的时机邀请投入度高的贡献者成为核心开发者。 成为核心开发者也意味着更频繁的参与到 AgentScope 的开发工作中,包括: - 更加频繁的设计讨论、代码评审与多轮迭代,需要持续的时间和精力投入 - 为保证 AgentScope 的整体一致性与可靠性,核心团队保留对项目技术方向与质量标准的把控 **提出新想法**。针对有路线图上还没有的想法,请新建 issue 描述提议。核心开发团队会尽可能地及时回复并一起讨论可行的推进路径。 ## 2. 在贡献中负责任地使用 AI AgentScope 欢迎使用 AI 编码助手的贡献者——Claude Code、Cursor、Codex、Copilot 等等。我们只要求**负责任地使用**。AgentScope 依靠评审者的时间和社区信任运转,AI 辅助的贡献需要兼顾两者。 涉及 AI 时的几条要求: - **作者是人,不是 AI**。在 push 之前,请逐行阅读 diff,运行代码,确认理解了**改了什么**和**为什么改**。“Claude Code / Cursor / Codex 就是这么写的”并不是一个合适的理由,也不利于开源社区的健康发展。 - **创建 PR 前先自行评审 AI 生成的代码**。所有人的事件都是宝贵的资源,请不要将没有审阅过的 AI 代码/改动直接丢给维护者评审。 - **保持 PR 原子化**。不要提交 AI 一次性生成的 10K+ 行 PR,这种 PR 无法评审,会被拒绝。请把改动拆成若干个聚焦原子化功能的、具有单一目标的 PR。 - **AI 生成代码遵守同样的原则**。AgentScope 的所有开发原则——模块化、惰性导入、约定式提交、测试覆盖、不破坏 API——对 AI 辅助代码同等适用。 简而言之:AI 让我们的开发更快,但确保合入 AgentScope 的代码质量责任仍在贡献者本人。 ## 3. 贡献流程 端到端的贡献流程如下。 ### 第 1 步:认领或创建 issue 在写代码之前,先找到或创建对应的 issue。 - **基于已有任务**:浏览 [Projects](https://github.com/orgs/agentscope-ai/projects/2) 与 [Issues](https://github.com/agentscope-ai/agentscope/issues) 中标有 `help wanted` 的条目(参见 [§1](#1-开发路线图与参与方式)),在 issue 下评论认领后再开始。 - **提出新想法**:新建 issue 描述问题、方案与设计上的取舍。等待核心开发团队反馈后再开始实现,避免事后大规模返工。 - **数量限制**:每位贡献者同时最多有 5 个 open 状态的 issue,最多同时认领 5 个 issue。超出后新提的 issue 会被自动关闭、新的认领会被拒绝,请先聚焦手头已有的。 ### 第 2 步:Fork 仓库并创建开发分支 1. 在 GitHub 上 fork [agentscope-ai/agentscope](https://github.com/agentscope-ai/agentscope)。 2. clone 自己的 fork 并添加 upstream 远端: ```bash git clone https://github.com/<your-username>/agentscope.git cd agentscope git remote add upstream https://github.com/agentscope-ai/agentscope.git ``` 3. 基于最新的 `main` 创建主题分支: ```bash git checkout main git pull upstream main git checkout -b feat/<short-description> ``` ### 第 3 步:搭建本地环境 AgentScope 要求 **Python 3.11+**(详见 `pyproject.toml`)。 ```bash # 创建隔离环境(这里用 uv,也可用 virtualenv / conda) uv venv source .venv/bin/activate # 以可编辑模式安装 AgentScope,并带上 dev extras pip install -e ".[dev]" # 等价的 uv 写法: uv pip install -e ".[dev]" # 启用 git pre-commit hooks pre-commit install ``` `dev` extra 会拉入 `pre-commit`、`pytest`、文档工具链以及 `full` extra(包含 `models`、`service`、`storage`)。一次安装即可获得开发与运行完整测试套件所需的一切。 ### 第 4 步:开发 写代码时遵守的几条约定: - **可选依赖必须惰性导入**。任何**未列在 `pyproject.toml` 的 `[project.dependencies]` 中**的依赖——也就是来自可选 extra(`gemini`、`ollama`、`xai`、`service`、`storage` 等)的——**必须在使用点惰性导入**,而不是放在模块顶部: ```python def some_function(): import google.genai # 来自 `gemini` extra,惰性导入 # ... 在这里使用 google.genai ``` 这样保持 `import agentscope` 轻量,`ImportError` 只在实际用到该 extra 的功能时才抛出。如果改动需要引入全新的依赖,先决定它属于基础 `[project.dependencies]`(始终需要、保持精简)还是某个可选 extra,并在 issue 中讨论后再合入。 - **遵守项目代码风格**。pre-commit 会自动处理格式与大部分 lint 规则,请在提交前运行 pre-commit 来修复问题。 - **功能要配套写单元测试**。测试位于 `tests/` 下,沿用现有结构。依赖可选 extra 的测试(如 Redis、Ollama)在该 extra 未安装时应能干净 skip。 ### 第 5 步:跑 pre-commit、测试,并更新文档 创建 PR 之前,请在本地运行如下的命令检查代码格式与功能: ```bash # 自动格式化与 lint pre-commit run --all-files # 单元测试 pytest tests ``` 如果 pre-commit hook 失败,请修复格式问题(多数会自动修复),然后重新 commit。 **改代码的同时请更新文档**。 - AgentScope 文档放在独立仓库:**[agentscope-ai/docs](https://github.com/agentscope-ai/docs)**。如果改动影响用户可见行为——新模块、新公开 API、行为变化、教程——请在该仓库同步开一个配套 PR。 - 为新公开 API 更新 docstring 与示例片段。 - 如果改动影响新手上手或 AgentScope 的对外宣传内容,更新 `README.md`。 ### 第 6 步:提交与发起 PR **Commit 信息格式**。我们遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范,便于阅读历史与自动生成 changelog。 ``` <type>(<scope>): <subject> ``` **Type 列表:** - `feat:` 新功能 - `fix:` bug 修复 - `docs:` 仅文档变更 - `style:` 不影响代码语义的改动(空白、格式等) - `refactor:` 既不是修 bug 也不是加功能的代码改动 - `perf:` 性能优化 - `test:` 增补或修正测试 - `ci:` CI 配置或工作流脚本的变更 - `chore:` 构建流程或辅助工具/库的变更 **示例:** ```bash feat(models): add support for Claude-3 model fix(agent): resolve memory leak in ReActAgent docs(readme): update installation instructions refactor(formatter): simplify message formatting logic test(models): add unit tests for OpenAI integration ``` **PR 标题格式**。PR 标题同样遵循 Conventional Commits 格式,并由 GitHub Actions 在针对 `main` 的 PR 上自动校验。标题不合规的 PR 会被阻止合入,直到修正为止。 ``` <type>(<scope>): <description> ``` **要求:** - 标题须以下列 type 之一开头:`feat`、`fix`、`docs`、`ci`、`refactor`、`test`、`chore`、`perf`、`style`、`build`、`revert` - scope 可选,建议带上 - **scope 必须小写**——只允许小写字母、数字、连字符(`-`)和下划线(`_`) - description 以小写字母开头 - 标题保持简洁、有信息量 **示例:** ``` ✅ 合规: feat(memory): add redis cache support fix(agent): resolve memory leak in ReActAgent docs(tutorial): update installation guide ci(workflow): add PR title validation refactor(my-feature): simplify logic ❌ 不合规: feat(Memory): add cache # scope 必须小写 feat(MEMORY): add cache # scope 必须小写 feat(MyFeature): add feature # scope 必须小写 ``` **发起 PR**。把分支 push 到自己的 fork,对 `agentscope-ai/agentscope:main` 发起 pull request。在 PR 描述里: - 关联认领的 issue(`Fixes #123` 或 `Refs #123`) - 概述改了什么、为什么改 - 标注任何破坏性改动、废弃项或迁移步骤 - 如果同时开了文档 PR,链接到 [agentscope-ai/docs](https://github.com/agentscope-ai/docs) 的对应 PR ## 4. 重要事项 开始贡献前需要了解的几条横向约束。模块特定的事项见下文对应模块指南。 - **非平凡改动先开 issue**。突然提交涉及大量文件、改动公开 API 或引入新模块的 PR 难以评审,多半会被拒。先在 issue 中讨论设计。 - **PR 保持聚焦、原子**。一个 PR 一个目的。不要把重构和功能、或功能和不相干的 bug 修复混在一起。 - **不擅自破坏公开 API**。能保持向后兼容就保持。无法避免的破坏性改动,在 PR 描述中清楚说明,并在同一个 PR 里更新受影响的示例和文档。 - **不绕过惰性导入原则**。可选依赖必须在使用点导入,不能放在模块顶部。 - **不随意引入依赖**。每个新依赖都是长期维护负担。如果只有一个模块用到,优先在该模块内部惰性导入。 - **不忽视 CI 失败**。pre-commit、类型检查、测试必须通过后再发起 review,不要把修复负担推给评审者。 - **保持尊重**。遵守行为准则。AgentScope 的评审风格直接但友善,对贡献者也是同样期待。 ## 5. 模块特定贡献指南 下文覆盖社区贡献者最常扩展的模块。其他模块请先开 issue 协调。 ### Chat Model AgentScope 中的一个 chat model 不只是一个类——要在 `Agent` 中可用,需要一组上下游配套实现。一个完整的 chat model 贡献需包含**以下全部**: 1. **Credential 类**——位于 `agentscope.credential`,继承 `CredentialBase`。承载 API key、endpoint 及 SDK 所需的其他鉴权字段。 _参考:`agentscope/credential/_anthropic.py`_ 2. **Chat model 类**——位于 `agentscope.model.<provider>/`,继承 `ChatModelBase`。实现需覆盖: - 流式与非流式两种模式 - Tools API 集成(function/tool calling) - `tool_choice` 参数 - 适用时的 reasoning 模型支持 _参考:`agentscope/model/_anthropic/`_ 3. **Model card YAML**——位于 `agentscope.model.<provider>._models/`,每个支持的模型一份 YAML。必填字段:`name`、`label`、`status`、`input_types`、`output_types`、`context_size`、`output_size`。可选字段:`parameter_overrides`、`deprecated_at`。 示例(`claude-sonnet-4-6.yaml`): ```yaml name: claude-sonnet-4-6 label: Claude Sonnet 4.6 status: active input_types: - text/plain - image/jpeg output_types: - text/plain context_size: 1000000 output_size: 65536 parameter_overrides: max_tokens: {"maximum": 65536} ``` 4. **Formatter 类**——位于 `agentscope.formatter`,均继承 `FormatterBase`。需要两种变体,因为部分 API 对多 agent 对话与单用户对话的处理方式不同: - `<Provider>ChatFormatter` 处理单用户对话场景 - `<Provider>MultiAgentFormatter` 处理多 agent 场景 每个 formatter 把 `Msg` 对象转换成对应 provider API 期望的请求格式。 _参考:`agentscope/formatter/_anthropic_formatter.py`_ > ⚠️ 只加 model 类、缺少配套 credential、model card YAML 与两种 formatter 变体的 PR 不会被合入。 ### Agent AgentScope 目前只维护**一个核心 agent 类**——`agentscope.agent.Agent`——它整合了 AgentScope 库的全部功能(memory、tools、MCP、formatter、model 等)。 特定领域或专用 agent 请作为 [example](#examples) 贡献,而不是在 `agentscope.agent` 中新增类。 如果确信某个用例需要新的顶层 agent 类: 1. **先开 issue**,描述用例并说明为什么组合现有 `Agent` 能力不够。 2. **等核心团队的设计讨论**,再开始具体的代码实现。 3. 未经事先讨论就引入新 agent 类的 PR 会被拒绝。 ### Workspace Workspace 提供 agent 运行所需的运行时上下文(skills、scheduled tasks 等)。新增 workspace 后端需要两个类加配套文档: 1. **Workspace 类**——位于 `agentscope.workspace`,继承 `WorkspaceBase`。实现该后端的存储与生命周期语义。 _参考:`agentscope/workspace/_local_workspace.py`(`LocalWorkspace`)_ 2. **Workspace manager 类**——位于 `agentscope/app/workspace_manager/`,继承 `WorkspaceManagerBase`。把 workspace 接入应用生命周期。 _参考:`agentscope/app/workspace_manager/_local_workspace_manager.py` 中的 `LocalWorkspaceManager`_ 3. **文档**——在 [agentscope-ai/docs](https://github.com/agentscope-ai/docs) 配套发起 PR,说明该 workspace 的配置与使用方式。 ### Examples 我们非常欢迎新增展示 AgentScope 能力的 example。 主仓库 `examples/` 目录聚焦于**演示具体特性与能力**——简洁、教学性的参考实现。更完整、贴近生产形态的应用,请贡献到 **[agentscope-samples](https://github.com/agentscope-ai/agentscope-samples)**。 新 example 放在自己的子目录下: ``` examples/ └── <example-name>/ ├── main.py ├── README.md # 说明 example 的目的、运行方式与预期输出 └── ... ``` `examples/agent_service/` 是不错的参考起点。 ## 获取帮助 需要协助或有问题,可以: - 发起 [Discussion](https://github.com/agentscope-ai/agentscope/discussions) - 在 [Issues](https://github.com/agentscope-ai/agentscope/issues) 中报告 bug - 通过钉钉或 Discord 联系维护者(链接见 README.md) --- 感谢您为 AgentScope 所做的贡献!每一份努力都在为社区构建更好的开源工具。 - CONTRIBUTING.md (17230 bytes)
# Contributing to AgentScope Thank you for your interest in contributing to AgentScope! As an open-source project, we warmly welcome and encourage contributions from the community. Whether you're fixing bugs, adding new features, improving documentation, or sharing ideas, your contributions help make AgentScope better for everyone. ## 1. Development Roadmap and How to Get Involved To support the long-term, healthy growth of AgentScope and its open-source community, we keep our development plan transparent and openly tracked. **Our roadmap is public.** The AgentScope development plan is published and continuously updated on our [GitHub Projects page](https://github.com/orgs/agentscope-ai/projects/2). The roadmap reflects the technical direction set by the core team, who are responsible for AgentScope's overall design and quality. **Tasks open to the community.** Items labeled `help wanted` on the Projects page/issues are contribution opportunities open to everyone. If one of these interests you: - Comment on the related issue to let us know you'd like to take it on - This helps us avoid duplicate efforts and coordinate with you early **If you'd like to join the core development.** We warmly welcome contributors who want to go deeper and help shape AgentScope itself. Over time, we plan to gradually invite committed contributors into the core development circle. Before reaching out, we'd like to share a few honest expectations so you can decide whether it's a good fit right now: - Core development involves frequent design discussions, code reviews, and iterative revisions — it asks for a sustained investment of time and energy - To keep AgentScope cohesive and reliable, the core team retains responsibility for the project's technical direction and quality bar; core contributors work within this collaborative process If this fits your situation, please reach out to the core developers — we'd love to talk. **Proposing something new.** If you have an idea that isn't on the roadmap yet, please open a new issue describing your proposal. The core team will respond and discuss it with you so we can find the best path forward together. ## 2. Responsible Use of AI in Contributions AgentScope welcomes contributors who use AI coding assistants — Claude Code, Cursor, Codex, Copilot, and others. We just ask that they be used **responsibly**. AgentScope is sustained by reviewer time and community trust, and AI-assisted contributions need to honor both. A few expectations when AI is involved in your work: - **You — not the AI — are the author.** Read the diff line by line, run it, and make sure you understand *what* changed and *why* before you push. "Claude Code / Cursor / Codex told me to do it" is not an acceptable answer in code review, and is not the kind of behavior that builds a healthy open-source community. PRs whose authors cannot explain their own changes will be closed. - **Review your AI-generated code before opening a PR.** Reviewer time is the most precious resource in this project. Don't outsource your own review to the maintainers by dumping unreviewed AI output into a PR. - **Keep PRs atomic.** Do not submit a 10K+-line PR produced by an AI in a single shot. Such PRs are unreviewable and will be rejected. Break the work into focused, single-purpose PRs the same way a human contributor would. - **AI-assisted code follows the same rules.** All of AgentScope's development principles — modularity, lazy imports, conventional commits, test coverage, no surprise API breaks — apply identically to code written with AI assistance. AI is not an excuse for skipping conventions. The goal is simple: AI helps you move faster, but the responsibility for what lands in AgentScope still rests with you as a human contributor. ## 3. Contribution Workflow End-to-end, contributing a change to AgentScope looks like this. ### Step 1. Claim or create an issue Before writing code, find or open the issue that frames your work. - **Working on an existing item?** Browse [Projects](https://github.com/orgs/agentscope-ai/projects/2) and [Issues](https://github.com/agentscope-ai/agentscope/issues) for items labeled `help wanted` (see [§1](#1-development-roadmap-and-how-to-get-involved)). Comment on the issue to claim it before starting. - **Proposing something new?** Open a new issue describing the problem, your proposed solution, and any design alternatives. Wait for feedback from the core team before starting a non-trivial implementation — this avoids wasted rewrites. - **One thing at a time.** Each contributor can have at most 5 open issues and hold at most 5 claimed issues at once. Beyond that, a new issue is closed and a new claim is declined automatically, so please see the ones you already have through first. ### Step 2. Fork the repo and create a development branch 1. Fork [agentscope-ai/agentscope](https://github.com/agentscope-ai/agentscope) on GitHub. 2. Clone your fork and add the upstream remote: ```bash git clone https://github.com/<your-username>/agentscope.git cd agentscope git remote add upstream https://github.com/agentscope-ai/agentscope.git ``` 3. Create a topic branch off the latest `main`: ```bash git checkout main git pull upstream main git checkout -b feat/<short-description> ``` Use a branch name aligned with the change type, e.g., `feat/redis-memory`, `fix/react-agent-leak`, `docs/contributing-update`. ### Step 3. Set up your local environment AgentScope requires **Python 3.11+** (see `pyproject.toml`). ```bash # Create an isolated environment (uv shown; virtualenv / conda also fine) uv venv source .venv/bin/activate # Install AgentScope in editable mode with the dev extras pip install -e ".[dev]" # or, equivalently, with uv: uv pip install -e ".[dev]" # Enable the git pre-commit hooks pre-commit install ``` The `dev` extra pulls in `pre-commit`, `pytest`, the documentation toolchain, and the `full` extra (which itself includes `models`, `service`, and `storage`). A single installation gives you everything needed to develop and run the complete test suite. ### Step 4. Develop A few conventions to follow while writing code: - **Lazy imports for optional dependencies.** Any dependency **not listed in `[project.dependencies]` of `pyproject.toml`** — i.e., anything coming from the optional groups (`gemini`, `ollama`, `xai`, `service`, `storage`, etc.) — **must be lazy-imported** at point of use rather than at module top level: ```python def some_function(): import google.genai # from the `gemini` extra — lazy-imported # ... use google.genai here ``` This keeps `import agentscope` lightweight, and `ImportError` surfaces only when a feature actually relying on the extra is invoked. If your change requires a brand-new dependency, decide first whether it belongs in the base `[project.dependencies]` (always required, kept small) or in one of the optional extras — and discuss it in the issue before merging. - **Follow the project's code style.** Pre-commit handles formatting and most lint rules automatically. Don't fight the formatter. - **Write unit tests alongside features.** Tests live under `tests/` and follow the existing structure. Tests that rely on an optional extra (e.g., Redis, Ollama) should skip cleanly when that extra isn't installed. ### Step 5. Run pre-commit, tests, and update documentation Before opening the PR, run the same checks CI will run: ```bash # Auto-format and lint pre-commit run --all-files # Run the unit tests pytest tests ``` If a pre-commit hook fails, fix the issue (most fixes are applied automatically) and re-stage the files. Don't bypass hooks with `--no-verify`. **Update documentation alongside the code change.** - AgentScope's user-facing documentation lives in a separate repository: **[agentscope-ai/docs](https://github.com/agentscope-ai/docs)**. If your change affects user-facing behavior — new modules, new public APIs, behavior changes, tutorials — please open a companion PR there. - Update inline docstrings and example snippets for any new public APIs. - Update `README.md` if your change affects how users get started or what AgentScope advertises. ### Step 6. Commit and open a pull request **Commit message format.** We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This keeps commit history readable and enables automatic changelog generation. ``` <type>(<scope>): <subject> ``` **Types:** - `feat:` A new feature - `fix:` A bug fix - `docs:` Documentation only changes - `style:` Changes that do not affect the meaning of the code (whitespace, formatting, etc.) - `refactor:` A code change that neither fixes a bug nor adds a feature - `perf:` A code change that improves performance - `test:` Adding missing tests or correcting existing tests - `ci:` Changes to CI configuration files and scripts - `chore:` Changes to the build process or auxiliary tools and libraries **Examples:** ```bash feat(models): add support for Claude-3 model fix(agent): resolve memory leak in ReActAgent docs(readme): update installation instructions refactor(formatter): simplify message formatting logic test(models): add unit tests for OpenAI integration ``` **Pull request title format.** PR titles follow the same Conventional Commits format and are validated automatically by GitHub Actions on PRs against `main`. PRs with invalid titles will be blocked until corrected. ``` <type>(<scope>): <description> ``` **Requirements:** - Title must start with one of: `feat`, `fix`, `docs`, `ci`, `refactor`, `test`, `chore`, `perf`, `style`, `build`, `revert` - Scope is optional but recommended - **Scope must be lowercase** — only lowercase letters, numbers, hyphens (`-`), and underscores (`_`) are allowed - Description should start with a lowercase letter - Keep the title concise and descriptive **Examples:** ``` ✅ Valid: feat(memory): add redis cache support fix(agent): resolve memory leak in ReActAgent docs(tutorial): update installation guide ci(workflow): add PR title validation refactor(my-feature): simplify logic ❌ Invalid: feat(Memory): add cache # Scope must be lowercase feat(MEMORY): add cache # Scope must be lowercase feat(MyFeature): add feature # Scope must be lowercase ``` **Open the PR.** Push your branch to your fork and open a pull request against `agentscope-ai/agentscope:main`. In the PR description: - Link the issue you claimed (`Fixes #123` or `Refs #123`) - Summarize what changed and why - Note any breaking changes, deprecations, or migration steps - Link the companion docs PR in [agentscope-ai/docs](https://github.com/agentscope-ai/docs) if you opened one ## 4. Important Notices A few cross-cutting constraints worth knowing before you start a contribution. Module-specific notices live in the corresponding module guide below. - **Open an issue before non-trivial work.** Surprise PRs that touch many files, change public APIs, or introduce a new module are difficult to review and likely to be rejected. Discuss the design in an issue first. - **Keep PRs focused and atomic.** One PR, one purpose. Don't bundle a refactor with a feature, or a feature with an unrelated bug fix. - **Don't break public APIs without notice.** Maintain backward compatibility when you can. If a breaking change is unavoidable, call it out clearly in the PR description and update the affected examples and docs in the same PR. - **Don't bypass the lazy import principle.** Optional dependencies must be imported at point of use, not at module top level. - **Don't add dependencies casually.** Every new dependency is a long-term maintenance commitment. If a dependency is needed by only one module, prefer a lazy import inside that module. - **Don't ignore CI failures.** Pre-commit, type checks, and tests must pass before a PR is ready for review. Don't push the burden of fixing them onto the reviewer. - **Be respectful.** Follow our Code of Conduct. AgentScope's review culture is direct but kind, and we expect the same from contributors. ## 5. Module-Specific Contribution Guides The notes below cover the modules most commonly extended by community contributors. For other modules, please open an issue first so we can coordinate. ### Chat Model A chat model in AgentScope is more than a single class — to be usable inside an `Agent`, it needs a small set of upstream/downstream pieces. A complete chat-model contribution includes **all** of the following: 1. **Credential class** — under `agentscope.credential`, subclassing `CredentialBase`. Carries the API key, endpoint, and other auth fields your SDK needs. _Reference: `agentscope/credential/_anthropic.py`_ 2. **Chat model class** — under `agentscope.model.<provider>/`, subclassing `ChatModelBase`. The implementation needs to cover: - Both streaming and non-streaming modes - Tools API integration (function/tool calling) - The `tool_choice` argument - Reasoning models, where applicable _Reference: `agentscope/model/_anthropic/`_ 3. **Model card YAML(s)** — under `agentscope.model.<provider>._models/`, one YAML per supported model. Required fields: `name`, `label`, `status`, `input_types`, `output_types`, `context_size`, `output_size`. Optional: `parameter_overrides`, `deprecated_at`. Example (`claude-sonnet-4-6.yaml`): ```yaml name: claude-sonnet-4-6 label: Claude Sonnet 4.6 status: active input_types: - text/plain - image/jpeg output_types: - text/plain context_size: 1000000 output_size: 65536 parameter_overrides: max_tokens: {"maximum": 65536} ``` 4. **Formatter classes** — under `agentscope.formatter`, both subclassing `FormatterBase`. Two variants are required because some APIs treat multi-agent conversations differently from single-user chat: - `<Provider>ChatFormatter` for single-user chat scenarios - `<Provider>MultiAgentFormatter` for multi-agent scenarios Each formatter converts `Msg` objects into the request format the provider's API expects. _Reference: `agentscope/formatter/_anthropic_formatter.py`_ > ⚠️ PRs that add only the model class without the matching credential, > model card YAML, and both formatter variants will not be merged. ### Agent AgentScope deliberately maintains a **single core agent class** — `agentscope.agent.Agent` — that integrates all functionality of the AgentScope library (memory, tools, MCP, formatters, models, etc.). For specialized or domain-specific agents, please contribute them as [examples](#examples) rather than as new classes in `agentscope.agent`. If you believe a use case genuinely requires a new top-level agent class: 1. **Open an issue first** describing the use case and explaining why composing existing `Agent` capabilities is insufficient. 2. - INSTRUCTIONS.md (477 bytes)
You are the autonomous runtime coordinator for agentscope. System Archetype: agent. Description: Build and run agents you can see, understand and trust. Core Directives: 1. Execute operations deterministically following verified repository manifests. 2. Strictly enforce safe input validation and local-first execution boundaries. 3. Provide structured outputs, formatted logs, and actionable resolution steps. 4. Preserve data integrity and respect local workspace isolation.
- LICENSE (20637 bytes)
Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright 2024 Alibaba Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -------------------------------------------------------------------------------- Some codes of tests/run.py is modified from https://github.com/alibaba/FederatedScope/blob/master/tests/run.py, which is also licensed under the terms of the Apache 2.0. -------------------------------------------------------------------------------- Code in src/agentscope/web/static/js/socket.io.js is adapted from https://cdnjs.cloudflare.com/ajax/libs/socket.io/3.1.3/socket.io.js (MIT License) Copyright (c) 2014-2021 Guillermo Rauch Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- Code in src/agentscope/web/static/js/jquery-3.3.1.min.js is adapted from https://code.jquery.com/jquery-3.3.1.min.js (MIT License) Copyright (c) JS Foundation and other contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- Code in src/agentscope/web/static/js/bootstrap.bundle.min.js is adapted from https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js (MIT License) Copyright (c) 2011-2019 The Bootstrap Authors (https://github .com/twbs/bootstrap/graphs/contributors) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice a - pyproject.toml (7918 bytes)
[project] name = "agentscope" dynamic = ["version"] description = "AgentScope: A Flexible yet Robust Multi-Agent Platform." readme = "README.md" authors = [ { name = "SysML team of Alibaba Tongyi Lab", email = "[email protected]" } ] license = "Apache-2.0" keywords = ["agent", "multi-agent", "LLM", "AI"] classifiers = [ "Development Status :: 4 - Beta", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.11", "Operating System :: OS Independent", "Intended Audience :: Developers", "Intended Audience :: Science/Research", "Topic :: Scientific/Engineering :: Artificial Intelligence", ] requires-python = ">=3.11" dependencies = [ "aioitertools", "anthropic", "certifi>=2026.10.19", "dashscope>=1.20.0", "docstring_parser", "filetype", "json5", "json_repair[schema]>=0.63.4", "mcp>=2.0.0", "httpx", "httpx2>=2.5.0", "numpy", "openai", "python-datauri", "opentelemetry-api>=1.39.0", "opentelemetry-sdk>=1.39.0", "opentelemetry-exporter-otlp>=1.39.0", "opentelemetry-semantic-conventions>=0.60b0", "python-socketio", "rich", "shortuuid", "python-frontmatter", "jinja2", "aiofiles", "tree_sitter", "tree_sitter_bash", "jsonschema", "referencing", "pypdf", # The IANA timezone database, which is absent on Windows and slim images "tzdata", ] [project.optional-dependencies] # ------------ Model APIs ------------ model-gemini = ["google-genai>=3.3.0"] model-ollama = ["ollama>=0.5.4"] model-xai = ["xai-sdk"] classifier-jev = ["typesafe-sdk>=0.7"] models = [ "agentscope[model-gemini]", "agentscope[model-ollama]", "agentscope[model-xai]", ] classifiers = ["agentscope[classifier-jev]"] # ------------ Service ------------ service = [ "fastapi", "uvicorn", "apscheduler", "ag-ui-protocol>=0.1.10", "aiortc>=1.14", ] # ------------ Storage backends ------------ storage-redis = ["redis"] # Async SQLAlchemy 2.0 + Alembic. The concrete driver # (aiosqlite / asyncpg / aiomysql / asyncmy) is left to the user # so the extra stays lightweight. storage-sql = [ "sqlalchemy[asyncio]>=2.0", "alembic>=1.13", ] # S3-compatible blob store storage-s3 = ["aioboto3"] # ------------ Channel ------------ channel = [ "lark-oapi>=1.4.0", "discord.py>=2.3", "dingtalk-stream>=0.24.3", ] # ------------ Workspace (sandbox backends) ------------ workspace-docker = ["aiodocker"] workspace-e2b = ["e2b"] workspace-daytona = ["daytona"] workspace-k8s = ["kubernetes-asyncio"] workspace-opensandbox = ["opensandbox"] workspace = [ "agentscope[workspace-docker]", "agentscope[workspace-e2b]", "agentscope[workspace-daytona]", "agentscope[workspace-k8s]", "agentscope[workspace-opensandbox]", ] # ------------ Tools ------------ # Ships the ``rg`` binary for the builtin Grep tool on LocalWorkspace # (remote sandboxes install ripgrep inside the sandbox instead). # 15.x ships wheels only for macOS-arm64 and manylinux_2_39 x86_64, so # everything else (Windows, glibc<2.39, musl, aarch64) falls back to the # Rust sdist and fails without a toolchain (#2504). 14.0 lacks those # wheels too, hence the lower bound. Lift once upstream restores them. tools = [ "ripgrep>=14.1,<15", ] # ------------ Realtime voice ------------ realtime = [ "websockets>=14", ] realtime-local = ["sounddevice"] # ------------ Terminal UI ------------ tui = [ "textual>=8.2,<9", ] # ------------ A2A ------------ a2a = [ "a2a-sdk>=1.1.1", ] # ------------ Vector stores ------------ vdb-qdrant = ["qdrant-client"] vdb-milvus = [ "pymilvus>=2.4.0", "milvus-lite>=3.1.0", ] vdb-mongodb = ["pymongo>=4.7"] vdb-elasticsearch = ["elasticsearch[async]>=8.12"] # ------------ RAG ------------ # Document parsers; pick a vector store via the vdb-* extras. rag = [ "pypdf", "python-pptx", "python-docx", "openpyxl>=3.1.5", "xlrd>=2.0", "pandas", ] # ------------ Long-term memory ------------ # Required by `agentscope.middleware._longterm_memory.Mem0Middleware`. # Pinned to mem0 v2.x because the middleware targets that # architecture: ADDITIVE_EXTRACTION_PROMPT + AGENT_CONTEXT_SUFFIX # (replaced v1's USER/AGENT_MEMORY_EXTRACTION_PROMPT split) and the # v3 phased pipeline in `_add_to_vector_store`. Running on mem0 1.x # wouldn't crash but the 2-tier add fallback degenerates into a # wasted LLM call. memory-mem0 = ["mem0ai>=2.0.0"] # Required by `agentscope.middleware._longterm_memory.ReMeMiddleware`. memory-reme = ["reme-ai>=0.4.0.6"] memory = [ "agentscope[memory-mem0]", "agentscope[memory-reme]", ] # ------------ Deprecated aliases ------------ # Kept for backward compatibility; will be removed in a future # major release. Use the prefixed names instead. gemini = ["agentscope[model-gemini]"] ollama = ["agentscope[model-ollama]"] xai = ["agentscope[model-xai]"] storage = ["agentscope[storage-redis]"] sql = ["agentscope[storage-sql]"] s3 = ["agentscope[storage-s3]"] k8s = ["agentscope[workspace-k8s]"] milvuslite = ["agentscope[vdb-milvus]"] mongodb = ["agentscope[vdb-mongodb]"] elasticsearch = ["agentscope[vdb-elasticsearch]"] mem0 = ["agentscope[memory-mem0]"] reme = ["agentscope[memory-reme]"] # ------------ Full ------------ full = [ "agentscope[models]", "agentscope[classifiers]", "agentscope[service]", "agentscope[realtime]", "agentscope[storage-redis]", "agentscope[storage-sql]", "agentscope[storage-s3]", "agentscope[channel]", "agentscope[workspace]", "agentscope[tools]", "agentscope[tui]", "agentscope[a2a]", "agentscope[rag]", "agentscope[vdb-qdrant]", "agentscope[vdb-milvus]", "agentscope[vdb-mongodb]", "agentscope[vdb-elasticsearch]", "agentscope[memory]", ] # ------------ Development ------------ dev = [ # Include full dependencies from local package "agentscope[full]", # Development tools "pre-commit", "pytest", "pytest-forked", "myst_parser", "matplotlib", # ``[lua]`` pulls in lupa so EVAL-based code paths are testable. "fakeredis[lua]", # SQL backend tests — SQLite via aiosqlite so no server is needed. "aiosqlite", # S3-backend testing — moto[server] spins up an in-process S3 # (aioboto3 comes via full→storage-s3), boto3 seeds/verifies buckets. "moto[server,s3]", "boto3", # RAG parser tests — used to generate PDF fixtures in-memory "reportlab", ] [project.urls] Homepage = "https://github.com/agentscope-ai/agentscope" Documentation = "https://docs.agentscope.io/" Repository = "https://github.com/agentscope-ai/agentscope" [tool.setuptools] packages = { find = { where = ["src"] } } include-package-data = true [tool.setuptools.package-data] # ``"*"`` applies to every discovered package. Patterns: # - ``py.typed`` marks the typed package per PEP 561. # - ``_models/*.yaml`` reaches into the data-only ``_models/`` # subdirs that ship with each model provider (they have no # ``__init__.py`` and are not packages, but the files still # live alongside the parent package's source on disk). "*" = [ "py.typed", "_models/*.yaml", "_cosyvoice_models/*.yaml", ] "agentscope.workspace._docker" = ["Dockerfile*.template"] # The Alembic scaffolding for the SQL storage backend lives in the # data-only ``_alembic/`` subtree (no ``__init__.py`` — Alembic loads # ``env.py`` / the version scripts by file path, not import). Ship them # explicitly so ``auto_migrate=True`` works from an installed wheel. "agentscope.app.storage._sql" = [ "_alembic/alembic.ini", "_alembic/script.py.mako", "_alembic/env.py", "_alembic/versions/*.py", ] [build-system] requires = ["setuptools>=45", "wheel"] build-backend = "setuptools.build_meta" [tool.setuptools.dynamic] version = {attr = "agentscope._version.__version__"} - README_zh.md (14519 bytes)
<p align="center"> <img src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg" alt="AgentScope Logo" width="200" /> </p> <span align="center"> [**English Homepage**](https://github.com/agentscope-ai/agentscope/blob/main/README.md) | [**文档**](https://docs.agentscope.io/) | [**路线图**](https://github.com/orgs/agentscope-ai/projects/2/views/1) </span> <p align="center"> <a href="https://arxiv.org/abs/2402.14034"> <img src="https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C" alt="arxiv" /> </a> <a href="https://pypi.org/project/agentscope/"> <img src="https://img.shields.io/badge/python-3.11+-blue?logo=python" alt="pypi" /> </a> <a href="https://pypi.org/project/agentscope/"> <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fagentscope%2Fjson&query=%24.info.version&prefix=v&logo=pypi&label=version" alt="pypi" /> </a> <a href="https://discord.gg/eYMpfnkG8h"> <img src="https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord&logoColor=white" alt="discord" /> </a> <a href="https://docs.agentscope.io/"> <img src="https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown" alt="docs" /> </a> <a href="./LICENSE"> <img src="https://img.shields.io/badge/license-Apache--2.0-black" alt="license" /> </a> <a href="https://deepwiki.com/agentscope-ai/agentscope"> <img src="https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)" alt="Ask DeepWiki" /> </a> </p> <p align="center"> <img src="https://trendshift.io/api/badge/repositories/20310" alt="agentscope-ai%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/> </p> ## What's AgentScope 2.0? AgentScope 2.0 是一款面向生产、易于使用的智能体框架,提供与不断进化的模型能力相匹配的核心抽象。 AgentScope 的目标是充分发挥大模型的推理与工具调用能力, 而非用严格的提示词和固化的编排方式来束缚它们。 <img src="https://img.alicdn.com/imgextra/i3/O1CN01k5XbA5dLCIB4S3xd_!!6000000003894-2-tps-2193-1564.png" alt="agentscope" width="100%"/> ## 新闻 <!-- BEGIN NEWS --> - **[2026-10] `功能`:** 支持音色配置管理与语音复刻,可在聊天中选择已保存的音色;Python SDK 新增 DashScope 和 OpenAI 音色复刻客户端。 - **[2026-10] `功能` `实验性`:** 智能体服务支持基于 WebRTC 的实时语音对话,文本与语音模式共享同一会话历史。 - **[2026-09] `功能` `实验性`:** 支持 SOP(标准作业流程)—— 将多步骤任务按标准流程执行,框架与智能体服务均已支持。[文档](https://docs.agentscope.io/latest/zh/building-blocks/sop) | [服务](https://docs.agentscope.io/latest/zh/deploy/sop) - **[2026-09] `功能`:** 支持 `TeamPipeline` —— 由 leader 智能体向成员智能体分派任务。[文档](https://docs.agentscope.io/latest/zh/building-blocks/pipeline/team) - **[2026-09] `集成`:** 通过 `MiniMaxChatModel` 支持 MiniMax 聊天模型(默认 MiniMax-M3)。 - **[2026-09] `功能`:** 支持模型路由 —— 使用 `ModelRouterMiddleware` 为每次回复选择合适的聊天模型。 - **[2026-09] `集成`:** 通过 TypeSafe SDK 集成 Jev 分类模型 `JevClassifierModel`。 - **[2026-09] `功能`:** [agentscope-skill](https://github.com/agentscope-ai/skills/tree/main/skills/agentscope-skill) 已适配 AgentScope v2。 - **[2026-09] `集成`:** `RealtimeAgent` 支持 DashScope、OpenAI、Gemini 与 xAI 的实时语音 API。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/realtime) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/realtime/speech-to-speech) - **[2026-09] `功能` `实验性`:** 支持实时语音智能体。[样例](https://github.com/agentscope-ai/agentscope/tree/main/examples/realtime) | [文档](https://docs.agentscope.io/latest/zh/building-blocks/realtime/overview) <!-- END NEWS --> [更多新闻 →](./docs/NEWS_zh.md) ## 社区 欢迎加入我们的社区 | [Discord](https://discord.gg/eYMpfnkG8h) | 钉钉 | |----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="./assets/images/dingtalk_qr_code.png" width="100" height="100"> | ## 快速开始 ### 安装 > AgentScope 需要 **Python 3.11** 或更高版本。 #### 从 PyPI 安装 ```bash uv pip install agentscope ``` #### 从源码安装 ```bash # 从 GitHub 拉取源码 git clone -b main https://github.com/agentscope-ai/agentscope.git # 以可编辑模式安装 cd agentscope uv pip install -e . ``` ## 智能体(Agent) SDK 层 —— 用一整套丰富的构建模块组合出你的智能体: | 构建模块 | 包含内容 | |---|---| | [**ReAct**](https://docs.agentscope.io/latest/zh/building-blocks/agent/overview) | 推理-行动循环,支持结构化输出、实时中断与恢复、以及批量(顺序 / 并发)工具执行 | | [**工具集**](https://docs.agentscope.io/latest/zh/building-blocks/tool/overview) | 智能体自主工具管理(囊括 Python 工具、MCP 与 Skill);内置编码工具(Shell、文件编辑、搜索)与任务/规划工具开箱即用 | | [**模型**](https://docs.agentscope.io/latest/zh/building-blocks/model/overview) | LLM、Embedding、TTS,覆盖主流厂商(OpenAI、Anthropic、Gemini、DashScope、DeepSeek、Moonshot、Volcengine、xAI、Ollama) | | [**上下文**](https://docs.agentscope.io/latest/zh/building-blocks/context/overview) | 自动压缩、工具结果卸载、以及上下文注入(系统提示、RAG、记忆),均由内置中间件实现 | | [**事件系统**](https://docs.agentscope.io/latest/zh/building-blocks/message-and-event) | 统一事件总线,将推理、工具调用与多模态内容(文本、图像、音频)流式推送到前端 | | [**权限与 HITL**](https://docs.agentscope.io/latest/zh/building-blocks/permission-system/overview) | 对工具和资源的细粒度控制、确认、bypass 模式 | | [**中间件**](https://docs.agentscope.io/latest/zh/building-blocks/middleware) | 贯穿整个循环的可组合钩子 —— 回复、推理、行动、模型调用、权限检查、上下文压缩、系统提示 | | [**记忆**](https://docs.agentscope.io/latest/zh/building-blocks/long-term-memory) | Agentic Memory,可切换后端(ReMe、Mem0) | | [**工作空间 / 沙箱**](https://docs.agentscope.io/latest/zh/building-blocks/workspace/overview) | 隔离工具与代码执行 —— local、Docker、Apple Container、Bubblewrap、E2B、OpenSandbox、Daytona、K8s | 使用 AgentScope 2.0,在终端中启动你的第一个智能体: ```python from agentscope.agent import Agent from agentscope.console import launch_console from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit from agentscope.credential import DashScopeCredential from agentscope.model import DashScopeChatModel import os, asyncio async def main() -> None: agent = Agent( name="Friday", system_prompt="You're a helpful assistant named Friday.", model=DashScopeChatModel( credential=DashScopeCredential( api_key=os.environ["DASHSCOPE_API_KEY"] ), model="qwen3.6-plus", ), toolkit=Toolkit( tools=[ Bash(), Grep(), Glob(), Read(), Write(), Edit(), ] ), ) # 在终端中与智能体对话 —— 流式输出、工具调用确认、 # Ctrl+C 中断均已内置处理 await launch_console(agent) asyncio.run(main()) ``` ## 智能体服务 —— 构建应用所需的一切 AgentScope 提供开箱即用的**智能体服务** —— 一个基于 FastAPI 的后端,并在 `examples/web_ui` 中附带预构建的 Web UI,将你的智能体变成一个多租户、多会话的应用,并自带一整套丰富的能力: | 能力 | 包含内容 | |---|---| | [**服务**](https://docs.agentscope.io/latest/zh/deploy/agent-service) | 多租户、多会话隔离、FastAPI 后端、预构建 Web UI | | [**智能体团队**](https://docs.agentscope.io/latest/zh/deploy/agent-team) | Leader–Worker 编排、内置团队工具、任务规划 | | [**消息渠道**](https://docs.agentscope.io/latest/zh/deploy/channel/overview) | 将智能体接入 IM 平台 —— 飞书(Lark)、Discord、自定义渠道、消息路由 | | [**RAG 服务**](https://docs.agentscope.io/latest/zh/deploy/rag) | Blob 存储、索引 Worker、多租户检索 | | [**MCP & 技能 Hub**](https://docs.agentscope.io/latest/zh/deploy/hub/overview) | 浏览 Hub(GitHub MCP Registry、ClawHub)、安装到你的库、添加到工作空间 | | [**资源共享**](https://docs.agentscope.io/latest/zh/deploy/sharing) | 面向 group 与 org 的资源管理,共享模型、MCP 服务、技能与工作空间 | | [**持久化**](https://docs.agentscope.io/latest/zh/deploy/agent-service#storage-backend) | 智能体状态与会话的 SQL & NoSQL 持久化 | | [**调度**](https://docs.agentscope.io/latest/zh/deploy/agent-service) | 定时任务、智能体唤醒、后台任务卸载 | 以上能力皆可组合,你只需少量胶水代码,就能在此服务之上搭建起自己的应用。 <table> <tr> <td align="center"> <img src="assets/images/team.gif" alt="智能体团队" width="100%"/> <br/> <sub><b>智能体团队</b> —— leader 智能体派生 worker,并通过内置的团队工具进行协调。</sub> </td> </tr> <tr> <td align="center"> <img src="assets/images/task.gif" alt="任务规划" width="100%"/> <br/> <sub><b>任务规划</b> —— 智能体将复杂工作拆解为可追踪的计划,并在执行过程中持续更新。</sub> </td> </tr> <tr> <td align="center"> <img src="assets/images/permission_bypass.gif" alt="bypass 模式下的权限控制" width="100%"/> <br/> <sub><b>bypass 模式下的权限控制</b> —— 智能体端到端运行,无需为工具调用确认而暂停。</sub> </td> </tr> <tr> <td align="center"> <img src="assets/images/bg_tool.gif" alt="后台任务卸载" width="100%"/> <br/> <sub><b>工具后台执行</b> —— 长时间运行的工具被转入后台;其结果稍后唤醒智能体并恢复对话。</sub> </td> </tr> </table> 运行以下命令启动智能体服务后端和 Web UI: ```bash git clone -b main https://github.com/agentscope-ai/agentscope.git cd agentscope/examples/agent_service # 启动智能体服务后端 python main.py ``` 然后打开另一个终端启动 Web UI: ```bash cd agentscope/examples/web_ui # 启动 webui pnpm install pnpm dev ``` ## 贡献 我们欢迎社区的贡献!请参阅我们的 [贡献指南](./CONTRIBUTING_zh.md) 了解如何贡献。 ## 许可 AgentScope 基于 Apache License 2.0 发布。 ## 论文 如果我们的工作对您的研究或应用有帮助,请引用我们的论文。 - [AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications](https://arxiv.org/abs/2508.16279) - [AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034) ``` @article{agentscope_v1, author = {Dawei Gao, Zitao Li, Yuexiang Xie, Weirui Kuang, Liuyi Yao, Bingchen Qian, Zhijian Ma, Yue Cui, Haohao Luo, Shen Li, Lu Yi, Yi Yu, Shiqi He, Zhiling Luo, Wenmeng Zhou, Zhicheng Zhang, Xuguang He, Ziqian Chen, Weikai Liao, Farruh Isakulovich Kushnazarov, Yaliang Li, Bolin Ding, Jingren Zhou} title = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications}, journal = {CoRR}, volume = {abs/2508.16279}, year = {2025}, } @article{agentscope, author = {Dawei Gao, Zitao Li, Xuchen Pan, Weirui Kuang, Zhijian Ma, Bingchen Qian, Fei Wei, Wenhao Zhang, Yuexiang Xie, Daoyuan Chen, Liuyi Yao, Hongyi Peng, Zeyu Zhang, Lin Zhu, Chen Cheng, Hongzhu Shi, Yaliang Li, Bolin Ding, Jingren Zhou} title = {AgentScope: A Flexible yet Robust Multi-Agent Platform}, journal = {CoRR}, volume = {abs/2402.14034}, year = {2024}, } ``` ## 贡献者 感谢所有贡献者: <a href="https://github.com/agentscope-ai/agentscope/graphs/contributors"> <img src="https://contrib.rocks/image?repo=agentscope-ai/agentscope&max=999&columns=12&anon=1" /> </a> - README.md (14699 bytes)
<p align="center"> <img src="https://img.alicdn.com/imgextra/i1/O1CN01nTg6w21NqT5qFKH1u_!!6000000001621-55-tps-550-550.svg" alt="AgentScope Logo" width="200" /> </p> <span align="center"> [**中文主页**](https://github.com/agentscope-ai/agentscope/blob/main/README_zh.md) | [**Documentation**](https://docs.agentscope.io/) | [**Roadmap**](https://github.com/orgs/agentscope-ai/projects/2/views/1) </span> <p align="center"> <a href="https://arxiv.org/abs/2402.14034"> <img src="https://img.shields.io/badge/cs.MA-2402.14034-B31C1C?logo=arxiv&logoColor=B31C1C" alt="arxiv" /> </a> <a href="https://pypi.org/project/agentscope/"> <img src="https://img.shields.io/badge/python-3.11+-blue?logo=python" alt="pypi" /> </a> <a href="https://pypi.org/project/agentscope/"> <img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fpypi.org%2Fpypi%2Fagentscope%2Fjson&query=%24.info.version&prefix=v&logo=pypi&label=version" alt="pypi" /> </a> <a href="https://discord.gg/eYMpfnkG8h"> <img src="https://img.shields.io/badge/Discord-Join%20Us-5865F2?logo=discord&logoColor=white" alt="discord" /> </a> <a href="https://docs.agentscope.io/"> <img src="https://img.shields.io/badge/Docs-English%7C%E4%B8%AD%E6%96%87-blue?logo=markdown" alt="docs" /> </a> <a href="./LICENSE"> <img src="https://img.shields.io/badge/license-Apache--2.0-black" alt="license" /> </a> <a href="https://deepwiki.com/agentscope-ai/agentscope"> <img src="https://img.shields.io/badge/DeepWiki-Ask_Devin-navy.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)" alt="Ask DeepWiki" /> </a> </p> <p align="center"> <img src="https://trendshift.io/api/badge/repositories/20310" alt="agentscope-ai%2Fagentscope | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/> </p> ## What is AgentScope 2.0? AgentScope 2.0 is a production-ready, easy-to-use agent framework with essential abstractions that keep up with rising model capability. We design for increasingly agentic LLMs. Our approach leverages the models' reasoning and tool use abilities rather than constraining them with strict prompts and opinionated orchestrations. <img src="https://img.alicdn.com/imgextra/i3/O1CN01k5XbA5dLCIB4S3xd_!!6000000003894-2-tps-2193-1564.png" alt="agentscope" width="100%"/> ## News <!-- BEGIN NEWS --> - **[2026-10] `FEAT`:** Voice profile management and voice cloning supported — select saved voices in chat, with DashScope and OpenAI voice cloning clients available in the Python SDK. - **[2026-10] `FEAT` `Experimental`:** Agent service supports realtime voice conversations over WebRTC, with text and voice sharing the same session history. - **[2026-09] `FEAT` `Experimental`:** SOP supported — run multi-step tasks as standard operating procedures, in both the framework and agent service. [Docs](https://docs.agentscope.io/latest/en/building-blocks/sop) | [Service](https://docs.agentscope.io/latest/en/deploy/sop) - **[2026-09] `FEAT`:** `TeamPipeline` supported — a leader agent delegates tasks to member agents. [Docs](https://docs.agentscope.io/latest/en/building-blocks/pipeline/team) - **[2026-09] `INTE`:** MiniMax chat models supported via `MiniMaxChatModel` (MiniMax-M3 by default). - **[2026-09] `FEAT`:** Model routing supported — use `ModelRouterMiddleware` to select an appropriate chat model for each reply. - **[2026-09] `INTE`:** Jev classifier model supported through the TypeSafe SDK via `JevClassifierModel`. - **[2026-09] `FEAT`:** [agentscope-skill](https://github.com/agentscope-ai/skills/tree/main/skills/agentscope-skill) now supports AgentScope v2. - **[2026-09] `INTE`:** Support DashScope, OpenAI, Gemini and xAI realtime APIs in `RealtimeAgent`. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/realtime) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/realtime/speech-to-speech) - **[2026-09] `FEAT` `Experimental`:** Realtime voice agent supported. [Example](https://github.com/agentscope-ai/agentscope/tree/main/examples/realtime) | [Docs](https://docs.agentscope.io/latest/en/building-blocks/realtime/overview) <!-- END NEWS --> [More news →](./docs/NEWS.md) ## Community Welcome to join our community on | [Discord](https://discord.gg/eYMpfnkG8h) | DingTalk | |----------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | <img src="https://gw.alicdn.com/imgextra/i1/O1CN01hhD1mu1Dd3BWVUvxN_!!6000000000238-2-tps-400-400.png" width="100" height="100"> | <img src="./assets/images/dingtalk_qr_code.png" width="100" height="100"> | ## Quickstart ### Installation > AgentScope requires **Python 3.11** or higher. #### From PyPI ```bash uv pip install agentscope ``` #### From source ```bash # Pull the source code from GitHub git clone -b main https://github.com/agentscope-ai/agentscope.git # Install the package in editable mode cd agentscope uv pip install -e . ``` ## Agent The SDK layer — compose an agent from a rich set of building blocks: | Building block | What's inside | |---|---| | [**ReAct**](https://docs.agentscope.io/latest/en/building-blocks/agent/overview) | Reasoning-acting loop with structured output, realtime interruption & resume, and batched (sequential / concurrent) tool acting | | [**Toolkit**](https://docs.agentscope.io/latest/en/building-blocks/tool/overview) | Agentic tool management over Python tools, MCP servers, and skills; ships with built-in coding tools (shell, file edit, search) and task/plan tools | | [**Model**](https://docs.agentscope.io/latest/en/building-blocks/model/overview) | LLM, embedding, and TTS across major providers (OpenAI, Anthropic, Gemini, DashScope, DeepSeek, Moonshot, Volcengine, xAI, Ollama) | | [**Context**](https://docs.agentscope.io/latest/en/building-blocks/context/overview) | Automatic compaction, tool-result offload, and context injection (system prompt, RAG, memory) via built-in middleware | | [**Event System**](https://docs.agentscope.io/latest/en/building-blocks/message-and-event) | Unified event bus streaming reasoning, tool calls, and multimodal content (text, image, audio) to the frontend | | [**Permission & HITL**](https://docs.agentscope.io/latest/en/building-blocks/permission-system/overview) | Fine-grained control over tools and resources, confirmation, bypass mode | | [**Middleware**](https://docs.agentscope.io/latest/en/building-blocks/middleware) | Composable hooks across the loop — reply, reasoning, acting, model calling, permission checking, context compression, system prompt | | [**Memory**](https://docs.agentscope.io/latest/en/building-blocks/long-term-memory) | Agentic memory with switchable backends (ReMe, Mem0) | | [**Workspace / Sandbox**](https://docs.agentscope.io/latest/en/building-blocks/workspace/overview) | Isolated tool & code execution — local, Docker, Apple Container, Bubblewrap, E2B, OpenSandbox, Daytona, K8s | Start your first agent with AgentScope 2.0 in console: ```python from agentscope.agent import Agent from agentscope.console import launch_console from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit from agentscope.credential import DashScopeCredential from agentscope.model import DashScopeChatModel import os, asyncio async def main() -> None: agent = Agent( name="Friday", system_prompt="You're a helpful assistant named Friday.", model=DashScopeChatModel( credential=DashScopeCredential( api_key=os.environ["DASHSCOPE_API_KEY"] ), model="qwen3.6-plus", ), toolkit=Toolkit( tools=[ Bash(), Grep(), Glob(), Read(), Write(), Edit(), ] ), ) # Chat with the agent in the terminal — streamed output, tool-call # confirmation and Ctrl+C interruption are all handled for you await launch_console(agent) asyncio.run(main()) ``` ## Agent Service — All You Need to Build Your App AgentScope ships a batteries-included **agent service** — a FastAPI backend with a pre-built Web UI (`examples/web_ui`) that turns your agents into a multi-tenant, multi-session application, with rich capabilities out of the box: | Capability | What you get | |---|---| | [**Serving**](https://docs.agentscope.io/latest/en/deploy/agent-service) | Multi-tenancy, multi-session isolation, FastAPI backend, pre-built Web UI | | [**Agent Team**](https://docs.agentscope.io/latest/en/deploy/agent-team) | Leader–worker orchestration, built-in team tools, task planning | | [**Channels**](https://docs.agentscope.io/latest/en/deploy/channel/overview) | Connect agents to IM platforms — Feishu (Lark), Discord, custom channels, message routing | | [**RAG Service**](https://docs.agentscope.io/latest/en/deploy/rag) | Blob storage, index worker, multi-tenant retrieval | | [**MCP & Skill Hub**](https://docs.agentscope.io/latest/en/deploy/hub/overview) | Browse hubs (GitHub MCP Registry, ClawHub), install into your library, add to a workspace | | [**Resource Sharing**](https://docs.agentscope.io/latest/en/deploy/sharing) | Group- and org-level management for sharing models, MCP servers, skills, and workspaces | | [**Persistence**](https://docs.agentscope.io/latest/en/deploy/agent-service#storage-backend) | SQL & NoSQL persistence of agent state and sessions | | [**Scheduling**](https://docs.agentscope.io/latest/en/deploy/agent-service) | Scheduled tasks, agent wakeup, background task offloading | Everything above is composable, so you can assemble your own application on top of the service with minimal glue code. <table> <tr> <td align="center"> <img src="assets/images/team.gif" alt="Agent team" width="100%"/> <br/> <sub><b>Agent team</b> — a leader agent spawns workers and coordinates them through the built-in team tools.</sub> </td> </tr> <tr> <td align="center"> <img src="assets/images/task.gif" alt="Task planning" width="100%"/> <br/> <sub><b>Task planning</b> — the agent breaks complex work into a tracked plan and updates it as it goes.</sub> </td> </tr> <tr> <td align="center"> <img src="assets/images/permission_bypass.gif" alt="Permission control in bypass mode" width="100%"/> <br/> <sub><b>Permission control in bypass mode</b> — the agent runs end-to-end without pausing for tool-call confirmations.</sub> </td> </tr> <tr> <td align="center"> <img src="assets/images/bg_tool.gif" alt="Background task offloading" width="100%"/> <br/> <sub><b>Background task offloading</b> — a long-running tool moves to the background; its result later wakes the agent up and the conversation resumes.</sub> </td> </tr> </table> Run the following commands to start the agent service backend and the web UI: ```bash git clone -b main https://github.com/agentscope-ai/agentscope.git cd agentscope/examples/agent_service # start the agent service backend python main.py ``` Then open another terminal to start the web UI: ```bash cd agentscope/examples/web_ui # start the webui pnpm install pnpm dev ``` ## Contributing We welcome contributions from the community! Please refer to our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute. ## License AgentScope is released under Apache License 2.0. ## Publications If you find our work helpful for your research or application, please cite our papers. - [AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications](https://arxiv.org/abs/2508.16279) - [AgentScope: A Flexible yet Robust Multi-Agent Platform](https://arxiv.org/abs/2402.14034) ``` @article{agentscope_v1, author = {Dawei Gao, Zitao Li, Yuexiang Xie, Weirui Kuang, Liuyi Yao, Bingchen Qian, Zhijian Ma, Yue Cui, Haohao Luo, Shen Li, Lu Yi, Yi Yu, Shiqi He, Zhiling Luo, Wenmeng Zhou, Zhicheng Zhang, Xuguang He, Ziqian Chen, Weikai Liao, Farruh Isakulovich Kushnazarov, Yaliang Li, Bolin Ding, Jingren Zhou} title = {AgentScope 1.0: A Developer-Centric Framework for Building Agentic Applications}, journal = {CoRR}, volume = {abs/2508.16279}, year = {2025}, } @article{agentscope, author = {Dawei Gao, Zitao Li, Xuchen Pan, Weirui Kuang, Zhijian Ma, Bingchen Qian, Fei Wei, Wenhao Zhang, Yuexiang Xie, Daoyuan Chen, Liuyi Yao, Hongyi Peng, Zeyu Zhang, Lin Zhu, Chen Cheng, Hongzhu Shi, Yaliang Li, Bolin Ding, Jingren Zhou} title = {AgentScope: A Flexible yet Robust Multi-Agent Platform}, journal = {CoRR}, volume = {abs/2402.14034}, year = {2024}, } ``` ## Contributors All thanks to our contributors: <a href="https://github.com/agentscope-ai/agentscope/graphs/contributors"> <img src="https://contrib.rocks/image?repo=agentscope-ai/agentscope&max=999&columns=12&anon=1" /> </a> - src/agentscope/__init__.py (440 bytes)
# -*- coding: utf-8 -*- """The agentscope package.""" import warnings from ._logging import ( logger, setup_logger, ) from ._utils._common import set_id_factory, set_timestamp_factory from ._version import __version__ # Raise each warning only once warnings.filterwarnings("once", category=DeprecationWarning) __all__ = [ "logger", "setup_logger", "set_id_factory", "set_timestamp_factory", "__version__", ] - src/agentscope/_logging.py (1223 bytes)
# -*- coding: utf-8 -*- """The logger for agentscope.""" import logging _DEFAULT_FORMAT = ( "%(asctime)s | %(levelname)-7s | " "%(module)s:%(funcName)s:%(lineno)s - %(message)s" ) logger = logging.getLogger("as") def setup_logger( level: str, filepath: str | None = None, ) -> None: """Set up the agentscope logger. Args: level (`str`): The logging level, chosen from "INFO", "DEBUG", "WARNING", "ERROR", "CRITICAL". filepath (`str | None`, optional): The filepath to save the logging output. """ if level not in ["INFO", "DEBUG", "WARNING", "ERROR", "CRITICAL"]: raise ValueError( f"Invalid logging level: {level}. Must be one of " f"'INFO', 'DEBUG', 'WARNING', 'ERROR', 'CRITICAL'.", ) logger.handlers.clear() logger.setLevel(level) handler = logging.StreamHandler() handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT)) logger.addHandler(handler) if filepath: handler = logging.FileHandler(filepath) handler.setFormatter(logging.Formatter(_DEFAULT_FORMAT)) logger.addHandler(handler) logger.propagate = False setup_logger("INFO") - src/agentscope/_utils/__init__.py (0 bytes)
- src/agentscope/_utils/_audio.py (3979 bytes)
# -*- coding: utf-8 -*- """Audio utilities shared across model providers.""" import struct def _wav_header( riff_size: int, data_size: int, sample_rate: int = 24000, channels: int = 1, bits_per_sample: int = 16, ) -> bytes: """Build a 44-byte WAV/RIFF header with explicit chunk sizes. Args: riff_size (`int`): The size to declare for the RIFF chunk. data_size (`int`): The size to declare for the ``data`` chunk. Returns: `bytes`: A 44-byte WAV header. """ byte_rate = sample_rate * channels * bits_per_sample // 8 block_align = channels * bits_per_sample // 8 return ( b"RIFF" + struct.pack("<I", riff_size) + b"WAVE" + b"fmt " + struct.pack("<I", 16) + struct.pack( "<HHIIHH", 1, channels, sample_rate, byte_rate, block_align, bits_per_sample, ) + b"data" + struct.pack("<I", data_size) ) def _build_streaming_wav_header( sample_rate: int = 24000, channels: int = 1, bits_per_sample: int = 16, ) -> bytes: """Build a 44-byte WAV/RIFF header for streaming PCM. The RIFF and ``data`` chunk sizes are set to ``0xFFFFFFFF`` since the total length isn't known yet. Decoders that only need sample-rate, channel count and bit depth (e.g. the web ``WavStreamPlayer``) treat everything after the ``data`` chunk header as PCM, so this is sufficient for live decoding of an open-ended stream. Both DashScope omni and OpenAI streaming deliver raw PCM upstream; prefixing the first chunk with this header lets the frontend start playback immediately without buffering the whole response. For a *complete* buffer use :func:`_build_wav_header` instead, which declares real chunk sizes. """ return _wav_header( 0xFFFFFFFF, 0xFFFFFFFF, sample_rate, channels, bits_per_sample, ) def _build_wav_header( data_len: int, sample_rate: int = 24000, channels: int = 1, bits_per_sample: int = 16, ) -> bytes: """Build a 44-byte WAV/RIFF header for a complete PCM buffer. Unlike :func:`_build_streaming_wav_header`, the RIFF and ``data`` chunk sizes are real, so the result is a well-formed WAV that ordinary decoders and file-based players accept, not only a live-stream player. """ return _wav_header( 36 + data_len, data_len, sample_rate, channels, bits_per_sample, ) def _finalize_streaming_wav(wav_bytes: bytes) -> bytes: """Declare real chunk sizes in a complete WAV built for streaming. A buffer assembled from streaming deltas starts with the placeholder header from :func:`_build_streaming_wav_header`. Once the buffer is complete, the RIFF and ``data`` chunk sizes are rewritten with the real values, so the result is a well-formed WAV just like :func:`_build_wav_header` produces. Only the canonical 44-byte layout emitted by :func:`_build_streaming_wav_header` is rewritten; other RIFF layouts are returned unchanged. Args: wav_bytes (`bytes`): The complete buffer assembled from the stream deltas. Returns: `bytes`: The buffer with real chunk sizes in its WAV header. """ placeholder_size = struct.pack("<I", 0xFFFFFFFF) if ( len(wav_bytes) >= 44 and wav_bytes[:4] == b"RIFF" and wav_bytes[4:8] == placeholder_size and wav_bytes[8:20] == b"WAVEfmt " + struct.pack("<I", 16) and wav_bytes[36:44] == b"data" + placeholder_size ): data_len = len(wav_bytes) - 44 finalized = bytearray(wav_bytes) struct.pack_into("<I", finalized, 4, 36 + data_len) struct.pack_into("<I", finalized, 40, data_len) return bytes(finalized) return wav_bytes - src/agentscope/_utils/_common.py (16332 bytes)
# -*- coding: utf-8 -*- """The common utilities for agentscope library.""" import asyncio import base64 import copy import functools import inspect import json import os import types import uuid from datetime import datetime from typing import Any, Callable from .._logging import logger from ..exception import ToolJSONDecodeError # These mappings use property names as keys and schemas as values. _SCHEMA_MAP_KEYWORDS = frozenset( {"properties", "patternProperties", "dependentSchemas", "dependencies"}, ) # These keywords hold instance data, which must be kept verbatim. _INSTANCE_VALUE_KEYWORDS = frozenset( {"default", "const", "enum", "examples"}, ) _id_factory: Callable[[], str] = lambda: uuid.uuid4().hex _timestamp_factory: Callable[[], str] = lambda: datetime.now().isoformat() def set_id_factory(factory: Callable[[], str]) -> None: """Override the global ID factory used by all AgentScope entities. Entity IDs default to ``uuid.uuid4().hex``. Call this once at startup to substitute a different strategy. .. note:: Security-sensitive tokens (gateway tokens, Redis lock tokens) are **not** affected and always use ``uuid.uuid4().hex``. Args: factory (`Callable[[], str]`): A no-arg callable returning a string ID. Raises: TypeError: If ``factory`` is not callable. Example: >>> from agentscope import set_id_factory >>> set_id_factory(lambda: uuid7().hex) """ if not callable(factory): raise TypeError( f"factory must be a callable, got {type(factory).__name__}", ) global _id_factory _id_factory = factory def set_timestamp_factory(factory: Callable[[], str]) -> None: """Override the global timestamp factory used by all AgentScope entities. Args: factory (`Callable[[], str]`): A no-arg callable returning a string ID. Raises: TypeError: If ``factory`` is not callable. """ if not callable(factory): raise TypeError( f"factory must be a callable, got {type(factory).__name__}", ) global _timestamp_factory _timestamp_factory = factory def _generate_id() -> str: """Generate an ID string using the current global ID factory.""" return _id_factory() def _generate_timestamp() -> str: """Generate a timestamp string using the current global timestamp factory.""" return _timestamp_factory() def _normalize_local_path(path: str) -> str: """Expand user-home shorthand and return an absolute local path.""" return os.path.abspath(os.path.expanduser(path)) def _has_dropped_keys(original: Any, repaired: Any) -> bool: """Whether any dict in ``repaired`` lost a key it has in ``original``.""" if isinstance(original, dict) and isinstance(repaired, dict): return bool(original.keys() - repaired.keys()) or any( _has_dropped_keys(original[key], value) for key, value in repaired.items() if key in original ) if isinstance(original, list) and isinstance(repaired, list): # ``zip`` below stops at the shorter list, so a truncated repair # would otherwise hide the trailing elements it dropped. if len(repaired) < len(original): return True return any( _has_dropped_keys(item, fixed) for item, fixed in zip(original, repaired) ) return False def _json_loads_with_repair( json_str: str, schema: dict | None = None, ) -> dict: """The given json_str maybe incomplete, e.g. '{"key', or carry arguments whose types don't match the schema, e.g. '{"n": "42"}', so we need to repair and load it into a Python object. .. note:: This function is currently only used for parsing the streaming output of the argument field in `tool_use`, so the parsed result must be a dict. Args: json_str (`str`): The JSON string to parse, which may be incomplete or malformed. schema (`dict`, optional): An optional JSON schema to guide the repair process. The repair is best-effort: arguments that it cannot fix are returned unchanged, so that the caller's validation reports them. Returns: `dict`: A dictionary parsed from the JSON string after repair attempts. Raises: `ToolJSONDecodeError`: If the JSON string cannot be loaded into a dict. """ # Some providers stream no arguments at all for a no-argument tool call if not json_str.strip(): return {} parsed = None error_message = "Error: Failed to parse your tool arguments." try: # Loads directly. A valid dict still goes through the repair below # when a schema is given, because its argument types may be wrong. parsed = json.loads(json_str) if not isinstance(parsed, dict): error_message = ( f"Error: Your argument string is decoded into a " f"{type(parsed)} object, but a dict object is expected!" ) elif schema is None: try: # NaN and Infinity are accepted as numbers by jsonschema, but # silently bypass the minimum/maximum constraints. Apply the # same guard as the schema path so both paths treat them # identically. json.dumps(parsed, allow_nan=False) except ValueError: error_message = ( "Error: NaN and Infinity are not valid JSON numbers." ) else: return parsed except json.JSONDecodeError as e: error_message = ( f"Error: When decoding your tool arguments from JSON format " f"to a Python dictionary, a JSONDecodeError was raised with " f"message: {str(e)}." ) try: # Try to repair with json_repair from json_repair import repair_json try: res = repair_json( json_str, stream_stable=True, schema=schema, return_objects=True, ) except ValueError: # The repair is best-effort. Leave arguments that it cannot fix # to the caller's schema validation, whose error message is more # helpful for the agent. res = parsed if isinstance(res, dict): if isinstance(parsed, dict) and _has_dropped_keys(parsed, res): # Dropping arguments, e.g. under `additionalProperties: # false`, is a rewrite rather than a type repair. res = parsed try: # NaN and Infinity are accepted as numbers by jsonschema, but # silently bypass the minimum/maximum constraints. json.dumps(res, allow_nan=False) except ValueError: error_message = ( "Error: NaN and Infinity are not valid JSON numbers." ) else: return res except Exception: # Whatever the error is, we throw the original error message to the # agent, which is more helpful for debugging. pass # If still failed, we throw the original error message to the agent, rather # than the error from json_repair, which is less helpful for debugging. if len(json_str) > 200: error_json_str = json_str[:100] + "[TRUNCATE]" + json_str[-100:] ellipsis_hint = ( "(Because the JSON string is too long, a truncated label " '"[TRUNCATE]" is used here to indicate the truncation)' ) else: error_json_str = json_str ellipsis_hint = "" raise ToolJSONDecodeError( f"""<system-reminder>{error_message} Your argument string is decoded by the following code snippet{ellipsis_hint}: ```python import json your_tool_arguments = {repr(error_json_str)} json.loads(your_tool_arguments) ``` **You should recorrect the arguments in JSON format.**</system-reminder>""", ) def _get_timestamp(add_random_suffix: bool = False) -> str: """Get the current timestamp in the format YYYY-MM-DD HH:MM:SS.sss.""" timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S.%f")[:-3] if add_random_suffix: # Add a random suffix to the timestamp timestamp += f"_{os.urandom(3).hex()}" return timestamp async def _is_async_func(func: Callable) -> bool: """Check if the given function is an async function, including coroutine functions, async generators, and coroutine objects. """ return ( inspect.iscoroutinefunction(func) or inspect.isasyncgenfunction(func) or isinstance(func, types.CoroutineType) or isinstance(func, types.GeneratorType) and asyncio.iscoroutine(func) or isinstance(func, functools.partial) and await _is_async_func(func.func) ) async def _execute_async_or_sync_func( func: Callable, *args: Any, **kwargs: Any, ) -> Any: """Execute an async or sync function based on its type. Args: func (`Callable`): The function to be executed, which can be either async or sync. *args (`Any`): Positional arguments to be passed to the function. **kwargs (`Any`): Keyword arguments to be passed to the function. Returns: `Any`: The result of the function execution. """ if await _is_async_func(func): return await func(*args, **kwargs) return func(*args, **kwargs) def _get_bytes_from_web_url( url: str, max_retries: int = 3, ) -> str: """Get the bytes from a given URL. Args: url (`str`): The URL to fetch the bytes from. max_retries (`int`, defaults to `3`): The maximum number of retries. """ import requests for _ in range(max_retries): try: response = requests.get(url) response.raise_for_status() return response.content.decode("utf-8") except UnicodeDecodeError: return base64.b64encode(response.content).decode("ascii") except Exception as e: logger.info( "Failed to fetch bytes from URL %s. Error %s. Retrying...", url, str(e), ) raise RuntimeError( f"Failed to fetch bytes from URL `{url}` after {max_retries} retries.", ) def _map_text_to_uuid(text: str) -> str: """Map the given text to a deterministic UUID string. Args: text (`str`): The input text to be mapped to a UUID. Returns: `str`: A deterministic UUID string derived from the input text. """ return str(uuid.uuid3(uuid.NAMESPACE_DNS, text)) def _flatten_json_schema(schema: dict) -> dict: """Flatten a JSON schema by resolving all local ``$ref`` references. Some LLM providers (e.g. Gemini, GLM-5.x via OpenCode Go) cannot process ``$defs`` / ``$ref`` patterns in tool parameter schemas. When Pydantic generates schemas for complex nested types it emits a ``$defs`` block (or the legacy ``definitions`` block) and refers to it with ``{"$ref": "#/$defs/TypeName"}``. This function resolves every such reference by substituting the full definition inline, then drops the ``$defs`` / ``definitions`` sections so the output is a flat, self-contained schema. Discriminators mapping to removed definitions are dropped: their mapping values must be strings, not inline schemas. Union branches and their constraints are preserved. Other discriminators are left unchanged. Circular references are detected and replaced with a fallback object schema to avoid infinite recursion. Only local references of the form ``#/$defs/<name>`` or ``#/definitions/<name>`` are expanded; external ``$ref`` URLs are left unchanged. Args: schema (`dict`): The JSON schema that may contain ``$defs`` and ``$ref`` references. Returns: `dict`: A flattened JSON schema with all references resolved inline. """ has_defs = isinstance(schema.get("$defs"), dict) or isinstance( schema.get("definitions"), dict, ) if not has_defs: return schema schema = copy.deepcopy(schema) defs: dict[str, Any] = {} if isinstance(schema.get("$defs"), dict): defs.update(schema.pop("$defs")) if isinstance(schema.get("definitions"), dict): defs.update(schema.pop("definitions")) if not defs: return schema def _resolve_ref(obj: Any, visited: frozenset = frozenset()) -> Any: if isinstance(obj, list): return [_resolve_ref(item, visited) for item in obj] if not isinstance(obj, dict): return obj resolved: dict[str, Any] = {} if "$ref" in obj: ref_path = obj["$ref"] if not isinstance(ref_path, str) or not ref_path.startswith( ("#/$defs/", "#/definitions/"), ): return obj def_name = ref_path.split("/")[-1] # JSON Pointer tokens decode ~1 before ~0 (RFC 6901). def_name = def_name.replace("~1", "/").replace("~0", "~") if def_name in visited: logger.warning( "Circular reference detected for '%s' in tool schema", def_name, ) return { "type": "object", "description": f"(circular: {def_name})", } if def_name not in defs: return obj visited = visited | {def_name} resolved = _resolve_ref(defs[def_name], visited) if resolved is True: # True adds no constraints; preserve the reference's siblings. resolved = {} elif not isinstance(resolved, dict): return resolved for key, value in obj.items(): if key in ("$ref", "$defs", "definitions"): continue if key in _INSTANCE_VALUE_KEYWORDS: resolved[key] = value elif key == "discriminator" and isinstance(value, dict): mapping = value.get("mapping") if isinstance(mapping, dict) and any( isinstance(ref, str) and ref.startswith(("#/$defs/", "#/definitions/")) and ref.rsplit("/", 1)[-1] in defs for ref in mapping.values() ): continue resolved[key] = value elif key in _SCHEMA_MAP_KEYWORDS and isinstance(value, dict): resolved[key] = { - src/agentscope/_utils/_mixin.py (1188 bytes)
# -*- coding: utf-8 -*- """The mixin for agentscope.""" class DictMixin(dict): """The dictionary mixin that allows attribute-style access.""" __setattr__ = dict.__setitem__ def __getattr__(self, key: str) -> object: """Get a dictionary item through attribute-style access. Args: key (`str`): The requested attribute name. Returns: `object`: The value stored under ``key``. Raises: `AttributeError`: If the dictionary does not contain ``key``. """ try: return dict.__getitem__(self, key) except KeyError as error: raise AttributeError(key) from error def __delattr__(self, key: str) -> None: """Delete a dictionary item through attribute-style access. Args: key (`str`): The attribute name to remove. Raises: `AttributeError`: If the dictionary does not contain ``key``. """ try: dict.__delitem__(self, key) except KeyError as error: raise AttributeError(key) from error - src/agentscope/_version.py (84 bytes)
# -*- coding: utf-8 -*- """The version of agentscope.""" __version__ = "2.0.13dev"
- src/agentscope/agent/__init__.py (450 bytes)
# -*- coding: utf-8 -*- """Initialize the agent module.""" from ._agent import Agent from ._a2a_agent import A2AAgent from ._config import ContextConfig, InjectionConfig, ModelConfig, ReActConfig from ._realtime import RealtimeAgent, TurnAggregator, TurnMetrics __all__ = [ "Agent", "A2AAgent", "RealtimeAgent", "TurnAggregator", "TurnMetrics", "ContextConfig", "InjectionConfig", "ModelConfig", "ReActConfig", ] - src/agentscope/agent/_a2a_agent.py (24189 bytes)
# -*- coding: utf-8 -*- """A stateful client-side adapter for remote A2A agents.""" from __future__ import annotations import base64 from collections.abc import AsyncGenerator, Iterable from dataclasses import dataclass, field from typing import Any, TYPE_CHECKING from ..state import A2AAgentState from .._logging import logger from .._utils._common import _generate_id from ..event import ( ReplyEndEvent, ReplyFinishedReason, ReplyStartEvent, AgentEvent, DataBlockDeltaEvent, DataBlockEndEvent, DataBlockStartEvent, TextBlockDeltaEvent, TextBlockEndEvent, TextBlockStartEvent, ) from ..message import ( AssistantMsg, Msg, TextBlock, Base64Source, DataBlock, URLSource, ) if TYPE_CHECKING: from a2a.client import Client from a2a.types import AgentCard from a2a.types import Part @dataclass class _TextRun: """The text block that consecutive text Parts stream into. A2A marks continuation per artifact update rather than per Part, so a run is identified by the metadata its Parts share and ends as soon as anything else is emitted. """ block_id: str | None = None metadata: dict[str, Any] = field(default_factory=dict) def _parts_to_events( parts: Iterable[Part], reply_id: str, metadata: dict[str, Any], run: _TextRun, append: bool = False, last_chunk: bool = True, ) -> list[AgentEvent]: """Build the events for one group of A2A Parts sharing one source. ``append`` and ``last_chunk`` are the artifact update flags of the same name: together they say whether this group continues the block ``run`` holds open and whether anything more can join it. Text Parts stream into that one block, because reopening a block per chunk fragments one reply into many; every other Part is a block of its own. The A2A ids the Parts came from are carried on each block end event. """ events: list[AgentEvent] = [] def close_run() -> None: """End the open text block, if any.""" if run.block_id: events.append( TextBlockEndEvent( reply_id=reply_id, block_id=run.block_id, metadata=run.metadata, ), ) run.block_id = None if not (append and run.metadata == metadata): close_run() for part in parts: kind = part.WhichOneof("content") if kind == "text": if run.block_id is None: run.block_id, run.metadata = _generate_id(), metadata events.append( TextBlockStartEvent( reply_id=reply_id, block_id=run.block_id, ), ) if part.text: events.append( TextBlockDeltaEvent( reply_id=reply_id, block_id=run.block_id, delta=part.text, ), ) continue close_run() if kind not in ("raw", "url"): raise ValueError( "A2AAgent supports text, raw, and URL parts; got " f"unsupported {kind or 'empty'} content.", ) block_id = _generate_id() media_type = part.media_type or "application/octet-stream" events.append( DataBlockStartEvent( reply_id=reply_id, block_id=block_id, media_type=media_type, name=part.filename or None, ), ) if kind == "url": events.append( DataBlockDeltaEvent( reply_id=reply_id, block_id=block_id, url=part.url, media_type=media_type, ), ) elif part.raw: events.append( DataBlockDeltaEvent( reply_id=reply_id, block_id=block_id, data=base64.b64encode(part.raw).decode("ascii"), media_type=media_type, ), ) events.append( DataBlockEndEvent( reply_id=reply_id, block_id=block_id, metadata=metadata, ), ) if last_chunk: close_run() return events def _get_finished_reason(state: int) -> ReplyFinishedReason: """Map the A2A Task state a response stream ended on to a reply outcome. A Task waiting for input ends the reply normally: it is suspended server-side, but nothing is suspended locally, so its status message is an ordinary turn that the caller answers with the next reply. """ from a2a.types import TaskState if state in ( TaskState.TASK_STATE_COMPLETED, TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED, ): return ReplyFinishedReason.COMPLETED if state == TaskState.TASK_STATE_CANCELED: return ReplyFinishedReason.INTERRUPTED # FAILED and REJECTED, plus a stream that died on SUBMITTED or WORKING # without ever resolving. return ReplyFinishedReason.ERROR def _awaiting_input(state: int) -> bool: """Whether a Task in this state is suspended waiting for the caller, so the next message continues it instead of starting a new Task.""" from a2a.types import TaskState return state in ( TaskState.TASK_STATE_INPUT_REQUIRED, TaskState.TASK_STATE_AUTH_REQUIRED, ) class A2AAgent: """A stateful client-side adapter for an A2A 1.0 agent. This class intentionally provides Agent-like interaction methods without inheriting :class:`agentscope.agent.Agent`. A local ``Agent`` owns a model, toolkit, state, and reasoning loop; this adapter delegates those concerns to the remote A2A server and owns only the remote conversation (``context_id``) and the Task the next message continues (``task_id``), both held in :class:`agentscope.state.A2AAgentState`. Each A2A Part of a response becomes one content block: text Parts become :class:`~agentscope.message.TextBlock`, raw byte and URL Parts become :class:`~agentscope.message.DataBlock`. The adapter owns its A2A client and closes it in :meth:`aclose`, so it is single-use: once closed it cannot be reopened. """ def __init__( self, agent_card: AgentCard, *, client: Client | None = None, state: A2AAgentState | None = None, ) -> None: """Initialize the A2A agent adapter. Args: agent_card (`a2a.types.AgentCard`): The remote Agent Card, used both to identify the peer (its ``name`` becomes this adapter's ``name``) and to select a transport. The SDK picks the newest protocol version the card advertises for the chosen binding, falling back to its A2A 0.3 compatibility transport when that is all the peer offers. client (`a2a.client.Client | None`, optional): An official SDK client, e.g. one configured for gRPC or with custom auth. If omitted, a streaming client is built from the card, which then requires a ``JSONRPC`` or ``HTTP+JSON`` interface. The adapter owns the client either way and closes it in :meth:`aclose`. state (`agentscope.state.A2AAgentState | None`, optional): An existing state to resume, e.g. one saved from an earlier adapter, so its ``context_id`` continues the same remote conversation. A fresh state is created when omitted. """ try: import a2a # noqa: F401 pylint: disable=unused-import except ImportError as error: raise ImportError( "A2AAgent requires the A2A extra. Install it with " "`pip install 'agentscope[a2a]'`.", ) from error self._agent_card = agent_card self.name = self._agent_card.name if client is None: from a2a.client import ClientConfig, ClientFactory from a2a.utils.constants import TransportProtocol client = ClientFactory( ClientConfig( streaming=True, polling=False, supported_protocol_bindings=[ TransportProtocol.JSONRPC, TransportProtocol.HTTP_JSON, ], ), ).create(self._agent_card) self._client = client self.state = state or A2AAgentState() self._closed = False async def __aenter__(self) -> A2AAgent: """Enter the asynchronous context manager. Leaving the block closes the owned client, and nothing reopens it, so an adapter can only be entered before it is closed. """ if self._closed: raise RuntimeError("A2AAgent is closed.") return self async def __aexit__(self, *_: Any) -> None: """Close the owned client when leaving the context manager.""" await self.aclose() async def aclose(self) -> None: """Close the owned A2A client. Repeated calls are safe.""" if not self._closed: await self._client.close() self._closed = True async def reply_stream( self, inputs: Msg | list[Msg] | None = None, yield_final_msg: bool = False, ) -> AsyncGenerator[AgentEvent | Msg, None]: """Send input and stream the remote reply as AgentScope events. Args: inputs (`Msg | list[Msg] | None`, optional): The messages to send, preceded by the observed ones. yield_final_msg (`bool`, defaults to `False`): Whether to yield the final reply message after the events. Yields: `AgentEvent | Msg`: Streamed events produced during the reply. """ async for event_or_msg in self._reply(inputs): if isinstance(event_or_msg, Msg) and not yield_final_msg: continue yield event_or_msg async def reply(self, inputs: Msg | list[Msg] | None = None) -> Msg: """Send input and return the final assistant message. Args: inputs (`Msg | list[Msg] | None`, optional): The messages to send, preceded by the observed ones. Returns: `Msg`: The reply message, assembled from the streamed events. """ final_msg: Msg | None = None async for event_or_msg in self._reply(inputs): if isinstance(event_or_msg, Msg): final_msg = event_or_msg if final_msg is None: raise RuntimeError("A2AAgent did not produce a final message.") return final_msg async def _reply( self, inputs: Msg | list[Msg] | None = None, ) -> AsyncGenerator[AgentEvent | Msg, None]: """Send one A2A Message and stream its response back. The observed messages lead the input, and the whole turn is flattened into a single A2A Message. It continues the remote Task the previous reply left waiting for input, if any, and otherwise starts a new one within the same ``context_id``. Args: inputs (`Msg | list[Msg] | None`): The input message(s) to send, preceded by the observed ones. Yields: `AgentEvent | Msg`: The streamed events, then the final reply message. Raises: `RuntimeError`: If the remote Task from an earlier reply is still running, since a second message would execute it again. """ from a2a.types import GetTaskRequest, TaskState from a2a.utils.errors import TaskNotFoundError # Ensure the client is open self._ensure_open() # Normalize the inputs into a2a-acceptable objects if isinstance(inputs, Msg): input_msgs = [inputs] elif isinstance(inputs, list) and all( isinstance(_, Msg) for _ in inputs ): input_msgs = inputs else: input_msgs = [] # Observed messages are earlier context, so they lead this input. # They stay cached until the reply is committed to sending below, # so a rejected pre-flight keeps them for the retry. input_msgs = [*self.state.observed_context, *input_msgs] if not input_msgs: raise ValueError( "A2AAgent reply requires at least one message.", ) # A Task left over from an earlier reply decides what this input # does, and only the server knows how it ended. if self.state.task_id: try: task = await self._client.get_task( GetTaskRequest(id=self.state.task_id), ) except TaskNotFoundError: # The server has forgotten the Task; start a new one. self.state.task_id = None else: if task.status.state in ( TaskState.TASK_STATE_SUBMITTED, TaskState.TASK_STATE_WORKING, ): # The server taps the running Task's own queue, so # sending now would execute it a second time. raise RuntimeError( f"A2A task {self.state.task_id} is still running " "on the remote server; retry once it has finished.", ) if not _awaiting_input(task.status.state): self.state.task_id = None # Build the request before anything is committed, so an input it # rejects neither consumes the observed messages nor leaves a # reply started without an end. request = self._build_request(input_msgs) reply_id = _generate_id() # The reply message is assembled from the very events streamed to # the caller, so the two can never disagree. msg = AssistantMsg( id=reply_id, name=self._agent_card.name, content=[], ) yield ReplyStartEvent( session_id=self.state.session_id, reply_id=reply_id, name=self._agent_card.name, ) finished_reason = ReplyFinishedReason.COMPLETED run = _TextRun() # The message is going out now: consume the observed messages. self.state.observed_context.clear() async for response in self._client.send_message(request): events: list[AgentE - src/agentscope/agent/_agent.py (163256 bytes)
# -*- coding: utf-8 -*- """The unified agent class in AgentScope library.""" import asyncio import collections import inspect import json import re import warnings from asyncio import Queue from copy import deepcopy from contextlib import aclosing from fnmatch import fnmatch from datetime import datetime from typing import ( Any, AsyncGenerator, Sequence, List, TYPE_CHECKING, Type, ) import jsonschema from pydantic import BaseModel, ValidationError from ._config import ( ContextConfig, ReActConfig, ModelConfig, InjectionConfig, _validate_context_config_ratios, ) from ..state import AgentState, ReplyContext from ._utils import _ToolCallBatch, Acting, Exit, Reasoning, _resolve_timezone from .._logging import logger from .._utils._common import ( _generate_id, _json_loads_with_repair, _execute_async_or_sync_func, ) from ..event import ( AgentEvent, CustomEvent, ModelCallEndEvent, ModelCallStartEvent, ReplyEndEvent, ReplyStartEvent, TextBlockDeltaEvent, TextBlockEndEvent, TextBlockStartEvent, ThinkingBlockDeltaEvent, ThinkingBlockEndEvent, ThinkingBlockStartEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolResultDataDeltaEvent, ToolResultEndEvent, ToolResultStartEvent, ToolResultTextDeltaEvent, RequireUserConfirmEvent, RequireExternalExecutionEvent, ExternalExecutionResultEvent, UserConfirmResultEvent, DataBlockStartEvent, DataBlockDeltaEvent, DataBlockEndEvent, ExceedMaxItersEvent, ReplyFinishedReason, UserInterruptEvent, HintBlockEvent, ) from ..exception import ( AgentOrientedException, ContentBlockedError, ContentBlockedPhase, ) from ..model import ( ChatResponse, ChatUsage, ChatModelBase, FinishedReason, ) from ..message import ( Msg, AssistantMsg, SystemMsg, UserMsg, TextBlock, ThinkingBlock, ToolCallBlock, ToolResultBlock, DataBlock, Base64Source, URLSource, ToolCallState, ToolResultState, Usage, HintBlock, ) from ..tool import ( AskUser, AskUserParams, Toolkit, ToolBase, ToolChunk, ToolChoice, ToolResponse, FunctionTool, ) from ..permission import ( PermissionBehavior, PermissionEngine, PermissionDecision, PermissionRule, ) from ._structured_output_tool import _GenerateStructuredOutput from ..workspace import Offloader, WorkspaceBase # The name of the tool that the agent uses to compress its own context _COMPRESSION_TOOL_NAME = "CompressContext" if TYPE_CHECKING: from ..middleware import MiddlewareBase else: MiddlewareBase = Any class Agent: """The agent class.""" def __init__( self, name: str, system_prompt: str, model: ChatModelBase, toolkit: Toolkit | None = None, middlewares: list[MiddlewareBase] | None = None, state: AgentState | None = None, offloader: Offloader | None = None, # The agent configurations model_config: ModelConfig | None = None, context_config: ContextConfig | None = None, react_config: ReActConfig | None = None, injection_config: InjectionConfig | None = None, ) -> None: """Initialize the agent class in AgentScope. Args: name (`str`): The agent identifier. system_prompt (`str`): The agent's system prompt. Additional instructions may be appended to it dynamically during operation. model (`ChatModelBase`): The chat model/llm used for this agent. toolkit (`Toolkit | None`, optional): The toolkit used for registering tools, MCPs and skills as the sole source. middlewares (`list[MiddlewareBase] | None`, optional): Middlewares applied to the agent to modify its behavior without altering its source code. Supported hook points include: reply, reasoning, permission checking, acting, model call, context compression, and system prompt retrieval. state (`AgentState | None`, optional): The agent state. A new state will be created if not provided. offloader (`Offloader | None`, optional): The context offloader. If provided, the compressed context and tool result will be offloaded. model_config (`ModelConfig | None`, optional): The additional chat model configuration including fallback model and retries. context_config (`ContextConfig | None`, optional): The context config for context compression and tool result compression. react_config (`ReActConfig | None`, optional): The config for the reasoning-acting loop. injection_config (`InjectionConfig | None`, optional): The runtime state injection config, which controls how the time, (plan) tasks and context usage are injected into the context to help the agent better reason and act. """ self.name = name self._system_prompt = system_prompt self.model = model self.state = state or AgentState() self.model_config = model_config or ModelConfig() self.context_config = context_config or ContextConfig() self.react_config = react_config or ReActConfig() self.injection_config = injection_config or InjectionConfig() if self.injection_config.context_buffer_ratio is not None: warnings.warn( "The 'context_buffer_ratio' of the injection config is " "deprecated, set it in the context config instead.", DeprecationWarning, stacklevel=2, ) # Other agents may share the caller's config. self.context_config = self.context_config.model_copy(deep=True) self.context_config.context_buffer_ratio = ( self.injection_config.context_buffer_ratio ) self._validate_configs() # The permission engine self._engine = PermissionEngine(self.state.permission_context) # The offloader/workspace self.offloader = offloader # ==================================================================== # The Tool-related logics # ==================================================================== self.toolkit = toolkit or Toolkit() # Built here rather than in ``_prepare_model_input``, so that the # registration can tell this agent's tool from a tool of the same # name, e.g. another agent sharing the toolkit self._compression_tool = FunctionTool( self._compress_context_tool, name=_COMPRESSION_TOOL_NAME, is_concurrency_safe=False, permission=PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{_COMPRESSION_TOOL_NAME} is always allowed.", ), ) # ==================================================================== # The Middleware-related attributes # ==================================================================== # Filter middlewares by implemented hooks (only once) middlewares = middlewares or [] self._reply_middlewares = [ _ for _ in middlewares if _.is_implemented("on_reply") ] self._reasoning_middlewares = [ _ for _ in middlewares if _.is_implemented("on_reasoning") ] self._check_permission_middlewares = [ _ for _ in middlewares if _.is_implemented("on_check_permission") ] self._acting_middlewares = [ _ for _ in middlewares if _.is_implemented("on_acting") ] self._model_call_middlewares = [ _ for _ in middlewares if _.is_implemented("on_model_call") ] self._system_prompt_middlewares = [ _ for _ in middlewares if _.is_implemented("on_system_prompt") ] self._compress_context_middlewares = [ _ for _ in middlewares if _.is_implemented("on_compress_context") ] # Set when a `ReplyEndEvent` escapes the reply middleware chain; the # reply loop only exits after the event is delivered (not swallowed) self._receive_reply_end: bool = False def _validate_configs(self) -> None: """Validate the config combinations that a single config class cannot check by itself. Raises: `ValueError`: If the reserved/buffer ratios don't leave room ahead of the context compression threshold. """ _validate_context_config_ratios( self.context_config, self.injection_config.inject_runtime_state, ) # ======================================================================= # Agent public methods # ======================================================================= async def reply_stream( self, inputs: Msg | list[Msg] | UserConfirmResultEvent | UserInterruptEvent | ExternalExecutionResultEvent | None = None, structured_schema: Type[BaseModel] | None = None, yield_final_msg: bool = False, ) -> AsyncGenerator[AgentEvent | Msg, None]: """Reply to the given inputs and stream agent events. Args: inputs (`Msg | list[Msg] | UserConfirmResultEvent | \ UserInterruptEvent | ExternalExecutionResultEvent | None`, \ optional): The inputs that trigger this reply. See :meth:`reply` for the full list of accepted variants. structured_schema (`Type[BaseModel] | None`, optional): The Pydantic model class that the reply's structured output must conform to. See :meth:`reply` for details. yield_final_msg (`bool`, defaults to `False`): If yield the final reply message. When requiring structured output, use this option to get the final message, and access it via the `structured_output` attribute. Yields: `AgentEvent | Msg`: Streamed events produced during the reply. .. note:: If requiring outside interaction for multiple tool calls and only receive partial confirmation or execution results, the agent won't re-send the requiring events for the unconfirmed or unexecuted tool calls. """ async with aclosing( self._reply(inputs=inputs, structured_schema=structured_schema), ) as stream: async for chunk in stream: if isinstance(chunk, Msg) and not yield_final_msg: continue yield chunk async def reply( self, inputs: Msg | list[Msg] | UserConfirmResultEvent | UserInterruptEvent | ExternalExecutionResultEvent | None = None, structured_schema: Type[BaseModel] | None = None, ) -> Msg: """Reply to the given inputs, consuming all streamed events. Args: inputs (`Msg | list[Msg] | UserConfirmResultEvent | \ UserInterruptEvent | ExternalExecutionResultEvent | None`, \ optional): The inputs that trigger this reply. It can be: - a single `Msg` or a list of `Msg` objects to start a new reply, - a `UserConfirmResultEvent` or `ExternalExecutionResultEvent` to continue from the outside interaction required by the previous reply, - a `UserInterruptEvent` to abort a parked reply — the agent closes all pending tool calls with an interrupted tool result and ends the reply without entering the reasoning-acting loop, - `None` if there is nothing new to feed in (e.g. just continue from the current state). structured_schema (`Type[BaseModel] | None`, optional): The Pydantic model class that the reply's structured output must conform to, with the validated result carried on the final message's ``structured_output`` attribute as a dict. Returns: `Msg`: A final reply message. """ final_msg: Msg | None = None async for evt_or_msg in self._reply( inputs=inputs, structured_schema=structured_schema, ): if isinstance(evt_or_msg, Msg): final_msg = evt_or_msg if final_msg is None: raise RuntimeError("Agent did not produce a final message.") return final_msg async def observe(self, msgs: Msg | list[Msg] | None = None) -> None: """Receive external observation message(s) and save them into context.""" await self._handle_incoming_messages(msgs) async def compress_context( self, context_config: ContextConfig | None = None, instructions: HintBlock | None = None, ) -> None: """Compress the agent's context if the token count exceeds the threshold. Args: context_config (`ContextConfig | None`, optional): If provided, compress the context with the given context config. Otherwise, use the default context config in the agent. instructions (`HintBlock | None`, optional): Optional hints or instructions injected into the compression context to guide the summarization behavior. """ if not self._compress_context_middlewares: await self._compress_context_impl( context_config=context_config, instructions=instructions, ) else: async def execute_chain( index: int = 0, context_config: ContextConfig | None = context_config, instructions: HintBlock | None = instructions, ) -> None: """Execute the compress_context middleware chain.""" if index >= len(self._compress_context_middlewares): await self._compress_context_impl( context_config=context_config, instructions=instructions, ) else: mw = self._compress_context_middlewares[index] input_kwargs = { "con - src/agentscope/agent/_config.py (18297 bytes)
# -*- coding: utf-8 -*- """The agent config classes.""" from pydantic import BaseModel, Field, field_validator from ..model import ChatModelBase class SummarySchema(BaseModel): """The compressed memory model, used to generate summary of old memories""" task_overview: str = Field( description=( "The user's core request and success criteria.\n" "Any clarifications or constraints they specified" ), ) current_state: str = Field( description=( "What has been completed so far.\n" "File created, modified, or analyzed (with paths if relevant).\n" "Key outputs or artifacts produced." ), ) important_discoveries: str = Field( description=( "Technical constraints or requirements uncovered.\n" "Decisions made and their rationale.\n" "Errors encountered and how they were resolved.\n" "What approaches were tried that didn't work (and why)" ), ) next_steps: str = Field( description=( "Specific actions needed to complete the task.\n" "Any blockers or open questions to resolve.\n" "Priority order if multiple steps remain" ), ) context_to_preserve: str = Field( description=( "User preferences or style requirements.\n" "Domain-specific details that aren't obvious.\n" "Any promises made to the user" ), ) """The important context to preserve across compression, e.g. user preferences, domain-specific details and promises made to the user.""" class ContextConfig(BaseModel): """The context related configuration in AgentScope""" model_config = {"arbitrary_types_allowed": True} """Allow arbitrary types in the pydantic model.""" trigger_ratio: float = Field(default=0.8, gt=0, le=0.9) """When the token exceeds this ratio of the maximum context length, the context will be compressed. To reserve the context for context compression, the maximum ratio is 0.9.""" reserve_ratio: float = Field(default=0.1, gt=0, lt=0.9) """The ratio of the tokens to reserve in context compression, which should be smaller than the trigger ratio.""" context_buffer_ratio: float = Field( title="Context Buffer", default=0.2, ge=0, le=1, description=( "The buffer ahead of the 'trigger_ratio', within which the agent " "is told that a compression is near, and can compress by itself " "if the compression tool is enabled. It must be smaller than the " "'trigger_ratio'." ), ) """The buffer ahead of the compression threshold, e.g. with a trigger ratio of 0.8 and a buffer of 0.2, the context length is injected once the input tokens exceed 60% of the model context size.""" compression_prompt: str = Field( default=( "<system-hint>You have been working on the task described above. " "Now write a continuation summary that will allow you to resume " "work efficiently in a future context window where the " "conversation history will be replaced with this summary. " "Your summary should be structured, concise, and actionable.\n" "The current time is {current_time}.\n" "This summary may itself be summarized again later, and the " "conversation history it refers to will be gone, so every " "reference must be self-contained — resolve anything that " "depends on the vanished context into an absolute, " "fully-qualified form:\n" "- Time: convert relative expressions ('today', 'now', " "'yesterday', 'tomorrow', 'recently') to absolute dates using " "the current time above; re-anchor them even if an earlier " "summary already wrote them relatively.\n" "- Names & pointers: use file paths, symbol names, PR/issue " "numbers, IDs, URLs, and exact commands/error strings verbatim " "instead of 'this file', 'the above', 'the second approach', " "'the 5 failing tests'.\n" "- In-flight work: record everything still pending, especially " "tools launched in the background whose results you are still " "waiting on — give each one's id and a short note of what it is " "doing — and mark each item's owner (user request vs your own " "decision) and status (done / pending / blocked).\n" "</system-hint>" ), # ``format: textarea`` is a hint for schema-driven UI renderers # to use a multi-line input. Plain JSON Schema doesn't natively # express this, so we piggy-back on ``json_schema_extra``. json_schema_extra={"format": "textarea"}, ) """The prompt used to guide the compression model to generate the compressed summary, which will be wrapped into a user message and attach to the end of the current memory.""" summary_template: str = Field( default=( "<system-info>Here is a summary of your previous work\n" "# Task Overview\n" "{task_overview}\n\n" "# Current State\n" "{current_state}\n\n" "# Important Discoveries\n" "{important_discoveries}\n\n" "# Next Steps\n" "{next_steps}\n\n" "# Context to Preserve\n" "{context_to_preserve}" "</system-info>" ), json_schema_extra={"format": "textarea"}, ) """The string template to present the compressed summary to the agent, which will be formatted with the fields from the `summary_schema`.""" summary_schema: dict = Field( default_factory=SummarySchema.model_json_schema, ) """The structured model used to guide the agent to generate the structured compressed summary.""" tool_result_limit: int = Field( title="Tool Result Limit", default=50000, description=( "The maximum length of the tool results in tokens. " "If exceeded, the tool result will be truncated." ), ) """The tool result limit to avoid tool result bursting.""" compression_fallback_to_truncation: bool = Field( default=True, description=( "Whether to truncate the oldest context when the compression " "summary cannot be generated. Turning it off raises the error " "instead, keeping the context intact at the cost of exceeding " "the context length." ), ) """Whether to fall back to context truncation when the summary generation fails.""" compression_tool_enabled: bool = Field( default=False, description=( "Whether to expose a context compression tool to the agent. " "When runtime-state injection is enabled, the agent is prompted " "to use the tool between tasks as the context approaches the " "hard compression threshold." ), ) """Whether the agent can explicitly request context compression.""" max_image_num: int = Field( title="Max Image Number", default=5, ge=0, description=( "The maximum number of images kept in the context. The oldest " "images exceeding the limit will be removed." ), ) """The maximum number of images kept in the context. When the number of images exceeds this limit, the oldest images will be offloaded to the workspace (if an offloader is provided) and replaced by a hint that records the offloaded path; otherwise they are dropped and replaced by a hint without path information.""" def _validate_context_config_ratios( context_config: ContextConfig, inject_runtime_state: bool, ) -> None: """Validate that context compression thresholds leave room to operate.""" if context_config.reserve_ratio >= context_config.trigger_ratio: raise ValueError( "The 'reserve_ratio' of the context config must be smaller " "than its 'trigger_ratio', got " f"{context_config.reserve_ratio} and " f"{context_config.trigger_ratio}.", ) # The buffer is only consumed by runtime-state injection and the # compression tool, so it is checked only when one of them is enabled. if ( (inject_runtime_state or context_config.compression_tool_enabled) and context_config.context_buffer_ratio >= context_config.trigger_ratio ): raise ValueError( "The 'context_buffer_ratio' of the context config must be " "smaller than its 'trigger_ratio', so that the context " "length is injected and the compression tool takes effect " "before the hard compression, got " f"{context_config.context_buffer_ratio} and " f"{context_config.trigger_ratio}.", ) class InjectionConfig(BaseModel): """The state injection related configuration in AgentScope.""" inject_runtime_state: bool = Field( title="Inject Runtime State", description=( "Inject the runtime state to context, including current time," "tasks state, context length, etc." ), default=True, ) """Whether to inject the runtime state to context, including current time, tasks state, context length, etc.""" timezone: str = Field( title="Timezone", default="UTC", description=( "The injected timezone. e.g. 'America/New_York' or " "'Asia/Shanghai'." ), ) """The timezone to inject into the context, follow the standard timezone database format, e.g. 'America/New_York' or 'Asia/Shanghai'.""" time_format: str = Field( title="Time Format", default="%Y-%m-%dT%H:%M:%S", description=( "The format to inject and parse the time information, which must " "round-trip a full timestamp, i.e. carry the date part. A " "time-only format such as '%H:%M:%S' makes the parsed time fall " "back to year 1900, so that the time is injected in every " "iteration." ), ) """The format to inject and parse the time information, which must carry the date part to round-trip a full timestamp.""" time_interval: float = Field( title="Time Interval", default=0.5, ge=0, description=( "The minimum time interval in hours from the last injection to " "trigger new time injection" ), ) """The minimum elapsed time in **hours** from the recorded time to trigger a new time injection.""" context_buffer_ratio: float | None = Field( title="Context Buffer", default=None, ge=0, le=1, description=( "Deprecated, use the 'context_buffer_ratio' of the context " "config instead. When provided, it overrides the one in the " "context config." ), ) """Deprecated in favor of ``ContextConfig.context_buffer_ratio``, which is also consumed by the context compression tool.""" tool_retries_limit: int = Field( title="Tool Retries Limit", default=3, ge=3, description=( "The number of consecutive failures of the same tool call that " "triggers the tool error injection." ), ) """The number of consecutive failures of the same tool call, i.e. the same tool name and arguments, that triggers the tool error injection.""" tool_retries_hint: str = Field( title="Tool Retries Hint", default=( "The last {count} calls to '{tool_name}' with the same arguments " "all failed. Stop retrying the same call as-is, check the error " "message and try a different approach." ), description=( "The hint injected when the same tool call keeps failing, where " "the '{tool_name}' and '{count}' placeholders will be replaced " "by the failing tool name and the number of consecutive failures." ), ) """The hint injected when the same tool call keeps failing, which supports the ``{tool_name}`` and ``{count}`` placeholders.""" template: str = Field( title="Template", default="""<system-reminder>Treat the following as the ground truth \ at this point of the conversation. Anything stated earlier is outdated, and a \ later reminder, if any, supersedes this one: {runtime_state} </system-reminder>""", description=( "The template to wrap the injected runtime state, where the " "'{runtime_state}' placeholder will be replaced by the injected " "fields." ), ) """The template to wrap the injected runtime state, which must contain the ``{runtime_state}`` placeholder.""" @field_validator("template") @classmethod def _check_template(cls, value: str) -> str: """Ensure the template won't silently drop the injected fields.""" if "{runtime_state}" not in value: raise ValueError( "The injection template must contain the '{runtime_state}' " f"placeholder, got {value!r}.", ) return value injection_source: str = Field( title="Injection Source", default='{"label": "System", "sublabel": "Runtime State"}', description=( "The source of the injected hint block, which is also used to " "identify the previous injections within the context." ), ) """The source of the injected hint block, used to identify the agent's own injections when scanning the context.""" task_tool_names: list[str] = Field( title="Task Tool Names", default_factory=lambda: [ "TaskCreate", "TaskGet", "TaskList", "TaskUpdate", ], description=( "The names of the task related tools. Their presence in the " "context suppresses the tasks injection." ), ) """The names of the task related tools, whose tool calls in the context indicate the agent is already aware of the tasks.""" extra_fields: dict[str, str] = Field( title="Extra Fields", default_factory=dict, description=( "The extra fields to inject, which will be wrapped into the " "'<{key}>{value}</{key}>' format." ), ) """The user defined fields to inject, which are attached to the injection without triggering one by themselves.""" emit_hint_event: bool = Field( t - src/agentscope/agent/_realtime/__init__.py (226 bytes)
# -*- coding: utf-8 -*- """The realtime voice agent.""" from ._agent import RealtimeAgent from ._aggregator import TurnAggregator from ._metrics import TurnMetrics __all__ = ["RealtimeAgent", "TurnAggregator", "TurnMetrics"]
- src/agentscope/agent/_realtime/_agent.py (105132 bytes)
# -*- coding: utf-8 -*- """The realtime voice agent.""" import asyncio import base64 import time import uuid from collections import deque from collections.abc import Callable, Iterator from contextlib import nullcontext from copy import deepcopy from dataclasses import dataclass, field from typing import Any, AsyncIterator, TYPE_CHECKING from ...realtime import _events as me from ._aggregator import TurnAggregator from ...realtime._base import ( InteractionMode, ModelDisconnectedError, RealtimeModelBase, ) from ._metrics import TurnMetrics from ...realtime._transport._base import ( AudioFrame, ControlFrame, ControlFrameType, TransportBase, ) from ...realtime._vad import SpeechTransition, VADBase from ..._logging import logger from ..._utils._common import _json_loads_with_repair from ...event import ( AgentEvent, ConfirmResult, CustomEvent, DataBlockDeltaEvent, DataBlockEndEvent, DataBlockStartEvent, ModelCallEndEvent, ModelCallStartEvent, ReplyEndEvent, ReplyStartEvent, RequireExternalExecutionEvent, RequireUserConfirmEvent, TextBlockDeltaEvent, TextBlockEndEvent, TextBlockStartEvent, ToolCallDeltaEvent, ToolCallEndEvent, ToolCallStartEvent, ToolResultEndEvent, ToolResultDataDeltaEvent, ToolResultStartEvent, ToolResultTextDeltaEvent, ExternalExecutionResultEvent, UserConfirmResultEvent, UserInterruptEvent, ) from ...message import ( Msg, SystemMsg, TextBlock, ToolCallBlock, ToolCallState, ToolResultBlock, ToolResultState, Usage, UserMsg, ) from ...permission import PermissionBehavior, PermissionEngine from ...state import AgentState from ...tool import ToolChunk, ToolResponse, Toolkit from ...types import ReplyFinishedReason if TYPE_CHECKING: from .._agent import Agent # Audio buffered while the model is being reconnected: 10 s at 100 ms chunks. _BACKLOG_FRAMES = 100 _HISTORY_MAX_MESSAGES = 100 _HISTORY_MAX_TEXT_CHARS = 32_000 _LIVE_SEGMENT_MAX_TEXT_CHARS = 4_000 _LIVE_CHECKPOINT_INTERVAL_SECS = 2.0 _DELEGATION_INPUT_TIMEOUT_SECS = 300.0 @dataclass class _Reply: """One in-flight model response.""" item_id: str """The provider's response item identifier.""" reply_id: str """The agent's reply this response belongs to, as seen in events and context. A reply spans every response up to the next user turn, so one that calls tools has several responses.""" text_block_id: str = field(default_factory=lambda: uuid.uuid4().hex) audio_block_id: str = field(default_factory=lambda: uuid.uuid4().hex) text_started: bool = False audio_started: bool = False text_chars: int = 0 @dataclass class _UserTurn: """One user reply, retained until its transcription settles.""" reply_id: str item_id: str = "" open: bool = True speech_ended: bool = False partial_transcription: bool = False @dataclass class _QueuedEvent: """One outward event and its state at a persistence boundary.""" event: AgentEvent checkpoint: AgentState | None = None @dataclass class _BackgroundTools: """Work that must settle before a logical reply can complete.""" pending: int = 0 model_done: bool = False lock: asyncio.Lock = field(default_factory=asyncio.Lock) @dataclass class _ClientDelegation: """One application-managed task requested by a Live session.""" delegation_id: str prompt: Msg generation: int agent: "Agent | None" = None prompt_id: str = "" baseline_ids: set[str] = field(default_factory=set) synced_ids: set[str] = field(default_factory=set) buffered_events: list[AgentEvent] = field(default_factory=list) visible: bool = False timeout_task: asyncio.Task[None] | None = None expiring: bool = False class RealtimeAgent: """A voice agent: a realtime model on one side, a transport on the other, and the turn-taking state machine in between. Unlike :class:`~agentscope.agent.Agent` it is bidirectional and has no request/reply boundary — audio flows in continuously while events flow out of :meth:`reply_stream`. Three lifetimes are kept apart on purpose. The agent owns the model session and the state; a transport is owned by whoever created it; a :meth:`reply_stream` borrows both for as long as both are alive. So a client can drop and reconnect without losing the model session, and the model session can time out during a long silence and be re-established on the next word without touching the transport. The public methods are the only entry point for discrete input. A transport carrying a browser's ``ControlFrame`` calls exactly those methods rather than reaching into the agent, so one code path handles the semantics whether the caller is Python or a browser. Continuous audio is separate and always arrives through the transport. Example: .. code-block:: python agent = RealtimeAgent("Friday", "Be brief.", model) async with agent: # model session async with LocalAudioTransport() as t: # sound card async for event in agent.reply_stream(t): # this call print(event) """ def __init__( self, name: str, system_prompt: str, model: RealtimeModelBase, toolkit: Toolkit | None = None, state: AgentState | None = None, vad: VADBase | None = None, aggregator: TurnAggregator | None = None, delegation_agent_factory: ( Callable[[AgentState], "Agent"] | None ) = None, ) -> None: """Initialize the realtime agent. Args: name (`str`): Display name stamped on assistant messages and events. system_prompt (`str`): System instructions sent to the model on connect, with the toolkit's skill instructions appended. model (`RealtimeModelBase`): The realtime model. Its session is opened by :meth:`connect` and lives as long as this agent — not as long as any one transport — and is re-established on the next user input if the provider closes it. toolkit (`Toolkit | None`, optional): Tools the model may call. Executed here, with permission checks against ``state.permission_context``. state (`AgentState | None`, optional): Conversation history, permission rules and tool context. A new one is created if omitted. vad (`VADBase | None`, optional): Server-side voice activity detection over the audio arriving from the transport. ``STARTED`` cuts off a reply the user speaks over; ``ENDED`` closes the user's turn and hands it to the model. When given, the provider's own turn detection is switched off so that exactly one source decides turn boundaries; when ``None``, the provider decides and this agent only reacts to what it reports. aggregator (`TurnAggregator | None`, optional): Collapses the provider's transcripts into clean user turns: merging one that endpointing split, dropping bare acknowledgements. Subclass it to change what counts as a turn. A default with no backchannel list is used if omitted. delegation_agent_factory (`Callable[[AgentState], Agent] | None`, optional): Builds a chat agent for each client-delegated Live task from the supplied isolated session state. Its model, toolkit, and permission state normally come from the current persisted chat session. The returned agent must have the same name as this realtime agent so tool routing and checkpoint recovery use the same assistant identity. A mismatched name fails the delegation before backend execution. """ self.name = name self.system_prompt = system_prompt self.model = model self.toolkit = toolkit self.state = state or AgentState() self.vad = vad self.aggregator = aggregator or TurnAggregator() self._delegation_agent_factory = delegation_agent_factory if ( self.model.interaction_mode is InteractionMode.FULL_DUPLEX and self.vad is not None ): raise ValueError( "A full-duplex model cannot use client-side turn VAD.", ) self._engine = PermissionEngine(self.state.permission_context) self._transport: TransportBase | None = None self._out: asyncio.Queue[_QueuedEvent] = asyncio.Queue() self._yielded_checkpoint: tuple[str, AgentState] | None = None self._reply: _Reply | None = None self._audio_pending = False self._finished_item = "" # The agent's open logical reply. Multiple provider responses may # belong to it when tools are involved. self._reply_id = "" # The user's turn in flight, reported as a reply of its own. self._user_turn: _UserTurn | None = None self._pending_user_turns: dict[str, _UserTurn] = {} self._metrics = TurnMetrics() self._pending_tools: dict[str, ToolCallBlock] = {} self._confirmations: dict[str, asyncio.Future[ConfirmResult]] = {} self._confirmation_replies: dict[str, str] = {} self._background_tools: dict[str, _BackgroundTools] = {} self._tasks: set[asyncio.Task] = set() self._barge_lock = asyncio.Lock() self._live_session_id = "" self._live_replies: dict[str, _Reply] = {} self._live_message_ids: set[str] = set() self._live_transcript: deque[tuple[str, str, int, int]] = deque() self._live_transcript_chars = 0 self._last_live_checkpoint_at: float | None = None self._last_live_checkpoint_end_ms: int | None = None self._delegations: dict[str, _ClientDelegation] = {} self._delegation_queue: deque[str] = deque() self._active_delegation_id: str | None = None self._delegated_tool_calls: dict[str, str] = {} self._delegation_lock = asyncio.Lock() self._closing = False # Model session: connected flag, the downlink pump that outlives # any transport, and reconnect bookkeeping. self._connected = False self._connected_event = asyncio.Event() self._connection_generation = 0 self._downlink: asyncio.Task | None = None self._backlog: list[bytes] = [] self._retry_at = 0.0 self._backoff = 1.0 # ------------------------------------------------------------------ # Lifecycle: the model session # ------------------------------------------------------------------ async def __aenter__(self) -> "RealtimeAgent": """Connect on entry.""" await self.connect() return self async def __aexit__(self, *exc: Any) -> None: """Disconnect on exit.""" await self.close() async def connect(self) -> None: """Open the model session. Safe to call again after the provider closed it; a no-op while connected.""" if self._connected: return if self._connection_generation: async with self._barge_lock: self._reset_user_turns() self._finish_reply(ReplyFinishedReason.ERROR) self._finish_live_replies(ReplyFinishedReason.ERROR) if self.model.interaction_mode is InteractionMode.FULL_DUPLEX: # A new Live session cannot accept old delegation IDs. # Close and persist its tasks before opening the new socket. await self.close() self._closing = False self._connection_generation += 1 instructions = self.system_prompt tools = None if self.toolkit is not None: groups = self.state.tool_context.activated_groups skills = await self.toolkit.get_skill_instructions(groups) if skills: instructions = f"{instructions}\n\n{skills}" if self.model.card.supports_tools: tools = await self.toolkit.get_tool_schemas(groups) # TODO(realtime): tools and instructions are sent once, here. # Activating a tool group or installing a skill mid-session — # ResetTools, the meta tool — therefore has no effect until the # next connect, even though the model is told it can do it. # # Fix: a `RealtimeModelBase.update_session(instructions, tools)` # re-sent whenever `state.tool_context.activated_groups` changes. # OpenAI, DashScope and xAI accept `session.update` on the open # connection; Gemini forbids it and must reconnect with a # `sessionResumption` handle plus a new `setup`, which keeps the # context. No provider documents whether the update applies # retroactively, so treat it as affecting future turns only. Do # not let it change `voice`: OpenAI locks it after first audio. history = [ message for message in self.state.context if message.id != self._reply_id and ( message.role != "assistant" or message.finished_reason is not ReplyFinishedReason.ERROR ) ][-_HISTORY_MAX_MESSAGES:] summary = self.state.summary if isinstance(summary, str): summary_text = summary else: summary_text = "\n".join( block.text for block in summary if isinstance(block, TextBlock) ) if summary_text.strip(): history.insert( 0, SystemMsg(name="summary", content=summary_text), ) if history and not self.model.supports_history_replay: lines = [ f"{message.name}: {text}" for message in history if (text := message.get_text_content()) ] kept: list[str] = [] kept_chars = 0 for line in reversed(lines): separator_chars = 1 if kept else 0 if ( kept_chars + separator_chars + len(line) > _HISTORY_MAX_TEXT_CHARS ): break kept.append(line) kept_chars += separator_chars + len(line) fallback = "\n".join(reversed(kept)) if fallback: instructions = ( f"{i - src/agentscope/agent/_realtime/_aggregator.py (2711 bytes)
# -*- coding: utf-8 -*- """Turn aggregation.""" import time _TRAILING = " 。,,.!?!?、" class TurnAggregator: """Collapses the transcripts a provider emits into clean user turns. Turn boundaries in speech are inferred, and inferred wrongly often enough to matter: one sentence gets split across two turns when the speaker pauses, and a stray "mm-hmm" gets promoted to a turn of its own. Neither is visible to the provider once it has answered, but both end up in our own context, where they outlive the call. """ def __init__( self, merge_window_ms: int = 800, backchannels: frozenset[str] = frozenset(), min_chars: int = 1, ) -> None: """Initialize the aggregator. Args: merge_window_ms (`int`, defaults to `800`): A transcript arriving this soon after the previous turn continues it rather than starting a new one. backchannels (`frozenset[str]`, optional): Acknowledgements that never constitute a turn. Language specific, so empty by default. min_chars (`int`, defaults to `1`): Transcripts shorter than this are dropped. """ self.merge_window_ms = merge_window_ms self.backchannels = frozenset(backchannels) self.min_chars = min_chars self._last_at: float | None = None self._merges = False def take(self, transcript: str) -> str | None: """Accept a settled transcript and decide whether it is a turn. Args: transcript (`str`): The transcript the provider settled on. Returns: `str | None`: The turn text, or ``None`` for an empty transcript or a bare acknowledgement. """ text = transcript.strip() # A transcript that is not a turn did not continue the previous # turn either, so do not leave merges_with_previous() stale. self._merges = False if len(text) < self.min_chars: return None if text.strip(_TRAILING) in self.backchannels: return None now = time.monotonic() self._merges = ( self._last_at is not None and (now - self._last_at) * 1000 <= self.merge_window_ms ) self._last_at = now return text def merges_with_previous(self) -> bool: """Whether the last :meth:`take` continued the previous turn.""" return self._merges def reset(self) -> None: """Forget the previous turn, e.g. on reconnect.""" self._last_at = None self._merges = False - src/agentscope/agent/_realtime/_metrics.py (2024 bytes)
# -*- coding: utf-8 -*- """Per-turn latency metrics.""" from pydantic import BaseModel, Field class TurnMetrics(BaseModel): """The four timestamps of one turn, and the delays derived from them. All timestamps are :func:`time.monotonic` readings, in seconds. """ user_speech_end_at: float | None = None """The user stopped speaking.""" turn_committed_at: float | None = None """Endpointing settled and the turn was handed to the backend.""" backend_first_audio_at: float | None = None """The backend produced its first audio byte.""" first_audio_played_at: float | None = None """That audio actually reached the speaker. Reported by the transport, and the only timestamp that reflects what the user perceives.""" input_tokens: int = Field(default=0, ge=0) output_tokens: int = Field(default=0, ge=0) @property def endpointing_delay(self) -> float | None: """Time spent deciding the user had finished.""" return self._delta(self.user_speech_end_at, self.turn_committed_at) @property def backend_ttfb(self) -> float | None: """Time the backend took to start answering.""" return self._delta( self.turn_committed_at, self.backend_first_audio_at, ) @property def transport_delay(self) -> float | None: """Time between audio leaving the server and reaching the ear.""" return self._delta( self.backend_first_audio_at, self.first_audio_played_at, ) @property def e2e_latency(self) -> float | None: """The user stopped speaking until they heard an answer.""" return self._delta( self.user_speech_end_at, self.first_audio_played_at, ) @staticmethod def _delta(start: float | None, end: float | None) -> float | None: """The gap between two optional timestamps.""" if start is None or end is None: return None return end - start - src/agentscope/agent/_structured_output_tool.py (6160 bytes)
# -*- coding: utf-8 -*- """The builtin tool used to generate the required structured output.""" from copy import deepcopy from typing import Any, Generator, List, Type from jsonschema import Draft202012Validator, validators from pydantic import BaseModel, ValidationError from ..permission._context import PermissionContext from ..permission._decision import PermissionDecision from ..permission._types import PermissionBehavior from ..tool._utils import _remove_title_field from ..message import TextBlock, ToolResultState from ..tool._base import ToolBase, ToolMiddlewareBase from ..tool._response import ToolChunk from ..state import AgentState def _extend_with_default(validator_class: Any) -> Any: """Extend a jsonschema validator to fill the schema-declared defaults into the instance during validation.""" validate_properties = validator_class.VALIDATORS["properties"] def set_defaults( validator: Any, properties: dict, instance: Any, schema: dict, ) -> Generator[Any, None, None]: for prop, subschema in properties.items(): if isinstance(instance, dict) and "default" in subschema: instance.setdefault(prop, deepcopy(subschema["default"])) yield from validate_properties(validator, properties, instance, schema) return validators.extend(validator_class, {"properties": set_defaults}) _DefaultFillingValidator = _extend_with_default(Draft202012Validator) class _GenerateStructuredOutput(ToolBase): """The builtin tool used to generate structured output.""" name = "GenerateStructuredOutput" description = """Generate the required structured output by this tool. This tool is equipped only when you're required to generate structured output. The input schema represents the required structured output. When you are ready to generate a structured output, call this tool with the structured output as input. When you're equipped this tool, you MUST end your response with calling this tool. Once this tool is called, your current response is finished and the structured output is sent to the user. # When to Use This Tool - When you collect enough resources and information. """ is_state_injected = True is_concurrency_safe = True is_read_only = True def __init__( self, schema: Type[BaseModel] | dict, middlewares: List[ToolMiddlewareBase] | None = None, ) -> None: """Initialize the tool with a model class or a JSON schema dict.""" super().__init__(middlewares=middlewares) self.schema = schema @property def input_schema(self) -> dict: # type: ignore[override] """The input schema of this tool.""" if isinstance(self.schema, type): return _remove_title_field(self.schema.model_json_schema()) return _remove_title_field(deepcopy(self.schema)) async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """The generate structured output tool is always allowed to be called.""" return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{self.name} is always allowed.", ) async def call( # type: ignore[override] self, _agent_state: AgentState, **kwargs: Any, ) -> ToolChunk: """Validate the given structured output and record it in the agent state. The tool input fields (defined by the required schema) arrive as keyword arguments.""" schema = _agent_state.reply_context.structured_schema if not schema: return ToolChunk( content=[ TextBlock( text="No structured output is required for now.", ), ], state=ToolResultState.SUCCESS, ) if isinstance(schema, type): # In-process: validate with the model class itself try: validated = schema.model_validate(kwargs) # Custom validators may raise arbitrary exceptions except Exception as e: # pylint: disable=broad-exception-caught if isinstance(e, ValidationError): message = "; ".join( f"{'.'.join(str(_) for _ in err['loc'])}: " f"{err['msg']}" for err in e.errors() ) else: message = str(e) return ToolChunk( content=[ TextBlock( text="ValidationError: Structured output " f"validation failed with error: {message}", ), ], state=ToolResultState.ERROR, ) _agent_state.reply_context.structured_output = ( validated.model_dump(mode="json") ) else: # Reloaded state: only the JSON schema dict remains, and the # validation fills the schema-declared defaults into ``kwargs`` validator = _DefaultFillingValidator(schema) errors = list(validator.iter_errors(kwargs)) if errors: messages = "; ".join( f"{_.json_path}: {_.message}" for _ in errors ) return ToolChunk( content=[ TextBlock( text="ValidationError: Structured output " f"validation failed with error: {messages}", ), ], state=ToolResultState.ERROR, ) _agent_state.reply_context.structured_output = kwargs return ToolChunk( content=[ TextBlock( text="Structured output generated successfully.", ), ], state=ToolResultState.SUCCESS, ) - src/agentscope/agent/_utils.py (1687 bytes)
# -*- coding: utf-8 -*- """The utility classes used in building the agent class.""" from dataclasses import dataclass from typing import Literal from datetime import timezone, tzinfo from zoneinfo import ZoneInfo, ZoneInfoNotFoundError from pydantic import BaseModel from ..tool import ToolChoice from ..message import ToolCallBlock, HintBlock, Msg from ..event import AgentEvent from .._logging import logger @dataclass class _ToolCallBatch: """A batch of tool calls that execute either sequentially or concurrently.""" type: Literal["sequential", "concurrent"] """The batch type""" tool_calls: list[ToolCallBlock] """The list of tool calls in the batch.""" class Acting(BaseModel): """Next action: execute the given tool calls.""" tool_calls: list[ToolCallBlock] class Reasoning(BaseModel): """Next action: another model call, with optional hint and tool choice.""" hint: HintBlock | None = None tool_choice: ToolChoice | None = None class Exit(BaseModel): """Next action: end the reply.""" exit_msg: Msg exit_events: list[AgentEvent] | None = None def _resolve_timezone(name: str) -> tzinfo: """Resolve the given timezone name, falling back to UTC when the name is invalid or the timezone database is unavailable, e.g. on Windows or slim images without the ``tzdata`` package.""" try: return ZoneInfo(name) except (ZoneInfoNotFoundError, ValueError): logger.warning( "Failed to resolve the timezone %s, fallback to UTC. Install the " "'tzdata' package if the timezone database is missing.", repr(name), ) return timezone.utc - src/agentscope/app/__init__.py (281 bytes)
# -*- coding: utf-8 -*- """The FastAPI based agent service module, which contains all service-related components and a configurable FastAPI app factory. """ from ._app import create_app from ._types import SubAgentTemplate __all__ = [ "create_app", "SubAgentTemplate", ] - src/agentscope/app/_app.py (21979 bytes)
# -*- coding: utf-8 -*- """AgentScope app factory.""" import json import os import secrets from weakref import WeakValueDictionary from typing import Type, TYPE_CHECKING, Any from pydantic import TypeAdapter from ._lifespan import lifespan from .access import DenyAllResourceAccessPolicy, ResourceAccessPolicyBase from .hub import HubBase, HubError, MCPHubBase, SkillHubBase from ._service._session import SessionBusyError from .rag.blob_store import BlobStoreBase, LocalBlobStore from .rag.knowledge_base_manager import KnowledgeBaseManagerBase from .workspace_manager import WorkspaceManagerBase from ._router import ( asr_router, agent_router, background_task_router, channel_router, chat_router, credential_router, health_router, hub_router, knowledge_base_router, embedding_model_router, mcp_router, model_router, realtime_router, tts_model_router, voice_profile_router, schedule_router, session_router, skill_router, sop_router, workspace_router, ) from ._types import ( AgentMiddlewareFactory, AgentToolFactory, RealtimeIceServer, SubAgentTemplate, ) from .channel import ChannelBase, ChannelTypeRegistry from .message_bus import MessageBus from .storage import StorageBase from ..agent import Agent from ..credential import CredentialFactory, CredentialBase from ..rag import ApproxTokenChunker, ChunkerBase, ParserBase, TextParser from .._logging import logger from .._version import __version__ if TYPE_CHECKING: from fastapi import FastAPI from fastapi.middleware import Middleware as FastAPIMiddleware else: FastAPI = Any FastAPIMiddleware = Any def _index_hubs(hubs: list | None, kind: str) -> dict: """Key the hubs by id, rejecting duplicates. Args: hubs (`list | None`): The hubs passed to :func:`create_app`. kind (`str`): The hub kind, used in the error message. Returns: `dict`: The hubs keyed by :attr:`HubBase.hub_id`. Raises: `ValueError`: When two hubs of the same kind share an id, which would make them indistinguishable in the routes. """ indexed: dict[str, HubBase] = {} for hub in hubs or []: if hub.hub_id in indexed: raise ValueError( f"Duplicate {kind} hub id {hub.hub_id!r}: hub ids must be " f"unique so routes address exactly one hub.", ) indexed[hub.hub_id] = hub return indexed def _load_realtime_ice_servers( configured: list[dict[str, Any]] | None, ) -> list[dict[str, Any]]: """Load and validate browser-compatible ICE server dictionaries.""" servers: Any = configured if servers is None: raw = os.getenv("AGENTSCOPE_REALTIME_ICE_SERVERS") if not raw: return [] try: servers = json.loads(raw) except json.JSONDecodeError as exc: raise ValueError( "AGENTSCOPE_REALTIME_ICE_SERVERS must be valid JSON.", ) from exc validated = TypeAdapter(list[RealtimeIceServer]).validate_python(servers) return [ server.model_dump(mode="json", by_alias=True, exclude_none=True) for server in validated ] def create_app( storage: StorageBase, message_bus: MessageBus, workspace_manager: WorkspaceManagerBase, knowledge_base_manager: KnowledgeBaseManagerBase | None = None, knowledge_parsers: list[ParserBase] | dict[str, ParserBase] | None = None, knowledge_chunkers: list[Type[ChunkerBase]] | None = None, blob_store: BlobStoreBase | None = None, enable_index_worker: bool = True, mcp_hubs: list[MCPHubBase] | None = None, skill_hubs: list[SkillHubBase] | None = None, *, enable_channel_worker: bool = True, enable_scheduler: bool = True, extra_credentials: list[Type[CredentialBase]] | None = None, extra_middlewares: list[FastAPIMiddleware] | None = None, extra_agent_middlewares: AgentMiddlewareFactory | None = None, extra_agent_tools: AgentToolFactory | None = None, tool_offload_timeout_secs: float | None = 10.0, custom_subagent_templates: list[SubAgentTemplate] | None = None, custom_agent_cls: Type[Agent] | None = None, resource_access_policy: ResourceAccessPolicyBase | None = None, channels: list[Type[ChannelBase]] | None = None, download_secret: str | None = None, realtime_ice_servers: list[dict[str, Any]] | None = None, title: str = "AgentScope", version: str = __version__, **kwargs: Any, ) -> FastAPI: """Create and configure a FastAPI application. This is the primary entry point for embedding AgentScope into an existing service or running it standalone. All built-in routers are registered automatically; pass ``extra_middlewares`` to add your own. Usage — standalone:: app = create_app( storage=RedisStorage(), message_bus=RedisMessageBus(), workspace_manager=LocalWorkspaceManager(), ) uvicorn.run(app, host="0.0.0.0", port=8000) Usage — mount onto an existing app:: root = FastAPI() agentscope_app = create_app( storage=RedisStorage(), message_bus=RedisMessageBus(), workspace_manager=LocalWorkspaceManager(), ) root.mount("/agentscope", agentscope_app) Args: storage (`StorageBase`): The storage backend. Its lifecycle (``__aenter__`` / ``__aexit__``) is managed by the app lifespan. message_bus (`MessageBus`): The live message bus used for cross-session inbox delivery and idle-session triggers. Required — the bus is intentionally decoupled from ``storage`` so the persistence backend (e.g. SQL) can differ from the transport backend (Redis). Its lifecycle is also managed by the app lifespan. workspace_manager (`WorkspaceManagerBase`): The workspace manager. Required — every chat run and every ``/workspace`` endpoint depends on it. Its lifecycle ( ``__aenter__`` / ``__aexit__``) is managed by the app lifespan. Pass a :class:`~agentscope.app._manager. LocalWorkspaceManager` for local-directory workspaces. knowledge_base_manager (`KnowledgeBaseManagerBase | None`, \ optional): The knowledge base manager that owns knowledge base lifecycle and serves :class:`~agentscope.rag.KnowledgeBase` runtime handles to both HTTP service and agent code. The manager carries its own vector store instance — its ``__aenter__`` / ``__aexit__`` enter and release that vector store, so the caller does not pass the vector store separately. ``None`` disables knowledge base endpoints entirely. knowledge_parsers (`list[ParserBase] | dict[str, ParserBase] | \ None`, optional): Parsers registered for knowledge base document uploads. Pass a **list** to have the service route by each parser's ``supported_media_types`` (later entries override earlier ones for overlapping types, with a warning); pass a **dict** ``media_type → parser`` for explicit routing (one parser bound to multiple types, type aliases, ...). Defaults to ``[TextParser()]`` when ``knowledge_base_manager`` is set. knowledge_chunkers (`list[Type[ChunkerBase]] | None`, optional): The chunker classes users can choose from when creating a knowledge base. The chunker type and parameters are pinned on the knowledge base record and reconstructed by the index worker. Defaults to ``[ApproxTokenChunker]`` when ``knowledge_base_manager`` is set. blob_store (`BlobStoreBase | None`, optional): Backend storing uploaded document bytes between the upload endpoint and the indexing worker. Required when ``knowledge_base_manager`` is set; defaults to :class:`~agentscope.app.rag.blob_store.LocalBlobStore` rooted at ``./blobs``. Its lifecycle (``__aenter__`` / ``__aexit__``) is managed by the app lifespan. enable_index_worker (`bool`, defaults to ``True``): When ``True`` (embedded deployment) the API process starts an :class:`~agentscope.app._service.IndexWorker` and an :class:`~agentscope.app._service.IndexSweeper` in its lifespan, and dispatches indexing tasks via an in-process queue. When ``False`` (dedicated deployment) the API process performs no indexing — a separate worker process is expected to consume tasks from the message bus. No effect when ``knowledge_base_manager`` is ``None``. mcp_hubs (`list[MCPHubBase] | None`, optional): The MCP hubs that provide MCPs. skill_hubs (`list[SkillHubBase] | None`, optional): The SkillHubs that provide skills. enable_channel_worker (`bool`, defaults to ``True``): Whether this process holds the channels' long connections. ``True`` (embedded deployment) suits a desktop build or a single API process. Set ``False`` when running dedicated channel workers: a platform gives one bot's events to one connection, so every replica connecting would either waste connections or duplicate messages. The channel API, the client factory and webhook delivery stay available either way — only the connections move. enable_scheduler (`bool`, defaults to ``True``): Whether this process owns the schedule timers. APScheduler's jobstore is in-memory, so every process holding them fires every cron tick and a schedule runs once per replica — set ``False`` on all but one. The schedule API and the agent's schedule tools stay available either way; those processes persist the record and notify the owner over the bus. extra_credentials (`list[Type[CredentialBase]] | None`, optional): Additional :class:`~agentscope.credential.CredentialBase` subclasses to register before the app starts. Equivalent to calling :func:`~agentscope.credential.CredentialFactory. register_credential` for each class. extra_middlewares (`list[Middleware] | None`, optional): Additional ASGI middlewares to add to the application. extra_agent_middlewares (`AgentMiddlewareFactory | None`, optional): An async factory ``(user_id, agent_id, session_id, workspace) -> awaitable of list[MiddlewareBase]`` that produces extra :class:`~agentscope.middleware.MiddlewareBase` instances to attach to the agent on each invocation. Called once per agent assembly (i.e. per chat turn / scheduled trigger), so it can return user/session-specific middleware (auth, audit logging, tenant isolation, etc.). ``workspace`` is the session's resolved :class:`~agentscope.workspace.WorkspaceBase`, exposing ``workdir`` and ``get_backend()`` for filesystem-backed middleware such as :class:`~agentscope.middleware.AgenticMemoryMiddleware`. Factories written against the older three-argument signature keep working — the fourth argument is only passed to factories that accept it. The returned middlewares are appended to the framework-supplied ones (e.g. ``ToolOffloadMiddleware``). extra_agent_tools (`AgentToolFactory | None`, optional): An async factory ``(user_id, agent_id, session_id) -> awaitable of list[ToolBase]`` that produces extra :class:`~agentscope.tool.ToolBase` instances to register in the agent's toolkit on each invocation. Useful when tool availability depends on the caller (per-tenant integrations, user-specific credentials). The returned tools are added to the workspace-derived tools in the toolkit's ``"basic"`` group. custom_subagent_templates (`list[SubAgentTemplate] | None`, optional): Reusable blueprints for sub-agent creation within teams. Each template defines a sub-agent *type* (e.g. ``"researcher"``, ``"coder"``) with pre-configured system prompt, context config, ReAct config, 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 :class:`~agentscope.app._types.SubAgentTemplate` for details. custom_agent_cls (`Type[Agent] | None`, optional): A custom :class:`~agentscope.agent.Agent` subclass to use when assembling agents. When ``None`` (default), the built-in :class:`~agentscope.agent.Agent` is used. resource_access_policy (`ResourceAccessPolicyBase | None`, optional): Policy deciding whether a viewer may access credentials / agents / knowledge bases owned by another user. When ``None`` (default), a :class:`DenyAllResourceAccessPolicy` is installed which preserves the historical owner-isolated behavior. channels (`list[Type[ChannelBase]] | None`, optional): Channel adapter classes this service allows (e.g. ``[DingTalkChannel, FeishuChannel, DiscordChannel]``). Each class self-describes its ``channel_type``, credentials and config, so the service registers it without a separate table; pass a custom :class:`~agentscope.app.channel.ChannelBase` subclass to add a platform. When ``None`` (default), no channel types are registered and the channel feature stays off until the caller opts in by passing at least one adapter class. download_secret (`str | None`, optional): Signs the short-lived tokens that let a browser download a workspace file by navigation. Defaults to a value generated per process, which is fine for a single instance but **must be set explicitly behind a load balancer** — otherwise a token minted by one replica is rejected by the next, and downloads fail at random. realtime_ice_servers (`list[dict[str, Any]] | None`, optional): STUN and TURN servers exposed to browser WebRTC clients. When omitted, the JSON array in ``AGENTSCOPE_REALTIME_ICE_SERVE - src/agentscope/app/_bus_ops.py (50972 bytes)
# -*- coding: utf-8 -*- """Business-level operations built on top of MessageBus primitives. These helpers compose generic bus primitives (``log_append``, ``publish``, ``queue_push``) with domain-specific key layouts from ``MessageBusKeys``. They live here — between the transport layer (``message_bus``) and the service layer (``_service``) — so that neither layer needs to know about the other's internals. .. list-table:: :widths: 30 70 * - :func:`publish_session_event` - Append an event to the session replay log and fan it out live. * - :func:`enqueue_run_trigger` - Enqueue a typed run trigger and signal dispatchers. * - :func:`enqueue_chat_input` - Append an ordinary user turn to a per-session FIFO. * - :func:`enqueue_index_task` - Enqueue a knowledge-document indexing task and signal consumers. """ from __future__ import annotations import json import uuid from contextlib import AsyncExitStack, asynccontextmanager from datetime import datetime, timezone from typing import AsyncGenerator, TYPE_CHECKING, Literal from .._logging import logger from ..event import CustomEvent from ..middleware import SteeringAcknowledgementUncertainError from .message_bus._keys import MessageBusKeys from ._chat_input_store import ( cleanup_session, discard_input, decode_input, queue_entry, ) if TYPE_CHECKING: from ._client_external_tool import ( ClientBuiltinToolName, ClientExternalToolDefinition, ) from .message_bus._base import MessageBus from agentscope.event import ( ExternalExecutionResultEvent, UserConfirmResultEvent, UserInterruptEvent, ) from agentscope.message import Msg # ── publish_session_event ────────────────────────────────────────────── class ChatQueueFullError(RuntimeError): """Raised when a session has reached its pending-turn limit.""" class ChatQueueBusyError(RuntimeError): """Raised when a short queue mutation lock cannot be acquired.""" class ChatSteeringUnavailableError(RuntimeError): """Raised when a queued turn cannot steer the requested active reply.""" @asynccontextmanager async def chat_input_mutation( bus: "MessageBus", session_id: str, *, timeout_secs: float | None = None, ) -> AsyncGenerator[None, None]: """Acquire a short-lived queue mutation lock with bounded waiting. Args: bus (`MessageBus`): Application message bus that owns the distributed lock. session_id (`str`): Session whose pending-input queue will be mutated. timeout_secs (`float | None`, optional): Maximum time to wait for the lock. ``None`` uses the configured queue-mutation timeout. Yields: `None`: Control while the session mutation lock is held. Raises: `ChatQueueBusyError`: The lock could not be acquired before the timeout. """ timeout = ( MessageBusKeys.CHAT_INPUT_MUTATION_TIMEOUT_SECS if timeout_secs is None else timeout_secs ) async with AsyncExitStack() as stack: try: await stack.enter_async_context( bus.acquire_lock_bounded( MessageBusKeys.chat_input_mutation_lock(session_id), ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS, timeout_secs=timeout, ), ) except TimeoutError as exc: raise ChatQueueBusyError( "The pending message queue is busy; retry shortly.", ) from exc yield @asynccontextmanager async def _chat_input_user_quota( bus: "MessageBus", user_id: str, ) -> AsyncGenerator[None, None]: """Serialize the bounded per-user quota check performed by enqueue. Args: bus (`MessageBus`): Application message bus that owns the distributed lock. user_id (`str`): User whose aggregate pending-input quota is being checked. Yields: `None`: Control while the per-user quota lock is held. Raises: `ChatQueueBusyError`: The quota lock could not be acquired before the timeout. """ async with AsyncExitStack() as stack: try: await stack.enter_async_context( bus.acquire_lock_bounded( MessageBusKeys.chat_input_user_quota_lock(user_id), ttl_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TTL_SECS, timeout_secs=( MessageBusKeys.CHAT_INPUT_MUTATION_TIMEOUT_SECS ), ), ) except TimeoutError as exc: raise ChatQueueBusyError( "The pending message quota is busy; retry shortly.", ) from exc yield def _serialized_input( inputs: "Msg | list[Msg]", ) -> dict | list[dict]: """Serialize one ordinary input without imposing a queue byte limit. Args: inputs (`Msg | list[Msg]`): One message or a non-empty ordered message list. Returns: `dict | list[dict]`: JSON-compatible message payload suitable for the bus. Raises: `ValueError`: ``inputs`` is an empty list. """ if isinstance(inputs, list) and not inputs: raise ValueError("A queued message list must not be empty.") return ( [msg.model_dump(mode="json") for msg in inputs] if isinstance(inputs, list) else inputs.model_dump(mode="json") ) async def publish_session_event( bus: "MessageBus", session_id: str, event: dict, ) -> str: """Append event to replay log + fan out live. Args: bus (`MessageBus`): The application message bus. session_id (`str`): The session this event belongs to. event (`dict`): JSON-serializable event payload. Returns: `str`: The replay-log entry id assigned by the backend. """ key = MessageBusKeys.session_events(session_id) entry_id = await bus.log_append( key, event, max_len=MessageBusKeys.SESSION_REPLAY_MAX_LEN, ) await bus.publish(key, {**event, "_entry_id": entry_id}) return entry_id # ── enqueue_run_trigger ──────────────────────────────────────────────── async def enqueue_run_trigger( bus: "MessageBus", user_id: str, session_id: str, agent_id: str, *, kind: Literal[ "wake", "resume", "message", "queued_message", ] = MessageBusKeys.WAKEUP_KIND_WAKE, inputs: UserConfirmResultEvent | ExternalExecutionResultEvent | UserInterruptEvent | Msg | None = None, client_external_tools: list[ClientExternalToolDefinition] | None = None, client_builtin_tools: list[ClientBuiltinToolName] | None = None, signal: bool = True, ) -> None: """Enqueue a typed run trigger and optionally signal dispatchers. ``kind`` selects how the dispatcher handles the entry: - ``wake`` — idle-session wake-up. The dispatcher skips the entry when the session is already running (the live run drains the inbox itself). ``inputs`` must be ``None``. - ``resume`` — resume a HITL-parked session with a user confirmation, an external execution result, or a user interrupt. The dispatcher waits (with backoff) until the parked run releases its lock, then spawns with ``input_msg`` set to the deserialised event. - ``message`` — start a new turn from a genuine user ``Msg`` (e.g. an inbound channel message). Like ``resume`` it carries input and is re-queued rather than dropped while the session is running; the run persists it and reasons over it as a real user turn. - ``queued_message`` — signal that a session's ordinary browser-input FIFO should be drained. ``inputs`` must be ``None``. The payload is serialised to a plain dict before being pushed to the wakeup queue; the ``MessageBus`` transport layer never sees event types. Args: bus (`MessageBus`): The application message bus. user_id (`str`): The owning user id. session_id (`str`): The session to trigger a run for. agent_id (`str`): The agent id that owns the session. kind: Trigger kind. Defaults to ``"wake"``. inputs: The input for ``resume`` and ``message`` triggers. Ignored (and should be ``None``) for ``wake`` and ``queued_message``. The function calls ``model_dump(mode="json")`` internally — callers pass the model object, not a pre-serialised dict. client_external_tools: External tools supported by the client that produced this trigger. They remain scoped to the resulting run. client_builtin_tools: Native external tool names supported by this trigger's client. signal: Whether to publish the shared wakeup signal after pushing. Recovery sweeps pass ``False`` to batch many durable triggers behind one signal. """ payload: dict[str, object] = { "user_id": user_id, "session_id": session_id, "agent_id": agent_id, "kind": kind, "input": inputs.model_dump(mode="json") if inputs else None, } if client_builtin_tools: payload["client_builtin_tools"] = client_builtin_tools if client_external_tools: payload["client_external_tools"] = [ tool.model_dump(mode="json") for tool in client_external_tools ] await bus.queue_push(MessageBusKeys.wakeup_queue(), payload) if signal: await bus.publish(MessageBusKeys.wakeup_signal(), {}) async def nudge_chat_inputs( bus: "MessageBus", user_id: str, session_id: str, agent_id: str, ) -> None: """Wake pending input after releasing locks; recovery is fallback.""" try: pending = await bus.queue_read( MessageBusKeys.chat_inputs(session_id), max_count=1, ) claimed = await bus.registry_exists( MessageBusKeys.chat_input_inflight_registry(), session_id, ) if pending or claimed: await enqueue_run_trigger( bus, user_id, session_id, agent_id, kind=MessageBusKeys.WAKEUP_KIND_QUEUED_MESSAGE, ) except Exception: logger.exception("Failed to nudge queued inputs for %s.", session_id) async def enqueue_chat_input( bus: "MessageBus", user_id: str, session_id: str, agent_id: str, inputs: Msg | list[Msg], *, client_external_tools: list[ClientExternalToolDefinition] | None = None, client_builtin_tools: list[ClientBuiltinToolName] | None = None, ) -> dict: """Append an ordinary user turn to a session FIFO and wake its pump. The input and its wake-up marker are deliberately separate: the per-session queue owns ordering, while the shared trigger queue only nudges an available dispatcher. Duplicate ``queued_message`` triggers are harmless because the per-session queue is consumed exactly once. Once the input is stored, notification failures are logged rather than reported as rejection; pending-input recovery retries dispatch. Args: bus: Application message bus. user_id: Owning user id. session_id: Target session id. agent_id: Agent that owns the session. inputs: One user message or a non-empty ordered message list. client_external_tools: Client tool definitions scoped to this queued turn. client_builtin_tools: Native external tool names supported by this turn's client. Returns: `dict`: Public queue item containing ``id``, ``created_at``, and serialized ``input``. Raises: `ValueError`: ``inputs`` is an empty list. `ChatQueueFullError`: The session queue or aggregate per-user quota is full. `ChatQueueBusyError`: A queue or quota mutation lock cannot be acquired promptly. """ serialized = _serialized_input(inputs) item: dict = { # Queue identity is independent from message identity. Clients may # legitimately retry/replay the same Msg.id; management operations # still need one unambiguous id per pending turn. "id": uuid.uuid4().hex, "user_id": user_id, "session_id": session_id, "agent_id": agent_id, "created_at": datetime.now(timezone.utc).isoformat(), "input": serialized, "state": "queued", } if client_external_tools: item["client_external_tools"] = [ tool.model_dump(mode="json") for tool in client_external_tools ] if client_builtin_tools: item["client_builtin_tools"] = client_builtin_tools async with _chat_input_user_quota(bus, user_id): if ( await _count_user_chat_inputs(bus, user_id) >= MessageBusKeys.CHAT_INPUT_USER_MAX_LEN ): raise ChatQueueFullError( "Your pending message quota is full; wait for a message " "to finish or remove one before sending another.", ) async with chat_input_mutation(bus, session_id): existing = await bus.queue_read( MessageBusKeys.chat_inputs(session_id), max_count=MessageBusKeys.CHAT_INPUT_MAX_LEN, ) if len(existing) >= MessageBusKeys.CHAT_INPUT_MAX_LEN: raise ChatQueueFullError( "The pending message queue is full; wait for a message " "to start or remove one before sending another.", ) # Register before pushing. If the process dies between these two # operations recovery sees a harmless stale marker and removes it; # the inverse order could leave an unindexed queue permanently # stranded after a lost trigger. await bus.registry_set( MessageBusKeys.chat_input_pending_registry(), session_id, json.dumps( { "user_id": user_id, "agent_id": agent_id, }, ), ) await bus.registry_set( MessageBusKeys.chat_input_user_sessions(user_id), session_id, agent_id, ) item["input_ref"] = item["id"] await bus.registry_set( MessageBusKeys.chat_input_payloads(session_id), - src/agentscope/app/_chat_input_store.py (3071 bytes)
# -*- coding: utf-8 -*- """Session-local payload storage and lightweight queue indexes.""" import json from typing import TYPE_CHECKING from .._logging import logger from .message_bus import MessageBusKeys if TYPE_CHECKING: from .message_bus import MessageBus def queue_entry(payload: dict) -> dict: """Remove hydrated input from a reference-backed queue entry.""" if "input_ref" not in payload: return payload return {key: value for key, value in payload.items() if key != "input"} async def hydrate_input(bus: "MessageBus", payload: dict) -> dict | None: """Load one input reference; tolerate a concurrently deleted item.""" if "input" in payload: return payload if "input_ref" not in payload: return None raw = await bus.registry_get( MessageBusKeys.chat_input_payloads(payload["session_id"]), payload["input_ref"], ) if raw is None: return None return decode_input(payload, raw) def decode_input(payload: dict, raw: str | None) -> dict | None: """Decode a referenced input, omitting missing or corrupt payloads.""" if raw is None: return None try: return {**payload, "input": json.loads(raw)} except (TypeError, ValueError): logger.warning("Invalid queued input payload %s.", payload.get("id")) return None async def discard_input(bus: "MessageBus", payload: dict) -> None: """Best-effort cleanup after the queue mutation has committed.""" if "input_ref" not in payload: return try: await bus.registry_del( MessageBusKeys.chat_input_payloads(payload["session_id"]), payload["input_ref"], ) except Exception: logger.exception("Could not discard queued input %s.", payload["id"]) async def cleanup_session(bus: "MessageBus", session_id: str) -> None: """Remove empty queue indexes and payloads under the mutation lock.""" if await bus.queue_read( MessageBusKeys.chat_inputs(session_id), max_count=1, ): return if await bus.registry_exists( MessageBusKeys.chat_input_inflight_registry(), session_id, ): return raw = await bus.registry_get( MessageBusKeys.chat_input_pending_registry(), session_id, ) if raw is not None: try: user_id = json.loads(raw)["user_id"] if not isinstance(user_id, str) or not user_id: raise ValueError("Invalid pending-input owner.") except (KeyError, TypeError, ValueError): logger.warning("Invalid pending-input owner for %s.", session_id) else: await bus.registry_del( MessageBusKeys.chat_input_user_sessions(user_id), session_id, ) await bus.registry_drop(MessageBusKeys.chat_input_payloads(session_id)) await bus.registry_drop(MessageBusKeys.chat_input_claim(session_id)) await bus.registry_del( MessageBusKeys.chat_input_pending_registry(), session_id, ) - src/agentscope/app/_client_external_tool.py (9253 bytes)
# -*- coding: utf-8 -*- """Client-provided external tool definitions and runtime adapters.""" import json from collections.abc import Iterator from typing import Any, Literal from jsonschema import Draft202012Validator from jsonschema.exceptions import SchemaError from pydantic import ( BaseModel, ConfigDict, Field, TypeAdapter, field_validator, ) from referencing import Registry from referencing.exceptions import Unresolvable from referencing.jsonschema import DRAFT202012 from .._logging import logger from ..permission import ( PermissionBehavior, PermissionContext, PermissionDecision, ) from ..tool import ToolBase _MAX_INPUT_SCHEMA_BYTES = 64 * 1024 ClientBuiltinToolName = Literal["AskUser"] CLIENT_EXTERNAL_TOOL_NAME_PREFIX = "client__" _REFERENCE_KEYWORDS = {"$ref", "$dynamicRef", "$recursiveRef"} _SUPPORTED_SCHEMA_URIS = { "https://json-schema.org/draft/2020-12/schema", "https://json-schema.org/draft/2020-12/schema#", } _SINGLE_SCHEMA_KEYWORDS = { "additionalProperties", "unevaluatedProperties", "propertyNames", "items", "contains", "unevaluatedItems", "not", "if", "then", "else", "contentSchema", } _SCHEMA_MAP_KEYWORDS = { "$defs", "definitions", "properties", "patternProperties", "dependentSchemas", "dependencies", } _SCHEMA_ARRAY_KEYWORDS = {"allOf", "anyOf", "oneOf", "prefixItems"} def _iter_schema_nodes(value: dict[str, Any]) -> Iterator[dict[str, Any]]: """Walk subschemas and local pointer targets, excluding literal data.""" resource = DRAFT202012.create_resource(value) # The default registry cannot retrieve resources from the network. pending = [(value, Registry().resolver_with_root(resource))] seen: set[tuple[int, int]] = set() while pending: node, resolver = pending.pop() if not isinstance(node, dict): continue try: scope = resolver.lookup("#").contents except (Unresolvable, ValueError): scope = None identity = (id(node), id(scope)) if identity in seen: continue seen.add(identity) yield node for keyword, child in node.items(): children = [] if keyword in _SINGLE_SCHEMA_KEYWORDS: children = [child] elif keyword in _SCHEMA_MAP_KEYWORDS and isinstance(child, dict): children = list(child.values()) elif keyword in _SCHEMA_ARRAY_KEYWORDS and isinstance(child, list): children = child elif ( keyword in _REFERENCE_KEYWORDS and isinstance(child, str) and child.startswith("#") ): try: resolved = resolver.lookup(child) except (Unresolvable, ValueError, TypeError): # Broken references remain tool errors at execution. continue pending.append((resolved.contents, resolved.resolver)) for item in children: if isinstance(item, dict): pending.append( ( item, resolver.in_subresource( DRAFT202012.create_resource(item), ), ), ) def _validate_schema_metadata(value: dict[str, Any]) -> None: """Reject unsupported dialects and references to remote schemas.""" for node in _iter_schema_nodes(value): for key, child in node.items(): if ( key == "$schema" and isinstance(child, str) and child not in _SUPPORTED_SCHEMA_URIS ): raise ValueError( "Client tool schemas only support JSON Schema " "Draft 2020-12.", ) if ( key in _REFERENCE_KEYWORDS and isinstance(child, str) and not child.startswith("#") ): raise ValueError( f"Client tool schemas only support local {key} values.", ) class ClientExternalToolDefinition(BaseModel): """A tool that the active client can execute for one chat run.""" model_config = ConfigDict(extra="forbid") name: str = Field( min_length=1, max_length=64, pattern=r"^client__[a-zA-Z0-9_-]+$", description=( "The namespaced tool name exposed to the model. It must start " f"with '{CLIENT_EXTERNAL_TOOL_NAME_PREFIX}'." ), ) description: str = Field( min_length=1, max_length=2000, description="The model-facing tool description.", ) read_only: bool = Field( default=False, description=( "Whether executing the tool can only read client-side state." ), ) input_schema: dict[str, Any] = Field( description="The tool input schema in JSON Schema format.", ) @field_validator("input_schema") @classmethod def validate_input_schema( cls, value: dict[str, Any], ) -> dict[str, Any]: """Validate schema syntax and the object shape tools require.""" try: schema_size = len( json.dumps( value, ensure_ascii=False, separators=(",", ":"), ).encode("utf-8"), ) if schema_size > _MAX_INPUT_SCHEMA_BYTES: raise ValueError( f"Tool input_schema exceeds {_MAX_INPUT_SCHEMA_BYTES} " "bytes.", ) Draft202012Validator.check_schema(value) _validate_schema_metadata(value) except SchemaError as error: raise ValueError( f"Invalid JSON Schema: {error.message}", ) from error except RecursionError as error: raise ValueError( "Tool input_schema is nested too deeply.", ) from error if value.get("type") != "object" or not isinstance( value.get("properties"), dict, ): raise ValueError( "Tool input_schema must define an object with properties.", ) return value _CLIENT_EXTERNAL_TOOLS_ADAPTER: TypeAdapter = TypeAdapter( list[ClientExternalToolDefinition], ) _CLIENT_BUILTIN_TOOLS_ADAPTER: TypeAdapter = TypeAdapter( list[ClientBuiltinToolName], ) def parse_client_tool_capabilities( raw_external_tools: object, raw_builtin_tools: object, ) -> tuple[list[ClientExternalToolDefinition], list[ClientBuiltinToolName]]: """Decode optional queued capabilities without discarding valid input.""" try: external_tools = ( _CLIENT_EXTERNAL_TOOLS_ADAPTER.validate_python(raw_external_tools) if raw_external_tools is not None else [] ) except (ValueError, RecursionError): logger.exception("Ignoring invalid queued client external tools.") external_tools = [] try: builtin_tools = ( _CLIENT_BUILTIN_TOOLS_ADAPTER.validate_python(raw_builtin_tools) if raw_builtin_tools is not None else [] ) except (ValueError, RecursionError): logger.exception("Ignoring invalid queued client builtin tools.") builtin_tools = [] return external_tools, builtin_tools class ClientExternalTool(ToolBase): """Runtime proxy for a tool executed by the active chat client.""" is_concurrency_safe: bool = False is_read_only: bool = False is_external_tool: bool = True is_state_injected: bool = False is_mcp: bool = False mcp_name: str | None = None def __init__(self, definition: ClientExternalToolDefinition) -> None: """Initialize the proxy from a validated client definition.""" super().__init__() self.name = definition.name self.description = definition.description self.is_read_only = definition.read_only self.input_schema = definition.input_schema async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """Allow client reads and ask before other client-side effects.""" del tool_input, context if self.is_read_only: return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"Client external tool '{self.name}' is read-only.", decision_reason=( f"The active client declared '{self.name}' read-only." ), ) return PermissionDecision( behavior=PermissionBehavior.ASK, message=( f"Client external tool '{self.name}' may change " "client-side state." ), decision_reason=( f"The active client did not declare '{self.name}' read-only." ), ) - src/agentscope/app/_lifespan.py (13343 bytes)
# -*- coding: utf-8 -*- """The lifespan of the agent service.""" import asyncio import socket import uuid from contextlib import AsyncExitStack, asynccontextmanager from typing import TYPE_CHECKING, Any, AsyncIterator from ._manager import ( BackgroundTaskManager, CancelDispatcher, ChatRunRegistry, SchedulerManager, WakeupDispatcher, ) from ._service import ( ChannelService, CredentialBindingService, ChatService, IndexSweeper, IndexTaskConsumer, IndexWorker, KnowledgeBaseService, RealtimeService, ResourceAccessService, SessionService, SOPService, WorkspaceService, ) if TYPE_CHECKING: from fastapi import FastAPI else: FastAPI = Any @asynccontextmanager async def lifespan(app: FastAPI) -> AsyncIterator[None]: """Manage startup and shutdown of all application-wide resources. Every resource with a lifecycle is an async context manager and is entered through a single :class:`AsyncExitStack`. The stack tears them down in reverse order on shutdown — including when an entry later in the sequence raises during startup, so no resource leaks on partial failure. Service-layer ``ChatService`` and ``SessionService`` have no lifecycle of their own and are constructed inline. """ storage = app.state.storage message_bus = app.state.message_bus workspace_manager = app.state.workspace_manager knowledge_base_manager = app.state.knowledge_base_manager blob_store = app.state.blob_store enable_index_worker = app.state.enable_index_worker enable_channel_worker = app.state.enable_channel_worker enable_scheduler = app.state.enable_scheduler resource_access_policy = app.state.resource_access_policy async with AsyncExitStack() as stack: await stack.enter_async_context(storage) await stack.enter_async_context(message_bus) await stack.enter_async_context(workspace_manager) if knowledge_base_manager is not None: # ``KnowledgeBaseManagerBase.__aenter__`` enters the bound # vector store too, so a single context covers both. await stack.enter_async_context(knowledge_base_manager) if blob_store is not None: await stack.enter_async_context(blob_store) # Hubs live as long as the process so each can hold one client # to its registry, instead of re-handshaking per catalog page. for hub in ( *app.state.mcp_hubs.values(), *app.state.skill_hubs.values(), ): await stack.enter_async_context(hub) bg_manager = await stack.enter_async_context( BackgroundTaskManager(message_bus=message_bus), ) app.state.background_task_manager = bg_manager # Per-process registry of in-flight chat-run asyncio tasks. # Entered before the wake-up + cancel dispatchers so they can # share the same registry; exited last so its shutdown can # cancel any leftover runs after the dispatchers stop. chat_run_registry = await stack.enter_async_context(ChatRunRegistry()) app.state.chat_run_registry = chat_run_registry # Scheduler is independent of ChatService now (its fire path # pushes to inbox + enqueues wakeup via the bus), so we build it # before ChatService and inject it via the constructor. scheduler = await stack.enter_async_context( SchedulerManager( storage=storage, message_bus=message_bus, workspace_manager=workspace_manager, enabled=enable_scheduler, ), ) app.state.scheduler_manager = scheduler # Resource access service — combines owner-scoped storage reads # with the injected policy so both routers and runtime services # go through a single choke point when resolving credentials / # agents / knowledge bases. resource_access_service = ResourceAccessService( storage=storage, policy=resource_access_policy, ) app.state.resource_access_service = resource_access_service # Channel wiring is built here (before ChatService) so the chat # service can hand the client factory to get_toolkit: a session # that came from a channel gets that channel's platform tools. # The clients hold no connection, so they exist in every process # regardless of who runs the dispatcher. from .channel import ( ChannelClients, ChannelGateway, ChannelLifecycleDispatcher, ) # Only wire the channel subsystem when channel types are # registered — otherwise the dispatcher's reconcile would hit # storage backends that don't implement channel methods. channel_type_registry = app.state.channel_type_registry channel_clients = None channel_dispatcher = None if channel_type_registry: channel_clients = await stack.enter_async_context( ChannelClients( storage=storage, message_bus=message_bus, type_registry=channel_type_registry, ), ) app.state.channel_service = ChannelService( storage=storage, message_bus=message_bus, type_registry=channel_type_registry, ) # Binding sessions live in the bus and hold no connection, # so this is available wherever the channel API is. app.state.credential_binding_service = CredentialBindingService( message_bus=message_bus, type_registry=channel_type_registry, ) # The dispatcher is what holds the long connections, so a # deployment that runs dedicated channel workers turns it # off here and every replica stays connection-free. if enable_channel_worker: channel_dispatcher = ChannelLifecycleDispatcher( storage=storage, message_bus=message_bus, type_registry=channel_type_registry, gateway=ChannelGateway( storage=storage, message_bus=message_bus, workspace_manager=workspace_manager, ), ) app.state.channel_clients = channel_clients app.state.channel_dispatcher = channel_dispatcher chat_service = ChatService( storage=storage, workspace_manager=workspace_manager, scheduler_manager=scheduler, background_task_manager=bg_manager, message_bus=message_bus, resource_access_service=resource_access_service, knowledge_base_manager=knowledge_base_manager, extra_agent_middlewares=app.state.extra_agent_middlewares, extra_agent_tools=app.state.extra_agent_tools, custom_subagent_templates=app.state.custom_subagent_templates, custom_agent_cls=app.state.custom_agent_cls, tool_offload_timeout_secs=app.state.tool_offload_timeout_secs, channel_clients=channel_clients, ) app.state.chat_service = chat_service app.state.realtime_service = RealtimeService( storage=storage, workspace_manager=workspace_manager, scheduler_manager=scheduler, background_task_manager=bg_manager, message_bus=message_bus, resource_access_service=resource_access_service, knowledge_base_manager=knowledge_base_manager, extra_agent_middlewares=app.state.extra_agent_middlewares, extra_agent_tools=app.state.extra_agent_tools, custom_subagent_templates=app.state.custom_subagent_templates, custom_agent_cls=app.state.custom_agent_cls, channel_clients=channel_clients, ) app.state.session_service = SessionService( storage=storage, message_bus=message_bus, workspace_manager=workspace_manager, ) # On the stack so its detached advances stop before storage closes. sop_service = await stack.enter_async_context( SOPService( storage=storage, workspace_manager=workspace_manager, message_bus=message_bus, chat=chat_service, session_service=app.state.session_service, ), ) app.state.sop_service = sop_service # So a turn resuming a step carries its run on. chat_service.sop_service = sop_service app.state.workspace_service = WorkspaceService( storage=storage, workspace_manager=workspace_manager, download_secret=app.state.download_secret, ) # ---------------- Knowledge-base wiring ---------------- knowledge_base_service = None if knowledge_base_manager is not None: # Indexing is uniformly driven by the message bus: the # service publishes an index-task entry, and a consumer # (in-process or in a dedicated worker process) drains it. # # * Embedded — ``enable_index_worker=True``: this lifespan # additionally starts an :class:`IndexWorker` plus an # :class:`IndexTaskConsumer` that subscribes to the same # channel. The ``InMemoryMessageBus`` makes the round # trip near-free; everything runs in one binary. # # * Dedicated — ``enable_index_worker=False``: this # lifespan does NOT start a worker. One or more separate # processes (``python -m agentscope.app.rag.index_worker``) # run their own consumer + worker pair subscribed to the # same channel. # # The sweeper STILL runs in the API process either way, # because the API is the only resource guaranteed to be # live whenever uploads happen — if the publish ever races # a worker restart the durable queue catches the task, and # if the queue write itself failed the sweeper eventually # re-enqueues from storage. if enable_index_worker: node_id = f"{socket.gethostname()}:{uuid.uuid4().hex[:8]}" worker = IndexWorker( storage=storage, blob_store=blob_store, knowledge_base_manager=knowledge_base_manager, parsers=app.state.knowledge_parsers, chunkers=app.state.knowledge_chunkers, node_id=node_id, ) await stack.enter_async_context( IndexTaskConsumer( message_bus=message_bus, worker=worker, ), ) sweeper = IndexSweeper( storage=storage, message_bus=message_bus, ) await sweeper.start() stack.push_async_callback(sweeper.stop) knowledge_base_service = KnowledgeBaseService( storage=storage, knowledge_base_manager=knowledge_base_manager, blob_store=blob_store, message_bus=message_bus, resource_access_service=resource_access_service, chunkers=app.state.knowledge_chunkers, ) app.state.knowledge_base_service = knowledge_base_service # Dispatchers need live references somewhere, or they would be # garbage-collected; the AsyncExitStack holds those references # for us, so we don't need local bindings or app.state slots. await stack.enter_async_context( WakeupDispatcher( message_bus=message_bus, storage=storage, chat_service=chat_service, chat_run_registry=chat_run_registry, ), ) await stack.enter_async_context( CancelDispatcher( message_bus=message_bus, registry=chat_run_registry, bg_manager=bg_manager, realtime_connections=app.state.realtime_connections, ), ) # Start the channel reconcile/heartbeat/outbound loops (the # dispatcher itself was built above, before ChatService) — only # when the channel subsystem is enabled. if channel_dispatcher is not None: await stack.enter_async_context(channel_dispatcher.lifespan()) async def _close_realtime_connections() -> None: connections = list(app.state.realtime_connections.values()) app.state.realtime_connections.clear() if connections: await asyncio.gather( *(connection.close() for connection in connections), return_exceptions=True, ) stack.push_async_callback(_close_realtime_connections) yield - src/agentscope/app/_manager/__init__.py (538 bytes)
# -*- coding: utf-8 -*- """The agent service managers, used in FastAPI lifespan to manage application-wide resources.""" from ._scheduler import SchedulerManager from ._wakeup_dispatcher import WakeupDispatcher from ._cancel_dispatcher import CancelDispatcher from ._chat_run_registry import ChatRunRegistry from ._background_task_manager import BackgroundTaskManager, TaskStatus __all__ = [ "BackgroundTaskManager", "CancelDispatcher", "ChatRunRegistry", "SchedulerManager", "TaskStatus", "WakeupDispatcher", ] - src/agentscope/app/_manager/_background_task_manager.py (29936 bytes)
# -*- coding: utf-8 -*- """The background task manager.""" import asyncio import json import time from collections import OrderedDict from dataclasses import dataclass, field from enum import Enum from typing import Any, Self, TYPE_CHECKING import shortuuid from pydantic import BaseModel, ConfigDict, Field from ...message import TextBlock, ToolResultState from ...permission import ( PermissionContext, PermissionDecision, PermissionBehavior, ) from ...tool import ToolBase, ToolChunk, ToolResponse from ..._logging import logger from ..message_bus import MessageBusKeys if TYPE_CHECKING: from ..message_bus import MessageBus class TaskStatus(str, Enum): """Status of a background task throughout its lifecycle.""" RUNNING = "running" COMPLETED = "completed" FAILED = "failed" CANCELLED = "cancelled" _MAX_RETAINED_TASKS = 50 # Maximum number of terminal-state tasks retained per user. _RECORD_LEASE_SECS = 120 _RENEWAL_CONCURRENCY = 16 _IO_TIMEOUT_SECS = 2.0 _RETRY_DELAY_SECS = 1.0 _SHUTDOWN_TIMEOUT_SECS = 5.0 @dataclass class BackgroundTask: """Metadata for a single background task. Attributes: asyncio_task (`asyncio.Task`): The running asyncio task. session_id (`str`): The session id of the originating request. agent_id (`str`): The name of the agent that created the task. user_id (`str`): The user id of the originating request. tool_name (`str`): The name of the tool that was offloaded. id (`str`): Auto-generated unique task identifier. summary (`str`): A short human-readable summary of the tool invocation for frontend display (at most 128 characters). started_at (`float`): Unix epoch (UTC) when the task was registered. completed_at (`float | None`): Unix epoch (UTC) when the task reached a terminal state, or ``None`` while still running. status (`TaskStatus`): Current lifecycle status of the task. error_summary (`str | None`): Brief description of the failure reason when ``status == FAILED``. execution_started_at (`float | None`): Unix epoch (UTC) when tool execution began, before offload. ``None`` when the original start time was not recorded. """ asyncio_task: asyncio.Task """The running asyncio task.""" session_id: str """The session id of the background task.""" agent_id: str """The agent that created the background task.""" user_id: str """The user id of the originating request.""" tool_name: str """The name of the offloaded tool.""" id: str = field(default_factory=shortuuid.uuid) """The background task id.""" summary: str = "" """Short human-readable summary for frontend display.""" started_at: float = field(default_factory=time.time) """Unix epoch (UTC) when the task was registered.""" completed_at: float | None = None """Unix epoch (UTC) when the task finished, or None if running.""" status: TaskStatus = TaskStatus.RUNNING """Current lifecycle status.""" error_summary: str | None = None """Brief failure description (populated only for FAILED tasks).""" execution_started_at: float | None = None """Unix epoch (UTC) when tool execution began, if known.""" class BackgroundTaskRecord(BaseModel): """Serializable task snapshot, independent of the local task handle.""" model_config = ConfigDict(from_attributes=True) id: str session_id: str agent_id: str user_id: str tool_name: str summary: str started_at: float completed_at: float | None status: TaskStatus error_summary: str | None execution_started_at: float | None = None class _ToolStopParams(BaseModel): """The params of the stop tool.""" task_id: str = Field( description="The task id of the background tool to stop.", ) class ToolStop(ToolBase): """A tool to stop a running background tool execution.""" name: str = "ToolStop" """The tool name.""" description: str = ( "Stop a background tool execution by its task id. " "Use this when you want to cancel a previously offloaded tool " "that is still running in the background." ) """The tool description.""" input_schema: dict = _ToolStopParams.model_json_schema() """The input schema.""" is_concurrency_safe: bool = True is_read_only: bool = False is_state_injected: bool = False is_external_tool: bool = False is_mcp: bool = False mcp_name: str | None = None def __init__( self, background_tasks: dict[str, BackgroundTask], message_bus: "MessageBus", session_id: str, ) -> None: """Initialize the ToolStop tool. Args: background_tasks (`dict[str, BackgroundTask]`): A reference to the local background tasks managed by the :class:`BackgroundTaskManager`. message_bus (`MessageBus`): The application message bus, used to check the global registry and broadcast cross-worker cancel requests. session_id (`str`): The current session id, used to scope Redis registry lookups. """ self.background_tasks = background_tasks self._message_bus = message_bus self._session_id = session_id async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """Check permission for the tool usage. Args: tool_input (`dict[str, Any]`): The tool input parameters. context (`PermissionContext`): The permission context. Returns: `PermissionDecision`: Always returns ALLOW. """ return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{self.name} is always allowed to be called.", ) async def __call__(self, task_id: str) -> ToolChunk: """Stop the background task. Args: task_id (`str`): The task id. Returns: `ToolChunk`: The tool chunk. """ # Path 1: task is on this worker — cancel directly. # Only cancel when the task belongs to the same session as this # ToolStop instance, so a leaked/guessed task_id from another # session cannot trigger cross-session cancellation on a shared # worker. local_task = self.background_tasks.get(task_id) if ( local_task is not None and local_task.session_id == self._session_id and not local_task.asyncio_task.done() ): local_task.asyncio_task.cancel() logger.info( "Background task stopped via ToolStop (local): task_id=%s, " "session_id=%s, agent_id=%s", task_id, local_task.session_id, local_task.agent_id, ) return ToolChunk( content=[ TextBlock(text=f"Task {task_id} stopped successfully."), ], state=ToolResultState.SUCCESS, ) # Path 2: task exists in the global registry (another worker, or # a different session on this worker). if await self._message_bus.registry_exists( MessageBusKeys.bg_tasks(self._session_id), task_id, ): await self._message_bus.publish( MessageBusKeys.task_cancel_channel(), {"task_id": task_id}, ) logger.info( "Background task cancel broadcast via ToolStop (remote): " "task_id=%s, session_id=%s", task_id, self._session_id, ) return ToolChunk( content=[ TextBlock( text=f"Cancel request sent for task {task_id}. " f"The owning worker will stop it shortly.", ), ], state=ToolResultState.SUCCESS, ) # Path 3: task not found anywhere. return ToolChunk( content=[ TextBlock( text=f"TaskNotFoundError: The task {task_id} " f"does not exist.", ), ], state=ToolResultState.ERROR, ) class BackgroundTaskManager: """Tracks background asyncio task lifecycle within the agent service. Responsibilities: - **Global registry**: register/unregister tasks in Redis so any process can query which tasks are alive for a session. - **Local handle cache**: hold ``asyncio.Task`` references for cancel and shutdown. - **Task scheduling**: convenience method for creating a task from a plain coroutine with a done callback that cleans up both sides. Completion results are delivered via the :class:`MessageBus` inbox + wakeup path (same as team messages), so any process's :class:`WakeupDispatcher` can pick up the result. """ def __init__(self, message_bus: "MessageBus") -> None: """Initialise the background task manager. Args: message_bus (`MessageBus`): The application message bus; used for the global BG task registry (Redis Hash) and task-level cancel broadcasts. """ self._message_bus = message_bus self.tasks: OrderedDict[str, BackgroundTask] = OrderedDict() self._completion_tasks: set[asyncio.Task] = set() self._renewal_task: asyncio.Task | None = None self._closed = False # ------------------------------------------------------------------ # Task registration # ------------------------------------------------------------------ async def register_task( self, asyncio_task: asyncio.Task, session_id: str, agent_id: str, user_id: str, tool_name: str = "", *, summary: str = "", execution_started_at: float | None = None, ) -> str: """Register an already-running asyncio task. Tracks running handles locally and publishes metadata globally. On completion, releases the handle and retains terminal metadata for polling from any worker. Args: asyncio_task (`asyncio.Task`): The already-running task to register. session_id (`str`): The originating session id. agent_id (`str`): The agent record id that owns the task. user_id (`str`): The user id of the originating request. tool_name (`str`, optional): The name of the offloaded tool. summary (`str`, optional): Short human-readable summary of the tool invocation for frontend display. execution_started_at (`float | None`, optional): Unix epoch (UTC) when execution began, before offload. Omit when the original start time is unknown. Returns: `str`: The generated task id. """ bg_task = BackgroundTask( asyncio_task=asyncio_task, session_id=session_id, agent_id=agent_id, user_id=user_id, tool_name=tool_name, summary=summary, execution_started_at=execution_started_at, ) task_id = bg_task.id self.tasks[task_id] = bg_task # Install cleanup even if a registry write fails or is cancelled. # The callback is attached after writes settle, so a fast task cannot # publish a terminal state before its initial running state. try: async with asyncio.timeout(_IO_TIMEOUT_SECS): await self._message_bus.registry_set( MessageBusKeys.bg_tasks(session_id), task_id, json.dumps( { "tool_name": tool_name, "agent_id": agent_id, "started_at": bg_task.started_at, }, ensure_ascii=False, ), ttl_secs=MessageBusKeys.BG_TASKS_TTL_SECS, ) await self._store_record( BackgroundTaskRecord.model_validate(bg_task), ) # A round timeout can temporarily mark the scheduler cancelling. if self._renewal_task is None or self._renewal_task.done(): self._renewal_task = asyncio.create_task( self._renew_running_records(), ) except BaseException: asyncio_task.cancel() raise finally: asyncio_task.add_done_callback( lambda task: self._on_done(bg_task, task), ) logger.info( "Background task registered: task_id=%s, session_id=%s, " "agent_id=%s, tool_name=%s", task_id, session_id, agent_id, tool_name, ) return task_id def _on_done( self, bg_task: BackgroundTask, task: asyncio.Task, ) -> None: """Record the actual outcome and schedule shared-state cleanup.""" bg_task.completed_at = time.time() if task.cancelled(): bg_task.status = TaskStatus.CANCELLED elif task.exception() is not None: bg_task.status = TaskStatus.FAILED bg_task.error_summary = str(task.exception())[:512] else: result = task.result() bg_task.status = TaskStatus.COMPLETED if isinstance(result, ToolResponse): if result.state == ToolResultState.ERROR: bg_task.status = TaskStatus.FAILED bg_task.error_summary = "\n".join( block.text for block in result.content if isinstance(block, TextBlock) )[:512] elif result.state == ToolResultState.INTERRUPTED: bg_task.status = TaskStatus.CANCELLED self.tasks.pop(bg_task.id, None) # Let renewal exit when idle so new registrations can reuse it safely. if self._closed: return completion = asyncio.create_task( self._finis - src/agentscope/app/_manager/_cancel_dispatcher.py (11718 bytes)
# -*- coding: utf-8 -*- """Single per-process dispatcher for cross-process cancels. Subscribes to two bus channels: 1. **Session cancel** — cancel all local work for a session (chat run, realtime run, and all BG tasks). Triggered by session deletion or explicit abort. 2. **Task cancel** — cancel a single BG task by task_id. Triggered by the :class:`ToolStop` agent tool when the target task lives on a different worker. Processes whose registry / BG-manager do not hold the targeted session or task simply do no work — the publisher does not need to know which worker holds what; it broadcasts and lets each holder self-select. Each subscription is retried with bounded backoff if the bus drops the pub/sub, so one disconnect does not stop cancel delivery on this process. """ import asyncio from collections.abc import Callable, Mapping from typing import TYPE_CHECKING, Self from ..._logging import logger from ..message_bus import MessageBusKeys # Same curve as the channel and schedule listeners. _SUBSCRIBE_BACKOFF_INITIAL_SECS = 1.0 _SUBSCRIBE_BACKOFF_MAX_SECS = 30.0 if TYPE_CHECKING: from ..message_bus import MessageBus from .._service._webrtc_session import WebRTCSession from ._background_task_manager import BackgroundTaskManager from ._chat_run_registry import ChatRunRegistry class CancelDispatcher: """Subscribes to bus cancel channels and cancels matching local tasks. Args: message_bus (`MessageBus`): Application message bus. registry (`ChatRunRegistry`): The per-process chat-run registry whose tasks may be cancelled. bg_manager (`BackgroundTaskManager`): The per-process background task manager. realtime_connections (`Mapping`, optional): The per-process browser realtime sessions. The shared cancel broadcast closes matching runners on whichever process owns them. """ def __init__( self, message_bus: "MessageBus", registry: "ChatRunRegistry", bg_manager: "BackgroundTaskManager", realtime_connections: Mapping[ tuple[str, str], "WebRTCSession", ] | None = None, ) -> None: """Bind dependencies. Args: message_bus (`MessageBus`): Application message bus. registry (`ChatRunRegistry`): The per-process chat-run registry. bg_manager (`BackgroundTaskManager`): The per-process background task manager. realtime_connections (`Mapping`, optional): The per-process browser realtime sessions. """ self._bus = message_bus self._registry = registry self._bg_manager = bg_manager self._realtime_connections = ( realtime_connections if realtime_connections is not None else {} ) self._session_task: asyncio.Task | None = None self._task_cancel_task: asyncio.Task | None = None self._interrupt_task: asyncio.Task | None = None async def __aenter__(self) -> Self: """Start both dispatcher loops and wait until their bus subscriptions are live. Returns: `Self`: This dispatcher instance. """ session_ready = asyncio.Event() task_ready = asyncio.Event() interrupt_ready = asyncio.Event() self._session_task = asyncio.create_task( self._session_cancel_loop(session_ready), name="cancel-dispatcher:session", ) self._task_cancel_task = asyncio.create_task( self._task_cancel_loop(task_ready), name="cancel-dispatcher:task", ) self._interrupt_task = asyncio.create_task( self._interrupt_loop(interrupt_ready), name="cancel-dispatcher:interrupt", ) await session_ready.wait() await task_ready.wait() await interrupt_ready.wait() return self async def __aexit__(self, *exc: object) -> None: """Cancel all dispatcher loops on context exit.""" for task in ( self._session_task, self._task_cancel_task, self._interrupt_task, ): if task is None: continue task.cancel() try: await task except asyncio.CancelledError: pass self._session_task = None self._task_cancel_task = None self._interrupt_task = None # ------------------------------------------------------------------ # Session-level cancel loop # ------------------------------------------------------------------ async def _session_cancel_loop(self, ready: asyncio.Event) -> None: """Subscribe to session cancel channel and act on each signal. Args: ready (`asyncio.Event`): Signalled after the underlying SUBSCRIBE completes. """ def _on_payload(payload: dict) -> None: sid = payload.get("session_id") if isinstance(sid, str): self._cancel_session(sid) await self._consume_subscription( MessageBusKeys.session_cancel_channel(), ready, _on_payload, name="session-cancel", ) def _cancel_session(self, session_id: str) -> None: """Cancel every locally-tracked task for a session. Args: session_id (`str`): The session whose runs and BG tasks should be cancelled. """ task = self._registry.get(session_id) if task is not None and not task.done(): logger.info( "CancelDispatcher: cancelling local chat run for " "session %s", session_id, ) task.cancel() bg_cancelled = self._bg_manager.cancel_session_tasks(session_id) if bg_cancelled: logger.info( "CancelDispatcher: cancelled %d local BG task(s) for " "session %s", bg_cancelled, session_id, ) realtime_cancelled = 0 for (_, candidate_session_id), runner in list( self._realtime_connections.items(), ): if candidate_session_id == session_id: runner.request_close() realtime_cancelled += 1 if realtime_cancelled: logger.info( "CancelDispatcher: closing %d local realtime run(s) for " "session %s", realtime_cancelled, session_id, ) # ------------------------------------------------------------------ # Task-level cancel loop # ------------------------------------------------------------------ async def _task_cancel_loop(self, ready: asyncio.Event) -> None: """Subscribe to the task cancel channel and act on each signal. Args: ready (`asyncio.Event`): Signalled after the underlying SUBSCRIBE completes. """ def _on_payload(payload: dict) -> None: task_id = payload.get("task_id") if not isinstance(task_id, str): return cancelled = self._bg_manager.cancel_task(task_id) if cancelled: logger.info( "CancelDispatcher: cancelled local BG task %s " "via task-level broadcast.", task_id, ) await self._consume_subscription( MessageBusKeys.task_cancel_channel(), ready, _on_payload, name="task-cancel", ) # ------------------------------------------------------------------ # Session-level interrupt loop # ------------------------------------------------------------------ async def _interrupt_loop(self, ready: asyncio.Event) -> None: """Subscribe to the session interrupt channel and cancel matching local tasks. Args: ready (`asyncio.Event`): Signalled after the underlying SUBSCRIBE completes. """ def _on_payload(payload: dict) -> None: sid = payload.get("session_id") if isinstance(sid, str): self._interrupt_session(sid) await self._consume_subscription( MessageBusKeys.session_interrupt_channel(), ready, _on_payload, name="interrupt", ) async def _consume_subscription( self, channel: str, ready: asyncio.Event, on_payload: Callable[[dict], None], *, name: str, ) -> None: """Subscribe until cancelled, reconnecting when the pub/sub drops. A generator that returns or raises is logged and retried with bounded exponential backoff. ``asyncio.CancelledError`` exits without sleeping so :meth:`__aexit__` stays prompt. ``ready`` is set from ``on_ready`` and again in ``finally``, including when the first subscribe fails before ``on_ready``. Args: channel (`str`): Bus channel name. ready (`asyncio.Event`): Signalled after the underlying SUBSCRIBE completes. on_payload (`Callable[[dict], None]`): Invoked for each delivered payload. name (`str`): Short loop name used in log lines. """ backoff = _SUBSCRIBE_BACKOFF_INITIAL_SECS while True: try: async for payload in self._bus.subscribe( channel, on_ready=ready.set, ): # A delivered payload means the subscription is # healthy, so the next drop starts again at the # initial delay. Same rule as the schedule listener. backoff = _SUBSCRIBE_BACKOFF_INITIAL_SECS on_payload(payload) except asyncio.CancelledError: # pylint: disable=try-except-raise raise except Exception: # pylint: disable=broad-except logger.exception( "CancelDispatcher %s loop crashed.", name, ) else: logger.warning( "CancelDispatcher %s subscription ended.", name, ) finally: # Unblock ``__aenter__`` even if subscribe failed before # ``on_ready`` ran, so startup cannot deadlock. ready.set() await asyncio.sleep(backoff) backoff = min(backoff * 2, _SUBSCRIBE_BACKOFF_MAX_SECS) def _interrupt_session(self, session_id: str) -> None: """Cancel the local chat-run task for a session. Unlike ``_cancel_session``, this method only cancels the chat-run asyncio task—it does **not** cancel background tasks. The agent handles ``CancelledError`` gracefully at each breakpoint, preserving partial context. Args: session_id (`str`): The session whose chat run should be interrupted. """ task = self._registry.get(session_id) if task is not None and not task.done(): logger.info( "CancelDispatcher: interrupting local chat run for " "session %s", session_id, ) task.cancel() - src/agentscope/app/_manager/_chat_input_queue.py (40186 bytes)
# -*- coding: utf-8 -*- """Durable FIFO claims, bounded retries, recovery and session wakeups.""" import asyncio import json import time import uuid from typing import Any, Coroutine, TYPE_CHECKING from pydantic import TypeAdapter from ..._logging import logger from ...event import ( CustomEvent, ExternalExecutionResultEvent, UserConfirmResultEvent, UserInterruptEvent, ) from ...message import Msg from .._client_external_tool import ( ClientBuiltinToolName, ClientExternalToolDefinition, parse_client_tool_capabilities, ) from ..message_bus import MessageBusKeys from ._chat_run_registry import CHAT_RUN_SHUTDOWN from .._bus_ops import ( ChatQueueBusyError, chat_input_mutation, enqueue_run_trigger, publish_session_event, ) from .._chat_input_store import ( cleanup_session, discard_input, hydrate_input, queue_entry, ) if TYPE_CHECKING: from ..message_bus import MessageBus from ..storage import StorageBase from .._service import ChatService _MESSAGE_INPUT_ADAPTER: TypeAdapter = TypeAdapter(Msg | list[Msg]) _MESSAGE_FALLBACK_TICK_SECS = 30.0 _MESSAGE_RECOVERY_LOCK_TTL_SECS = 60 _MESSAGE_RECOVERY_OWNER_FIELD = "owner" _MESSAGE_RECOVERY_EXPIRES_FIELD = "expires_at" _MESSAGE_CLAIMED = "claimed" _MESSAGE_INPUT_PERSISTED = "input_persisted" _MESSAGE_CANCELLED = "cancelled" _MESSAGE_FAILED = "failed" _MESSAGE_COMPLETED = "completed" class ChatInputQueue: """Own the lifecycle of queued input independently from run dispatch.""" def __init__( self, bus: "MessageBus", storage: "StorageBase", chat_service: "ChatService", ) -> None: self._bus = bus self._storage = storage self._chat_service = chat_service self._recovery_task: asyncio.Task | None = None self._recovery_owner = uuid.uuid4().hex self._retry_tasks: set[asyncio.Task] = set() self._closed = False async def close(self, *, release_leadership: bool = True) -> None: """Cancel retained timers and optionally release recovery leadership. Args: release_leadership (`bool`): Whether to contact the bus to release the recovery lease. Failed startup skips this and lets any lease expire. """ self._closed = True tasks = list(self._retry_tasks) for task in tasks: task.cancel() await asyncio.gather(*tasks, return_exceptions=True) self._retry_tasks.clear() self._recovery_task = None if release_leadership: await self._release_recovery_leadership() def schedule_recovery(self) -> None: """Retain at most one non-blocking recovery sweep per process.""" if self._recovery_task is not None and not self._recovery_task.done(): return task = asyncio.create_task( self._recover_pending_chat_inputs(), name="wakeup-dispatcher:recovery", ) self._recovery_task = task self._retry_tasks.add(task) def _done(completed: asyncio.Task) -> None: self._retry_tasks.discard(completed) if self._recovery_task is completed: self._recovery_task = None task.add_done_callback(_done) async def _recover_pending_chat_inputs(self) -> None: """Recreate message triggers for durably indexed non-empty FIFOs. A cluster-wide renewable leader lease lets only one API process perform the O(N) sweeps. Queue probes do not take the foreground mutation lock; an empty marker is removed only after a locked recheck. """ pushed_count = 0 try: recovery_lock = MessageBusKeys.chat_input_recovery_lock() async with self._bus.acquire_lock_bounded( recovery_lock, ttl_secs=_MESSAGE_RECOVERY_LOCK_TTL_SECS, timeout_secs=0.1, ): now = time.time() recovery_state = await self._bus.registry_getall( MessageBusKeys.chat_input_recovery_state(), ) try: expires_at = float( recovery_state.get( _MESSAGE_RECOVERY_EXPIRES_FIELD, "0", ), ) except (TypeError, ValueError): expires_at = 0.0 owner = recovery_state.get(_MESSAGE_RECOVERY_OWNER_FIELD) if owner != self._recovery_owner and expires_at > now: return await self._bus.registry_set( MessageBusKeys.chat_input_recovery_state(), _MESSAGE_RECOVERY_OWNER_FIELD, self._recovery_owner, ttl_secs=_MESSAGE_RECOVERY_LOCK_TTL_SECS * 2, ) # Owner and expiry are intentionally separate writes. If the # leader dies between them, readers treat missing expiry as # zero and immediately allow another process to take over. await self._bus.registry_set( MessageBusKeys.chat_input_recovery_state(), _MESSAGE_RECOVERY_EXPIRES_FIELD, str(now + _MESSAGE_FALLBACK_TICK_SECS * 2), ttl_secs=_MESSAGE_RECOVERY_LOCK_TTL_SECS * 2, ) pushed_count = await self._recover_pending_chat_inputs_locked() except TimeoutError: return except Exception: # pylint: disable=broad-except logger.exception( "WakeupDispatcher: pending chat queue recovery failed.", ) if pushed_count: # Recovery only creates durable triggers. One batched signal # wakes the single ``_loop`` consumer; non-leaders and empty # sweeps do not generate redundant pub/sub fan-out. try: await self._bus.publish(MessageBusKeys.wakeup_signal(), {}) except Exception: # pylint: disable=broad-except logger.exception( "WakeupDispatcher: failed to signal after recovery.", ) async def _release_recovery_leadership(self) -> None: """Release this process's recovery lease during graceful shutdown.""" try: recovery_lock = MessageBusKeys.chat_input_recovery_lock() async with self._bus.acquire_lock( recovery_lock, ttl_secs=_MESSAGE_RECOVERY_LOCK_TTL_SECS, ): recovery_state = await self._bus.registry_getall( MessageBusKeys.chat_input_recovery_state(), ) if ( recovery_state.get(_MESSAGE_RECOVERY_OWNER_FIELD) != self._recovery_owner ): return await self._bus.registry_del( MessageBusKeys.chat_input_recovery_state(), _MESSAGE_RECOVERY_OWNER_FIELD, ) await self._bus.registry_del( MessageBusKeys.chat_input_recovery_state(), _MESSAGE_RECOVERY_EXPIRES_FIELD, ) except Exception: # pylint: disable=broad-except logger.exception( "WakeupDispatcher: failed to release recovery leadership.", ) async def _recover_pending_chat_inputs_locked(self) -> int: """Run one cluster-elected pending-input recovery sweep. Returns: `int`: Number of durable ``queued_message`` triggers pushed. The caller publishes one shared signal when this value is non-zero. """ pushed_count = 0 pending_sessions = await self._bus.registry_getall( MessageBusKeys.chat_input_pending_registry(), ) inflight_sessions = await self._bus.registry_getall( MessageBusKeys.chat_input_inflight_registry(), ) recovery_timeout = MessageBusKeys.CHAT_INPUT_RECOVERY_LOCK_TIMEOUT_SECS for session_id in pending_sessions.keys() | inflight_sessions.keys(): try: raw_routing = pending_sessions.get(session_id) if raw_routing is not None: routing = json.loads(raw_routing) else: routing = json.loads(inflight_sessions[session_id]) user_id = routing["user_id"] agent_id = routing["agent_id"] if not isinstance(user_id, str) or not isinstance( agent_id, str, ): raise TypeError( "Pending-chat routing ids must be strings.", ) pending = await self._bus.queue_read( MessageBusKeys.chat_inputs(session_id), max_count=1, ) claimed = session_id in inflight_sessions if not pending and not claimed: # Enqueue can register before pushing. Recheck under the # same mutation lock before collecting a stale marker. try: async with chat_input_mutation( self._bus, session_id, timeout_secs=recovery_timeout, ): pending = await self._bus.queue_read( MessageBusKeys.chat_inputs(session_id), max_count=1, ) claimed = await self._bus.registry_exists( MessageBusKeys.chat_input_inflight_registry(), session_id, ) if not pending and not claimed: await cleanup_session(self._bus, session_id) except ChatQueueBusyError: # Never hold the cluster recovery lease while waiting # behind a foreground enqueue/edit operation. continue if not pending and not claimed: continue # Reuse the canonical trigger serializer but batch the # signal. The sole ``_loop`` drainer consumes it after the # recovery method publishes once for the whole sweep. await enqueue_run_trigger( self._bus, user_id=user_id, session_id=session_id, agent_id=agent_id, kind=MessageBusKeys.WAKEUP_KIND_QUEUED_MESSAGE, signal=False, ) pushed_count += 1 except Exception: # pylint: disable=broad-except logger.exception( "WakeupDispatcher: invalid pending-chat registry entry " "for session %s.", session_id, ) return pushed_count async def _is_session_parked( self, session: object, user_id: str, agent_id: str, ) -> bool: """Use the owning agent's canonical pending-tool-call semantics.""" state = getattr(session, "state", None) if not state or not state.context: return False record = await self._chat_service.resolve_agent(user_id, agent_id) return bool( state.get_awaiting_tool_calls(record.data.name), ) async def run_resume_serialized( self, user_id: str, session_id: str, agent_id: str, input_msg: UserConfirmResultEvent | ExternalExecutionResultEvent | UserInterruptEvent | None, client_external_tools: list[ClientExternalToolDefinition] | None = None, client_builtin_tools: list[ClientBuiltinToolName] | None = None, ) -> None: """Serialize a resume with chat-input claim and parked-state checks. Args: user_id (`str`): User that owns the session. session_id (`str`): Session whose parked run should resume. agent_id (`str`): Agent that owns the session. input_msg: Typed HITL/external-result/interrupt event, or ``None`` for a compatible control continuation. client_external_tools: Client tool definitions preserved across resume retries. client_builtin_tools: Native tool names supported by the resuming client. """ dispatch_lock = self._bus.acquire_lock_bounded( MessageBusKeys.chat_input_dispatch_lock(session_id), ttl_secs=MessageBusKeys.CHAT_INPUT_DISPATCH_TTL_SECS, timeout_secs=MessageBusKeys.CHAT_INPUT_MUTATION_TIMEOUT_SECS, ) try: # pylint: disable-next=unnecessary-dunder-call await dispatch_lock.__aenter__() except TimeoutError: await enqueue_run_trigger( self._bus, user_id=user_id, session_id=session_id, agent_id=agent_id, kind=MessageBusKeys.WAKEUP_KIND_RESUME, inputs=input_msg, client_external_tools=client_external_tools, client_builtin_tools=client_builtin_tools, ) return try: await self._chat_service.run( user_id=user_id, session_id=session_id, agent_id=agent_id, input_msg=input_msg, client_external_tools=client_external_tools, client_builtin_tools=client_builtin_tools, ) finally: await dispatch_lock.__aexit__(None, None, None) async def drain_chat_inputs( self, user_id: str, session_id: str, agent_id: str, ) -> bool: """Run at most one queued ordinary input for one session. A durable per-session claim is written before destructive dequeue. The input messages are then persisted before execution begins. A crash before persistence safely retries the claim; a crash after persistence publishes a terminal failure instead of replaying agent tools with unknown side effects. The long dispatch lease still surrounds generation, but contenders use a bounded acquisition wait and leave the durable claim/queue for a later nudge rather than blocking a process task indefinitely. - src/agentscope/app/_manager/_chat_run_registry.py (4976 bytes)
# -*- coding: utf-8 -*- """Per-process registry of in-flight ``ChatService.run`` asyncio tasks. Owns the asyncio.Task handles only — it is not the public cancel entry point. The cross-process cancel path goes through the bus's :meth:`~agentscope.app.message_bus.MessageBus.session_publish_cancel` broadcast, picked up locally by :class:`~agentscope.app._manager.CancelDispatcher`, which then looks up the task here and calls ``.cancel()`` on it. A given ``session_id`` can have at most one entry. Concurrent runs for the same session are already prevented at a cluster level by :meth:`~agentscope.app.message_bus.MessageBus.session_run` (the distributed lock), so a second :meth:`spawn` for the same id is treated as a programming error. """ import asyncio from typing import Coroutine, Self from ..._logging import logger CHAT_RUN_SHUTDOWN = "agentscope:shutdown" class ChatRunRegistry: """In-process index of active chat-run asyncio tasks, keyed by session id. Used by :class:`~agentscope.app._manager.CancelDispatcher` to find and cancel the local task for a given session, and by the lifespan to cancel any leftover runs on application shutdown. """ def __init__(self) -> None: """Initialise an empty registry.""" self._tasks: dict[str, asyncio.Task] = {} def spawn( self, coro: Coroutine, *, session_id: str, name: str | None = None, ) -> asyncio.Task: """Create and register an asyncio task that runs ``coro``. The task auto-removes from the registry when it finishes (via ``add_done_callback``). Args: coro (`Coroutine`): A coroutine — typically ``chat_service.run(...)`` — to run as a background task. Closed if the spawn is rejected. session_id (`str`): The session this run belongs to. Used as the registry key for later cancel lookup. name (`str | None`, optional): Optional task name passed through to :func:`asyncio.create_task`. Defaults to ``f"chat-run:{session_id}"``. Returns: `asyncio.Task`: The created task. Callers normally do not need to keep the reference — the registry holds it for the task's lifetime. Raises: `RuntimeError`: When a non-finished task is already registered for ``session_id``. Callers are expected to coordinate via the distributed session lock before spawning. """ existing = self._tasks.get(session_id) if existing is not None and not existing.done(): coro.close() raise RuntimeError( f"Session {session_id!r} already has an active chat run " "in this process.", ) task = asyncio.create_task( coro, name=name or f"chat-run:{session_id}", ) self._tasks[session_id] = task def _cleanup(t: asyncio.Task) -> None: # Only remove the entry if it still points at this task — # a fresh spawn for the same sid may have replaced it. if self._tasks.get(session_id) is t: self._tasks.pop(session_id, None) task.add_done_callback(_cleanup) return task def get(self, session_id: str) -> asyncio.Task | None: """Return the registered task for ``session_id``, or ``None``. Args: session_id (`str`): The session whose task to look up. Returns: `asyncio.Task | None`: The task if one is currently registered for the session, else ``None``. """ return self._tasks.get(session_id) async def __aenter__(self) -> Self: """No-op enter; the registry has no startup work. Returns: `Self`: This registry instance. """ return self async def __aexit__(self, *exc: object) -> None: """Cancel every still-running task on application shutdown. Each task is cancelled and awaited so its ``finally`` blocks and any ``async with`` cleanups (notably the bus's session run-lock release) execute before the process exits. """ if not self._tasks: return logger.info( "ChatRunRegistry shutdown: cancelling %d in-flight chat run(s).", len(self._tasks), ) tasks = list(self._tasks.values()) for task in tasks: # Preserve an explicit Stop that is already being delivered. if not task.cancelling(): task.cancel(CHAT_RUN_SHUTDOWN) # Wait for every cancel to land; swallow CancelledError per task. await asyncio.gather(*tasks, return_exceptions=True) self._tasks.clear() - src/agentscope/app/_manager/_scheduler/__init__.py (153 bytes)
# -*- coding: utf-8 -*- """The scheduler related components.""" from ._scheduler_manager import SchedulerManager __all__ = [ "SchedulerManager", ] - src/agentscope/app/_manager/_scheduler/_scheduler_manager.py (25711 bytes)
# -*- coding: utf-8 -*- """The cron scheduler manager class.""" import asyncio import json from collections.abc import Callable, Coroutine from datetime import datetime from zoneinfo import ZoneInfoNotFoundError from typing import Self, TYPE_CHECKING from ....message import HintBlock from ....permission import PermissionContext from ....state import AgentState from ....tool import ToolBase from ...._logging import logger from ...._utils._common import _generate_id from ._tools import ScheduleCreate, ScheduleDelete, ScheduleList, ScheduleView from ...message_bus import MessageBus, MessageBusKeys from ...workspace_manager import WorkspaceManagerBase from ..._bus_ops import deliver_to_inbox from ...storage import ( StorageBase, ScheduleRecord, ChatModelConfig, SessionConfig, ScheduleOrigin, ) if TYPE_CHECKING: from apscheduler.triggers.base import BaseTrigger class SchedulerManager: """The cron scheduler manager, responsible for managing scheduled-task lifecycle within the agent service. The manager owns both the in-memory APScheduler instance and the trigger logic that fires scheduled tasks. Triggers do not call ``ChatService`` directly; instead they push a :class:`HintBlock` to the target session's inbox and enqueue a wakeup, so that the application-wide :class:`WakeupDispatcher` (running on any process) picks up the work. This keeps the scheduler decoupled from ``ChatService`` and makes the fire path consistent with team / background-tool result delivery. The timers themselves are held by **one** node — APScheduler's jobstore is in-memory, so every node holding them fires every cron tick, and a schedule runs once per replica. Which node owns them is a deployment choice (``create_app(enable_scheduler=...)``), so writers cannot register a job in-process: they persist the record and call :meth:`notify_changed`, and the owner reconciles its jobs against storage. Storage is the source of truth; the notification only makes the owner look sooner than its periodic reconcile would. """ RECONCILE_INTERVAL_SECS = 60 """How often the owner re-reads storage regardless of notifications, so a dropped one costs at most one interval.""" def __init__( self, storage: StorageBase, message_bus: MessageBus, workspace_manager: WorkspaceManagerBase, enabled: bool = True, ) -> None: """Initialize the scheduler manager. Args: storage (`StorageBase`): The storage backend used for persistence and session creation. message_bus (`MessageBus`): The application message bus. Each scheduled fire pushes a :class:`HintBlock` to the target session's inbox and enqueues a wakeup via this bus. workspace_manager (`WorkspaceManagerBase`): Binds a workspace to the sessions this manager creates, under the application's isolation policy. enabled (`bool`, defaults to ``True``): Whether this node owns the timers. Exactly one node in a deployment should enable them; the rest still create, edit and delete schedules — they just do not fire them. """ from apscheduler.schedulers.asyncio import AsyncIOScheduler self._storage = storage self._message_bus = message_bus self._workspace_manager = workspace_manager self._enabled = enabled self._scheduler = AsyncIOScheduler() # ``updated_at`` of each registered job, so a reconcile can tell # an edited schedule from an unchanged one. self._versions: dict[str, datetime] = {} # Serialises reconcile. The periodic loop and the lifecycle listener # both call it, and a slow read must not apply its stale snapshot # after a newer reconcile has already changed the job set. self._reconcile_lock = asyncio.Lock() self._tasks: list[asyncio.Task] = [] # ------------------------------------------------------------------ # Lifecycle # ------------------------------------------------------------------ async def __aenter__(self) -> Self: """Take ownership of the timers, unless this node is disabled. A disabled manager holds no jobs and runs no loops; it stays usable for :meth:`notify_changed` and :meth:`list_tools`, which every node needs. Returns: `Self`: This manager instance. """ if not self._enabled: logger.info( "SchedulerManager disabled on this node; schedules are " "owned elsewhere.", ) return self logger.info("SchedulerManager starting APScheduler") self._scheduler.start() # Subscribe before the first reconcile, and wait for it: a # notification published in between would otherwise be lost, and # the schedule behind it would wait for the periodic pass. ready = asyncio.Event() self._tasks = [ asyncio.create_task( self._listen(ready), name="schedule-lifecycle", ), asyncio.create_task(self._periodic(), name="schedule-reconcile"), ] await ready.wait() await self.reconcile() logger.info("SchedulerManager APScheduler started") return self async def __aexit__(self, *exc: object) -> None: """Stop the loops and shut down APScheduler, if it was started.""" if not self._enabled: return logger.info("SchedulerManager shutting down APScheduler") for task in self._tasks: task.cancel() await asyncio.gather(*self._tasks, return_exceptions=True) self._scheduler.shutdown() logger.info("SchedulerManager APScheduler shut down") # ------------------------------------------------------------------ # Trigger construction # ------------------------------------------------------------------ def _build_trigger( self, record: ScheduleRecord, ) -> Callable[[], Coroutine]: """Build the zero-argument coroutine executed by APScheduler on each trigger fire. The returned coroutine: 1. Skips execution when the schedule is disabled. 2. Resolves or creates the target session (stateful reuses a fixed session; non-stateful creates a fresh one on every fire). 3. Calls :class:`~agentscope.app._service._chat.ChatService` and drains the response stream (fire-and-forget). 4. Catches and logs all exceptions to prevent APScheduler from removing the job on failure. Args: record (`ScheduleRecord`): The persisted schedule record that describes what to run. Returns: `Callable[[], Coroutine]`: A zero-argument async callable suitable for APScheduler. """ # Closure-friendly references so APScheduler doesn't have to # re-look these up on every fire. storage = self._storage message_bus = self._message_bus workspace_manager = self._workspace_manager async def _trigger() -> None: logger.info( "[Schedule:%s(%s)] Trigger fired", record.id, record.data.name, ) if not record.data.enabled: logger.info( "[Schedule:%s(%s)] Skipped — schedule disabled", record.id, record.data.name, ) return try: if record.data.stateful: stateful_session_id = f"{record.id}_stateful" logger.info( "[Schedule:%s(%s)] Stateful mode, " "looking up session %s", record.id, record.data.name, stateful_session_id, ) session = await storage.get_session( record.user_id, record.agent_id, stateful_session_id, ) if session is None: logger.info( "[Schedule:%s(%s)] First fire, " "creating stateful session", record.id, record.data.name, ) state = AgentState() state.permission_context = PermissionContext( mode=record.data.permission_mode, ) session_config = SessionConfig( workspace_id=( await workspace_manager.assign_workspace_id( user_id=record.user_id, agent_id=record.agent_id, session_id=stateful_session_id, ) ), chat_model_config=record.data.chat_model_config, ) session = await storage.upsert_session( user_id=record.user_id, agent_id=record.agent_id, config=session_config, state=state, session_id=stateful_session_id, origin=ScheduleOrigin(schedule_id=record.id), ) else: logger.info( "[Schedule:%s(%s)] Reusing existing " "stateful session %s", record.id, record.data.name, session.id, ) else: logger.info( "[Schedule:%s(%s)] Non-stateful mode, " "creating fresh session", record.id, record.data.name, ) state = AgentState() state.permission_context = PermissionContext( mode=record.data.permission_mode, ) session = await storage.upsert_session( user_id=record.user_id, agent_id=record.agent_id, config=SessionConfig( workspace_id=( await workspace_manager.assign_workspace_id( user_id=record.user_id, agent_id=record.agent_id, session_id=_generate_id(), ) ), chat_model_config=record.data.chat_model_config, ), state=state, origin=ScheduleOrigin(schedule_id=record.id), ) logger.info( "[Schedule:%s(%s)] Session ready: %s, " "delivering prompt via inbox + wakeup", record.id, record.data.name, session.id, ) # Wrap the schedule prompt in an XML tag so the LLM # recognises it as a system-driven trigger rather than # a regular user turn — same shape as team / system # notification hints. hint = HintBlock( hint=( f"<scheduled-task>\n" f"{record.data.description}\n" f"</scheduled-task>" ), source=json.dumps( { "label": "schedule", "sublabel": record.data.name, }, ensure_ascii=False, ), ) await deliver_to_inbox( message_bus, user_id=record.user_id, session_id=session.id, agent_id=record.agent_id, payload=hint.model_dump(mode="json"), ) logger.info( "[Schedule:%s(%s)] Wakeup enqueued for session %s", record.id, record.data.name, session.id, ) except Exception: logger.exception( "[Schedule:%s(%s)] Trigger failed", record.id, record.data.name, ) return _trigger # ------------------------------------------------------------------ # Schedule management # ------------------------------------------------------------------ @staticmethod def validate_schedule(record: ScheduleRecord) -> "BaseTrigger": """Build the record's cron trigger, rejecting a bad schedule. Writers call this before persisting so an invalid schedule never reaches storage, and :meth:`_add_job` reuses what it returns rather than parsing the expression a second time. ``CronTrigger.from_crontab`` is not usable here: it forwards only the 5 parsed fields and ``timezone``, with no parameter for ``start_date`` / ``end_date``, so the configured activation window would be dropped. Restricted day-of-month and day-of-week fields are alternatives, as in standard cron: ``0 9 1 * 1`` runs at 09:00 on every month's first day and every Monday, once when they coincide. If either day field contains ``*``, both fields must match instead. Args: record (`ScheduleRecord`): The schedule to check. Returns: `BaseTrigger`: The trigger the job would fire on. Raises: `ValueError`: The cron expression, the timezone, or the activation window is invalid. """ from apscheduler.triggers.cron import CronTrigger from apscheduler.triggers.combining import OrTrigger fields = record.data.cron_expression.split() if len(fields) != 5: raise ValueError( "Expected a 5-field cron expression, got " f"{record.data.cron_expression!r}", - src/agentscope/app/_manager/_scheduler/_tools/__init__.py (330 bytes)
# -*- coding: utf-8 -*- """The schedule related tools.""" from ._schedule_create import ScheduleCreate from ._schedule_delete import ScheduleDelete from ._schedule_list import ScheduleList from ._schedule_view import ScheduleView __all__ = [ "ScheduleCreate", "ScheduleDelete", "ScheduleList", "ScheduleView", ] - src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py (9155 bytes)
# -*- coding: utf-8 -*- """The schedule create tool.""" from datetime import datetime from typing import Any from pydantic import BaseModel, Field from .....message import ToolResultState, TextBlock from .....permission import ( PermissionContext, PermissionDecision, PermissionBehavior, PermissionMode, ) from .....state import AgentState from .....tool import ToolBase, ToolChunk from ....storage import ( ScheduleData, ScheduleRecord, ScheduleSource, ChatModelConfig, ) class _ScheduleCreateParams(BaseModel): """The params for the schedule create tool.""" name: str = Field(description="Display name of the schedule.") description: str = Field( default="", description="Description of the schedule, including its purpose.", ) cron_expression: str = Field( description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.", ) timezone: str = Field( default="UTC", description="IANA timezone name used to evaluate the cron expression, " "e.g. 'America/New_York' or 'Asia/Shanghai'.", ) enabled: bool = Field( default=True, description="Whether the schedule is active immediately after " "creation. Set to False to create a disabled schedule.", ) started_at: datetime | None = Field( default=None, description="ISO-8601 datetime at which the schedule becomes active. " "Defaults to the current time when not specified.", ) ended_at: datetime | None = Field( default=None, description="ISO-8601 datetime at which the schedule stops firing. " "If not set the schedule runs indefinitely.", ) stateful: bool = Field( default=False, description="If True, consecutive executions share the same session " "context. If False, each execution gets a fresh session.", ) permission_mode: str = Field( default=PermissionMode.DONT_ASK.value, description=( "Permission mode for the agent during scheduled execution. " f"Allowed values: {[m.value for m in PermissionMode]}. " "Defaults to 'dont_ask' since no user is present." ), ) class ScheduleCreate(ToolBase): """The schedule create tool. Creates a new scheduled task that will execute the current agent at a given cron interval. The record is persisted to storage and immediately registered with the in-memory APScheduler. The schedule inherits the model configuration of the current session. The agent that creates the schedule is also the agent that will be run on each trigger. """ name: str = "ScheduleCreate" description: str = """Create a new recurring scheduled task for yourself. \ You will be notified in a new session each time the schedule is triggered. **About the cron expression:** - Determine your current timezone first, that's very important for setting a \ correct cron expression. Get it by bash command like `date +%z`, \ `cat /etc/timezone` or directly ask the user. - Determine whether the task should run once or recur at an interval, \ then set the cron expression accordingly. - For a one-off task, query the current time first and set the cron \ expression to fire at that specific moment. - Set `started_at` and `ended_at` to match the user's requirements. \ When in doubt, ask for clarification before creating the schedule. **About the description field:** - The `description` is the only context available to you when the \ schedule fires in a new session. Include all necessary details: the goal, \ expected output, constraints, relevant file paths, and anything else needed \ to complete the task independently. """ input_schema: dict = _ScheduleCreateParams.model_json_schema() is_concurrency_safe: bool = False is_read_only: bool = False is_state_injected: bool = True is_external_tool: bool = False is_mcp: bool = False mcp_name: str | None = None def __init__( self, user_id: str, agent_id: str, chat_model_config: ChatModelConfig, storage: Any, scheduler_manager: Any, ) -> None: """Initialize the schedule create tool. Args: user_id (`str`): The authenticated user who owns this schedule. agent_id (`str`): The agent that will be executed on each trigger. chat_model_config (`ChatModelConfig`): Model configuration inherited from the current session. storage (`Any`): The storage backend used to persist the schedule record. scheduler_manager (`Any`): The scheduler manager, used to tell the timer-owning node that a schedule changed. Must expose a ``notify_changed(schedule_id)`` coroutine. """ self._user_id = user_id self._agent_id = agent_id self._chat_model_config = chat_model_config self._storage = storage self._scheduler_manager = scheduler_manager async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """Check permission for the tool usage.""" return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{self.name} is always allowed to be called.", ) async def __call__( # type: ignore[override] self, name: str, cron_expression: str, description: str = "", timezone: str = "UTC", enabled: bool = True, started_at: datetime | None = None, ended_at: datetime | None = None, stateful: bool = False, permission_mode: str = PermissionMode.DONT_ASK.value, _agent_state: AgentState | None = None, ) -> ToolChunk: """Create a new scheduled task. Args: name (`str`): Display name of the schedule. cron_expression (`str`): Standard 5-field cron expression, e.g. ``'0 9 * * 1-5'``. description (`str`, optional): Human-readable description of what this schedule does. timezone (`str`, optional): IANA timezone name, e.g. ``'Asia/Shanghai'``. enabled (`bool`, optional): Whether the schedule is active immediately after creation. started_at (`datetime | None`, optional): Datetime at which the schedule becomes active. Defaults to the current time when not specified. ended_at (`datetime | None`, optional): Datetime at which the schedule stops firing. If not set the schedule runs indefinitely. stateful (`bool`, optional): Whether consecutive executions share the same session context. permission_mode (`str`, optional): Permission mode value string. _agent_state (`AgentState | None`, optional): Injected agent state; provides the source session ID. Returns: `ToolChunk`: A chunk with the new schedule ID on success, or an error description on failure. """ try: perm_mode = PermissionMode(permission_mode) except ValueError: perm_mode = PermissionMode.DONT_ASK source_session_id = ( _agent_state.session_id if _agent_state is not None else "" ) record = ScheduleRecord( user_id=self._user_id, agent_id=self._agent_id, data=ScheduleData( name=name, description=description, enabled=enabled, cron_expression=cron_expression, timezone=timezone, started_at=started_at or datetime.now().astimezone(), ended_at=ended_at, stateful=stateful, permission_mode=perm_mode, source=ScheduleSource.AGENT, source_session_id=source_session_id, chat_model_config=self._chat_model_config, ), ) self._scheduler_manager.validate_schedule(record) await self._storage.upsert_schedule(self._user_id, record) await self._scheduler_manager.notify_changed(record.id) return ToolChunk( content=[ TextBlock( text=( f"Schedule {name!r} created successfully.\n" f"Schedule ID: {record.id}\n" f"Cron: {cron_expression} (timezone: {timezone})\n" f"Enabled: {enabled}\n" f"Started at: {record.data.started_at}\n" f"Ended at: {ended_at or '(no end time)'}\n" f"Stateful: {stateful}" ), ), ], state=ToolResultState.SUCCESS, ) - src/agentscope/app/_manager/_scheduler/_tools/_schedule_delete.py (5429 bytes)
# -*- coding: utf-8 -*- """Schedule delete tool – removes a job from the scheduler and storage.""" from typing import Any from pydantic import BaseModel, Field from apscheduler.jobstores.base import JobLookupError from .....message import ToolResultState, TextBlock from .....permission import ( PermissionContext, PermissionDecision, PermissionBehavior, ) from .....tool import ToolBase, ToolChunk from ....message_bus import MessageBus from ....storage._base import StorageBase class _ScheduleDeleteParams(BaseModel): """The params for the schedule delete tool.""" schedule_id: str = Field( description="The schedule ID to delete (permanently remove).", ) class ScheduleDelete(ToolBase): """The schedule delete tool. Permanently removes the given scheduled job from APScheduler, storage, and the message bus. Every execution session spawned by the schedule is cancelled (if running) and has its bus state purged. The job cannot be recovered after removal. """ name: str = "ScheduleDelete" description: str = ( "Permanently delete a scheduled task by its schedule ID. " "After this call the task will no longer be executed and its record " "will be deleted from storage." ) input_schema: dict = _ScheduleDeleteParams.model_json_schema() is_concurrency_safe: bool = False is_read_only: bool = False is_state_injected: bool = False is_external_tool: bool = False is_mcp: bool = False mcp_name: str | None = None def __init__( self, user_id: str, scheduler: Any, storage: StorageBase, message_bus: MessageBus, scheduler_manager: Any, ) -> None: """Initialize the schedule delete tool. Args: user_id (`str`): The authenticated user; used to scope the storage deletion. scheduler (`Any`): The ``AsyncIOScheduler`` instance whose job will be removed. storage (`StorageBase`): The storage backend used to delete the persisted record. message_bus (`MessageBus`): The message bus used to cancel in-flight chat runs for any execution session spawned by this schedule and to purge their per-session bus state. scheduler_manager (`Any`): The scheduler manager, used to tell the timer-owning node that a schedule changed. Must expose a ``notify_changed(schedule_id)`` coroutine. """ self._user_id = user_id self._scheduler = scheduler self._storage = storage self._message_bus = message_bus self._scheduler_manager = scheduler_manager async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """Check permission for the tool usage.""" return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{self.name} is always allowed to be called.", ) async def __call__( self, schedule_id: str, ) -> ToolChunk: # type: ignore[override] """Permanently delete the scheduled task with the given ID. Delegates the storage + bus cascade to :meth:`SessionService.delete_schedule`, which cancels in-flight runs for any session this schedule spawned and purges their bus state before dropping the schedule record. The APScheduler job is removed separately because it lives in-process and the service layer is bus/storage-only. Args: schedule_id (`str`): The unique identifier of the schedule to delete. Returns: `ToolChunk`: A chunk describing the result of the delete operation. """ # Remove from the in-memory scheduler (best-effort; may already be # absent if the job finished naturally or the server restarted) try: self._scheduler.remove_job(schedule_id) except JobLookupError: pass # Local import to avoid a circular dependency between # ``_manager`` and ``_service`` at module load. from ...._service import SessionService # noqa: PLC0415 session_service = SessionService( storage=self._storage, message_bus=self._message_bus, ) deleted = await session_service.delete_schedule( self._user_id, schedule_id, ) if not deleted: return ToolChunk( content=[ TextBlock( text=( f"ScheduleNotFoundError: Schedule with id " f"{schedule_id!r} not found in storage." ), ), ], state=ToolResultState.ERROR, ) await self._scheduler_manager.notify_changed(schedule_id) return ToolChunk( content=[ TextBlock( text=( f"Schedule {schedule_id!r} has been permanently " f"deleted." ), ), ], state=ToolResultState.SUCCESS, ) - src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py (3904 bytes)
# -*- coding: utf-8 -*- """The tool to list the scheduled jobs in the cron scheduler manager.""" from typing import Any from pydantic import BaseModel from .....message import ToolResultState, TextBlock from .....permission import ( PermissionContext, PermissionDecision, PermissionBehavior, ) from .....tool import ToolBase, ToolChunk from ....storage import StorageBase class _ScheduleListParams(BaseModel): """The params for the schedule list tool.""" class ScheduleList(ToolBase): """The schedule list tool. Lists all scheduled tasks owned by the current user. Each entry is fetched from storage (rich :class:`ScheduleData`) and augmented with ``next_run_time`` from the in-memory APScheduler job when available. """ name: str = "ScheduleList" description: str = ( "List all scheduled tasks for the current user. " "Shows schedule ID, name, cron expression, timezone, next run time, " "enabled/disabled status, and whether the schedule is stateful." ) input_schema: dict = _ScheduleListParams.model_json_schema() is_concurrency_safe: bool = True is_read_only: bool = True is_state_injected: bool = False is_external_tool: bool = False is_mcp: bool = False mcp_name: str | None = None def __init__( self, user_id: str, scheduler: Any, storage: StorageBase, ) -> None: """Initialize the schedule list tool. Args: user_id (`str`): The authenticated user; used to scope the storage lookup. scheduler (`Any`): The ``AsyncIOScheduler`` instance for reading ``next_run_time`` storage (`StorageBase`): The storage backend that holds the persisted schedule records. """ self._user_id = user_id self._scheduler = scheduler self._storage = storage async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """Check permission for the tool usage.""" return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{self.name} is always allowed to be called.", ) async def __call__(self) -> ToolChunk: # type: ignore[override] """List all scheduled tasks for the current user. Returns: `ToolChunk`: A chunk containing a formatted list of all scheduled tasks, or a message indicating none exist. """ records = await self._storage.list_schedules(self._user_id) if not records: return ToolChunk( content=[TextBlock(text="No scheduled tasks found.")], state=ToolResultState.SUCCESS, ) # Build a map of schedule_id -> next_run_time from the live scheduler next_run_map: dict[str, str] = { job.id: str(job.next_run_time) for job in self._scheduler.get_jobs() } lines: list[str] = [f"Found {len(records)} scheduled task(s):\n"] for record in records: enabled_str = "enabled" if record.data.enabled else "disabled" next_run = next_run_map.get(record.id, "not in scheduler") lines.append( f"- [{enabled_str}] {record.data.name!r} (ID: {record.id})\n" f" Cron: {record.data.cron_expression}" f" ({record.data.timezone})\n" f" Next run: {next_run}\n" f" Stateful: {record.data.stateful}" f" | Agent: {record.agent_id}\n" f" Source: {record.data.source.value}\n", ) return ToolChunk( content=[TextBlock(text="\n".join(lines))], state=ToolResultState.SUCCESS, ) - src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py (4440 bytes)
# -*- coding: utf-8 -*- """The schedule view tool.""" from typing import Any from pydantic import BaseModel, Field from .....message import ToolResultState, TextBlock from .....permission import ( PermissionContext, PermissionDecision, PermissionBehavior, ) from .....tool import ToolBase, ToolChunk from ....storage import StorageBase class _ScheduleViewParams(BaseModel): """The params for the schedule view tool.""" schedule_id: str = Field( description="The schedule ID.", ) class ScheduleView(ToolBase): """The schedule view tool. Fetches the persisted :class:`ScheduleRecord` from storage and enriches it with the ``next_run_time`` from the in-memory APScheduler job. """ name: str = "ScheduleView" description: str = ( "View the full details of a scheduled task by its schedule ID, " "including cron expression, timezone, stateful flag, permission " "mode, and the next scheduled run time." ) input_schema: dict = _ScheduleViewParams.model_json_schema() is_concurrency_safe: bool = True is_read_only: bool = True is_state_injected: bool = False is_external_tool: bool = False is_mcp: bool = False mcp_name: str | None = None def __init__( self, user_id: str, scheduler: Any, storage: StorageBase, ) -> None: """Initialize the schedule view tool. Args: user_id (`str`): The authenticated user; used to scope the storage lookup. scheduler (`Any`): The ``AsyncIOScheduler`` instance for reading ``next_run_time``. storage (`StorageBase`): The storage backend that holds the persisted schedule records. """ self._user_id = user_id self._scheduler = scheduler self._storage = storage async def check_permissions( self, tool_input: dict[str, Any], context: PermissionContext, ) -> PermissionDecision: """Check permission for the tool usage.""" return PermissionDecision( behavior=PermissionBehavior.ALLOW, message=f"{self.name} is always allowed to be called.", ) async def __call__( self, schedule_id: str, ) -> ToolChunk: # type: ignore[override] """View the full details of a scheduled task. Args: schedule_id (`str`): The unique identifier of the schedule to view. Returns: `ToolChunk`: A chunk containing the formatted schedule details, or an error description if the schedule is not found. """ record = await self._storage.get_schedule(self._user_id, schedule_id) if record is None: return ToolChunk( content=[ TextBlock( text=( f"ScheduleNotFoundError: Schedule with " f"id {schedule_id!r} not found." ), ), ], state=ToolResultState.ERROR, ) job = self._scheduler.get_job(schedule_id) next_run = ( str(job.next_run_time) if job is not None else "not in scheduler (may be disabled)" ) enabled_str = "enabled" if record.data.enabled else "disabled" text = ( f"Schedule ID: {record.id}\n" f"Name: {record.data.name}\n" f"Description: {record.data.description or '(none)'}\n" f"Status: {enabled_str}\n" f"Cron: {record.data.cron_expression}" f" (timezone: {record.data.timezone})\n" f"Next run: {next_run}\n" f"Stateful: {record.data.stateful}\n" f"Permission mode: {record.data.permission_mode.value}\n" f"Source: {record.data.source.value}\n" f"Source session: {record.data.source_session_id or '(none)'}\n" f"Agent ID: {record.agent_id}\n" f"Created at: {record.created_at}\n" f"Updated at: {record.updated_at}\n" ) return ToolChunk( content=[TextBlock(text=text)], state=ToolResultState.SUCCESS, ) - src/agentscope/app/_manager/_wakeup_dispatcher.py (23418 bytes)
# -*- coding: utf-8 -*- """Single per-process dispatcher for all cross-session run triggers. One asyncio task per process. Subscribes to the shared trigger signal channel and drains the durable trigger queue on each signal. It is the **sole** site that spawns :meth:`ChatService.run` into the shared :class:`ChatRunRegistry`, which is what makes concurrent-spawn races (two writers contending for one session's run slot → a spurious "already has an active chat run" 409) structurally impossible: every run trigger funnels through this one serial consumer. Each queue entry carries a ``kind`` that selects how a busy session is handled: - ``wake`` (idle-session wake-up, ``input_msg=None``): delivers pending inbox content and is retried while the session is running. - ``resume`` (a parked HITL run being fed its result): must *not* be skipped while running, because the session is typically still running the parked tail at trigger time. It is re-queued after a short backoff until the parked run releases its session lock, then spawned with the carried input event. - ``message`` (an inbound-channel ``Msg``): carries a genuine user message and is retried until it can start a run. - ``queued_message`` (ordinary browser input): drains a per-session FIFO only after the current reply is complete and the session is not parked on HITL. Durable recovery replaces per-session hot retries. All bus keys live on the :class:`MessageBus` base class (see ``enqueue_wakeup`` / ``enqueue_input``, ``dequeue_wakeups``, ``subscribe_wakeup_signal``, ``session_is_running``), so this file has no hard-coded key strings. """ import asyncio from typing import TYPE_CHECKING, Self from pydantic import TypeAdapter from ..._logging import logger from ...event import ( ExternalExecutionResultEvent, ReplyEndEvent, UserConfirmResultEvent, UserInterruptEvent, ) from ...message import Msg from ...types import ErrorInfo, ErrorType, ReplyFinishedReason from .._client_external_tool import ( ClientBuiltinToolName, ClientExternalToolDefinition, parse_client_tool_capabilities, ) from ..message_bus import MessageBusKeys from ._chat_input_queue import ChatInputQueue from .._bus_ops import ( enqueue_run_trigger, publish_session_event, ) if TYPE_CHECKING: from ..message_bus import MessageBus from ..storage import StorageBase from .._service import ChatService from ._chat_run_registry import ChatRunRegistry # Parses a queued ``resume`` input dict back into its concrete event, # discriminated by the ``type`` field shared by these result events. _RESUME_INPUT_ADAPTER: TypeAdapter = TypeAdapter( UserConfirmResultEvent | ExternalExecutionResultEvent | UserInterruptEvent, ) # Delay before re-queuing a trigger whose target session still holds # its run lock. Short enough to feel instant to the user, long enough # to avoid a hot re-enqueue loop while the lock is held. _RESUME_RETRY_BACKOFF_SECS = 0.1 # Durably indexed pending queues are revisited at this low frequency. # This is a crash/lost-signal safety net, not a per-session hot poll. _MESSAGE_FALLBACK_TICK_SECS = 30.0 class WakeupDispatcher: """One asyncio task per process, draining the shared trigger queue. Args: message_bus (`MessageBus`): Application message bus. Used for signal subscription, queue drain, ``session_is_running`` checks, and re-queuing deferred ``resume`` triggers. storage (`StorageBase`): Persistent storage backend. Consulted before spawning a run so triggers whose target session has been deleted are dropped instead of crashing :class:`ChatService.run`. chat_service (`ChatService`): Drives the actual chat run when a trigger fires. chat_run_registry (`ChatRunRegistry`): Per-process registry that holds the spawned task handle so it can be located by :class:`CancelDispatcher`. """ def __init__( self, message_bus: "MessageBus", storage: "StorageBase", chat_service: "ChatService", chat_run_registry: "ChatRunRegistry", ) -> None: """Bind dependencies. Args: message_bus (`MessageBus`): Application message bus. storage (`StorageBase`): Persistent storage backend. chat_service (`ChatService`): Drives session runs via :meth:`ChatService.run`. chat_run_registry (`ChatRunRegistry`): Shared chat-run registry to spawn into. """ self._bus = message_bus self._storage = storage self._chat_service = chat_service self._registry = chat_run_registry self._task: asyncio.Task | None = None self._fallback_task: asyncio.Task | None = None self._chat_queue = ChatInputQueue(message_bus, storage, chat_service) # Detached resume timers. Held # so they are not garbage-collected mid-await and can be cancelled # on shutdown. self._retry_tasks: set[asyncio.Task] = set() async def __aenter__(self) -> Self: """Start the dispatcher loop and wait until its bus subscription is live. After subscribing, publishes a signal for durable triggers that predate process startup. The potentially O(N) pending-session recovery sweep runs in a retained background task so application startup is not blocked by the number of indexed sessions. Returns: `Self`: This dispatcher instance. Raises: `Exception`: The subscription's error if it fails before it is live, or `RuntimeError` if it ends cleanly before then. Started tasks are cleaned up, as on a cancelled startup. """ ready = asyncio.Event() loop_task = asyncio.create_task( self._loop(ready), name="wakeup-dispatcher", ) self._task = loop_task ready_waiter = asyncio.create_task(ready.wait()) try: await asyncio.wait( {loop_task, ready_waiter}, return_when=asyncio.FIRST_COMPLETED, ) ready_waiter.cancel() await asyncio.gather(ready_waiter, return_exceptions=True) if not ready.is_set(): await loop_task raise RuntimeError( "WakeupDispatcher subscription ended before it was " "ready.", ) if self._task.done(): raise RuntimeError("Wakeup subscription ended during startup") self._fallback_task = asyncio.create_task( self._fallback_loop(), name="wakeup-dispatcher:fallback", ) await self._bus.publish(MessageBusKeys.wakeup_signal(), {}) if self._task.done(): raise RuntimeError("Wakeup subscription ended during startup") self._chat_queue.schedule_recovery() except BaseException: # Failed entry does not invoke __aexit__. The listener and # fallback may already have spawned retries or recovery work. tasks = [ task for task in ( ready_waiter, self._task, self._fallback_task, *self._retry_tasks, ) if task is not None ] for task in tasks: task.cancel() await asyncio.gather(*tasks, return_exceptions=True) self._task = None self._fallback_task = None self._retry_tasks.clear() # Stop queue helpers and late run callbacks without contacting # the failed bus to release recovery leadership. await self._chat_queue.close(release_leadership=False) raise return self async def __aexit__(self, *exc: object) -> None: """Cancel the dispatcher loop and any pending retries.""" retries = list(self._retry_tasks) for retry in retries: retry.cancel() for retry in retries: try: await retry except asyncio.CancelledError: pass self._retry_tasks.clear() for task in (self._fallback_task, self._task): if task is None: continue task.cancel() try: await task except asyncio.CancelledError: pass self._fallback_task = None self._task = None await self._chat_queue.close() # ------------------------------------------------------------------ # Internals # ------------------------------------------------------------------ async def _loop(self, ready: asyncio.Event) -> None: """Long-lived loop: subscribe to the signal channel and drain the queue on every received signal. Args: ready (`asyncio.Event`): Signalled after the underlying SUBSCRIBE completes. :meth:`start` blocks on this so callers can publish a trigger immediately after start without racing. """ try: async for _signal in self._bus.subscribe( MessageBusKeys.wakeup_signal(), on_ready=ready.set, ): await self._drain_and_dispatch() except Exception: # pylint: disable=broad-except if not ready.is_set(): raise logger.exception( "WakeupDispatcher loop crashed; subscription ended.", ) async def _fallback_loop(self) -> None: """Periodically signal the sole drain loop and schedule recovery.""" while True: await asyncio.sleep(_MESSAGE_FALLBACK_TICK_SECS) try: # Never drain here: Redis queue_drain is XRANGE + XDEL and # therefore requires a single in-process consumer. All # actual draining remains serialized in ``_loop``. await self._bus.publish(MessageBusKeys.wakeup_signal(), {}) except Exception: # pylint: disable=broad-except logger.exception("WakeupDispatcher fallback signal failed.") try: self._chat_queue.schedule_recovery() except Exception: # pylint: disable=broad-except logger.exception( "WakeupDispatcher recovery scheduling failed.", ) async def _drain_and_dispatch(self) -> None: """Read up to a batch of trigger entries and dispatch each.""" try: raw_entries = await self._bus.queue_drain( MessageBusKeys.wakeup_queue(), max_count=64, ) entries = [payload for _, payload in raw_entries] except Exception: # pylint: disable=broad-except logger.exception("WakeupDispatcher: dequeue_wakeups failed.") return for payload in entries: try: user_id = payload["user_id"] session_id = payload["session_id"] agent_id = payload["agent_id"] except (KeyError, TypeError): logger.warning( "WakeupDispatcher: skipping malformed trigger entry %r", payload, ) continue # Entries from older producers omit ``kind`` — treat as wake. kind = payload.get("kind", MessageBusKeys.WAKEUP_KIND_WAKE) await self._dispatch_one( user_id=user_id, session_id=session_id, agent_id=agent_id, kind=kind, raw_input=payload.get("input"), raw_client_external_tools=payload.get( "client_external_tools", ), raw_client_builtin_tools=payload.get("client_builtin_tools"), ) async def _dispatch_one( self, user_id: str, session_id: str, agent_id: str, kind: str, raw_input: dict | list[dict] | None, raw_client_external_tools: list[dict] | None = None, raw_client_builtin_tools: list[str] | None = None, ) -> None: """Dispatch a single trigger entry by its ``kind``. Args: user_id (`str`): The owning user id. session_id (`str`): The session to trigger. agent_id (`str`): The agent that owns the session. kind (`str`): Trigger kind (``wake`` / ``resume`` / ``message`` / ``queued_message``); see the module docstring. raw_input (`dict | list[dict] | None`): Serialised input event for ``resume`` triggers, else ``None``. raw_client_external_tools (`list[dict] | None`): Serialised client tool definitions for this run. raw_client_builtin_tools (`list[str] | None`): Native external tool names supported by this run's client. """ is_resume = kind == MessageBusKeys.WAKEUP_KIND_RESUME is_message = kind == MessageBusKeys.WAKEUP_KIND_MESSAGE is_queued_message = kind == MessageBusKeys.WAKEUP_KIND_QUEUED_MESSAGE # Queued-message triggers are only hints. Avoid storage/lock work # for stale completion nudges after the durable queue is empty. if is_queued_message: pending = await self._bus.queue_read( MessageBusKeys.chat_inputs(session_id), max_count=1, ) claimed = await self._bus.registry_exists( MessageBusKeys.chat_input_inflight_registry(), session_id, ) if not pending and not claimed: return if await self._bus.is_locked( MessageBusKeys.chat_input_dispatch_lock(session_id), ): return # ``resume`` and ``message`` both carry input that must be # delivered — never dropped while the session is busy. carries_input = is_resume or is_message # Parse the carried input early so every downstream path # (lock-retry, spawn-retry) receives a typed object rather than a # raw dict. input_msg: ( UserConfirmResultEvent | ExternalExecutionResultEvent | UserInterruptEvent | Msg | None ) = None ( client_external_tools, client_builtin_tools, ) = parse_client_tool_capabilities( raw_client_external_tools, - src/agentscope/app/_router/__init__.py (1274 bytes)
# -*- coding: utf-8 -*- """App routers.""" from ._asr import asr_router from ._agent import agent_router from ._background_task import background_task_router from ._channel import channel_router from ._chat import chat_router from ._credential import credential_router from ._embedding_model import embedding_model_router from ._health import health_router from ._hub import hub_router from ._knowledge_base import knowledge_base_router from ._mcp import mcp_router from ._schedule import schedule_router from ._session import session_router from ._skill import skill_router from ._sop import sop_router from ._model import model_router from ._realtime import realtime_router from ._tts_model import tts_model_router from ._voice_profile import voice_profile_router from ._workspace import workspace_router __all__ = [ "asr_router", "agent_router", "background_task_router", "channel_router", "model_router", "realtime_router", "embedding_model_router", "tts_model_router", "voice_profile_router", "chat_router", "credential_router", "health_router", "hub_router", "knowledge_base_router", "mcp_router", "schedule_router", "session_router", "skill_router", "sop_router", "workspace_router", ] - src/agentscope/app/_router/_agent.py (12501 bytes)
# -*- coding: utf-8 -*- """Agent router — CRUD endpoints for agent configurations.""" from datetime import datetime from fastapi import APIRouter, Depends, HTTPException, status from pydantic import ValidationError from ...agent import ContextConfig, ReActConfig from ...agent._config import _validate_context_config_ratios from ..._utils._common import _flatten_json_schema from ..access import ResourceKind from ..deps import ( get_current_user_id, get_resource_access_service, get_session_service, get_storage, ) from ._schema import ( AgentSchemaResponse, AgentSchemaV2Response, ListAgentsResponse, CreateAgentRequest, CreateAgentResponse, UpdateAgentRequest, ) from .._service import AgentView, ResourceAccessService, SessionService from ..storage import StorageBase, AgentData, AgentRecord agent_router = APIRouter( prefix="/agent", tags=["agent"], responses={404: {"description": "Not found"}}, ) @agent_router.get( "/schema", response_model=AgentSchemaResponse, deprecated=True, summary="[Deprecated] Legacy sectioned schema — use /schema/v2", ) async def get_agent_schema() -> AgentSchemaResponse: """Return the legacy sectioned JSON Schema fragments. .. deprecated:: Superseded by :func:`get_agent_schema_v2`, which returns the full :class:`AgentData` schema in a single ``schema`` field. Kept for backwards compatibility with existing API consumers. New consumers should call ``GET /agent/schema/v2``. The frontend previously used three sections — identity, context config, and react config — so we return them as separate self-contained schemas rather than a single :class:`AgentData` schema with ``$ref`` s. Returns: `AgentSchemaResponse`: Schemas for the three form sections. """ # Slice ``AgentData``'s schema down to the identity-relevant fields. # Going through ``AgentData.model_json_schema()`` (rather than building # a dict by hand) keeps Pydantic as the single source of truth for # defaults, titles, descriptions, and the ``format: textarea`` hint. agent_schema = AgentData.model_json_schema() identity_keys = ("name", "system_prompt") identity = { "type": "object", "title": "Identity", "properties": { k: v for k, v in agent_schema.get("properties", {}).items() if k in identity_keys }, "required": [ r for r in agent_schema.get("required", []) if r in identity_keys ], } context_schema = ContextConfig.model_json_schema() # ``summary_schema`` holds a Pydantic JSON Schema describing how the # compression model should structure its output. The end-user is not # expected to edit it from the form, so we hide it. context_schema.get("properties", {}).pop("summary_schema", None) return AgentSchemaResponse( identity=identity, context_config=context_schema, react_config=ReActConfig.model_json_schema(), ) @agent_router.get( "/schema/v2", response_model=AgentSchemaV2Response, summary="Full AgentData JSON Schema for the agent form", ) async def get_agent_schema_v2() -> AgentSchemaV2Response: """Return the full :class:`AgentData` JSON Schema. Superset of the legacy sectioned endpoint. The response body is a single ``schema`` field carrying the whole Pydantic-generated schema of :class:`AgentData`, with two curated exclusions handled at the model layer (so no post-processing is needed here): - ``id``: server-assigned, marked :class:`SkipJsonSchema` on :attr:`AgentData.id`. - ``chat_config.context_config.summary_schema``: internal structured-output spec for the compression model, dropped below since it is not user-editable and there is no equivalent hook on the Pydantic side. ``$ref`` inlining is delegated to :func:`~agentscope._utils._common._flatten_json_schema` so the frontend can render every property from the response body alone. The frontend derives its section grouping directly from this schema — top-level scalar properties are the "identity" section, and every nested object below a mode block (``chat_config``) becomes its own section. Adding a new user-editable field to :class:`AgentData` is thus enough to have it appear in the create / edit form without a router change. Returns: `AgentSchemaV2Response`: ``schema`` = the full :class:`AgentData` JSON Schema. """ schema = _flatten_json_schema(AgentData.model_json_schema()) # ``summary_schema`` is Pydantic's structured-output spec fed to the # compression model — internal, not user-editable. No pydantic-side # hook covers this deep nested field, so drop it after inlining. chat_config = schema.get("properties", {}).get("chat_config", {}) context_config = chat_config.get("properties", {}).get( "context_config", {}, ) context_config.get("properties", {}).pop("summary_schema", None) return AgentSchemaV2Response(schema=schema) @agent_router.get( "/", response_model=ListAgentsResponse, summary="List all agents", ) async def list_agents( user_id: str = Depends(get_current_user_id), access: ResourceAccessService = Depends(get_resource_access_service), ) -> ListAgentsResponse: """Return all agent records visible to the authenticated user. Includes the caller's own ``source == "user"`` agents plus any agents shared to them through :class:`ResourceAccessPolicyBase`. Each entry carries an ``editable`` flag indicating whether the caller may PATCH/DELETE it. Args: user_id (`str`): Injected authenticated user ID. access (`ResourceAccessService`): Injected resource access service. Returns: `ListAgentsResponse`: All visible agent records paired with per-viewer editability. """ entries = await access.list_resource(user_id, ResourceKind.AGENT) return ListAgentsResponse(agents=entries, total=len(entries)) @agent_router.post( "/", response_model=CreateAgentResponse, status_code=status.HTTP_201_CREATED, summary="Create a new agent", ) async def create_agent( body: CreateAgentRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), ) -> CreateAgentResponse: """Create and persist a new agent configuration. Args: body (`CreateAgentRequest`): Agent configuration to store. user_id (`str`): Injected authenticated user ID. storage (`StorageBase`): Injected storage backend. Returns: `CreateAgentResponse`: The server-assigned agent identifier. Raises: `HTTPException`: 422 if the request body passes :class:`CreateAgentRequest` validation but the resulting :class:`AgentData` fails its cross-field invariants or its context ratios are invalid for the default Agent runtime. Symmetrical with :func:`update_agent`. """ try: data = AgentData.model_validate(body.model_dump(exclude_none=True)) # Validate writes only, so old invalid records remain repairable. _validate_context_config_ratios( data.chat_config.context_config, inject_runtime_state=True, ) except ValueError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=( exc.errors(include_context=False) if isinstance(exc, ValidationError) else str(exc) ), ) from exc record = AgentRecord(user_id=user_id, data=data) agent_id = await storage.upsert_agent(user_id, record) return CreateAgentResponse(agent_id=agent_id) @agent_router.patch( "/{agent_id}", response_model=AgentView, summary="Update an agent", ) async def update_agent( agent_id: str, body: UpdateAgentRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), access: ResourceAccessService = Depends(get_resource_access_service), ) -> AgentView: """Partially update an existing agent configuration. Only the fields present in the request body are updated; all other fields keep their current values. Args: agent_id (`str`): The agent to update. body (`UpdateAgentRequest`): Fields to update. user_id (`str`): Injected authenticated user ID. storage (`StorageBase`): Injected storage backend. access (`ResourceAccessService`): Injected access service. Returns: `AgentView`: The full agent record after the update. Raises: `HTTPException`: 404 if the agent is not visible to the caller; 403 if visible but only readable; 422 if the merged settings violate configuration constraints. """ owner_id, existing = await access.resolve_for_edit( user_id, ResourceKind.AGENT, agent_id, ) updates = body.model_dump(exclude_none=True, exclude_unset=True) current_data = existing.data.model_dump() chat_updates = updates.pop("chat_config", None) if chat_updates is not None: updates["chat_config"] = { **current_data["chat_config"], **chat_updates, } # ``model_copy(update=...)`` skips validators; re-run # ``AgentData.model_validate`` on the merged shape so the # ``invite_config`` sub-model's ``invitable ⇒ non-empty description`` # invariant enforced by ``@model_validator(mode="after")`` produces # an HTTP 422 instead of a stored-but-invalid record. Nested updates # replace only the supplied sub-configs. A body still using the # pre-``chat_config`` field names is folded in there too, on top of # the stored block rather than over it. try: updated_data = AgentData.model_validate( {**current_data, **updates}, ) _validate_context_config_ratios( updated_data.chat_config.context_config, inject_runtime_state=True, ) except ValueError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=( exc.errors(include_context=False) if isinstance(exc, ValidationError) else str(exc) ), ) from exc updated_agent = existing.model_copy( update={"data": updated_data, "updated_at": datetime.now()}, ) await storage.upsert_agent(owner_id, updated_agent) # Only reachable via ``resolve_for_edit``, so the caller has edit # permission by construction. return AgentView.model_validate( {**updated_agent.model_dump(), "editable": True}, ) @agent_router.delete( "/{agent_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete an agent", ) async def delete_agent( agent_id: str, user_id: str = Depends(get_current_user_id), session_service: SessionService = Depends(get_session_service), access: ResourceAccessService = Depends(get_resource_access_service), ) -> None: """Permanently delete an agent configuration. Cascades through every session owned by this agent (and, for team leaders, through every worker session) — cancelling any in-flight chat run, removing storage records, and purging bus state. Args: agent_id (`str`): The agent to delete. user_id (`str`): Injected authenticated user ID. session_service (`SessionService`): Injected session service. access (`ResourceAccessService`): Injected access service — used to resolve the owning user and enforce the edit permission when a shared editor deletes the agent. Raises: `HTTPException`: 404 if the agent is not visible to the caller; 403 if visible but only readable. """ owner_id, _ = await access.resolve_for_edit( user_id, ResourceKind.AGENT, agent_id, ) deleted = await session_service.delete_agent(owner_id, agent_id) if not deleted: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Agent '{agent_id}' not found.", ) - src/agentscope/app/_router/_asr.py (12098 bytes)
# -*- coding: utf-8 -*- """Speech recognition endpoints for browser-recorded audio.""" import json from urllib.parse import quote from fastapi import ( APIRouter, Depends, File, Form, HTTPException, UploadFile, WebSocket, WebSocketDisconnect, ) from fastapi import status from pydantic import ValidationError from ..deps import ( get_current_user_id, get_download_secret, get_resource_access_service, ) from .._service import ( ResourceAccessService, get_asr_model, sign_download_token, verify_download_token, ) from ._schema import ( ListASRModelsRequest, ListASRModelsResponse, RealtimeASRStartRequest, RealtimeASRTokenRequest, RealtimeASRTokenResponse, TranscriptionResponse, ) from ...credential import CredentialFactory asr_router = APIRouter( tags=["asr"], responses={404: {"description": "Not found"}}, ) _MAX_AUDIO_UPLOAD_BYTES = 25 * 1024 * 1024 _REALTIME_TOKEN_TTL_SECONDS = 60 def _realtime_token_scope(credential_id: str, model: str) -> str: """Return the capability scope for one realtime ASR configuration.""" encoded_credential = quote(credential_id, safe="") encoded_model = quote(model, safe="") return f"/asr/realtime/{encoded_credential}/{encoded_model}" @asr_router.get( "/asr-model/", response_model=ListASRModelsResponse, summary="List ASR models under a credential provider", ) async def list_asr_models( body: ListASRModelsRequest = Depends(), ) -> ListASRModelsResponse: """Return batch and realtime ASR cards for a credential provider. Args: body (`ListASRModelsRequest`): The provider whose ASR models should be listed. Returns: `ListASRModelsResponse`: The available ASR model cards and their total count. Raises: `HTTPException`: If the requested credential provider is not registered. """ credential_cls = CredentialFactory.get_credential_class(body.provider) if credential_cls is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Provider {body.provider!r} not found.", ) models = credential_cls.list_asr_models() return ListASRModelsResponse(models=models, total=len(models)) @asr_router.post( "/asr/transcriptions", response_model=TranscriptionResponse, summary="Transcribe an uploaded audio recording", ) async def transcribe_audio( file: UploadFile = File(), credential_id: str = Form(), model: str = Form(), parameters: str = Form(default="{}"), user_id: str = Depends(get_current_user_id), access: ResourceAccessService = Depends(get_resource_access_service), ) -> TranscriptionResponse: """Transcribe one complete browser recording with a batch ASR model. Args: file (`UploadFile`): The uploaded audio recording. Files larger than 25 MiB are rejected. credential_id (`str`): The stored credential used to call the ASR provider. model (`str`): The batch ASR model name. parameters (`str`): Provider-specific parameters encoded as a JSON object. user_id (`str`): The authenticated viewer's user ID. access (`ResourceAccessService`): The service used to authorize and resolve the credential. Returns: `TranscriptionResponse`: The recognized text. Raises: `HTTPException`: If the upload is empty or too large, the parameters are invalid, or the credential and model cannot be used by the viewer. """ if file.size is not None and file.size > _MAX_AUDIO_UPLOAD_BYTES: raise HTTPException( status_code=status.HTTP_413_CONTENT_TOO_LARGE, detail="Audio file exceeds the 25 MiB upload limit.", ) audio = await file.read(_MAX_AUDIO_UPLOAD_BYTES + 1) if len(audio) > _MAX_AUDIO_UPLOAD_BYTES: raise HTTPException( status_code=status.HTTP_413_CONTENT_TOO_LARGE, detail="Audio file exceeds the 25 MiB upload limit.", ) if not audio: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="Audio file must not be empty.", ) try: parsed_parameters = json.loads(parameters) except json.JSONDecodeError as error: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="ASR parameters must be valid JSON.", ) from error if not isinstance(parsed_parameters, dict): raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail="ASR parameters must be a JSON object.", ) try: asr_model = await get_asr_model( user_id=user_id, credential_id=credential_id, model=model, access=access, parameters=parsed_parameters, ) except ValidationError as error: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=str(error), ) from error try: result = await asr_model.transcribe( audio=audio, filename=file.filename or "audio.webm", ) except ValueError as error: # A filename the model cannot encode is the caller's problem; every # other user-input failure on this route is already a 400. raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=str(error), ) from error return TranscriptionResponse( text=result.content.text if result.content is not None else "", ) @asr_router.post( "/asr/realtime/token", response_model=RealtimeASRTokenResponse, summary="Mint a short-lived realtime ASR WebSocket token", ) async def create_realtime_asr_token( body: RealtimeASRTokenRequest, user_id: str = Depends(get_current_user_id), access: ResourceAccessService = Depends(get_resource_access_service), download_secret: str = Depends(get_download_secret), ) -> RealtimeASRTokenResponse: """Authorize one credential and model before opening a WebSocket. The returned token is scoped to the requested credential and model and expires after a short interval. Args: body (`RealtimeASRTokenRequest`): The credential and realtime ASR model to authorize. user_id (`str`): The authenticated viewer's user ID. access (`ResourceAccessService`): The service used to authorize and resolve the credential. download_secret (`str`): The server secret used to sign the capability token. Returns: `RealtimeASRTokenResponse`: The signed token and its expiration timestamp. Raises: `HTTPException`: If the credential is unavailable to the viewer or does not support the requested realtime model. """ await get_asr_model( user_id=user_id, credential_id=body.credential_id, model=body.model, access=access, realtime=True, ) token, expires_at = sign_download_token( download_secret, user_id, _realtime_token_scope(body.credential_id, body.model), ttl=_REALTIME_TOKEN_TTL_SECONDS, ) return RealtimeASRTokenResponse( token=token, expires_at=expires_at, ) @asr_router.websocket("/asr/realtime") async def transcribe_realtime(websocket: WebSocket) -> None: """Proxy browser PCM audio to a server-side realtime ASR model. The connection requires a signed ``token`` query parameter. The first client frame must contain :class:`RealtimeASRStartRequest` JSON, followed by binary PCM16 audio frames and a final ``{"type": "stop"}`` control frame. The server emits ``ready``, ``transcript``, or ``error`` JSON frames and closes the connection after the final transcript. Args: websocket (`WebSocket`): The browser WebSocket connection carrying control and audio frames. """ await websocket.accept() try: start = RealtimeASRStartRequest.model_validate( await websocket.receive_json(), ) token = websocket.query_params.get("token") if token is None: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Realtime ASR token is required.", ) try: user_id = verify_download_token( websocket.app.state.download_secret, token, _realtime_token_scope(start.credential_id, start.model), ) except ValueError as error: raise HTTPException( status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid or expired realtime ASR token.", ) from error access = websocket.app.state.resource_access_service parameters = {**start.parameters, "sample_rate": start.sample_rate} asr_model = await get_asr_model( user_id=user_id, credential_id=start.credential_id, model=start.model, access=access, parameters=parameters, realtime=True, ) async with asr_model: await websocket.send_json({"type": "ready"}) while True: message = await websocket.receive() if message["type"] == "websocket.disconnect": return audio = message.get("bytes") if audio is not None: response = await asr_model.push(audio) await _send_transcript(websocket, response) continue text = message.get("text") if text is None: continue control = json.loads(text) if control.get("type") != "stop": raise ValueError("Unsupported realtime ASR control frame.") response = await asr_model.transcribe() await _send_transcript(websocket, response) await websocket.close(code=status.WS_1000_NORMAL_CLOSURE) return except WebSocketDisconnect: return except ValidationError as error: await _send_realtime_error(websocket, str(error)) except HTTPException as error: close_code = ( status.WS_1008_POLICY_VIOLATION if error.status_code in { status.HTTP_401_UNAUTHORIZED, status.HTTP_403_FORBIDDEN, } else status.WS_1011_INTERNAL_ERROR ) await _send_realtime_error( websocket, str(error.detail), close_code=close_code, ) except (json.JSONDecodeError, ValueError) as error: await _send_realtime_error(websocket, str(error)) except Exception as error: # pylint: disable=broad-exception-caught await _send_realtime_error(websocket, str(error)) async def _send_transcript(websocket: WebSocket, response: object) -> None: """Send one non-empty ASR response to the browser.""" content = getattr(response, "content", None) is_last = bool(getattr(response, "is_last", False)) text = content.text if content is not None else "" if text or is_last: await websocket.send_json( { "type": "transcript", "text": text, "is_last": is_last, }, ) async def _send_realtime_error( websocket: WebSocket, detail: str, close_code: int = status.WS_1011_INTERNAL_ERROR, ) -> None: """Report a realtime failure and close the browser connection.""" try: await websocket.send_json({"type": "error", "detail": detail}) await websocket.close(code=close_code) except RuntimeError: return - src/agentscope/app/_router/_background_task.py (3037 bytes)
# -*- coding: utf-8 -*- """Background-task router — read-only endpoints for task observability.""" from fastapi import APIRouter, Depends, HTTPException, Query, status from ..deps import get_background_task_manager, get_current_user_id from .._manager import BackgroundTaskManager from ._schema import ( BackgroundTaskInfo, ListBackgroundTasksResponse, ) from ._schema._background_task import to_info background_task_router = APIRouter( prefix="/background-tasks", tags=["background-tasks"], responses={404: {"description": "Not found"}}, ) @background_task_router.get( "", response_model=ListBackgroundTasksResponse, summary="List background tasks for the current user", ) async def list_background_tasks( session_id: str | None = Query( default=None, description="Optional session filter.", ), user_id: str = Depends(get_current_user_id), bg_manager: BackgroundTaskManager = Depends( get_background_task_manager, ), ) -> ListBackgroundTasksResponse: """List all background tasks (running and recently-completed) visible to the authenticated user. Args: session_id (`str | None`, optional): If provided, only return tasks belonging to this session. user_id (`str`): The authenticated user id (from ``X-User-ID`` header). bg_manager (`BackgroundTaskManager`): The application-wide background task manager. Returns: `ListBackgroundTasksResponse`: Tasks and their total count. """ tasks = await bg_manager.list_tasks( user_id=user_id, session_id=session_id, ) infos = [to_info(t) for t in tasks] return ListBackgroundTasksResponse(tasks=infos, total=len(infos)) @background_task_router.get( "/{task_id}", response_model=BackgroundTaskInfo, summary="Get a single background task by id", ) async def get_background_task( task_id: str, user_id: str = Depends(get_current_user_id), bg_manager: BackgroundTaskManager = Depends( get_background_task_manager, ), ) -> BackgroundTaskInfo: """Retrieve details of a single background task. Returns 404 when the task does not exist or belongs to a different user (no information leakage about task existence). Args: task_id (`str`): The unique task identifier. user_id (`str`): The authenticated user id (from ``X-User-ID`` header). bg_manager (`BackgroundTaskManager`): The application-wide background task manager. Returns: `BackgroundTaskInfo`: The task details. Raises: `HTTPException`: 404 if the task is not found or not owned by the user. """ task = await bg_manager.get_task(task_id, user_id=user_id) if task is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Background task '{task_id}' not found.", ) return to_info(task) - src/agentscope/app/_router/_channel.py (12678 bytes)
# -*- coding: utf-8 -*- """Channel HTTP API. GET /channels/types List channel types + schemas POST /channels/bindings Open a credential binding GET /channels/bindings/{id} Poll it, advancing one step POST /channels/bindings/{id}/cancel Abandon it GET /channels/ List the user's channels POST /channels/ Create a channel GET /channels/{id} Channel details PATCH /channels/{id} Update routing/session/config DELETE /channels/{id} Delete a channel POST /channels/{id}/enable Enable POST /channels/{id}/disable Disable GET /channels/{id}/status Aggregated runtime status GET /channels/{id}/chat_ids Known chats (for routing config) """ from fastapi import APIRouter, Depends, HTTPException, status from ..channel import ( ChannelError, ChannelClients, ChannelStatus, ChannelTypeRegistry, ChannelTypeSchema, ) from .._service import ( ChannelService, CredentialBindingError, CredentialBindingService, ) from .._service._credential_binding import BindingView from ..deps import ( get_channel_clients, get_credential_binding_service, get_channel_service, get_channel_type_registry, get_current_user_id, get_storage, ) from ..storage import ChannelRecord, StorageBase from ._schema import ( ChannelActionResponse, ChannelChatId, ChannelChatIdsResponse, ChannelResponse, ChannelSessionsResponse, CreateChannelRequest, StartCredentialBindingRequest, UpdateChannelRequest, ) channel_router = APIRouter(prefix="/channels", tags=["channels"]) def _to_response( record: ChannelRecord, registry: ChannelTypeRegistry, ) -> ChannelResponse: """Project a stored record into a client response (credentials hidden). Args: record (`ChannelRecord`): The stored channel record. registry (`ChannelTypeRegistry`): Used to derive the display-only ``platform_bot_id`` from the credentials. Returns: `ChannelResponse`: The safe, client-facing view. """ try: bot_id = registry.extract_platform_bot_id( record.channel_type, record.credentials, ) except ValueError: bot_id = "" return ChannelResponse( id=record.id, channel_type=record.channel_type, name=record.name, user_id=record.user_id, platform_bot_id=bot_id, enabled=record.enabled, platform_config=record.platform_config, routing=record.routing, session=record.session, created_at=record.created_at, updated_at=record.updated_at, ) async def _owned( channel_id: str, user_id: str, storage: StorageBase, ) -> ChannelRecord: """Load a channel and assert the caller owns it. Args: channel_id (`str`): The channel to load. user_id (`str`): The caller. storage (`StorageBase`): Application storage. Returns: `ChannelRecord`: The owned record. Raises: `HTTPException`: 404 if it does not exist, 403 if owned by someone else. """ record = await storage.get_channel(channel_id) if record is None: raise HTTPException(status.HTTP_404_NOT_FOUND, "Channel not found.") if record.user_id != user_id: raise HTTPException(status.HTTP_403_FORBIDDEN, "Access denied.") return record @channel_router.get("/types") async def list_channel_types( registry: ChannelTypeRegistry = Depends(get_channel_type_registry), ) -> list[ChannelTypeSchema]: """List supported channel types with their JSON schemas.""" return registry.list_types() @channel_router.get("/") async def list_channels( storage: StorageBase = Depends(get_storage), registry: ChannelTypeRegistry = Depends(get_channel_type_registry), user_id: str = Depends(get_current_user_id), ) -> list[ChannelResponse]: """List channels owned by the current user.""" records = await storage.list_channels(user_id) return [_to_response(r, registry) for r in records] @channel_router.post("/", status_code=status.HTTP_201_CREATED) async def create_channel( body: CreateChannelRequest, service: ChannelService = Depends(get_channel_service), registry: ChannelTypeRegistry = Depends(get_channel_type_registry), bindings: CredentialBindingService = Depends( get_credential_binding_service, ), user_id: str = Depends(get_current_user_id), ) -> ChannelResponse: """Create a channel, from a completed binding or from the body.""" credentials = body.credentials if body.credential_binding_id: try: credentials = await bindings.claim( user_id, body.credential_binding_id, body.channel_type, ) except CredentialBindingError as e: raise HTTPException(e.status_code, str(e)) from e try: record = await service.create( user_id=user_id, channel_type=body.channel_type, name=body.name, credentials=credentials, platform_config=body.platform_config, routing=body.routing, session=body.session, enabled=body.enabled, ) except ChannelError as e: raise HTTPException(e.status_code, str(e)) from e except ValueError as e: raise HTTPException(status.HTTP_400_BAD_REQUEST, str(e)) from e return _to_response(record, registry) @channel_router.post("/bindings", response_model=BindingView) async def start_credential_binding( body: StartCredentialBindingRequest, bindings: CredentialBindingService = Depends( get_credential_binding_service, ), user_id: str = Depends(get_current_user_id), ) -> BindingView: """Open a session and return the URL the operator must approve. Returns immediately; the client polls for the outcome, and each poll is what advances the session. """ try: return await bindings.start(user_id, body.channel_type) except CredentialBindingError as e: raise HTTPException(e.status_code, str(e)) from e @channel_router.get("/bindings/{binding_id}", response_model=BindingView) async def poll_credential_binding( binding_id: str, bindings: CredentialBindingService = Depends( get_credential_binding_service, ), user_id: str = Depends(get_current_user_id), ) -> BindingView: """Report the session, asking the platform once when due. Never returns the credentials themselves — those are handed over only by creating a channel with this ``binding_id``. """ try: return await bindings.poll(user_id, binding_id) except CredentialBindingError as e: raise HTTPException(e.status_code, str(e)) from e @channel_router.post("/bindings/{binding_id}/cancel") async def cancel_credential_binding( binding_id: str, bindings: CredentialBindingService = Depends( get_credential_binding_service, ), user_id: str = Depends(get_current_user_id), ) -> ChannelActionResponse: """Abandon the session, from whichever replica takes this call.""" try: await bindings.cancel(user_id, binding_id) except CredentialBindingError as e: raise HTTPException(e.status_code, str(e)) from e return ChannelActionResponse(status="cancelled") @channel_router.get("/{channel_id}") async def get_channel( channel_id: str, storage: StorageBase = Depends(get_storage), registry: ChannelTypeRegistry = Depends(get_channel_type_registry), user_id: str = Depends(get_current_user_id), ) -> ChannelResponse: """Get channel details.""" record = await _owned(channel_id, user_id, storage) return _to_response(record, registry) @channel_router.patch("/{channel_id}") async def update_channel( channel_id: str, body: UpdateChannelRequest, storage: StorageBase = Depends(get_storage), service: ChannelService = Depends(get_channel_service), registry: ChannelTypeRegistry = Depends(get_channel_type_registry), user_id: str = Depends(get_current_user_id), ) -> ChannelResponse: """Update routing / session / config / enabled.""" await _owned(channel_id, user_id, storage) updates = body.model_dump(exclude_unset=True) if not updates: raise HTTPException( status.HTTP_400_BAD_REQUEST, "No fields to update.", ) try: record = await service.update(channel_id, updates) except ChannelError as e: raise HTTPException(e.status_code, str(e)) from e return _to_response(record, registry) @channel_router.delete( "/{channel_id}", status_code=status.HTTP_204_NO_CONTENT, ) async def delete_channel( channel_id: str, storage: StorageBase = Depends(get_storage), service: ChannelService = Depends(get_channel_service), user_id: str = Depends(get_current_user_id), ) -> None: """Delete a channel.""" await _owned(channel_id, user_id, storage) try: await service.delete(channel_id) except ChannelError as e: raise HTTPException(e.status_code, str(e)) from e @channel_router.post("/{channel_id}/enable") async def enable_channel( channel_id: str, storage: StorageBase = Depends(get_storage), service: ChannelService = Depends(get_channel_service), user_id: str = Depends(get_current_user_id), ) -> ChannelActionResponse: """Enable a channel.""" await _owned(channel_id, user_id, storage) try: await service.set_enabled(channel_id, True) except ChannelError as e: raise HTTPException(e.status_code, str(e)) from e return ChannelActionResponse(status="enabled") @channel_router.post("/{channel_id}/disable") async def disable_channel( channel_id: str, storage: StorageBase = Depends(get_storage), service: ChannelService = Depends(get_channel_service), user_id: str = Depends(get_current_user_id), ) -> ChannelActionResponse: """Disable a channel.""" await _owned(channel_id, user_id, storage) try: await service.set_enabled(channel_id, False) except ChannelError as e: raise HTTPException(e.status_code, str(e)) from e return ChannelActionResponse(status="disabled") @channel_router.get("/{channel_id}/status") async def channel_status( channel_id: str, storage: StorageBase = Depends(get_storage), service: ChannelService = Depends(get_channel_service), user_id: str = Depends(get_current_user_id), ) -> ChannelStatus: """The channel's live connection status, from whichever node holds it — this replica need not be the one connected.""" await _owned(channel_id, user_id, storage) return await service.get_status(channel_id) @channel_router.get("/{channel_id}/sessions") async def list_channel_sessions( channel_id: str, storage: StorageBase = Depends(get_storage), user_id: str = Depends(get_current_user_id), ) -> ChannelSessionsResponse: """Sessions this channel spawned, newest first.""" await _owned(channel_id, user_id, storage) sessions = await storage.list_sessions_by_channel(user_id, channel_id) return ChannelSessionsResponse(sessions=sessions, total=len(sessions)) @channel_router.get("/{channel_id}/chat_ids") async def list_chat_ids( channel_id: str, storage: StorageBase = Depends(get_storage), service: ChannelService = Depends(get_channel_service), clients: ChannelClients = Depends(get_channel_clients), user_id: str = Depends(get_current_user_id), ) -> ChannelChatIdsResponse: """Known chats for routing config: platform list ∪ passively seen. The platform list is fetched over REST through a client, so it answers from a replica that holds no connection. """ await _owned(channel_id, user_id, storage) chats: list[ChannelChatId] = [] platform_ids: set[str] = set() channel = await clients.get(channel_id) for chat in await channel.list_bot_chats() if channel else []: cid = chat.get("chat_id", "") if cid: platform_ids.add(cid) chats.append( ChannelChatId( chat_id=cid, name=chat.get("name", ""), source="platform", ), ) for cid in await service.list_seen_chat_ids(channel_id): if cid not in platform_ids: chats.append(ChannelChatId(chat_id=cid, source="recorded")) return ChannelChatIdsResponse(chats=chats) - src/agentscope/app/_router/_chat.py (19008 bytes)
# -*- coding: utf-8 -*- """Chat router — fire-and-forget trigger for chat runs. The endpoint no longer returns an SSE stream. Instead, it kicks off a chat run as a background task and returns immediately. Events produced by the run are published to the message bus and delivered to the frontend via the long-lived ``GET /sessions/{sid}/stream`` SSE connection provided by the session router. Three trigger paths, deliberately asymmetric: - **New user message(s)** are appended to a per-session FIFO and drained by :class:`WakeupDispatcher`, one complete reply at a time. - **HITL results** (``UserConfirmResultEvent`` / ``ExternalExecutionResultEvent``) are *enqueued* onto the shared run-trigger queue and drained by the single :class:`WakeupDispatcher`. Routing the resume through the queue keeps the dispatcher the sole spawn site, so a resume can never collide with the worker's still-finishing parked run (the old 409 race) — the dispatcher serialises them. """ from typing import Annotated from fastapi import APIRouter, Depends, HTTPException, Path, Query, status from ..deps import ( get_chat_run_registry, get_chat_service, get_current_user_id, get_message_bus, get_storage, ) from ._schema import ( ChatQueueResponse, ChatRequest, ChatTriggerResponse, ReorderChatQueueRequest, SteerChatQueueItemRequest, UpdateChatQueueItemRequest, ) from .._manager import ChatRunRegistry from .._service import ( ChatService, SessionProjection, SubagentHitlProjector, ) from ..message_bus import MessageBus, MessageBusKeys from ..storage import StorageBase from .._bus_ops import ( ChatQueueBusyError, ChatQueueFullError, ChatSteeringUnavailableError, delete_chat_input, enqueue_chat_input, enqueue_run_trigger, list_chat_inputs, reorder_chat_inputs, steer_chat_input, update_chat_input, ) from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent from ...message import Msg chat_router = APIRouter( prefix="/chat", tags=["chat"], responses={404: {"description": "Not found"}}, ) async def _ensure_session( storage: StorageBase, user_id: str, agent_id: str, session_id: str, ) -> None: """Ensure the caller owns the target session before queue access. Args: storage (`StorageBase`): Persistent session storage. user_id (`str`): Authenticated user that must own the session. agent_id (`str`): Agent that must own the session. session_id (`str`): Session to validate. Raises: `HTTPException`: HTTP 404 when the session does not exist for this owner. """ session = await storage.get_session(user_id, agent_id, session_id) if session is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Session '{session_id}' not found.", ) @chat_router.get( "/queue", response_model=ChatQueueResponse, summary="List editable pending user turns", ) async def get_chat_queue( agent_id: Annotated[ str, Query(description="Agent that owns the target session."), ], session_id: Annotated[ str, Query(description="Session whose pending FIFO should be listed."), ], user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), message_bus: MessageBus = Depends(get_message_bus), ) -> ChatQueueResponse: """Return ordinary user turns that have not begun execution. Args: agent_id (`str`): Agent that owns the target session. session_id (`str`): Session whose editable pending FIFO should be returned. user_id (`str`): Injected authenticated user id. storage (`StorageBase`): Injected persistent session storage. message_bus (`MessageBus`): Injected message bus containing the pending FIFO. Returns: `ChatQueueResponse`: Complete editable pending queue in FIFO order. Raises: `HTTPException`: HTTP 404 if the session is not owned by the caller. """ await _ensure_session(storage, user_id, agent_id, session_id) items = await list_chat_inputs(message_bus, session_id) return ChatQueueResponse(items=items) @chat_router.patch( "/queue/order", response_model=ChatQueueResponse, summary="Reorder editable pending user turns", ) async def reorder_chat_queue( request: ReorderChatQueueRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), message_bus: MessageBus = Depends(get_message_bus), ) -> ChatQueueResponse: """Apply an exact FIFO permutation, rejecting stale snapshots. Args: request (`ReorderChatQueueRequest`): Target session and exact desired pending-item permutation. user_id (`str`): Injected authenticated user id. storage (`StorageBase`): Injected persistent session storage. message_bus (`MessageBus`): Injected message bus containing the pending FIFO. Returns: `ChatQueueResponse`: Complete editable queue after reordering. Raises: `HTTPException`: HTTP 404 if the session is not owned by the caller, HTTP 409 for a stale or invalid permutation, or HTTP 503 when the queue mutation lock cannot be acquired promptly. """ await _ensure_session( storage, user_id, request.agent_id, request.session_id, ) try: items = await reorder_chat_inputs( message_bus, user_id, request.session_id, request.agent_id, request.item_ids, ) except ValueError as exc: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=str(exc), ) from exc except ChatQueueBusyError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc), ) from exc return ChatQueueResponse(items=items) @chat_router.post( "/queue/{item_id}/steer", response_model=ChatQueueResponse, summary="Steer an active reply with one pending user turn", ) async def steer_chat_queue_item( item_id: Annotated[ str, Path(description="Stable id of the pending item to inject."), ], request: SteerChatQueueItemRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), message_bus: MessageBus = Depends(get_message_bus), ) -> ChatQueueResponse: """Reserve a pending item for non-interrupting reply steering. Args: item_id (`str`): Stable id of the pending item to inject. request (`SteerChatQueueItemRequest`): Target session, agent, and active reply id. user_id (`str`): Injected authenticated user id. storage (`StorageBase`): Injected persistent session storage. message_bus (`MessageBus`): Injected message bus containing queue and active-reply state. Returns: `ChatQueueResponse`: Complete queue snapshot with the selected item steering. Raises: `HTTPException`: HTTP 404 for a missing session, HTTP 409 for a stale reply or started item, or HTTP 503 when the queue is busy. """ await _ensure_session( storage, user_id, request.agent_id, request.session_id, ) try: items = await steer_chat_input( message_bus, user_id, request.session_id, request.agent_id, item_id, request.reply_id, ) except (LookupError, ChatSteeringUnavailableError) as exc: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=str(exc), ) from exc except ChatQueueBusyError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc), ) from exc return ChatQueueResponse(items=items) @chat_router.patch( "/queue/{item_id}", response_model=ChatQueueResponse, summary="Edit one pending user turn", ) async def update_chat_queue_item( item_id: Annotated[ str, Path(description="Stable id of the pending item to update."), ], request: UpdateChatQueueItemRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), message_bus: MessageBus = Depends(get_message_bus), ) -> ChatQueueResponse: """Replace a pending item; started items produce HTTP 409. Args: item_id (`str`): Stable id of the pending item to update. request (`UpdateChatQueueItemRequest`): Target session and replacement message payload. user_id (`str`): Injected authenticated user id. storage (`StorageBase`): Injected persistent session storage. message_bus (`MessageBus`): Injected message bus containing the pending FIFO. Returns: `ChatQueueResponse`: Complete editable queue after the update. Raises: `HTTPException`: HTTP 404 if the session is not owned by the caller, HTTP 409 if the item is no longer pending, or HTTP 503 if the queue is busy. """ await _ensure_session( storage, user_id, request.agent_id, request.session_id, ) try: items = await update_chat_input( message_bus, user_id, request.session_id, request.agent_id, item_id, request.input, ) except LookupError as exc: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=str(exc), ) from exc except ChatQueueBusyError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc), ) from exc return ChatQueueResponse(items=items) @chat_router.delete( "/queue/{item_id}", response_model=ChatQueueResponse, summary="Delete one pending user turn", ) async def delete_chat_queue_item( item_id: Annotated[ str, Path(description="Stable id of the pending item to delete."), ], agent_id: Annotated[ str, Query(description="Agent that owns the target session."), ], session_id: Annotated[ str, Query(description="Session whose pending item should be deleted."), ], user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), message_bus: MessageBus = Depends(get_message_bus), ) -> ChatQueueResponse: """Delete a pending item; started items produce HTTP 409. Args: item_id (`str`): Stable id of the pending item to delete. agent_id (`str`): Agent that owns the target session. session_id (`str`): Session whose pending item should be deleted. user_id (`str`): Injected authenticated user id. storage (`StorageBase`): Injected persistent session storage. message_bus (`MessageBus`): Injected message bus containing the pending FIFO. Returns: `ChatQueueResponse`: Complete editable queue after deletion. Raises: `HTTPException`: HTTP 404 if the session is not owned by the caller, HTTP 409 if the item is no longer pending, or HTTP 503 if the queue is busy. """ await _ensure_session(storage, user_id, agent_id, session_id) try: items = await delete_chat_input( message_bus, user_id, session_id, agent_id, item_id, ) except LookupError as exc: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=str(exc), ) from exc except ChatQueueBusyError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=str(exc), ) from exc return ChatQueueResponse(items=items) @chat_router.post( "/", response_model=ChatTriggerResponse, summary="Trigger a chat run (fire-and-forget)", ) async def chat( request: ChatRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), chat_service: ChatService = Depends(get_chat_service), chat_run_registry: ChatRunRegistry = Depends(get_chat_run_registry), message_bus: MessageBus = Depends(get_message_bus), ) -> ChatTriggerResponse: """Trigger a chat run for the specified session. Events produced during the run are published to the message bus and delivered to any active ``GET /sessions/{session_id}/stream`` SSE subscriber. The caller does **not** receive events from this endpoint's response body. Accepts the same ``input`` payloads as before: - ``Msg`` / ``list[Msg]``: new user message(s) — queued FIFO. - ``UserConfirmResultEvent`` / ``ExternalExecutionResultEvent``: resume a paused tool call (human-in-the-loop) — routed to the owning session and enqueued for the dispatcher. - ``None``: continue from current state — spawned directly. Args: request (`ChatRequest`): JSON body with ``agent_id``, ``session_id``, and ``input``. user_id (`str`): Injected user id. storage (`StorageBase`): Injected persistent storage used to verify session ownership. chat_service (`ChatService`): Injected application-wide chat service. chat_run_registry (`ChatRunRegistry`): Injected per-process chat-run registry. message_bus (`MessageBus`): Injected message bus, used to resolve subagent-confirm routing and to enqueue ordinary or resume triggers. Returns: `ChatTriggerResponse`: Reports ``queued`` for an accepted ordinary turn and ``started`` for continuation or control triggers. Raises: `HTTPException`: HTTP 404 if an ordinary-message session is not owned by the caller; HTTP 409 for a conflicting direct ``None`` continuation; HTTP 429 when a queue quota is full; or HTTP 503 when queue mutation is temporarily busy. """ # ------------------------------------------------------------------ # HITL resume — route to the owning session, then enqueue. # # A confirmation / external-result POSTed to a *lea - src/agentscope/app/_router/_credential.py (6654 bytes)
# -*- coding: utf-8 -*- """Credential router — CRUD endpoints for API key credentials.""" from fastapi import APIRouter, Depends, status from ..access import ResourceKind from ..deps import ( get_current_user_id, get_resource_access_service, get_storage, ) from ._schema import ( CreateCredentialRequest, CreateCredentialResponse, ListCredentialsResponse, ListCredentialSchemasResponse, UpdateCredentialRequest, ) from .._service import CredentialView, ResourceAccessService from ..storage import StorageBase from ...credential import CredentialFactory credential_router = APIRouter( prefix="/credential", tags=["credential"], responses={404: {"description": "Not found"}}, ) @credential_router.get( "/schemas", response_model=ListCredentialSchemasResponse, summary="List JSON schemas for all credential types", ) async def list_credential_schemas() -> ListCredentialSchemasResponse: """Return JSON schemas for all registered credential types. Used by the frontend to render credential creation forms dynamically. """ return ListCredentialSchemasResponse( schemas=CredentialFactory.list_schemas(), ) @credential_router.get( "/", response_model=ListCredentialsResponse, summary="List all credentials", ) async def list_credentials( user_id: str = Depends(get_current_user_id), access: ResourceAccessService = Depends(get_resource_access_service), ) -> ListCredentialsResponse: """Return all credential records visible to the authenticated user. Includes the caller's own credentials plus any credentials shared to them through :class:`ResourceAccessPolicyBase`. Shared entries have their secret ``data`` payload masked — only the discriminator and display name survive in the response — while runtime resolution (e.g. the chat model service) still sees the full payload. Args: user_id (`str`): Injected authenticated user ID. access (`ResourceAccessService`): Injected resource access service. Returns: `ListCredentialsResponse`: All visible credentials paired with editability and (for shared entries) redacted data. """ entries = await access.list_resource(user_id, ResourceKind.CREDENTIAL) return ListCredentialsResponse( credentials=entries, total=len(entries), ) @credential_router.post( "/", response_model=CreateCredentialResponse, status_code=status.HTTP_201_CREATED, summary="Create a new credential", ) async def create_credential( body: CreateCredentialRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), ) -> CreateCredentialResponse: """Store a new credential. Args: body (`CreateCredentialRequest`): Credential payload to store. user_id (`str`): Injected authenticated user ID. storage (`StorageBase`): Injected storage backend. Returns: `CreateCredentialResponse`: The server-assigned credential identifier. """ credential_id = await storage.upsert_credential( user_id, CredentialFactory.from_dict(body.data), ) return CreateCredentialResponse(credential_id=credential_id) @credential_router.patch( "/{credential_id}", response_model=CredentialView, summary="Update a credential", ) async def update_credential( credential_id: str, body: UpdateCredentialRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), access: ResourceAccessService = Depends(get_resource_access_service), ) -> CredentialView: """Replace the payload of an existing credential. Args: credential_id (`str`): The credential to update. body (`UpdateCredentialRequest`): New credential payload. user_id (`str`): Injected authenticated user ID. storage (`StorageBase`): Injected storage backend. access (`ResourceAccessService`): Injected access service — used to resolve the owning user and enforce the edit permission when a shared editor updates the credential. Returns: `CredentialView`: The updated credential record. Raises: `HTTPException`: 404 if the credential is not visible to the caller; 403 if visible but only readable. """ owner_id, _ = await access.resolve_for_edit( user_id, ResourceKind.CREDENTIAL, credential_id, ) credential = CredentialFactory.from_dict(body.data) credential.id = credential_id await storage.upsert_credential(owner_id, credential) # ``resolve_for_edit`` proved the record existed under ``owner_id`` # and the upsert above just wrote back to the same key, so the read # is a value refresh, not an existence check. If it still comes back # empty (e.g. a concurrent delete), surface an explicit server error # rather than relying on ``assert`` (which ``-O`` strips). updated = await storage.get_credential(owner_id, credential_id) if updated is None: raise RuntimeError( f"Credential {credential_id!r} for owner {owner_id!r} " "disappeared immediately after a successful upsert.", ) # Only reachable via ``resolve_for_edit``, so the caller has edit # permission by construction. return CredentialView.model_validate( {**updated.model_dump(), "editable": True}, ) @credential_router.delete( "/{credential_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete a credential", ) async def delete_credential( credential_id: str, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), access: ResourceAccessService = Depends(get_resource_access_service), ) -> None: """Permanently delete a credential. Args: credential_id (`str`): The credential to delete. user_id (`str`): Injected authenticated user ID. storage (`StorageBase`): Injected storage backend. access (`ResourceAccessService`): Injected access service — used to resolve the owning user and enforce the edit permission when a shared editor deletes the credential. Raises: `HTTPException`: 404 if the credential is not visible to the caller; 403 if visible but only readable. """ owner_id, _ = await access.resolve_for_edit( user_id, ResourceKind.CREDENTIAL, credential_id, ) await storage.delete_credential(owner_id, credential_id) - src/agentscope/app/_router/_embedding_model.py (1800 bytes)
# -*- coding: utf-8 -*- """The embedding model router.""" from fastapi import APIRouter, Depends, HTTPException, status from ._schema import ListEmbeddingModelsResponse, ListEmbeddingModelsRequest from ...credential import CredentialFactory embedding_model_router = APIRouter( prefix="/embedding-model", tags=["embedding-model"], responses={404: {"description": "Not found"}}, ) @embedding_model_router.get( "/", response_model=ListEmbeddingModelsResponse, summary=( "List all candidate embedding models under the given credential type" ), ) async def list_embedding_models( body: ListEmbeddingModelsRequest = Depends(), ) -> ListEmbeddingModelsResponse: """Return all candidate embedding models under the credential type. Unlike ``/knowledge_bases/embedding_models``, which narrows the list to what the knowledge base's dimension policy accepts, this endpoint reports the provider's full catalogue — it answers "what can this credential do", not "what can I build a KB with". Args: body (ListEmbeddingModelsRequest): The request body. Returns: `ListEmbeddingModelsResponse`: The response body. """ credential_cls = CredentialFactory.get_credential_class(body.provider) if credential_cls is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Provider '{body.provider}' not found.", ) embedding_cls = credential_cls.get_embedding_model_class() # Providers without embedding support report an empty catalogue # rather than 404 — "none available" is a valid answer here. models = [] if embedding_cls is None else embedding_cls.list_models() return ListEmbeddingModelsResponse(models=models, total=len(models)) - src/agentscope/app/_router/_health.py (3324 bytes)
# -*- coding: utf-8 -*- """The health router.""" from fastapi import APIRouter, Depends, Request, Response, status from ._schema import ComponentStatus, HealthResponse from ..deps import get_current_user_id health_router = APIRouter(tags=["health"]) # Attached by ``create_app`` before the server starts serving. _EAGER_COMPONENTS = ("storage", "message_bus", "workspace_manager") # Built during the lifespan startup, in the order they are created. _LIFESPAN_COMPONENTS = ( "background_task_manager", "chat_run_registry", "scheduler_manager", "resource_access_service", "chat_service", "session_service", ) # Optional hubs, attached eagerly — empty means the deployment # registered none, which is a healthy state, not a failure. _OPTIONAL_HUBS = ("mcp_hubs", "skill_hubs") @health_router.get( "/health", response_model=HealthResponse, summary="Report service liveness and per-component readiness", ) async def get_health( request: Request, response: Response, _: str = Depends(get_current_user_id), ) -> HealthResponse: """Report whether the service is ready to serve requests. The check is deliberately I/O-free — it only inspects what is attached to ``app.state``, so probing it never touches Redis, the database or a workspace backend. Under a plain ``uvicorn.run(app)`` the ``not_ready`` status is effectively unreachable: uvicorn completes the lifespan startup before it accepts connections, so anything that reaches this handler already has the lifespan components in place. What it does catch is the mount-as-sub-app deployment documented in :func:`~agentscope.app.create_app` — Starlette does not run a mounted sub-app's lifespan, so every lifespan component stays missing and all business endpoints are broken. Reporting 503 here turns that silent misconfiguration into one clear signal. Args: request (`Request`): The incoming FastAPI request. response (`Response`): The outgoing response, whose status code is downgraded to ``503`` when the service is not ready. Returns: `HealthResponse`: The overall status, API version and the per-component readiness map. """ state = request.app.state components: dict[str, ComponentStatus] = { name: "ok" if getattr(state, name, None) is not None else "not_ready" for name in _EAGER_COMPONENTS + _LIFESPAN_COMPONENTS } for name in _OPTIONAL_HUBS: components[name] = "ok" if getattr(state, name, None) else "disabled" # The KB feature is off when no manager was passed to create_app; only # when it is on does a missing service mean the startup fell short. if getattr(state, "knowledge_base_manager", None) is None: components["knowledge_base"] = "disabled" elif getattr(state, "knowledge_base_service", None) is not None: components["knowledge_base"] = "ok" else: components["knowledge_base"] = "not_ready" ready = all(value != "not_ready" for value in components.values()) if not ready: response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE return HealthResponse( status="ok" if ready else "not_ready", version=request.app.version, components=components, ) - src/agentscope/app/_router/_hub.py (9561 bytes)
# -*- coding: utf-8 -*- """Hub router — browse resource hubs and install from them. The frontend flow is three levels deep: list the hubs, browse one hub's cards, then install a chosen card into the caller's library. Cards are never merged across hubs, which keeps ranking a per-hub concern. Installing is user-level for both kinds — nothing here touches a workspace. See ``_mcp.py`` / ``_skill.py`` for the libraries it writes. """ from typing import TypeVar from fastapi import APIRouter, Depends, HTTPException, Query, status from ..deps import ( get_current_user_id, get_mcp_hubs, get_skill_hubs, get_storage, ) from ..hub import ( HubBase, MCPCard, MCPHubBase, MCPHubPage, SkillCard, SkillHubBase, SkillHubPage, ) from .._service import MCPRenderError, render_mcp from ..storage import MCPRecord, SkillRecord, StorageBase from ._schema import HubInfo, InstallMCPRequest, MCPView, SkillView hub_router = APIRouter(prefix="/hub", tags=["hub"]) HubT = TypeVar("HubT", bound=HubBase) def _pick_hub(hubs: dict[str, HubT], hub_id: str) -> HubT: """Return the hub under ``hub_id`` or raise 404. Args: hubs (`dict[str, HubT]`): The registered hubs keyed by id. hub_id (`str`): The requested hub id. Returns: `HubT`: The matching hub, keeping its concrete type. Raises: `HTTPException`: ``404`` when no hub is registered under ``hub_id``. """ hub = hubs.get(hub_id) if hub is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Hub {hub_id!r} is not registered.", ) return hub def _describe(hubs: dict) -> list[HubInfo]: """Render the hub picker entries in a stable order. Args: hubs (`dict`): The registered hubs keyed by id. Returns: `list[HubInfo]`: One entry per hub, ordered by id. """ return [ HubInfo( hub_id=hub.hub_id, display_name=hub.display_name, description=hub.description, icon_url=hub.icon_url, ) for _, hub in sorted(hubs.items()) ] # --------------------------------------------------------------------------- # MCP hubs # --------------------------------------------------------------------------- @hub_router.get("/mcp") async def list_mcp_hubs( hubs: dict[str, MCPHubBase] = Depends(get_mcp_hubs), ) -> list[HubInfo]: """Return every registered MCP hub.""" return _describe(hubs) @hub_router.get("/mcp/{hub_id}/cards") async def list_mcp_cards( hub_id: str, *, q: str | None = Query(default=None), cursor: str | None = Query(default=None), limit: int = Query(default=20, ge=1, le=200), user_id: str = Depends(get_current_user_id), hubs: dict[str, MCPHubBase] = Depends(get_mcp_hubs), ) -> MCPHubPage: """Browse or search one MCP hub's catalog.""" hub = _pick_hub(hubs, hub_id) return await hub.list_mcps(user_id, q=q, cursor=cursor, limit=limit) @hub_router.get("/mcp/{hub_id}/cards/{card_id}") async def get_mcp_card( hub_id: str, card_id: str, *, user_id: str = Depends(get_current_user_id), hubs: dict[str, MCPHubBase] = Depends(get_mcp_hubs), ) -> MCPCard: """Return one MCP card, including the inputs the user must fill.""" hub = _pick_hub(hubs, hub_id) try: return await hub.get_mcp(user_id, card_id) except KeyError as e: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Hub {hub_id!r} has no MCP {card_id!r}.", ) from e @hub_router.post( "/mcp/{hub_id}/cards/{card_id}/install", status_code=status.HTTP_201_CREATED, ) async def install_mcp( hub_id: str, card_id: str, body: InstallMCPRequest, *, user_id: str = Depends(get_current_user_id), hubs: dict[str, MCPHubBase] = Depends(get_mcp_hubs), storage: StorageBase = Depends(get_storage), ) -> MCPView: """Fill a card's template and add the result to the user's library. Installing is a user-level act with no workspace involved — putting the MCP into a session's workspace is separate and explicit. The record keeps ``(hub_id, card_id)`` so the library can later answer "where did this come from" and "is there a newer version". Note that the config is not connection-tested here, so a mistyped API key surfaces on first use rather than now. Testing it would mean connecting from the app process, and a stdio MCP would then spawn its command here instead of in the workspace sandbox. """ hub = _pick_hub(hubs, hub_id) try: card = await hub.get_mcp(user_id, card_id) except KeyError as e: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Hub {hub_id!r} has no MCP {card_id!r}.", ) from e try: client = render_mcp(card, body.values, body.name) except MCPRenderError as e: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=str(e), ) from e record = MCPRecord( user_id=user_id, client=client, values=body.values, display_name=card.display_name, description=card.description, tags=card.tags, author=card.author, icon_url=card.icon_url, url=card.url, hub_id=card.hub_id, card_id=card.id, version=card.version, ) try: await storage.upsert_mcp(user_id, record) except ValueError as e: # The name is unique per user, so a clash is the caller's to # resolve by passing a different one. raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=( f"{e} Pass a different 'name' to install it alongside " f"the existing one." ), ) from e return MCPView.from_record(record) # --------------------------------------------------------------------------- # Skill hubs # --------------------------------------------------------------------------- @hub_router.get("/skill") async def list_skill_hubs( hubs: dict[str, SkillHubBase] = Depends(get_skill_hubs), ) -> list[HubInfo]: """Return every registered skill hub.""" return _describe(hubs) @hub_router.get("/skill/{hub_id}/cards") async def list_skill_cards( hub_id: str, *, q: str | None = Query(default=None), cursor: str | None = Query(default=None), limit: int = Query(default=20, ge=1, le=200), user_id: str = Depends(get_current_user_id), hubs: dict[str, SkillHubBase] = Depends(get_skill_hubs), ) -> SkillHubPage: """Browse or search one skill hub's catalog.""" hub = _pick_hub(hubs, hub_id) return await hub.list_skills(user_id, q=q, cursor=cursor, limit=limit) @hub_router.post( "/skill/{hub_id}/cards/{card_id:path}/install", status_code=status.HTTP_201_CREATED, ) async def install_skill( hub_id: str, card_id: str, *, name: str | None = Query(default=None), user_id: str = Depends(get_current_user_id), hubs: dict[str, SkillHubBase] = Depends(get_skill_hubs), storage: StorageBase = Depends(get_storage), ) -> SkillView: """Add a skill card to the user's library. Mirrors the MCP install: user-level, no workspace involved. The archive is not downloaded here — only the card's metadata is recorded, and the files are fetched when the skill is actually put into a workspace. So a hub that has since dropped the card fails then rather than now. """ hub = _pick_hub(hubs, hub_id) try: card = await hub.get_skill(user_id, card_id) except KeyError as e: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Hub {hub_id!r} has no skill {card_id!r}.", ) from e record = SkillRecord( user_id=user_id, name=name or card.name, display_name=card.display_name, description=card.description, tags=card.tags, author=card.author, icon_url=card.icon_url, url=card.url, markdown=card.markdown or "", hub_id=card.hub_id, card_id=card.id, version=card.version, ) try: await storage.upsert_skill(user_id, record) except ValueError as e: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=( f"{e} Pass a different 'name' to install it alongside " f"the existing one." ), ) from e return SkillView.from_record(record) # Keep this catch-all path route after the more specific ``/install`` route. # This keeps route precedence explicit and protects specific routes from # accidental shadowing as more card actions are added. @hub_router.get("/skill/{hub_id}/cards/{card_id:path}") async def get_skill_card( hub_id: str, card_id: str, *, user_id: str = Depends(get_current_user_id), hubs: dict[str, SkillHubBase] = Depends(get_skill_hubs), ) -> SkillCard: """Return one skill card, including its ``SKILL.md`` body.""" hub = _pick_hub(hubs, hub_id) try: return await hub.get_skill(user_id, card_id) except KeyError as e: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Hub {hub_id!r} has no skill {card_id!r}.", ) from e - src/agentscope/app/_router/_knowledge_base.py (34107 bytes)
# -*- coding: utf-8 -*- """Knowledge base router — manage knowledge bases and their documents. A knowledge base is the user-facing concept; physically each one maps to a single vector store collection (in the MVP isolation strategy). The HTTP layer is intentionally thin — every endpoint translates the request into a single :class:`~agentscope.app._service. KnowledgeBaseService` call and returns the result. """ from urllib.parse import quote from fastapi import ( APIRouter, Depends, File, Form, Header, HTTPException, Path, Query, UploadFile, status, ) from fastapi.responses import StreamingResponse from ..access import ResourceKind from ..deps import ( get_current_user_id, get_download_secret, get_knowledge_base_manager, get_knowledge_base_service, get_knowledge_chunkers, get_knowledge_parsers, get_resource_access_service, ) from ._schema import ( ChunkerInfo, DocumentDownloadTokenResponse, ListDocumentChunksResponse, CreateKnowledgeBaseRequest, CreateKnowledgeBaseResponse, KbEmbeddingProvider, KbMiddlewareParametersSchemaResponse, KnowledgeDocumentView, ListChunkersResponse, ListKbEmbeddingModelsResponse, ListKnowledgeBasesResponse, ListKnowledgeDocumentsResponse, ListKnowledgeDocumentStatusResponse, ListSupportedContentTypesResponse, SearchKnowledgeBaseRequest, SearchKnowledgeBaseResponse, UpdateKnowledgeBaseRequest, UploadKnowledgeDocumentResponse, ) from ...credential import CredentialFactory from ..rag.knowledge_base_manager import KnowledgeBaseManagerBase from .._service import ( KnowledgeBaseService, sign_download_token, verify_download_token, KnowledgeBaseView, ResourceAccessService, ) from ...middleware import RAGMiddleware from ...rag import ChunkerBase, ParserBase knowledge_base_router = APIRouter( prefix="/knowledge_bases", tags=["knowledge_bases"], responses={404: {"description": "Not found"}}, ) @knowledge_base_router.get( "/embedding_models", response_model=ListKbEmbeddingModelsResponse, summary="List embedding models compatible with the KB dimension policy", ) async def list_kb_embedding_models( user_id: str = Depends(get_current_user_id), access: "ResourceAccessService" = Depends(get_resource_access_service), manager: "KnowledgeBaseManagerBase" = Depends( get_knowledge_base_manager, ), ) -> ListKbEmbeddingModelsResponse: """List embedding models the user can pick at KB-creation time. Walks every credential visible to the caller (own + shared via the resource access policy), looks up each provider's embedding model class, gathers its model cards, and projects each card through the manager's :class:`DimensionPolicy`. Incompatible cards are dropped; matryoshka cards under a ``FIXED`` / ``LOCKED_BY_EXISTING`` policy are narrowed to the locked dimension. Providers that end up with zero compatible models are omitted from the response entirely. Args: user_id (`str`): Injected authenticated user ID. access (`ResourceAccessService`): Injected resource access service; enumerates visible credentials (own + shared) so KB creation works against shared credentials too. manager (`KnowledgeBaseManagerBase`): Injected knowledge base manager. Returns: `ListKbEmbeddingModelsResponse`: One entry per credential with at least one compatible embedding model, plus the policy used for filtering. """ policy = await manager.get_dimension_policy() credentials = await access.list_resource(user_id, ResourceKind.CREDENTIAL) providers: list[KbEmbeddingProvider] = [] for credential in credentials: credential_type = credential.data.get("type") if not credential_type: continue credential_cls = CredentialFactory.get_credential_class( credential_type, ) if credential_cls is None: continue embedding_cls = credential_cls.get_embedding_model_class() if embedding_cls is None: continue filtered = [] for card in embedding_cls.list_models(): projected = policy.filter_card(card) if projected is not None: filtered.append(projected) if not filtered: continue providers.append( KbEmbeddingProvider(credential=credential, models=filtered), ) return ListKbEmbeddingModelsResponse(providers=providers, policy=policy) @knowledge_base_router.get( "/chunkers", response_model=ListChunkersResponse, summary="List available chunker types and their parameter schemas", ) async def list_chunkers( _: str = Depends(get_current_user_id), chunker_classes: list[type[ChunkerBase]] = Depends( get_knowledge_chunkers, ), ) -> ListChunkersResponse: """List every available chunker type with its parameter schema. The front-end uses this to populate the chunker selector and to render a dynamic parameter form when creating a knowledge base. Args: _ (`str`): Injected authenticated user ID; only used to gate the endpoint behind authentication. chunker_classes (`list[type[ChunkerBase]]`): The chunker classes configured via ``create_app(knowledge_chunkers=...)``. Returns: `ListChunkersResponse`: All available chunker types with their JSON Schemas. """ return ListChunkersResponse( chunkers=[ ChunkerInfo( type=cls.chunker_type, parameter_schema=cls.Parameters.model_json_schema(), ) for cls in chunker_classes ], ) @knowledge_base_router.get( "/middleware/parameters_schema", response_model=KbMiddlewareParametersSchemaResponse, summary="JSON Schema for the KB middleware's tunable parameters", ) async def get_kb_middleware_parameters_schema( _: str = Depends(get_current_user_id), ) -> KbMiddlewareParametersSchemaResponse: """Return the parameter schema for :class:`agentscope.middleware.RAGMiddleware`. The schema is shaped like every other ``parameter_schema`` served by this service — title / description / default / enum / minimum / maximum — so the front-end can render the session-level KB attachment form with the same schema-driven component used for model parameters. Args: _ (`str`): Injected authenticated user ID; only used to gate the endpoint behind authentication. Returns: `KbMiddlewareParametersSchemaResponse`: The JSON Schema describing the middleware's user-tunable parameters. """ return KbMiddlewareParametersSchemaResponse( parameter_schema=(RAGMiddleware.Parameters.model_json_schema()), ) @knowledge_base_router.get( "/supported_content_types", response_model=ListSupportedContentTypesResponse, summary="List file types the configured parsers can ingest", ) async def list_supported_content_types( _: str = Depends(get_current_user_id), parsers: list[ParserBase] | dict[str, ParserBase] = Depends( get_knowledge_parsers, ), ) -> ListSupportedContentTypesResponse: """Advertise the union of media types and filename extensions every registered parser accepts. Used by the front-end to populate the document picker's ``accept`` attribute and to reject drag-dropped files whose extension lies outside the supported set before the upload starts. Routing on upload still goes through the media type — this endpoint is a capability hint, not authoritative dispatch. Args: _ (`str`): Injected authenticated user ID; only used to gate the endpoint behind authentication. parsers (`list[ParserBase] | dict[str, ParserBase]`): Injected parser registry — the same value the index worker uses to dispatch uploads. Returns: `ListSupportedContentTypesResponse`: Deduplicated, sorted unions of ``media_types`` and ``extensions``. """ parser_iter = parsers.values() if isinstance(parsers, dict) else parsers media_types: set[str] = set() extensions: set[str] = set() for parser in parser_iter: media_types.update(parser.supported_media_types) extensions.update(parser.supported_extensions()) return ListSupportedContentTypesResponse( media_types=sorted(media_types), extensions=sorted(extensions), ) # ---------------------------------------------------------------------- # Knowledge base management # ---------------------------------------------------------------------- @knowledge_base_router.post( "/", response_model=CreateKnowledgeBaseResponse, status_code=status.HTTP_201_CREATED, summary="Create a new knowledge base", ) async def create_knowledge_base( body: CreateKnowledgeBaseRequest, user_id: str = Depends(get_current_user_id), service: "KnowledgeBaseService" = Depends(get_knowledge_base_service), ) -> CreateKnowledgeBaseResponse: """Create a new knowledge base for the authenticated user. Allocates a fresh vector store collection sized to the embedding model's output dimension and persists the knowledge base record. Args: body (`CreateKnowledgeBaseRequest`): Knowledge base name, description, and embedding model configuration. user_id (`str`): Injected authenticated user ID. service (`KnowledgeBaseService`): Injected knowledge base service. Returns: `CreateKnowledgeBaseResponse`: The server-assigned knowledge base identifier. """ record = await service.create_knowledge_base( user_id=user_id, name=body.name, description=body.description, embedding_model_config=body.embedding_model_config, chunker_config=body.chunker_config, ) return CreateKnowledgeBaseResponse(knowledge_base_id=record.id) @knowledge_base_router.get( "/", response_model=ListKnowledgeBasesResponse, summary="List the caller's knowledge bases", ) async def list_knowledge_bases( id: str # pylint: disable=redefined-builtin # noqa: A002 | None = Query( default=None, description=( "Filter down to one knowledge base — the list endpoint " "doubles as get-single, RAGFlow style." ), ), name: str | None = Query( default=None, description="Case-insensitive substring filter on the name.", ), page: int = Query(default=1, ge=1, description="1-based page number."), page_size: int = Query(default=30, ge=1, le=128), orderby: str = Query( default="create_time", pattern="^(create_time|update_time)$", ), desc: bool = Query(default=True, description="Sort newest first."), user_id: str = Depends(get_current_user_id), service: "KnowledgeBaseService" = Depends(get_knowledge_base_service), ) -> ListKnowledgeBasesResponse: """Return the caller's knowledge bases, filtered and paginated. Includes the caller's own knowledge bases plus any shared to them through :class:`ResourceAccessPolicyBase`. Each entry carries an ``editable`` flag (``read`` grants search + attach; ``edit`` also grants document add/delete and metadata update) plus the aggregated document / chunk / per-status counts and the resolved ``credential_name`` a detail page needs — the list is the single source of truth; there is no separate get-single endpoint. Args: id (`str | None`, optional): Filter down to one knowledge base by id. name (`str | None`, optional): Case-insensitive substring filter on the display name. page (`int`, defaults to ``1``): 1-based page number. page_size (`int`, defaults to ``30``): Knowledge bases per page (max 128). orderby (`str`, defaults to ``"create_time"``): Sort key — ``"create_time"`` or ``"update_time"``. desc (`bool`, defaults to ``True``): Sort newest first. user_id (`str`): Injected authenticated user ID. service (`KnowledgeBaseService`): Injected knowledge base service. Returns: `ListKnowledgeBasesResponse`: The requested page of views plus the filtered total. """ views, total = await service.list_knowledge_base_views( user_id, knowledge_base_id=id, name=name, page=page, page_size=page_size, orderby=orderby, desc=desc, ) return ListKnowledgeBasesResponse( knowledge_bases=views, total=total, page=page, page_size=page_size, ) @knowledge_base_router.patch( "/{knowledge_base_id}", response_model=KnowledgeBaseView, summary="Update mutable fields on a knowledge base", ) async def update_knowledge_base( body: UpdateKnowledgeBaseRequest, knowledge_base_id: str = Path(description="The knowledge base id."), user_id: str = Depends(get_current_user_id), service: "KnowledgeBaseService" = Depends(get_knowledge_base_service), ) -> KnowledgeBaseView: """Update mutable fields on a knowledge base. Only ``name`` and ``description`` can be updated. The embedding model configuration is pinned at creation time and cannot be changed. Args: body (`UpdateKnowledgeBaseRequest`): The fields to update; omitted fields stay unchanged. knowledge_base_id (`str`): The knowledge base to update. user_id (`str`): Injected authenticated user ID. service (`KnowledgeBaseService`): Injected knowledge base service. Returns: `KnowledgeBaseView`: The knowledge base record after the update. """ record = await service.update_knowledge_base( user_id=user_id, knowledge_base_id=knowledge_base_id, name=body.name, description=body.description, ) # Only reachable via ``_require_edit`` inside the service, so the # caller definitionally has edit permission. return KnowledgeBaseView.model_validate( {**record.model_dump(), "editable": True}, ) @knowledge_base_router.delete( "/{knowledge_base_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete a knowledge base", ) async def delete_knowledge_base( knowledge_base_id: str = Path(description="The knowledge base id."), user_id: str = Depends(get_current_user_id), service: "KnowledgeBaseService" = Depends(get_knowledge_base_service), ) -> None: """Pe - src/agentscope/app/_router/_mcp.py (5338 bytes)
# -*- coding: utf-8 -*- """MCP router — the user's own library of installed MCPs. This is the user-level collection an install lands in, distinct from ``/workspace/mcp``, which manages the MCPs of one session's workspace. Installing from a hub only writes here; putting an MCP into a workspace stays a separate, explicit act. """ from fastapi import APIRouter, Depends, HTTPException, status from pydantic import ValidationError from ..deps import get_current_user_id, get_mcp_hubs, get_storage from ..hub import MCPHubBase from .._service import MCPRenderError, render_mcp from ..storage import StorageBase from ...mcp import MCPClient from ._schema import MCPView, UpdateMCPRequest mcp_router = APIRouter(prefix="/mcp", tags=["mcp"]) @mcp_router.get("") async def list_mcps( user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), ) -> list[MCPView]: """Return every MCP the user has installed, ordered by name.""" records = await storage.list_mcps(user_id) return sorted( (MCPView.from_record(r) for r in records), key=lambda view: view.name, ) @mcp_router.patch("/{mcp_id}") async def update_mcp( mcp_id: str, body: UpdateMCPRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), hubs: dict[str, MCPHubBase] = Depends(get_mcp_hubs), ) -> MCPView: """Rename, enable/disable, or re-key an installed MCP. Changing a secret is a re-render, not a field edit: an API key can sit anywhere in the config — inside a URL, a header, an env var — so the card's template plus the merged answers is the only thing that knows where to put it. Raises: `HTTPException`: 404 if the MCP is not in the caller's library, 400 if the MCP has no card to re-render from, 409 if the new name is taken, or 422 if the name is not made of ``[a-zA-Z0-9_-]``. """ record = await storage.get_mcp(user_id, mcp_id) if record is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"No installed MCP with id {mcp_id!r}.", ) if body.values is not None: hub = hubs.get(record.hub_id or "") if hub is None or record.card_id is None: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=( "This MCP has no card to re-render from — its hub is " "not registered, or it was added by hand." ), ) try: card = await hub.get_mcp(user_id, record.card_id) except KeyError as e: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=( f"Hub {record.hub_id!r} no longer has the card this " f"MCP was installed from." ), ) from e # Merged, not replaced: the client sends only what changed, and # a write-only field the form did not echo back must survive. merged = {**record.values, **body.values} try: record.client = render_mcp( card, merged, body.name or record.client.name, ) except MCPRenderError as e: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=str(e), ) from e record.values = merged record.version = card.version elif body.name is not None: # ``MCPClient`` checks its name in ``model_post_init``, which a # plain attribute assignment skips; rebuild the client through # ``model_validate`` so an illegal name is refused here. Stored # as-is it would fail the same check on the next read, turning # every route that loads the library into a 500. try: record.client = MCPClient.model_validate( {**record.client.model_dump(), "name": body.name}, ) except ValidationError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc), ) from exc if body.enabled is not None: record.enabled = body.enabled try: await storage.upsert_mcp(user_id, record) except ValueError as e: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=str(e), ) from e return MCPView.from_record(record) @mcp_router.delete("/{mcp_id}", status_code=status.HTTP_204_NO_CONTENT) async def delete_mcp( mcp_id: str, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), ) -> None: """Remove an MCP from the user's library. Workspaces that already hold this MCP keep it — the workspace relation is derived by name, not a foreign key, and tearing down a live stateful MCP session as a side effect of a library edit would surprise the user. """ if not await storage.delete_mcp(user_id, mcp_id): raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"No installed MCP with id {mcp_id!r}.", ) - src/agentscope/app/_router/_model.py (1135 bytes)
# -*- coding: utf-8 -*- """The model router.""" from fastapi import APIRouter, Depends, HTTPException, status from ._schema import ListModelsResponse, ListModelsRequest from ...credential import CredentialFactory model_router = APIRouter( prefix="/model", tags=["model"], responses={404: {"description": "Not found"}}, ) @model_router.get( "/", response_model=ListModelsResponse, summary="List all candidate models under the given credential type", ) async def list_models( body: ListModelsRequest = Depends(), ) -> ListModelsResponse: """Return all candidate models under the given credential type. Args: body (ListModelsRequest): The request body. Returns: `ListModelsResponse`: The response body. """ credential_cls = CredentialFactory.get_credential_class(body.provider) if credential_cls is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Provider '{body.provider}' not found.", ) models = credential_cls.list_models() return ListModelsResponse(models=models, total=len(models)) - src/agentscope/app/_router/_realtime.py (10406 bytes)
# -*- coding: utf-8 -*- """Realtime voice model discovery and WebRTC negotiation endpoints.""" import asyncio from typing import Any from weakref import WeakValueDictionary from fastapi import APIRouter, Depends, HTTPException, Request, status from ...agent import RealtimeAgent from ...credential import CredentialFactory from ..deps import ( get_current_user_id, get_message_bus, get_resource_access_service, get_realtime_service, get_storage, ) from ..message_bus import MessageBus, MessageBusKeys from ..storage import StorageBase from .._service import ( RealtimeService, ResourceAccessService, get_realtime_model, ) from ._schema import ( ListRealtimeModelsRequest, ListRealtimeModelsResponse, RealtimeConfigResponse, RealtimeOfferRequest, RealtimeOfferResponse, ) realtime_router = APIRouter( prefix="/realtime", tags=["realtime"], responses={404: {"description": "Not found"}}, ) _SESSION_LOCK_ACQUIRE_TIMEOUT_SECONDS = 1.0 @realtime_router.get( "/models", response_model=ListRealtimeModelsResponse, summary="List realtime models for a credential provider", ) async def list_realtime_models( body: ListRealtimeModelsRequest = Depends(), ) -> ListRealtimeModelsResponse: """Return realtime model cards supported by a credential provider.""" credential_cls = CredentialFactory.get_credential_class(body.provider) if credential_cls is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Provider {body.provider!r} not found.", ) models = credential_cls.list_realtime_models() return ListRealtimeModelsResponse(models=models, total=len(models)) @realtime_router.get( "/config", response_model=RealtimeConfigResponse, summary="Get browser WebRTC configuration", ) async def get_realtime_config( request: Request, _: str = Depends(get_current_user_id), ) -> RealtimeConfigResponse: """Return deployment-provided ICE servers for browser negotiation.""" return RealtimeConfigResponse( ice_servers=request.app.state.realtime_ice_servers, ) @realtime_router.post( "/sessions/{session_id}/offer", response_model=RealtimeOfferResponse, summary="Start a realtime session from a WebRTC offer", ) async def create_realtime_offer( session_id: str, body: RealtimeOfferRequest, request: Request, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), message_bus: MessageBus = Depends(get_message_bus), access: ResourceAccessService = Depends(get_resource_access_service), realtime_service: RealtimeService = Depends(get_realtime_service), ) -> RealtimeOfferResponse: """Negotiate one browser peer connection for a persisted session.""" connection_key = (user_id, session_id) offer_locks: WeakValueDictionary[ tuple[str, str], asyncio.Lock, ] = request.app.state.realtime_offer_locks offer_lock = offer_locks.setdefault(connection_key, asyncio.Lock()) async with offer_lock: return await _create_realtime_offer( session_id=session_id, body=body, request=request, user_id=user_id, storage=storage, message_bus=message_bus, access=access, realtime_service=realtime_service, ) async def _create_realtime_offer( *, session_id: str, body: RealtimeOfferRequest, request: Request, user_id: str, storage: StorageBase, message_bus: MessageBus, access: ResourceAccessService, realtime_service: RealtimeService, ) -> RealtimeOfferResponse: """Create one offer while this process serializes session starts.""" agent_record = await access.resolve_agent(user_id, body.agent_id) session = await storage.get_session( user_id, body.agent_id, session_id, ) if session is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Session {session_id!r} not found.", ) connection_key = (user_id, session_id) connections: dict[ tuple[str, str], Any, ] = request.app.state.realtime_connections previous = connections.get(connection_key) if previous is not None: await previous.close() # The old runner persists during close, so reload after it is gone. session = await storage.get_session( user_id, body.agent_id, session_id, ) if session is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Session {session_id!r} not found.", ) config = session.config.realtime_model_config if config is None: raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail="Configure a realtime model before starting voice mode.", ) if config.parameters.get("turn_detection") == "none": raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=( "Browser voice mode does not support " "turn_detection='none'. Select provider turn detection." ), ) try: model = await get_realtime_model(user_id, config, access) except ValueError as exc: raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=str(exc), ) from exc card = getattr(model, "card", None) uses_session_chat = ( getattr(card, "delegation_backend", "none") == "session_chat" ) if uses_session_chat and session.state.has_awaiting_tool_calls( agent_record.data.name, ): raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=( "Complete the pending Chat confirmation or " "external execution before starting GPT Live." ), ) if ( uses_session_chat and getattr(session.config, "chat_model_config", None) is None ): raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail="Configure a chat model before starting GPT Live.", ) lock_key = MessageBusKeys.session_lock(session_id) if await message_bus.is_locked(lock_key): raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=f"Session {session_id!r} is already running.", ) try: from aiortc import ( RTCConfiguration, RTCIceServer, RTCPeerConnection, RTCSessionDescription, ) from .._service._webrtc_audio_transport import ( WebRTCAudioTransport, ) from .._service._webrtc_session import WebRTCSession except ImportError as exc: raise HTTPException( status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=( "WebRTC support is not installed. Install " "agentscope[realtime]." ), ) from exc ice_servers = [ RTCIceServer(**server) for server in request.app.state.realtime_ice_servers ] peer_connection = RTCPeerConnection( configuration=RTCConfiguration(iceServers=ice_servers), ) transport = WebRTCAudioTransport( input_sample_rate=model.input_sample_rate, output_sample_rate=model.output_sample_rate, ) runner: WebRTCSession | None = None @peer_connection.on("track") def _on_track(track: Any) -> None: if track.kind == "audio": transport.set_input_track(track) @peer_connection.on("datachannel") def _on_datachannel(channel: Any) -> None: if channel.label == "control": transport.set_data_channel(channel) @peer_connection.on("connectionstatechange") def _on_connection_state_change() -> None: if runner is not None and peer_connection.connectionState in { "failed", "closed", }: runner.request_close() try: await peer_connection.setRemoteDescription( RTCSessionDescription(sdp=body.sdp, type=body.type), ) peer_connection.addTrack(transport.output_track) answer = await peer_connection.createAnswer() await peer_connection.setLocalDescription(answer) local_description = peer_connection.localDescription if local_description is None: raise RuntimeError("WebRTC negotiation produced no answer.") async def _create_agent() -> RealtimeAgent: return await realtime_service.create_agent( user_id=user_id, agent_id=body.agent_id, session_id=session_id, model=model, ) def _remove_closed(closed: WebRTCSession) -> None: if connections.get(connection_key) is closed: connections.pop(connection_key, None) runner = WebRTCSession( peer_connection=peer_connection, transport=transport, agent_factory=_create_agent, storage=storage, message_bus=message_bus, user_id=user_id, agent_id=body.agent_id, session_id=session_id, on_closed=_remove_closed, ) transport.on_disconnect = runner.request_close connections[connection_key] = runner runner.start() if not await runner.wait_until_lock_acquired( _SESSION_LOCK_ACQUIRE_TIMEOUT_SECONDS, ): await runner.close() raise HTTPException( status_code=status.HTTP_409_CONFLICT, detail=f"Session {session_id!r} is already running.", ) return RealtimeOfferResponse( sdp=local_description.sdp, type="answer", ) except HTTPException: await transport.close() await peer_connection.close() raise except Exception as exc: await transport.close() await peer_connection.close() raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, detail=f"WebRTC negotiation failed: {exc}", ) from exc - src/agentscope/app/_router/_schedule.py (8959 bytes)
# -*- coding: utf-8 -*- """Schedule router — CRUD endpoints for scheduled agent tasks.""" from datetime import datetime from fastapi import APIRouter, Depends, HTTPException, status from ..access import ResourceKind from .._manager import SchedulerManager from ..deps import ( get_current_user_id, get_resource_access_service, get_scheduler_manager, get_session_service, get_storage, ) from ._schema import ( CreateScheduleRequest, CreateScheduleResponse, ListSchedulesResponse, ScheduleSessionsResponse, UpdateScheduleRequest, ) from .._service import ResourceAccessService, SessionService from ..storage import ( StorageBase, ScheduleData, ScheduleRecord, ScheduleSource, ) schedule_router = APIRouter( prefix="/schedule", tags=["schedule"], responses={404: {"description": "Not found"}}, ) @schedule_router.get( "/", response_model=ListSchedulesResponse, summary="List all schedules", ) async def list_schedules( user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), ) -> ListSchedulesResponse: """List all schedules owned by the current user. Args: user_id (`str`): Authenticated user ID. storage (`StorageBase`): Storage instance. Returns: `ListSchedulesResponse`: Paginated list of schedule records. """ schedules = await storage.list_schedules(user_id) return ListSchedulesResponse(schedules=schedules, total=len(schedules)) @schedule_router.post( "/", response_model=CreateScheduleResponse, status_code=status.HTTP_201_CREATED, summary="Create a new schedule", ) async def create_schedule( body: CreateScheduleRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), access: ResourceAccessService = Depends(get_resource_access_service), scheduler: SchedulerManager = Depends(get_scheduler_manager), ) -> CreateScheduleResponse: """Create a new schedule and hand it to the scheduler. The referenced agent may be either the viewer's own or one shared to them through :class:`ResourceAccessPolicyBase`; the schedule record itself is always owned by the caller. Args: body (`CreateScheduleRequest`): Schedule configuration. user_id (`str`): Authenticated user ID. storage (`StorageBase`): Storage instance. access (`ResourceAccessService`): Access service. scheduler (`SchedulerManager`): Scheduler manager. Returns: `CreateScheduleResponse`: The ID of the newly created schedule. Raises: `HTTPException`: 404 if the specified agent or the credential referenced by ``chat_model_config`` is not visible to the caller; 422 if the cron expression, timezone or activation window is invalid. """ # Visibility checks — raise 404 when neither owned nor shared. The # schedule fires under the owner's user_id, so re-validating the # credential here surfaces the error at creation time rather than # silently at the first (possibly much later) scheduled run. await access.resolve_agent(user_id, body.agent_id) await access.get_resource( user_id, ResourceKind.CREDENTIAL, body.chat_model_config.credential_id, ) record = ScheduleRecord( user_id=user_id, agent_id=body.agent_id, data=ScheduleData( name=body.name, description=body.description, cron_expression=body.cron_expression, timezone=body.timezone, enabled=body.enabled, stateful=body.stateful, permission_mode=body.permission_mode, chat_model_config=body.chat_model_config, source=ScheduleSource.USER, # Keep the fallback aware so it denotes an absolute instant # even when the task's timezone differs from the server's. started_at=body.started_at or datetime.now().astimezone(), ended_at=body.ended_at, ), ) try: scheduler.validate_schedule(record) except ValueError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc), ) from exc await storage.upsert_schedule(user_id, record) await scheduler.notify_changed(record.id) return CreateScheduleResponse(schedule_id=record.id) @schedule_router.patch( "/{schedule_id}", response_model=ScheduleRecord, summary="Update a schedule", ) async def update_schedule( schedule_id: str, body: UpdateScheduleRequest, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), scheduler: SchedulerManager = Depends(get_scheduler_manager), ) -> ScheduleRecord: """Partially update a schedule. Fields omitted from the request body keep their current values. Changing ``cron_expression`` or ``timezone`` reschedules the job, and ``enable=False`` stops it firing without deleting the record — both take effect once the timer-owning node reconciles. Args: schedule_id (`str`): ID of the schedule to update. body (`UpdateScheduleRequest`): Fields to update. user_id (`str`): Authenticated user ID. storage (`StorageBase`): Storage instance. scheduler (`SchedulerManager`): Scheduler manager. Returns: `ScheduleRecord`: The updated schedule record. Raises: `HTTPException`: 404 if the schedule does not exist; 422 if the update leaves an invalid cron expression, timezone or activation window. """ existing = await storage.get_schedule(user_id, schedule_id) if existing is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Schedule '{schedule_id}' not found.", ) updates = body.model_dump(exclude_none=True) updated_data = existing.data.model_copy(update=updates) updated_record = existing.model_copy( update={"data": updated_data, "updated_at": datetime.now()}, ) try: scheduler.validate_schedule(updated_record) except ValueError as exc: raise HTTPException( status_code=status.HTTP_422_UNPROCESSABLE_CONTENT, detail=str(exc), ) from exc await storage.upsert_schedule(user_id, updated_record) await scheduler.notify_changed(schedule_id) return updated_record @schedule_router.delete( "/{schedule_id}", status_code=status.HTTP_204_NO_CONTENT, summary="Delete a schedule", ) async def delete_schedule( schedule_id: str, user_id: str = Depends(get_current_user_id), session_service: SessionService = Depends(get_session_service), scheduler: SchedulerManager = Depends(get_scheduler_manager), ) -> None: """Permanently delete a schedule. Cancels any in-flight chat run for sessions this schedule has triggered, removes their records via the session service, and tells the timer-owning node to drop the job. Args: schedule_id (`str`): ID of the schedule to delete. user_id (`str`): Authenticated user ID. session_service (`SessionService`): Injected session service. scheduler (`SchedulerManager`): Scheduler manager. Raises: `HTTPException`: 404 if the schedule does not exist. """ deleted = await session_service.delete_schedule(user_id, schedule_id) if not deleted: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Schedule '{schedule_id}' not found.", ) await scheduler.notify_changed(schedule_id) @schedule_router.get( "/{schedule_id}/sessions", response_model=ScheduleSessionsResponse, summary="List execution sessions for a schedule", ) async def list_schedule_sessions( schedule_id: str, user_id: str = Depends(get_current_user_id), storage: StorageBase = Depends(get_storage), ) -> ScheduleSessionsResponse: """Return all sessions triggered by a given schedule. Args: schedule_id (`str`): ID of the schedule. user_id (`str`): Authenticated user ID. storage (`StorageBase`): Storage instance. Returns: `ScheduleSessionsResponse`: List of execution sessions ordered by creation time (newest first). Raises: `HTTPException`: 404 if the schedule does not exist. """ existing = await storage.get_schedule(user_id, schedule_id) if existing is None: raise HTTPException( status_code=status.HTTP_404_NOT_FOUND, detail=f"Schedule '{schedule_id}' not found.", ) sessions = await storage.list_sessions_by_schedule(user_id, schedule_id) return ScheduleSessionsResponse(sessions=sessions, total=len(sessions)) - src/agentscope/app/_router/_schema/__init__.py (7163 bytes)
# -*- coding: utf-8 -*- """Schema models for the agent service.""" from ._background_task import ( BackgroundTaskInfo, ListBackgroundTasksResponse, ) from ._channel import ( StartCredentialBindingRequest, ChannelActionResponse, ChannelChatId, ChannelChatIdsResponse, ChannelResponse, ChannelSessionsResponse, CreateChannelRequest, UpdateChannelRequest, ) from ._chat import ( ChatRequest, ChatTriggerResponse, ClientExternalToolDefinition, ChatQueueItem, ChatQueueResponse, ReorderChatQueueRequest, SteerChatQueueItemRequest, UpdateChatQueueItemRequest, ) from ._asr import ( ListASRModelsRequest, ListASRModelsResponse, RealtimeASRStartRequest, RealtimeASRTokenRequest, RealtimeASRTokenResponse, TranscriptionResponse, ) from ._health import ComponentStatus, HealthResponse from ._hub import HubInfo from ._hub_mcp import InstallMCPRequest, MCPView, UpdateMCPRequest from ._hub_skill import SkillView from ._workspace import ( AddFromLibraryRequest, AddFromLibraryResponse, AddSkillsFromLibraryRequest, DirectoryEntry, DirectoryListing, DownloadTokenResponse, MCPClientStatus, ToolInfo, ) from ._embedding_model import ( ListEmbeddingModelsResponse, ListEmbeddingModelsRequest, ) from ._model import ListModelsResponse, ListModelsRequest from ._realtime import ( ListRealtimeModelsRequest, ListRealtimeModelsResponse, RealtimeConfigResponse, RealtimeOfferRequest, RealtimeOfferResponse, ) from ._tts_model import ListTTSModelsResponse, ListTTSModelsRequest from ._schedule import ( CreateScheduleRequest, CreateScheduleResponse, ListSchedulesResponse, ScheduleSessionsResponse, UpdateScheduleRequest, ) from ._sop import ( CreateSOPRequest, CreateSOPResponse, ListSOPRunsResponse, ListSOPsResponse, SOPSchemaResponse, StartSOPRunRequest, SubmitVerdictRequest, UpdateSOPRequest, ) from ._agent import ( AgentSchemaResponse, AgentSchemaV2Response, ListAgentsResponse, CreateAgentRequest, CreateAgentResponse, UpdateAgentRequest, ) from ._credential import ( CreateCredentialRequest, CreateCredentialResponse, UpdateCredentialRequest, ListCredentialsResponse, ListCredentialSchemasResponse, ) from ._knowledge_base import ( ChunkerInfo, CreateKnowledgeBaseRequest, CreateKnowledgeBaseResponse, KbEmbeddingProvider, KbMiddlewareParametersSchemaResponse, KnowledgeDocumentView, ListChunkersResponse, ListKbEmbeddingModelsResponse, ListKnowledgeBasesResponse, ListDocumentChunksResponse, DocumentDownloadTokenResponse, ListKnowledgeDocumentsResponse, ListKnowledgeDocumentStatusResponse, ListSupportedContentTypesResponse, SearchKnowledgeBaseRequest, SearchKnowledgeBaseResponse, UpdateKnowledgeBaseRequest, UploadKnowledgeDocumentResponse, ) from ._session import ( CreateSessionRequest, CreateSessionResponse, InterruptSessionResponse, UpdateSessionRequest, ListSessionsResponse, ListMessagesResponse, SessionStatus, SessionStatusResponse, SessionView, TeamDetailResponse, TeamMemberView, ) from ._voice_profile import ( AvailableEnginesResponse, CloneVoiceRequest, CloneVoiceResponse, CreateVoiceProfileRequest, CreateVoiceProfileResponse, CredentialRef, EngineInfo, EngineModelInfo, ListVoiceProfilesResponse, OpenAIConsentRequest, OpenAIConsentResponse, UpdateVoiceProfileRequest, ) __all__ = [ # Health "ComponentStatus", "HealthResponse", # Hub "HubInfo", "InstallMCPRequest", "MCPView", "UpdateMCPRequest", "SkillView", # Workspace "AddFromLibraryRequest", "AddFromLibraryResponse", "AddSkillsFromLibraryRequest", "DirectoryEntry", "DirectoryListing", "DownloadTokenResponse", "MCPClientStatus", "ToolInfo", # Agent "CreateSOPRequest", "CreateSOPResponse", "ListSOPRunsResponse", "ListSOPsResponse", "SOPSchemaResponse", "StartSOPRunRequest", "SubmitVerdictRequest", "UpdateSOPRequest", "AgentSchemaResponse", "AgentSchemaV2Response", "ListAgentsResponse", "CreateAgentRequest", "CreateAgentResponse", "UpdateAgentRequest", "ListSchedulesResponse", # Background Task "BackgroundTaskInfo", "ListBackgroundTasksResponse", # Channel "ChannelActionResponse", "ChannelChatId", "ChannelChatIdsResponse", "ChannelResponse", "ChannelSessionsResponse", "CreateChannelRequest", "StartCredentialBindingRequest", "UpdateChannelRequest", # Chat "ClientExternalToolDefinition", "ChatRequest", "ChatTriggerResponse", "ChatQueueItem", "ChatQueueResponse", "ReorderChatQueueRequest", "SteerChatQueueItemRequest", "UpdateChatQueueItemRequest", # ASR "ListASRModelsRequest", "ListASRModelsResponse", "RealtimeASRStartRequest", "RealtimeASRTokenRequest", "RealtimeASRTokenResponse", "TranscriptionResponse", # Credential "CreateCredentialRequest", "CreateCredentialResponse", "UpdateCredentialRequest", "ListCredentialsResponse", "ListCredentialSchemasResponse", # Knowledge base "ChunkerInfo", "CreateKnowledgeBaseRequest", "CreateKnowledgeBaseResponse", "KbEmbeddingProvider", "KbMiddlewareParametersSchemaResponse", "KnowledgeDocumentView", "ListChunkersResponse", "ListKbEmbeddingModelsResponse", "ListKnowledgeBasesResponse", "ListDocumentChunksResponse", "DocumentDownloadTokenResponse", "ListKnowledgeDocumentsResponse", "ListKnowledgeDocumentStatusResponse", "ListSupportedContentTypesResponse", "SearchKnowledgeBaseRequest", "SearchKnowledgeBaseResponse", "UpdateKnowledgeBaseRequest", "UploadKnowledgeDocumentResponse", # Model "ListEmbeddingModelsRequest", "ListEmbeddingModelsResponse", "ListModelsRequest", "ListModelsResponse", "ListRealtimeModelsRequest", "ListRealtimeModelsResponse", "RealtimeConfigResponse", "RealtimeOfferRequest", "RealtimeOfferResponse", # TTS Model "ListTTSModelsRequest", "ListTTSModelsResponse", # Schedule "CreateScheduleRequest", "CreateScheduleResponse", "ListSchedulesResponse", "ScheduleSessionsResponse", "UpdateScheduleRequest", # Session "CreateSessionRequest", "CreateSessionResponse", "InterruptSessionResponse", "UpdateSessionRequest", "ListSessionsResponse", "ListMessagesResponse", "SessionStatus", "SessionStatusResponse", "SessionView", "TeamDetailResponse", "TeamMemberView", # Voice Profile "AvailableEnginesResponse", "CloneVoiceRequest", "CloneVoiceResponse", "CreateVoiceProfileRequest", "CreateVoiceProfileResponse", "CredentialRef", "EngineInfo", "EngineModelInfo", "ListVoiceProfilesResponse", "OpenAIConsentRequest", "OpenAIConsentResponse", "UpdateVoiceProfileRequest", ] - src/agentscope/app/_router/_schema/_agent.py (5534 bytes)
# -*- coding: utf-8 -*- """Request / response schemas for the agent router.""" import warnings from pydantic import BaseModel, Field from ....agent import ContextConfig, ReActConfig from ...storage import AgentChatConfig, InviteConfig from ..._service import AgentView class CreateAgentRequest(BaseModel): """Request body for creating a new agent. Mirrors :class:`AgentData`, so the shape a client reads back is the shape it writes. The three pre-``chat_config`` fields below are still accepted and are folded into it by :class:`AgentData`; sending both puts the flat one on top. """ name: str = Field(description="Display name of the agent.") system_prompt: str = Field( default="You're a helpful assistant.", description="Base system prompt fed to the agent.", ) chat_config: AgentChatConfig = Field( default_factory=AgentChatConfig, description="Settings for the agent's text conversations.", ) context_config: ContextConfig | None = Field( default=None, description="**Deprecated.** Use ``chat_config.context_config``.", deprecated=True, ) react_config: ReActConfig | None = Field( default=None, description="**Deprecated.** Use ``chat_config.react_config``.", deprecated=True, ) invite_config: InviteConfig | None = Field( default=None, description="**Deprecated.** Use ``chat_config.invite_config``.", deprecated=True, ) class CreateAgentResponse(BaseModel): """Response body after creating an agent.""" agent_id: str = Field(description="Server-assigned agent identifier.") class UpdateAgentRequest(BaseModel): """Request body for partially updating an agent. Omit any field to keep its current value. """ name: str | None = Field(default=None, description="New display name.") system_prompt: str | None = Field( default=None, description="New system prompt.", ) chat_config: AgentChatConfig | None = Field( default=None, description=( "New text-conversation settings. Only supplied sub-configs " "are replaced; omitted sub-configs keep their current values." ), ) context_config: ContextConfig | None = Field( default=None, description=( "**Deprecated.** Use ``chat_config``. Still honoured, and " "narrower: it replaces only this sub-config." ), deprecated=True, ) react_config: ReActConfig | None = Field( default=None, description="**Deprecated.** Use ``chat_config``.", deprecated=True, ) invite_config: InviteConfig | None = Field( default=None, description="**Deprecated.** Use ``chat_config``.", deprecated=True, ) class ListAgentsResponse(BaseModel): """Response body for listing agents.""" agents: list[AgentView] = Field(description="Agent records.") total: int = Field(description="Total number of agents.") class AgentSchemaResponse(BaseModel): """**Deprecated.** JSON Schema fragments used by the frontend to render the agent create / edit forms. Superseded by :class:`AgentSchemaV2Response`, which returns the full :class:`AgentData` JSON Schema in a single ``schema`` field so newly added agent fields (like the ``invite_config`` sub-model) reach the frontend automatically without the router having to know about them. The frontend previously split :class:`AgentData` into three hand-picked sections (``identity``, ``context_config``, ``react_config``) here, which required a router edit every time a new user-editable field landed on :class:`AgentData`. Kept for backwards compatibility with pre-v2 API consumers. """ identity: dict = Field( description=( "Schema for the agent's identity fields (``name``, " "``system_prompt``)." ), ) context_config: dict = Field( description="Schema for ``ContextConfig``.", ) react_config: dict = Field( description="Schema for ``ReActConfig``.", ) # The ``schema`` field name below is intentional — the wire contract for # ``GET /agent/schema/v2`` is ``{"schema": ...}`` so the response is # self-documenting. Pydantic v2's :meth:`BaseModel.schema` is a # deprecated legacy classmethod (superseded by ``model_json_schema``); # a like-named instance field triggers a cosmetic "shadows an attribute # in parent BaseModel" warning that is irrelevant here because we never # call the legacy classmethod. Suppress it locally instead of adding an # alias that would obscure the wire contract at every call site. with warnings.catch_warnings(): warnings.filterwarnings( "ignore", message=r'Field name "schema" in "AgentSchemaV2Response"', ) class AgentSchemaV2Response(BaseModel): """Response for ``GET /agent/schema/v2``. Wraps the full :class:`AgentData` JSON Schema in a single ``schema`` field so the frontend can render every user-editable property without the router having to enumerate them. """ schema: dict = Field( description=( "Full :class:`AgentData` JSON Schema. All user-editable " "fields appear as top-level entries in ``properties`` — " "the frontend derives its section grouping from this " "single schema." ), ) - src/agentscope/app/_router/_schema/_asr.py (1575 bytes)
# -*- coding: utf-8 -*- """Speech recognition request and response schemas.""" from typing import Literal from pydantic import BaseModel, Field from ....asr import ASRModelCard class ListASRModelsResponse(BaseModel): """List the candidate ASR models response.""" models: list[ASRModelCard] = Field( description="The candidate ASR models.", ) total: int = Field(description="The total number of candidates.") class ListASRModelsRequest(BaseModel): """List the candidate ASR models request.""" provider: str = Field( description="The credential provider type.", ) class TranscriptionResponse(BaseModel): """Text returned after transcribing an uploaded audio file.""" text: str = Field(description="The transcribed text.") class RealtimeASRTokenRequest(BaseModel): """Request a capability for one realtime ASR configuration.""" credential_id: str = Field(min_length=1) model: str = Field(min_length=1) class RealtimeASRTokenResponse(BaseModel): """Short-lived capability accepted by the realtime ASR socket.""" token: str = Field(description="Pass as the WebSocket token query.") expires_at: int = Field( description="Unix timestamp after which the token is refused.", ) class RealtimeASRStartRequest(BaseModel): """First browser frame for a realtime ASR connection.""" type: Literal["start"] credential_id: str = Field(min_length=1) model: str = Field(min_length=1) parameters: dict = Field(default_factory=dict) sample_rate: int = Field(gt=0) - src/agentscope/app/_router/_schema/_background_task.py (2972 bytes)
# -*- coding: utf-8 -*- """Request / response schemas for the background-task router.""" from datetime import datetime, timezone from pydantic import BaseModel, Field from ..._manager._background_task_manager import ( BackgroundTaskRecord, TaskStatus, ) class BackgroundTaskInfo(BaseModel): """Summary of a single background task for API responses.""" task_id: str = Field(description="Unique task identifier.") session_id: str = Field(description="Session that owns this task.") agent_id: str = Field(description="Agent that triggered this task.") tool_name: str = Field(description="Name of the offloaded tool.") summary: str = Field( description="Short human-readable summary of the tool invocation. " "May include unredacted tool arguments stored in shared task records.", ) status: TaskStatus = Field(description="Current lifecycle status.") started_at: datetime = Field( description="UTC timestamp when the task was registered.", ) execution_started_at: datetime | None = Field( default=None, description="UTC timestamp when tool execution began, before " "offload. Null when the original start time was not recorded.", ) completed_at: datetime | None = Field( default=None, description="UTC timestamp when the task reached a terminal " "state, or null while still running.", ) error_summary: str | None = Field( default=None, description="Brief failure description (only for failed tasks).", ) class ListBackgroundTasksResponse(BaseModel): """Response body for listing background tasks.""" tasks: list[BackgroundTaskInfo] = Field( description="Background tasks for the requested scope.", ) total: int = Field(description="Total number of tasks returned.") def to_info(task: BackgroundTaskRecord) -> BackgroundTaskInfo: """Convert shared task metadata to an API-facing schema. Args: task (`BackgroundTaskRecord`): The shared background task metadata. Returns: `BackgroundTaskInfo`: The serializable API response model. """ return BackgroundTaskInfo( task_id=task.id, session_id=task.session_id, agent_id=task.agent_id, tool_name=task.tool_name, summary=task.summary, status=task.status, started_at=datetime.fromtimestamp( task.started_at, tz=timezone.utc, ), execution_started_at=( datetime.fromtimestamp( task.execution_started_at, tz=timezone.utc, ) if task.execution_started_at is not None else None ), completed_at=( datetime.fromtimestamp(task.completed_at, tz=timezone.utc) if task.completed_at is not None else None ), error_summary=task.error_summary, ) - src/agentscope/app/_router/_schema/_channel.py (2754 bytes)
# -*- coding: utf-8 -*- """Request / response schemas for the channel router.""" from datetime import datetime from pydantic import BaseModel, Field from ...storage import ( RoutingConfig, SessionRecord, SessionSettings, ) class CreateChannelRequest(BaseModel): """Request body for creating a channel.""" channel_type: str = Field(description="Channel type id, e.g. 'feishu'.") name: str | None = Field( default=None, description="Optional display name.", ) credentials: dict = Field( default_factory=dict, description="Platform credentials. Omit when " "``credential_binding_id`` supplies them.", ) credential_binding_id: str | None = Field( default=None, description="Completed credential-binding session to take the " "credentials from, instead of passing them here.", ) platform_config: dict = Field( default_factory=dict, description="Non-secret platform options.", ) routing: RoutingConfig = Field(description="Inbound routing rules.") session: SessionSettings = Field(description="Session/model settings.") enabled: bool = Field(default=True, description="Start it enabled.") class UpdateChannelRequest(BaseModel): """Request body for updating a channel (type/credentials immutable).""" name: str | None = None platform_config: dict | None = None routing: RoutingConfig | None = None session: SessionSettings | None = None enabled: bool | None = None class ChannelResponse(BaseModel): """Channel details returned to the client (credentials omitted).""" id: str channel_type: str name: str | None user_id: str platform_bot_id: str enabled: bool platform_config: dict routing: RoutingConfig session: SessionSettings created_at: datetime updated_at: datetime class ChannelActionResponse(BaseModel): """Result of an enable/disable action.""" status: str = Field(description="New lifecycle status, e.g. 'enabled'.") class ChannelSessionsResponse(BaseModel): """Sessions a channel has spawned.""" sessions: list[SessionRecord] total: int class ChannelChatId(BaseModel): """A chat the bot can route to (from the platform or seen inbound).""" chat_id: str name: str = "" source: str = Field(description="'platform' or 'recorded'.") class ChannelChatIdsResponse(BaseModel): """Chats available for routing configuration.""" chats: list[ChannelChatId] = Field(default_factory=list) class StartCredentialBindingRequest(BaseModel): """Request body for opening a credential-binding session.""" channel_type: str = Field(description="Channel type id, e.g. 'feishu'.") - src/agentscope/app/_router/_schema/_chat.py (5531 bytes)
# -*- coding: utf-8 -*- """The chat endpoint schema.""" from typing import Annotated, Literal, TypeAlias from pydantic import BaseModel, Field, field_validator, model_validator from ..._client_external_tool import ( ClientBuiltinToolName, ClientExternalToolDefinition, ) from ....message import Msg, ToolResultState from ....tool import AskUser, AskUserMetadata from ....event import UserConfirmResultEvent, ExternalExecutionResultEvent NonEmptyMsgList: TypeAlias = Annotated[list[Msg], Field(min_length=1)] class ChatRequest(BaseModel): """Request body for the chat endpoint.""" agent_id: str = Field( description="Agent ID for the chat endpoint.", ) session_id: str = Field( description="The session to send the message to.", ) input: ( Msg | NonEmptyMsgList | UserConfirmResultEvent | ExternalExecutionResultEvent | None ) = Field( description="The input message(s), or agent event, or None.", ) client_builtin_tools: list[ClientBuiltinToolName] = Field( default_factory=list, max_length=1, description="Native external tools supported by this client run.", ) client_external_tools: list[ClientExternalToolDefinition] = Field( default_factory=list, max_length=16, description=( "External tools the active client can execute for this run." ), ) @field_validator("client_external_tools") @classmethod def validate_unique_client_external_tools( cls, value: list[ClientExternalToolDefinition], ) -> list[ClientExternalToolDefinition]: """Reject ambiguous duplicate client tool names.""" names = [tool.name for tool in value] if len(names) != len(set(names)): raise ValueError("Client external tool names must be unique.") return value @model_validator(mode="after") def validate_native_answers(self) -> "ChatRequest": """Validate resumed native results even if the tool was disabled. Disabling a tool governs future calls, not the contract of a call already waiting for its result. """ if isinstance(self.input, ExternalExecutionResultEvent): for result in self.input.execution_results: if ( result.name == AskUser.name and result.state == ToolResultState.SUCCESS ): AskUserMetadata.model_validate(result.metadata) return self class ChatTriggerResponse(BaseModel): """Response body for an accepted chat trigger. An ordinary user turn is accepted into the FIFO with ``queued``; continuation and control triggers use ``started``. Resulting events arrive separately via the session's SSE stream endpoint. """ status: Literal["started", "queued"] = Field( default="started", description=( '``"queued"`` for an accepted ordinary user turn; ' '``"started"`` for continuation/control triggers.' ), ) session_id: str = Field( description="Session whose queue or run accepted the trigger.", ) queue_item_id: str | None = Field( default=None, description="Stable queue item id for an ordinary user turn.", ) class ChatQueueItem(BaseModel): """One ordinary user turn that has not started execution.""" id: str = Field( description="Stable id used to edit, delete, or reorder this item.", ) created_at: str = Field( description="UTC ISO-8601 timestamp recorded when the item queued.", ) input: Msg | NonEmptyMsgList = Field( description="One message or non-empty ordered message list.", ) state: Literal["queued", "steering", "failed"] = Field( default="queued", description="Current deferred-send or steering state.", ) error: str | None = Field( default=None, description="Visible steering failure, when state is failed.", ) class ChatQueueResponse(BaseModel): """Current editable FIFO snapshot for a session.""" items: list[ChatQueueItem] = Field( description="Editable pending turns in FIFO execution order.", ) class UpdateChatQueueItemRequest(BaseModel): """Replace the input carried by one pending queue item.""" agent_id: str = Field( description="Agent that owns the target session.", ) session_id: str = Field( description="Session whose pending item will be updated.", ) input: Msg | NonEmptyMsgList = Field( description="Replacement message or non-empty message list.", ) class SteerChatQueueItemRequest(BaseModel): """Reserve one pending input for a currently active reply.""" agent_id: str = Field( description="Agent that owns the target session.", ) session_id: str = Field( description="Session whose pending item will steer the reply.", ) reply_id: str = Field( description="Active reply that should consume the pending item.", ) class ReorderChatQueueRequest(BaseModel): """Set the complete pending queue order.""" agent_id: str = Field( description="Agent that owns the target session.", ) session_id: str = Field( description="Session whose pending FIFO will be reordered.", ) item_ids: list[str] = Field( description="Exact desired permutation of all pending item ids.", ) - src/agentscope/app/_router/_schema/_credential.py (1182 bytes)
# -*- coding: utf-8 -*- """Request / response schemas for the credential router.""" from pydantic import BaseModel, Field from ..._service import CredentialView class CreateCredentialRequest(BaseModel): """Request body for creating a new credential.""" data: dict = Field(description="Credential payload (e.g. API keys).") class CreateCredentialResponse(BaseModel): """Response body after creating a credential.""" credential_id: str = Field( description="Server-assigned credential identifier.", ) class UpdateCredentialRequest(BaseModel): """Request body for updating an existing credential.""" data: dict = Field(description="New credential payload.") class ListCredentialsResponse(BaseModel): """Response body for listing credentials.""" credentials: list[CredentialView] = Field( description="Credential records.", ) total: int = Field(description="Total number of credentials.") class ListCredentialSchemasResponse(BaseModel): """Response body for listing credential type schemas.""" schemas: list[dict] = Field( description="JSON schemas for all registered credential types.", ) - src/agentscope/app/_router/_schema/_embedding_model.py (658 bytes)
# -*- coding: utf-8 -*- """The embedding model configuration, used as DTO layer.""" from pydantic import BaseModel, Field from ....embedding import EmbeddingModelCard class ListEmbeddingModelsResponse(BaseModel): """List the candidate embedding models response.""" models: list[EmbeddingModelCard] = Field( description="The candidate embedding models.", ) total: int = Field(description="The total number of candidates.") class ListEmbeddingModelsRequest(BaseModel): """List the candidate embedding models request.""" provider: str = Field( description="The provider type, e.g. openai, dashscope, etc.", )