Skip to content

Build and run agents you can see, understand and trust.

feat(service): implement the FastAPI based agent service (#1568)

DavdGaoa899b094ad5b
diff --git a/docs/tutorial/_static/css/gallery.css b/docs/tutorial/_static/css/gallery.css
deleted file mode 100644
index c06489337..000000000
--- a/docs/tutorial/_static/css/gallery.css
+++ /dev/null
@@ -1,166 +0,0 @@
-.sphx-glr-download-link-note.admonition.note {
- display: none;
-}
-
-.sphx-glr-footer {
- display: flex;
- flex-direction: row;
- gap: 8px;
-}
-
-.sphx-glr-download-zip {
- display: none;
-}
-
-.bordered-image {
- border: 1px solid #e5e5e5;
-}
-
-:root {
- --item-card-width: 200px;
- --item-card-margin: 10px;
- --item-card-title-height: 50px;
-
- --item-card-img-length: calc(var(--item-card-width) - 2*var(--item-card-margin));
- --item-card-title-width: calc(var(--item-card-width) - 2*var(--item-card-margin));
- --item-card-title-margin-top: var(--item-card-margin);
-
- --item-card-height: calc(var(--item-card-margin) * 3 + var(--item-card-img-length) + var(--item-card-title-height));
-}
-
-td .highlight-python.notranslate {
- margin-bottom: 0 !important;
-}
-
-/*cite {*/
-/* background: rgba(229, 229, 229, 0.69) !important;*/
-/* padding-left: 0.25rem !important;*/
-/* padding-right: 0.25rem !important;*/
-/* border-radius: 4px !important;*/
-/* font-style: normal !important;*/
-/* font-weight: 600 !important;*/
-/*}*/
-
-.sidebar-brand-text {
- display: flex;
- justify-content: center;
-}
-
-.sidebar-logo-container .sidebar-logo {
- max-height: 170px;
- width: auto;
- display: block;
-}
-
-.gallery-item {
- position: relative;
- display: inline-block;
- width: var(--item-card-width);
- height: var(--item-card-height);
- box-shadow: 0 0 8px rgba(0, 0, 0, 0.2);
- margin: 7px;
-}
-
-.docutils.align-default {
- white-space: normal !important;
- max-width: 100% !important;
- width: 100% !important;
- td {
- white-space: normal !important;
- }
-}
-
-.sphx-glr-script-out.highlight-none.notranslate .highlight pre{
- /*正常打印回车*/
- white-space: pre-wrap !important;
- /*white-space: normal !important;*/
- max-width: 100% !important;
- width: 100% !important;
-}
-
-.gallery-item-card {
- position: absolute;
- top: 0;
- left: 0;
- width: var(--item-card-width);
- height: var(--item-card-height);
- display: flex;
- flex-direction: column;
- margin: var(--item-card-margin);
-}
-
-.gallery-item-card-img {
- height: var(--item-card-img-length);
- width: var(--item-card-img-length);
- min-width: var(--item-card-img-length);
- min-height: var(--item-card-img-length);
- display: block;
-}
-
-.gallery-item-card-title {
- text-align: center;
- margin-top: var(--item-card-margin);
- font-weight: bold;
- min-height: var(--item-card-title-height);
- height: var(--item-card-title-height);
- width: var(--item-card-title-width);
- display: flex;
- align-items: center;
- justify-content: center;
-}
-
-.gallery-item-description {
- position: absolute;
- top: 0;
- left: 0;
- width: 100%;
- height: 100%;
- background-color: rgba(255, 255, 255, 0.9);
- /*background-color: #1e8449;*/
- color: black;
- display: none;
- justify-content: center;
- align-items: flex-start;
-}
-
-.gallery-item:hover .gallery-item-description {
- display: flex;
- padding: 10px;
- border: 1px solid rgba(0, 0, 0, 0.22);
-}
-
-.language-switch-button {
- background: transparent;
- display: flex;
- align-content: center;
- justify-content: center;
- font-size: 15px;
- margin-top: 0;
- margin-bottom: 4px;
- border: none;
- color: rgb(4, 4, 4);
- height: 20px;
- width: 20px;
- border-radius: 6px;
- font-weight: 325;
-}
-
-.language-switch-button:hover {
- color: #2758DA;
-}
-
-.version-select {
- display: flex;
- align-items: center;
- justify-content: center;
- background: transparent;
- font-size: 14px;
- border: 1px solid rgb(238, 235, 238);
- margin-inline: 16px;
- padding: 8px;
- height: fit-content;
- box-sizing: border-box;
- font-weight: 600;
- border-radius: 6px;
- fill: rgb(238, 235, 238);
-}
diff --git a/docs/tutorial/_static/images/embedding_cache.png b/docs/tutorial/_static/images/embedding_cache.png
deleted file mode 100644
index 91372fd77..000000000
Binary files a/docs/tutorial/_static/images/embedding_cache.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/evaluation.png b/docs/tutorial/_static/images/evaluation.png
deleted file mode 100644
index 8776f3983..000000000
Binary files a/docs/tutorial/_static/images/evaluation.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/handoffs.png b/docs/tutorial/_static/images/handoffs.png
deleted file mode 100644
index 6518a57e9..000000000
Binary files a/docs/tutorial/_static/images/handoffs.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/interruption_en.gif b/docs/tutorial/_static/images/interruption_en.gif
deleted file mode 100644
index 67d312e20..000000000
Binary files a/docs/tutorial/_static/images/interruption_en.gif and /dev/null differ
diff --git a/docs/tutorial/_static/images/interruption_zh.gif b/docs/tutorial/_static/images/interruption_zh.gif
deleted file mode 100644
index b33815f4a..000000000
Binary files a/docs/tutorial/_static/images/interruption_zh.gif and /dev/null differ
diff --git a/docs/tutorial/_static/images/logo.png b/docs/tutorial/_static/images/logo.png
deleted file mode 100644
index 93bed0036..000000000
Binary files a/docs/tutorial/_static/images/logo.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/logo.svg b/docs/tutorial/_static/images/logo.svg
deleted file mode 100644
index e781d9c87..000000000
--- a/docs/tutorial/_static/images/logo.svg
+++ /dev/null
@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" fill="none" version="1.1" width="550" height="550" viewBox="0 0 550 550"><defs><linearGradient x1="0.01500389538705349" y1="0.4831196665763855" x2="0.9407116114637801" y2="0.3076102348892569" id="master_svg0_8_2390"><stop offset="0%" stop-color="#01C5FF" stop-opacity="1"/><stop offset="100%" stop-color="#019DFB" stop-opacity="1"/></linearGradient><linearGradient x1="0.21085502207279205" y1="0.38703426718711853" x2="0.9523109409029081" y2="0.390888421140005" id="master_svg1_8_1638"><stop offset="0%" stop-color="#4701EF" stop-opacity="1"/><stop offset="100%" stop-color="#395EEF" stop-opacity="1"/></linearGradient></defs><g><g></g><g><g><path d="M275.4998779296875,211.25Q275.4998779296875,279.5,373.4999779296875,310.5Q338.4998779296875,287.5,343.9998779296875,232Q344.4969779296875,227.19400000000002,345.9004779296875,222.498Q352.96577792968753,198.857,382.9998779296875,178L415.9998779296875,193.5L469.7738779296875,193.5C477.0958779296875,193.5,481.9218779296875,185.91559999999998,478.3148779296875,179.543Q441.5068779296875,114.5,372.9998779296875,114.5C343.9998779296875,114.5,275.4998779296875,143,275.4998779296875,211.25Z" fill="url(#master_svg0_8_2390)" fill-opacity="1"/></g><g><path d="M343.9999162890625,231.99999791015625Q337.9999162890625,287.5000079101562,373.5000462890625,310.5000079101562L433.4998462890625,333.00010791015626Q449.4994462890625,314.2500079101562,449.4994462890625,295.5000079101562Q449.4994462890625,276.7500079101562,433.4998462890625,258.0000079101562L345.9004862890625,222.49810791015625Q344.4970462890625,227.19412791015625,343.9999162890625,231.99999791015625Z" fill="#0064FC" fill-opacity="1"/></g><g><path d="M122.9998779296875,351.5C124.3900479296875,350.6567,125.7727179296875,349.8325,127.1479779296875,349.0269Q125.0392779296875,350.2098,122.9998779296875,351.5ZM127.1479779296875,349.0269Q150.3716779296875,336,181.9998779296875,336C186.2692779296875,335.7983,190.4211779296875,335.9808,194.4638779296875,336.502C250.5488779296875,343.7327,285.6218779296875,416.14300000000003,321.9998779296875,432Q350.1248779296875,444,377.9998779296875,444Q405.8748779296875,444,433.4998779296875,432Q489.9998779296875,400,489.9998779296875,344.5Q489.9998779296875,283,433.4998779296875,258Q449.4998779296875,276.75,449.4998779296875,295.5Q449.4998779296875,314.25,433.4998779296875,333C394.3168779296875,374.257,360.65987792968747,359.947,319.4498779296875,342.4251C286.9518779296875,328.6077,249.7568779296875,312.7935,201.4527779296875,320.6594C179.2413779296875,324.2763,154.6808779296875,332.9,127.1479779296875,349.0269Z" fill="url(#master_svg1_8_1638)" fill-opacity="1"/></g><g><path d="M61,437.99973876953123L133.8305,437.99973876953123C141.5661,437.99973876953123,148.608,433.53913876953123,151.9131,426.54513876953126L194.464,336.50202976953125C190.421,335.98083496953126,186.269,335.79829376953126,182,335.99999996953125Q147.4999,335.99999996953125,122.9999,351.5000387695313C93.5,373.5000387695313,87,387.0000387695313,61,437.99973876953123Z" fill="#0064FC" fill-opacity="1"/></g><g><path d="M61,438.00038301849366C87,387.00038301849366,93.5,373.50038301849366,122.9999,351.50038301849366C152.2215,333.77438301849367,178.132,324.45738301849366,201.453,320.65938301849366L256.597,207.04148301849364C259.081,201.92438301849364,259.26800000000003,195.99188301849364,257.11199999999997,190.72838301849367L227.948,119.52337301849366C225.653,113.91851301849366,217.805,113.67667301849366,215.169,119.12954301849365L61,438.00038301849366Z" fill="#01C8FF" fill-opacity="1"/></g></g></g></svg>
\ No newline at end of file
diff --git a/docs/tutorial/_static/images/multiagent_msgs.png b/docs/tutorial/_static/images/multiagent_msgs.png
deleted file mode 100644
index 27995e126..000000000
Binary files a/docs/tutorial/_static/images/multiagent_msgs.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/plan.png b/docs/tutorial/_static/images/plan.png
deleted file mode 100644
index 482c8547c..000000000
Binary files a/docs/tutorial/_static/images/plan.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/sequential_hook.png b/docs/tutorial/_static/images/sequential_hook.png
deleted file mode 100644
index 983d3c07b..000000000
Binary files a/docs/tutorial/_static/images/sequential_hook.png and /dev/null differ
diff --git a/docs/tutorial/_static/images/studio_home.webp b/docs/tutorial/_static/images/studio_home.webp
deleted file mode 100644
index 4e88af6b3..000000000
Binary files a/docs/tutorial/_static/images/studio_home.webp and /dev/null differ
diff --git a/docs/tutorial/_static/images/studio_project.webp b/docs/tutorial/_static/images/studio_project.webp
deleted file mode 100644
index 2d5ca7a6d..000000000
Binary files a/docs/tutorial/_static/images/studio_project.webp and /dev/null differ
diff --git a/docs/tutorial/_static/images/studio_run.webp b/docs/tutorial/_static/images/studio_run.webp
deleted file mode 100644
index 0c63da12a..000000000
Binary files a/docs/tutorial/_static/images/studio_run.webp and /dev/null differ
diff --git a/docs/tutorial/_static/images/studio_tracing.webp b/docs/tutorial/_static/images/studio_tracing.webp
deleted file mode 100644
index 4d7491c36..000000000
Binary files a/docs/tutorial/_static/images/studio_tracing.webp and /dev/null differ
diff --git a/docs/tutorial/_static/language_switch.js b/docs/tutorial/_static/language_switch.js
deleted file mode 100644
index a78474442..000000000
--- a/docs/tutorial/_static/language_switch.js
+++ /dev/null
@@ -1,15 +0,0 @@
-function switchV1Language() {
- if (window.location.href.includes("zh_CN")) {
- window.location.href = "https://doc.agentscope.io";
- } else {
- window.location.href = "https://doc.agentscope.io/zh_CN";
- }
-}
-
-
-function navigateToV0(version) {
- if (version === "v0") {
- const suffix = window.location.href.includes("zh_CN") ? "/zh_CN" : "/en";
- window.location.href = "https://doc.agentscope.io/v0" + suffix;
- }
-}
diff --git a/docs/tutorial/_templates/components/language-switch.html b/docs/tutorial/_templates/components/language-switch.html
deleted file mode 100644
index 666819865..000000000
--- a/docs/tutorial/_templates/components/language-switch.html
+++ /dev/null
@@ -1,6 +0,0 @@
-{# _templates/components/language-switch.html #}
-<button onclick="switchV1Language()" class="language-switch-button" title="Switch to Chinese">
- <script>
- document.write(window.location.href.includes("zh_CN") ? "En": "中");
- </script>
-</button>
\ No newline at end of file
diff --git a/docs/tutorial/_templates/module.rst_t b/docs/tutorial/_templates/module.rst_t
deleted file mode 100644
index 74d73a4c5..000000000
--- a/docs/tutorial/_templates/module.rst_t
+++ /dev/null
@@ -1,5 +0,0 @@
-{{ basename | heading }}
-.. automodule:: {{ qualname }}
-{%- for option in automodule_options %}
- :{{ option }}:
-{%- endfor %}
\ No newline at end of file
diff --git a/docs/tutorial/_templates/package.rst_t b/docs/tutorial/_templates/package.rst_t
deleted file mode 100644
index 0c0f707da..000000000
--- a/docs/tutorial/_templates/package.rst_t
+++ /dev/null
@@ -1,10 +0,0 @@
-{%- macro automodule(modname, options) -%}
-.. automodule:: {{ modname }}
-{%- for option in options %}
- :{{ option }}:
-{%- endfor %}
-{%- endmacro %}
-
-{{- pkgname | heading }}
-
-{{ automodule(pkgname, automodule_options) }}
\ No newline at end of file
diff --git a/docs/tutorial/_templates/page.html b/docs/tutorial/_templates/page.html
deleted file mode 100644
index b4027017a..000000000
--- a/docs/tutorial/_templates/page.html
+++ /dev/null
@@ -1,239 +0,0 @@
-{% extends "base.html" %}
-
-{% block body -%}
-{{ super() }}
-{% include "partials/icons.html" %}
-
-<input type="checkbox" class="sidebar-toggle" name="__navigation" id="__navigation">
-<input type="checkbox" class="sidebar-toggle" name="__toc" id="__toc">
-<label class="overlay sidebar-overlay" for="__navigation">
- <div class="visually-hidden">Hide navigation sidebar</div>
-</label>
-<label class="overlay toc-overlay" for="__toc">
- <div class="visually-hidden">Hide table of contents sidebar</div>
-</label>
-
-<a class="skip-to-content muted-link" href="#furo-main-content">
- {%- trans -%}
- Skip to content
- {%- endtrans -%}
-</a>
-
-{% if theme_announcement -%}
-<div class="announcement">
- <aside class="announcement-content">
- {% block announcement %} {{ theme_announcement }} {% endblock announcement %}
- </aside>
-</div>
-{%- endif %}
-
-<div class="page">
- <header class="mobile-header">
- <div class="header-left">
- <label class="nav-overlay-icon" for="__navigation">
- <div class="visually-hidden">Toggle site navigation sidebar</div>
- <i class="icon"><svg><use href="#svg-menu"></use></svg></i>
- </label>
- </div>
- <div class="header-center">
- <a href="{{ pathto(master_doc) }}"><div class="brand">{{ docstitle if docstitle else project }}</div></a>
- </div>
- <div class="header-right">
- <div class="theme-toggle-container theme-toggle-header">
- <button class="theme-toggle">
- <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
- <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
- <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
- <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
- <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
- </button>
- </div>
- <label class="toc-overlay-icon toc-header-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
- <div class="visually-hidden">Toggle table of contents sidebar</div>
- <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
- </label>
- </div>
- </header>
- <aside class="sidebar-drawer">
- <div class="sidebar-container">
- {% block left_sidebar %}
- <div class="sidebar-sticky">
- {%- for sidebar_section in sidebars %}
- {%- include sidebar_section %}
- {%- endfor %}
- </div>
- {% endblock left_sidebar %}
- </div>
- </aside>
- <div class="main">
- <div class="content">
- <div class="article-container">
- <a href="#" class="back-to-top muted-link">
- <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
- <path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8v12z"></path>
- </svg>
- <span>{% trans %}Back to top{% endtrans %}</span>
- </a>
- <div class="content-icon-container">
- {% if theme_top_of_page_button != "edit" -%}
- {{ warning("Got configuration for 'top_of_page_button': this is deprecated.") }}
- {%- endif -%}
-
- {%- if theme_top_of_page_buttons == "" -%}
- {% if theme_top_of_page_button == None -%}
- {#- We respect the old configuration of disabling all the buttons -#}
- {%- set theme_top_of_page_buttons = [] -%}
- {% else %}
- {%- set theme_top_of_page_buttons = ["view", "edit"] -%}
- {%- endif -%}
- {% else -%}
- {% if theme_top_of_page_button != "edit" -%}
- {%- set theme_top_of_page_buttons = [] -%}
- {{ warning("Got configuration for both 'top_of_page_button' and 'top_of_page_buttons', ignoring both and removing all top of page buttons.") }}
- {%- endif -%}
- {%- endif -%}
- {%- include "components/language-switch.html" with context -%}
- {% for button in theme_top_of_page_buttons -%}
- {% if button == "view" %}
- {%- include "components/view-this-page.html" with context -%}
- {% elif button == "edit" %}
- {%- include "components/edit-this-page.html" with context -%}
- {% else %}
- {{ warning("Got an unsupported value in 'top_of_page_buttons' for theme configuration") }}
- {% endif %}
- {%- endfor -%}
- {#- Theme toggle -#}
- <div class="theme-toggle-container theme-toggle-content">
- <button class="theme-toggle">
- <div class="visually-hidden">Toggle Light / Dark / Auto color theme</div>
- <svg class="theme-icon-when-auto-light"><use href="#svg-sun-with-moon"></use></svg>
- <svg class="theme-icon-when-auto-dark"><use href="#svg-moon-with-sun"></use></svg>
- <svg class="theme-icon-when-dark"><use href="#svg-moon"></use></svg>
- <svg class="theme-icon-when-light"><use href="#svg-sun"></use></svg>
- </button>
- </div>
- <label class="toc-overlay-icon toc-content-icon{% if furo_hide_toc %} no-toc{% endif %}" for="__toc">
- <div class="visually-hidden">Toggle table of contents sidebar</div>
- <i class="icon"><svg><use href="#svg-toc"></use></svg></i>
- </label>
- </div>
- <article role="main" id="furo-main-content">
- {% block content %}{{ body }}{% endblock %}
- </article>
- </div>
- <footer>
- {% block footer %}
- <div class="related-pages">
- {% if next -%}
- <a class="next-page" href="{{ next.link }}">
- <div class="page-info">
- <div class="context">
- <span>{{ _("Next") }}</span>
- </div>
- <div class="title">{{ next.title }}</div>
- </div>
- <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
- </a>
- {%- endif %}
- {% if prev -%}
- <a class="prev-page" href="{{ prev.link }}">
- <svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
- <div class="page-info">
- <div class="context">
- <span>{{ _("Previous") }}</span>
- </div>
- {% if prev.link == pathto(master_doc) %}
- <div class="title">{{ _("Home") }}</div>
- {% else %}
- <div class="title">{{ prev.title }}</div>
- {% endif %}
- </div>
- </a>
- {%- endif %}
- </div>
- <div class="bottom-of-page">
- <div class="left-details">
- {%- if show_copyright %}
- <div class="copyright">
- {%- if hasdoc('copyright') %}
- {% trans path=pathto('copyright'), copyright=copyright|e -%}
- <a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
- {%- endtrans %}
- {%- else %}
- {% trans copyright=copyright|e -%}
- Copyright &#169; {{ copyright }}
- {%- endtrans %}
- {%- endif %}
- </div>
- {%- endif %}
- {% trans %}Made with {% endtrans -%}
- {%- if show_sphinx -%}
- {% trans %}<a href="https://www.sphinx-doc.org/">Sphinx</a> and {% endtrans -%}
- <a class="muted-link" href="https://pradyunsg.me">@pradyunsg</a>'s
- {% endif -%}
- {% trans %}
- <a href="https://github.com/pradyunsg/furo">Furo</a>
- {% endtrans %}
- {%- if last_updated -%}
- <div class="last-updated">
- {% trans last_updated=last_updated|e -%}
- Last updated on {{ last_updated }}
- {%- endtrans -%}
- </div>
- {%- endif %}
- </div>
- <div class="right-details">
- {% if theme_footer_icons or READTHEDOCS -%}
- <div class="icons">
- {% if theme_footer_icons -%}
- {% for icon_dict in theme_footer_icons -%}
- <a class="muted-link {{ icon_dict.class }}" href="{{ icon_dict.url }}" aria-label="{{ icon_dict.name }}">
- {{- icon_dict.html -}}
- </a>
- {% endfor %}
- {%- else -%}
- {#- Show Read the Docs project -#}
- {%- if READTHEDOCS and slug -%}
- <a class="muted-link" href="https://readthedocs.org/projects/{{ slug }}" aria-label="On Read the Docs">
- <svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
- <path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z" />
- </svg>
- </a>
- {%- endif -%}
- {#- Show GitHub repository home -#}
- {%- if READTHEDOCS and display_github and github_user != "None" and github_repo != "None" -%}
- <a class="muted-link" href="https://github.com/{{ github_user }}/{{ github_repo }}" aria-label="On GitHub">
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
- <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
- </svg>
- </a>
- {%- endif -%}
- {%- endif %}
- </div>
- {%- endif %}
- </div>
- </div>
- {% endblock footer %}
- </footer>
- </div>
- <aside class="toc-drawer{% if furo_hide_toc %} no-toc{% endif %}">
- {% block right_sidebar %}
- {% if not furo_hide_toc %}
- <div class="toc-sticky toc-scroll">
- <div class="toc-title-container">
- <span class="toc-title">
- {{ _("On this page") }}
- </span>
- </div>
- <div class="toc-tree-container">
- <div class="toc-tree">
- {{ toc }}
- </div>
- </div>
- </div>
- {% endif %}
- {% endblock right_sidebar %}
- </aside>
- </div>
-</div>
-{%- endblock %}
diff --git a/docs/tutorial/_templates/sidebar/navigation.html b/docs/tutorial/_templates/sidebar/navigation.html
deleted file mode 100644
index 14bd283ec..000000000
--- a/docs/tutorial/_templates/sidebar/navigation.html
+++ /dev/null
@@ -1,16 +0,0 @@
-<div class="sidebar-tree">
- <p class="caption" role="heading">
- <span class="caption-text">
- Version
- </span>
- <ul>
- <li>
- <select class="version-select" onchange="navigateToV0(this.value)">
- <option value="v1" selected>Stable(v1.0)</option>
- <option value="v0">v0.1.x</option>
- </select>
- </li>
- </ul>
- </p>
- {{ furo_navigation_tree }}
-</div>
diff --git a/docs/tutorial/en/Makefile b/docs/tutorial/en/Makefile
deleted file mode 100644
index 92dd33a1a..000000000
--- a/docs/tutorial/en/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS ?=
-SPHINXBUILD ?= sphinx-build
-SOURCEDIR = source
-BUILDDIR = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/tutorial/en/build.sh b/docs/tutorial/en/build.sh
deleted file mode 100755
index 1158fa280..000000000
--- a/docs/tutorial/en/build.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/bin/bash
-
-set -e
-
-# Clean old build files
-rm -rf build/ doctrees/
-
-# Build the html
-sphinx-build -M html ./ build
-
-# Remove temporary files (double insurance)
-rm -rf build/html/.doctrees
-rm -f build/html/.buildinfo
-find build/html -name "*.pickle" -delete
-find build/html -name "__pycache__" -delete
-find build/html -name "*.pyc" -delete
-
-echo "✅ English docs built successfully, temporary files cleaned"
\ No newline at end of file
diff --git a/docs/tutorial/en/conf.py b/docs/tutorial/en/conf.py
deleted file mode 100644
index 0f70577dc..000000000
--- a/docs/tutorial/en/conf.py
+++ /dev/null
@@ -1,140 +0,0 @@
-# -*- coding: utf-8 -*-
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-project = "AgentScope"
-copyright = "2025, Alibaba"
-author = "Alibaba Tongyi Lab"
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = [
- "myst_parser",
- "sphinx_gallery.gen_gallery",
- "sphinx.ext.autodoc",
- "sphinx.ext.viewcode",
- "sphinx.ext.napoleon",
-]
-
-myst_enable_extensions = [
- "colon_fence",
-]
-
-sphinx_gallery_conf = {
- "download_all_examples": False,
- "examples_dirs": [
- "src",
- ],
- "gallery_dirs": [
- "tutorial",
- ],
- "filename_pattern": "src/.*\.py",
- "example_extensions": [".py"],
-}
-
-templates_path = ["../_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-languages = ["en", "zh_CN"]
-language = "en"
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = "furo"
-html_title = (
- "<span style='font-weight: 700; color: #2196f3;'>AgentScope</span>"
-)
-html_logo = "../_static/images/logo.svg"
-html_favicon = "../_static/images/logo.svg"
-html_static_path = ["../_static"]
-html_css_files = [
- "css/gallery.css",
-]
-
-html_js_files = [
- "language_switch.js",
-]
-
-html_theme_options = {
- "footer_icons": [
- {
- "name": "GitHub",
- "url": "https://github.com/agentscope-ai/agentscope",
- "html": """
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
- <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
- </svg>
- """,
- "class": "",
- },
- {
- "name": "Discord",
- "url": "https://discord.gg/eYMpfnkG8h",
- "html": """
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" t="1753331148815" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="5721" width="200" height="200">
- <path d="M723.903423 359.138018c-69.65045-52.952793-136.256577-51.476757-136.256576-51.476757l-6.088649 7.564685c83.027027 25.738378 121.127207 62.085766 121.127207 62.085766a387.459459 387.459459 0 0 0-145.297297-46.956397 418.179459 418.179459 0 0 0-98.340901 1.752793 73.801802 73.801802 0 0 1-7.564684 1.476036 357.385225 357.385225 0 0 0-110.702703 30.258739 278.786306 278.786306 0 0 0-28.782703 13.653333S353.049369 339.488288 440.873514 313.657658l-4.612613-6.088649s-66.513874-1.476036-136.164324 51.476757A654.252973 654.252973 0 0 0 230.630631 642.167928s40.867748 71.126486 148.341621 73.801802c0 0 16.697658-22.694054 31.827027-40.867748-62.085766-18.45045-84.77982-57.565405-84.77982-57.565405a130.998198 130.998198 0 0 0 13.653334 7.564684s0 1.568288 1.476036 1.568289c1.476036 1.476036 3.044324 1.476036 4.52036 3.044324a238.748829 238.748829 0 0 0 34.779099 16.605405 513.199279 513.199279 0 0 0 71.218739 21.218018 350.558559 350.558559 0 0 0 125.555315 0 329.894054 329.894054 0 0 0 69.650451-21.218018A247.328288 247.328288 0 0 0 702.685405 618.09009s-24.262342 39.391712-87.824144 57.565405c13.653333 18.45045 31.827027 39.299459 31.827027 39.29946 107.473874-2.952072 148.341622-73.801802 146.773334-72.602523a654.990991 654.990991 0 0 0-69.558199-283.214414zM421.131532 596.77982a54.705586 54.705586 0 0 1 0-109.042162 54.705586 54.705586 0 0 1 0 109.042162z m177.124324 0a54.705586 54.705586 0 1 1 49.908468-54.521081 52.491532 52.491532 0 0 1-49.908468 54.521081z" p-id="5722"></path><path d="M512 1024A512 512 0 1 1 1024 512 512.645766 512.645766 0 0 1 512 1024z m0-972.892252a461.261261 461.261261 0 1 0 461.261261 461.261261 461.261261 461.261261 0 0 0-461.261261-461.261261z" p-id="5723"></path>
- </svg>
- """,
- "class": "",
- },
- {
- "name": "DingTalk",
- "url": "https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11",
- "html": """
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
- <path d="M512 0C229.205333 0 0 229.205333 0 512s229.205333 512 512 512 512-229.205333 512-512S794.794667 0 512 0z m237.312 480.810667c-1.109333 4.48-3.712 11.093333-7.424 18.986666h0.128l-0.426667 0.682667c-21.504 46.037333-77.610667 136.106667-77.610666 136.106667l-0.298667-0.597334-16.384 28.501334h79.018667l-150.912 200.917333 34.304-136.533333h-62.208l21.589333-90.282667c-17.493333 4.224-38.101333 10.026667-62.592 17.92 0 0-33.109333 19.370667-95.317333-37.333333 0 0-41.984-36.992-17.578667-46.165334 10.410667-3.925333 50.304-8.917333 81.706667-13.226666 42.410667-5.674667 68.48-8.789333 68.48-8.789334s-130.773333 2.005333-161.792-2.901333c-30.976-4.906667-70.4-56.704-78.805334-102.186667 0 0-12.970667-25.002667 27.904-13.226666 40.917333 11.818667 210.005333 46.08 210.005334 46.08S321.109333 411.434667 306.517333 394.922667c-14.634667-16.469333-43.093333-89.770667-39.424-134.869334 0 0 1.621333-11.221333 13.098667-8.192 0 0 162.602667 74.282667 273.792 114.986667 111.104 40.704 207.786667 61.397333 195.328 114.005333z" opacity=".65" p-id="6077"></path>
- </svg>
- """,
- "class": "",
- },
- ],
- "light_css_variables": {
- "color-brand-primary": "#2196f3",
- "color-brand-content": "#2196f3",
- "color-admonition-background": "#f8f9fa",
- },
- "dark_css_variables": {
- "color-link": "#2196f3",
- "color-link--hover": "#2196f3",
- "color-brand-primary": "#64b5f6",
- "color-brand-content": "#64b5f6",
- },
-}
-
-source_suffix = [".md", ".rst"]
-
-
-# -- Options for API documentation -------------------------------------------
-
-autodoc_member_order = "bysource"
-autodoc_typehints = "description"
-autodoc_class_signature = "separated"
-autodoc_default_options = {
- "special-members": "__call__",
-}
-
-add_module_names = False
-python_display_short_literal_types = True
-
-
-def skip_member(app, what, name, obj, skip, options):
- if name in [
- "__call__",
- "_format",
- "_format_agent_message",
- "_format_tool_sequence",
- ]:
- return False
-
- return skip
-
-
-def setup(app):
- app.connect("autodoc-skip-member", skip_member)
diff --git a/docs/tutorial/en/index.rst b/docs/tutorial/en/index.rst
deleted file mode 100644
index d39955f75..000000000
--- a/docs/tutorial/en/index.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-.. AgentScope Doc documentation master file, created by
- sphinx-quickstart on Thu Aug 8 15:07:21 2024.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to AgentScope's documentation!
-==========================================
-
-.. toctree::
- :maxdepth: 1
- :caption: Tutorial
-
- tutorial/quickstart_installation
- tutorial/quickstart_key_concept
- tutorial/quickstart_message
- tutorial/quickstart_agent
-
-.. toctree::
- :maxdepth: 1
- :caption: Workflow
-
- tutorial/workflow_conversation
- tutorial/workflow_multiagent_debate
- tutorial/workflow_concurrent_agents
- tutorial/workflow_routing
- tutorial/workflow_handoffs
-
-.. toctree::
- :maxdepth: 1
- :caption: FAQ
-
- tutorial/faq
-
-.. toctree::
- :maxdepth: 1
- :caption: Model and Context
-
- tutorial/task_model
- tutorial/task_prompt
- tutorial/task_token
- tutorial/task_memory
- tutorial/task_long_term_memory
-
-.. toctree::
- :maxdepth: 1
- :caption: Tool
-
- tutorial/task_tool
- tutorial/task_mcp
- tutorial/task_agent_skill
-
-.. toctree::
- :maxdepth: 1
- :caption: Agent
-
- tutorial/task_agent
- tutorial/task_state
- tutorial/task_hook
- tutorial/task_middleware
- tutorial/task_a2a
- tutorial/task_realtime
-
-.. toctree::
- :maxdepth: 1
- :caption: Features
-
- tutorial/task_pipeline
- tutorial/task_plan
- tutorial/task_rag
- tutorial/task_studio
- tutorial/task_tracing
- tutorial/task_eval
- tutorial/task_eval_openjudge
- tutorial/task_embedding
- tutorial/task_tts
- tutorial/task_tuner
diff --git a/docs/tutorial/en/make.bat b/docs/tutorial/en/make.bat
deleted file mode 100644
index dc1312ab0..000000000
--- a/docs/tutorial/en/make.bat
+++ /dev/null
@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.https://www.sphinx-doc.org/
- exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
diff --git a/docs/tutorial/en/src/faq.py b/docs/tutorial/en/src/faq.py
deleted file mode 100644
index 9134c8f33..000000000
--- a/docs/tutorial/en/src/faq.py
+++ /dev/null
@@ -1,53 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _faq:
-
-FAQ
-========================================
-
-About AgentScope
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*What is AgentScope?*
- AgentScope is a multi-agent framework, aiming to provide a simple yet efficient way to build LLM-empowered agent applications.
-
-*What is the difference between AgentScope v1.0 and v0.x?*
- AgentScope v1.0 is a complete refactoring of the framework, equipped with new features and improvements. Refer to for detailed changes.
-
-
-About Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*How to integrate my own model with AgentScope?*
- Create your own model by inheriting ``agentscope.model.ChatModelBase`` and implement the ``__call__`` method.
-
-*What models are supported by AgentScope?*
- Currently, AgentScope has built-in support for DashScope, Gemini, OpenAI, Anthropic, and Ollama APIs, and the ``OpenAIChatModel`` compatible with DeepSeek and vLLMs models.
-
-*How to monitor the token usage in AgentScope?*
- In AgentScope Studio, we provide visualization of token usage and tracing. Refer :ref:`studio` section for more details.
-
-
-About Agent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*How to create my own agent?*
- You can choose to use the ``ReActAgent`` class directly, or create your own agent by inheriting from ``AgentBase`` or ``ReActAgentBase`` classes. Refer to the :ref:`agent` section for more details.
-
-
-*How to forward the (streaming) output of agents to my own frontend or application?*
- Use the pre hook of the ``print`` function to forward printing messages. Refer to the :ref:`hook` section.
-
-
-About Tools
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*How many tools are provided by AgentScope?*
- AgentScope provides a set of built-in tools, including ``execute_python_code``, ``execute_shell_command``, ``write_text_file`` , etc. You can find them under ``agentscope.tool`` module.
-
-
-About Reporting Bugs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*How can I report a bug in AgentScope?*
- If you encounter a bug while using AgentScope, please report it by opening an issue on our GitHub repository.
-
-*How can I report a security bug in AgentScope?*
- If you discover a security issue in AgentScope, please report it to us through the `Alibaba Security Response Center (ASRC) <https://security.alibaba.com/>`_.
-
-"""
diff --git a/docs/tutorial/en/src/quickstart_agent.py b/docs/tutorial/en/src/quickstart_agent.py
deleted file mode 100644
index 38db4fbbe..000000000
--- a/docs/tutorial/en/src/quickstart_agent.py
+++ /dev/null
@@ -1,245 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _react-agent:
-
-Create ReAct Agent
-====================
-
-AgentScope provides out-of-the-box ReAct agent ``ReActAgent`` under ``agentscope.agent`` that can be used directly.
-
-It supports the following features at the same time:
-
-- ✨ Basic features
- - Support **hooks** around ``reply``, ``observe``, ``print``, ``_reasoning`` and ``_acting`` functions
- - Support structured output
-- ✋ Realtime Steering
- - Support user **interrupt**
- - Support customized **interruption handling**
-- 🛠️ Tools
- - Support both **sync/async** tool functions
- - Support **streaming** tool response
- - Support **stateful** tools management
- - Support **parallel** tool calls
- - Support **MCP** server
-- 💾 Memory
- - Support **agent-controlled** long-term memory management
- - Support static long-term memory management
-
-.. tip:: Refer to the :ref:`agent` section for more details about these
- features. In quickstart, we focus on how to create a ReAct agent and run it.
-
-"""
-
-from agentscope.agent import ReActAgent, AgentBase
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-import asyncio
-import os
-
-from agentscope.tool import Toolkit, execute_python_code
-
-
-# %%
-# Creating ReAct Agent
-# ------------------------------
-# To improve the flexibility, the ``ReActAgent`` class exposes the following parameters in its constructor:
-#
-# .. list-table:: Initialization parameters of ``ReActAgent`` class
-# :header-rows: 1
-#
-# * - Parameter
-# - Further Reading
-# - Description
-# * - ``name`` (required)
-# -
-# - The name of the agent
-# * - ``sys_prompt`` (required)
-# -
-# - The system prompt of the agent
-# * - ``model`` (required)
-# - :ref:`model`
-# - The model used by the agent to generate responses
-# * - ``formatter`` (required)
-# - :ref:`prompt`
-# - The prompt construction strategy, should be consistent with the model
-# * - ``toolkit``
-# - :ref:`tool`
-# - The toolkit to register/call tool functions.
-# * - ``memory``
-# - :ref:`memory`
-# - The short-term memory used to store the conversation history
-# * - ``long_term_memory``
-# - :ref:`long-term-memory`
-# - The long-term memory
-# * - ``long_term_memory_mode``
-# - :ref:`long-term-memory`
-# - The mode of the long-term memory:
-#
-# - ``agent_control``: allow agent to control the long-term memory by itself
-# - ``static_control``: retrieving and recording from/to long-term memory will happen in the beginning/end of each reply.
-# - ``both``: activate the above two modes at the same time
-# * - ``enable_meta_tool``
-# - :ref:`tool`
-# - Whether to enable the meta tool, which allows the agent to manage tools by itself
-# * - ``parallel_tool_calls``
-# - :ref:`agent`
-# - Whether to allow parallel tool calls
-# * - ``max_iters``
-# -
-# - The maximum number of iterations for the agent to generate a response
-# * - ``plan_notebook``
-# - :ref:`plan`
-# - The plan notebook to manage the plans
-# * - ``print_hint_msg``
-# -
-# - Whether to print the hint message generated by the plan notebook at each step
-#
-# Taking DashScope API as example, we create an agent object as follows:
-
-
-async def creating_react_agent() -> None:
- """Create a ReAct agent and run a simple task."""
- # Prepare tools
- toolkit = Toolkit()
- toolkit.register_tool_function(execute_python_code)
-
- jarvis = ReActAgent(
- name="Jarvis",
- sys_prompt="You're a helpful assistant named Jarvis",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=True,
- enable_thinking=False,
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- memory=InMemoryMemory(),
- )
-
- msg = Msg(
- name="user",
- content="Hi! Jarvis, run Hello World in Python.",
- role="user",
- )
-
- await jarvis(msg)
-
-
-asyncio.run(creating_react_agent())
-
-# %%
-# Creating From Scratch
-# --------------------------------
-# You may want to create an agent from scratch, AgentScope provides two base classes for you to inherit from:
-#
-# .. list-table::
-# :header-rows: 1
-#
-# * - Class
-# - Abstract Methods
-# - Description
-# * - ``AgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``handle_interrupt``
-# - - The base class for all agents, supporting pre- and post- hooks around ``reply``, ``observe`` and ``print`` functions.
-# - Implement the realtime steering within the ``__call__`` method.
-# * - ``ReActAgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``handle_interrupt``
-# | ``_reasoning``
-# | ``_acting``
-# - Add two abstract functions ``_reasoning`` and ``_acting`` on the basis of ``AgentBase``, as well as their hooks.
-#
-# Please refer to the :ref:`agent` section for more details about the agent class.
-#
-# Taking the ``AgentBase`` class as an example, we can create a custom agent
-# class by inheriting from it and implementing the ``reply`` method.
-
-
-class MyAgent(AgentBase):
- """A custom agent class"""
-
- def __init__(self) -> None:
- """Initialize the agent"""
- super().__init__()
-
- self.name = "Friday"
- self.sys_prompt = "You're a helpful assistant named Friday."
- self.model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- )
- self.formatter = DashScopeChatFormatter()
- self.memory = InMemoryMemory()
-
- async def reply(self, msg: Msg | list[Msg] | None) -> Msg:
- """Reply to the message."""
- await self.memory.add(msg)
-
- # Prepare the prompt
- prompt = await self.formatter.format(
- [
- Msg("system", self.sys_prompt, "system"),
- *await self.memory.get_memory(),
- ],
- )
-
- # Call the model
- response = await self.model(prompt)
-
- msg = Msg(
- name=self.name,
- content=response.content,
- role="assistant",
- )
-
- # Record the response in memory
- await self.memory.add(msg)
-
- # Print the message
- await self.print(msg)
- return msg
-
- async def observe(self, msg: Msg | list[Msg] | None) -> None:
- """Observe the message."""
- # Store the message in memory
- await self.memory.add(msg)
-
- async def handle_interrupt(self) -> Msg:
- """Postprocess the interrupt."""
- # Taking a fixed response as example
- return Msg(
- name=self.name,
- content="I noticed you interrupted me, how can I help you?",
- role="assistant",
- )
-
-
-async def run_custom_agent() -> None:
- """Run the custom agent."""
- agent = MyAgent()
- msg = Msg(
- name="user",
- content="Who are you?",
- role="user",
- )
- await agent(msg)
-
-
-asyncio.run(run_custom_agent())
-
-# %%
-#
-# Further Reading
-# ---------------------
-# - :ref:`agent`
-# - :ref:`model`
-# - :ref:`prompt`
-# - :ref:`tool`
-#
diff --git a/docs/tutorial/en/src/quickstart_installation.py b/docs/tutorial/en/src/quickstart_installation.py
deleted file mode 100644
index 90cae53f3..000000000
--- a/docs/tutorial/en/src/quickstart_installation.py
+++ /dev/null
@@ -1,56 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _installation:
-
-Installation
-============================
-
-AgentScope requires Python 3.10 or higher. You can install from source or pypi.
-
-From PyPI
-----------------
-.. code-block:: bash
-
- pip install agentscope
-
-From Source
-----------------
-To install AgentScope from source, you need to clone the repository from
-GitHub and install by the following commands
-
-.. code-block:: bash
-
- git clone -b main https://github.com/agentscope-ai/agentscope
- cd agentscope
- pip install -e .
-
-To ensure AgentScope is installed successfully, check via executing the following code:
-"""
-
-import agentscope
-
-print(agentscope.__version__)
-
-# %%
-# Extra Dependencies
-# ----------------------------
-#
-# To satisfy the requirements of different functionalities, AgentScope provides
-# extra dependencies that can be installed based on your needs.
-#
-# - full: Including extra dependencies for model APIs and tool functions
-# - dev: Development dependencies, including testing and documentation tools
-#
-# For example, when installing the full dependencies, the installation command varies depending on your operating system.
-#
-# For Windows users:
-#
-# .. code-block:: bash
-#
-# pip install agentscope[full]
-#
-# For Mac and Linux users:
-#
-# .. code-block:: bash
-#
-# pip install agentscope\[full\]
diff --git a/docs/tutorial/en/src/quickstart_key_concept.py b/docs/tutorial/en/src/quickstart_key_concept.py
deleted file mode 100644
index f3cc7aefd..000000000
--- a/docs/tutorial/en/src/quickstart_key_concept.py
+++ /dev/null
@@ -1,122 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. key-concepts:
-
-Key Concepts
-====================================
-
-This chapter establishes key concepts from an engineering
-perspective to introduce AgentScope's design.
-
-.. note:: The goal of introducing the key concepts in AgentScope is to claim what practical problems AgentScope addresses and how it supports developers, rather than to offer formal definitions.
-
-State
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In AgentScope, state management is a fundamental building block that maintains snapshots of objects' runtime data.
-
-AgentScope separates object initialization from state management, allowing
-object to be restored to different states after initialization through
-``load_state_dict`` and ``state_dict`` methods.
-
-In AgentScope, agent, memory, long-term memory and toolkit are all stateful
-objects. AgentScope links the state management of these objects together by supporting nested state management.
-
-Message
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In AgentScope, message is the fundamental data structure,
-used to
-
-- exchange information between agents,
-- display information in the user interface,
-- store information in memory,
-- act as a unified medium between AgentScope and different LLM APIs.
-
-Tool
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A tool in AgentScope refers to callable object, no matter it's a
-
-- function,
-- partial function,
-- instance method,
-- class method,
-- static method, or
-- callable instance with ``__call__`` method.
-
-Besides, the callable object can be either
-
-- async or sync,
-- streaming or non-streaming.
-
-So feel free to use any callable object as a tool in AgentScope.
-
-Agent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In AgentScope, the agent behaviors are abstracted into three core functions in
-``AgentBase`` class:
-
-- ``reply``: Handle incoming message(s) and generate a response message.
-- ``observe``: Receive message(s) from the environment or other agents without returning a response.
-- ``print``: Display message(s) to the target terminal, web interface, etc.
-
-To support realtime steering, an additional ``handle_interrupt`` function is
-provided to handle user interrupts during the agent's reply process.
-
-Additionally, ReAct agent is the most important agent in AgentScope, where
-the agent's reply process is divided into two stages:
-
-- reasoning: thinking and generating tool calls by calling the LLM
-- acting: execute the tool functions.
-
-Thus, we provide two additional core functions in ``ReActAgentBase`` class,
-``_reasoning`` and ``_acting``.
-
-Formatter
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Formatter is the core component for LLM compatibility in AgentScope,
-responsible for converting message objects into the required format for
-LLM APIs.
-
-Besides, additional functionality such as prompt engineering, truncation,
-and message validation can also be implemented in the formatter.
-
-Within the formatter, the "multi-agent" (or "multi-identity") concept differs
-from the common multi-agent orchestration concept.
-It focuses on the scenario where multiple identities are involved in the
-given messages, so that the common used ``role`` field (usually "role",
-"assistant" or "system") in LLM APIs cannot distinguish them.
-
-Therefore, AgentScope provides multi-agent formatter to handle
-this scenario, usually used in games, multi-person chats, and social
-simulations.
-
-.. note:: Multi-agent workflow **!=** multi-agent in formatter.
- For example, even if the following code snippet may involve multiple
- agents (the ``tool_agent`` and the ``tool_function`` caller), the input query
- is wrapped into a **user** message, so the ``role`` field can still distinguish
- between them.
-
- .. code-block:: python
-
- async def tool_function(query: str) -> str:
- \"\"\"Tool function calling another agent\"\"\"
- msg = Msg("user", query, role="user")
- tool_agent = Agent(name="Programmer")
- return await tool_agent(msg)
-
- Understanding this distinction helps developers better grasp AgentScope's formatter design.
-
-
-Long-Term Memory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Although providing different base classes for short- and
-long-term memory, there are no strict distinctions between them in AgentScope.
-
-In our view, everything should be **requirement-driven**. As long as your
-needs are excellently met, developers can completely use just one powerful
-memory system.
-
-For ensuring the flexibility of AgentScope, we provide a two mode long-term
-memory system, allowing the agent to manage (record and retrieve) the
-long-term memory by its own.
-"""
diff --git a/docs/tutorial/en/src/quickstart_message.py b/docs/tutorial/en/src/quickstart_message.py
deleted file mode 100644
index cf6bad84c..000000000
--- a/docs/tutorial/en/src/quickstart_message.py
+++ /dev/null
@@ -1,267 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _message:
-
-Create Message
-====================
-
-Message is the core concept in AgentScope, used to support multimodal data, tools API, information storage/exchange and prompt construction.
-
-A message consists of four fields:
-
-- ``name``,
-- ``role``,
-- ``content``, and
-- ``metadata``
-
-The types and descriptions of these fields are as follows:
-
-.. list-table:: The fields in a message object
- :header-rows: 1
-
- * - Field
- - Type
- - Description
- * - name
- - ``str``
- - The name/identity of the message sender
- * - role
- - | ``Literal[``
- | ``"system",``
- | ``"assistant",``
- | ``"user"``
- | ``]``
- - The role of the message sender, which must be one of "system", "assistant", or "user".
- * - content
- - ``str | list[ContentBlock]``
- - The data of the message, which can be a string or a list of blocks.
- * - metadata
- - ``dict[str, JSONSerializableObject] | None``
- - A dict containing additional metadata about the message, usually used for structured output.
-
-.. tip:: - In application with multiple identities, the ``name`` field is used to distinguish between different identities.
- - The ``metadata`` field is recommended for structured output, which won't be included in the prompt construction.
-
-Next, we introduce the supported blocks in the ``content`` field by their corresponding scenarios.
-"""
-
-from agentscope.message import (
- Msg,
- Base64Source,
- TextBlock,
- ThinkingBlock,
- ImageBlock,
- AudioBlock,
- VideoBlock,
- ToolUseBlock,
- ToolResultBlock,
-)
-import json
-
-# %%
-# Creating Textual Message
-# -----------------------------
-# Creating a message object by providing the ``name``, ``role``, and ``content`` fields.
-#
-
-msg = Msg(
- name="Jarvis",
- role="assistant",
- content="Hi! How can I help you?",
-)
-
-print(f"The name of the sender: {msg.name}")
-print(f"The role of the sender: {msg.role}")
-print(f"The content of the message: {msg.content}")
-
-# %%
-# Creating Multimodal Message
-# --------------------------------------
-# The message class supports multimodal content by providing different content blocks:
-#
-# .. list-table:: Multimodal content blocks in AgentScope
-# :header-rows: 1
-#
-# * - Class
-# - Description
-# - Example
-# * - TextBlock
-# - Pure text data
-# - .. code-block:: python
-#
-# TextBlock(
-# type="text",
-# text="Hello, world!"
-# )
-# * - ImageBlock
-# - The image data
-# - .. code-block:: python
-#
-# ImageBlock(
-# type="image",
-# source=URLSource(
-# type="url",
-# url="https://example.com/image.jpg"
-# )
-# )
-# * - AudioBlock
-# - The audio data
-# - .. code-block:: python
-#
-# AudioBlock(
-# type="audio",
-# source=URLSource(
-# type="url",
-# url="https://example.com/audio.mp3"
-# )
-# )
-# * - VideoBlock
-# - The video data
-# - .. code-block:: python
-#
-# VideoBlock(
-# type="video",
-# source=URLSource(
-# type="url",
-# url="https://example.com/video.mp4"
-# )
-# )
-#
-# For ``ImageBlock``, ``AudioBlock`` and ``VideoBlock``, you can use either a base64 encoded string as the source:
-#
-
-msg = Msg(
- name="Jarvis",
- role="assistant",
- content=[
- TextBlock(
- type="text",
- text="This is a multimodal message with base64 encoded data.",
- ),
- ImageBlock(
- type="image",
- source=Base64Source(
- type="base64",
- media_type="image/jpeg",
- data="/9j/4AAQSkZ...",
- ),
- ),
- AudioBlock(
- type="audio",
- source=Base64Source(
- type="base64",
- media_type="audio/mpeg",
- data="SUQzBAAAAA...",
- ),
- ),
- VideoBlock(
- type="video",
- source=Base64Source(
- type="base64",
- media_type="video/mp4",
- data="AAAAIGZ0eX...",
- ),
- ),
- ],
-)
-
-# %%
-# Creating Thinking Message
-# --------------------------------------
-# The ``ThinkingBlock`` is to support reasoning models, containing the thinking process of the model.
-#
-
-msg_thinking = Msg(
- name="Jarvis",
- role="assistant",
- content=[
- ThinkingBlock(
- type="thinking",
- thinking="I'm building an example for thinking block in AgentScope.",
- ),
- TextBlock(
- type="text",
- text="This is an example for thinking block.",
- ),
- ],
-)
-
-# %%
-# .. _tool-block:
-#
-# Creating Tool Use/Result Message
-# --------------------------------------
-# The ``ToolUseBlock`` and ``ToolResultBlock`` are to support tools API:
-#
-
-msg_tool_call = Msg(
- name="Jarvis",
- role="assistant",
- content=[
- ToolUseBlock(
- type="tool_use",
- id="343",
- name="get_weather",
- input={
- "location": "Beijing",
- },
- ),
- ],
-)
-
-msg_tool_res = Msg(
- name="system",
- role="system",
- content=[
- ToolResultBlock(
- type="tool_result",
- id="343",
- name="get_weather",
- output="The weather in Beijing is sunny with a temperature of 25°C.",
- ),
- ],
-)
-
-
-# %%
-# .. tip:: Refer to the :ref:`tool` section for more information about tools API in AgentScope.
-#
-# Serialization and Deserialization
-# ------------------------------------------------
-# Message object can be serialized and deserialized by ``to_dict`` and ``from_dict`` methods, respectively.
-
-serialized_msg = msg.to_dict()
-
-print(type(serialized_msg))
-print(json.dumps(serialized_msg, indent=4))
-
-# %%
-# Deserialize a message from a string in JSON format.
-
-new_msg = Msg.from_dict(serialized_msg)
-
-print(type(new_msg))
-print(f'The sender of the message: "{new_msg.name}"')
-print(f'The role of the sender: "{new_msg.role}"')
-print(f'The content of the message: "{json.dumps(new_msg.content, indent=4)}"')
-
-# %%
-# Property Functions
-# ------------------------------------------------
-# To ease the use of message object, AgentScope provides these functions:
-#
-# .. list-table:: Functions of the message object
-# :header-rows: 1
-#
-# * - Function
-# - Parameters
-# - Description
-# * - get_text_content
-# - \-
-# - Gather content from all ``TextBlock`` in to a single string (separated by "\\n").
-# * - get_content_blocks
-# - ``block_type``
-# - Return a list of content blocks of the specified type. If ``block_type`` not provided, return content in blocks format.
-# * - has_content_blocks
-# - ``block_type``
-# - Check whether the message has content blocks of the specified type. The ``str`` content is considered as a ``TextBlock`` type.
diff --git a/docs/tutorial/en/src/task_a2a.py b/docs/tutorial/en/src/task_a2a.py
deleted file mode 100644
index c46ec0e8a..000000000
--- a/docs/tutorial/en/src/task_a2a.py
+++ /dev/null
@@ -1,212 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _a2a:
-
-A2A Agent
-============================
-
-A2A (Agent-to-Agent) is an open standard protocol for enabling interoperable communication between different AI agents.
-
-AgentScope provides support for the A2A protocol at two levels: obtaining Agent Card information and connecting to remote agents. The related APIs are as follows:
-
-.. list-table:: A2A Related Classes
- :header-rows: 1
-
- * - Class
- - Description
- * - ``A2AAgent``
- - Agent class for communicating with remote A2A agents
- * - ``A2AChatFormatter``
- - Formatter for converting between AgentScope messages and A2A message/task formats
- * - ``AgentCardResolverBase``
- - Base class for Agent Card resolvers
- * - ``FileAgentCardResolver``
- - Resolver for loading Agent Cards from local JSON files
- * - ``WellKnownAgentCardResolver``
- - Resolver for fetching Agent Cards from the well-known path of a URL
- * - ``NacosAgentCardResolver``
- - Resolver for fetching Agent Cards from the Nacos Agent Registry
-
-This section demonstrates how to create an ``A2AAgent`` and communicate with remote A2A agents.
-
-.. note:: Note that A2A support is an **experimental feature** and may change in future versions. Due to limitations of the A2A protocol itself, ``A2AAgent`` cannot fully align with local agents like ``ReActAgent``, including:
-
- - Only supports chatbot scenarios, i.e., only supports conversations between one user and one agent (does not affect handoff/router usage patterns)
- - Does not support real-time interruption during conversations
- - Does not support agentic structured output
- - In the current implementation, messages received by the ``observe`` method are stored locally and sent to the remote agent together when the ``reply`` method is called. Therefore, if several ``observe`` calls are made without a subsequent ``reply`` call, those messages will not be seen by the remote agent
-
-
-"""
-
-from a2a.types import AgentCard, AgentCapabilities
-from v2.nacos import ClientConfig
-
-from agentscope.a2a import WellKnownAgentCardResolver, NacosAgentCardResolver
-from agentscope.agent import A2AAgent, UserAgent
-from agentscope.message import Msg, TextBlock
-from agentscope.tool import ToolResponse
-
-# %%
-# Obtaining Agent Cards
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# First, we need to obtain an Agent Card to connect to the corresponding agent. An Agent Card contains information such as the agent's name, description, capabilities, and connection details.
-#
-# Manually Creating Agent Card
-# --------------------------------
-#
-# If you know all the information of an Agent Card, you can directly create an Agent Card object from `a2a.types.AgentCard`.
-#
-
-# Create an Agent Card object
-agent_card = AgentCard(
- name="Friday", # Agent name
- description="A fun chatting companion", # Agent description
- url="http://localhost:8000", # Agent's RPC service URL
- version="1.0.0", # Agent version
- capabilities=AgentCapabilities( # Agent capability configuration
- push_notifications=False,
- state_transition_history=True,
- streaming=True,
- ),
- default_input_modes=["text/plain"], # Supported input formats
- default_output_modes=["text/plain"], # Supported output formats
- skills=[], # Agent skill list
-)
-
-# %%
-#
-# Fetching from Remote Services
-# --------------------------------
-# AgentScope also supports fetching from the standard path of remote services (well-known server).
-# Here's an example using ``WellKnownAgentCardResolver`` to fetch an Agent Card from the standard path of a remote service:
-#
-
-
-async def agent_card_from_well_known_website() -> AgentCard:
- """Example of fetching an Agent Card from the well-known path of a remote service."""
- # Create an Agent Card resolver
- resolver = WellKnownAgentCardResolver(
- base_url="http://localhost:8000",
- )
- # Fetch and return the Agent Card
- return await resolver.get_agent_card()
-
-
-# %%
-# Loading Agent Cards from Local Files
-# --------------------------------
-#
-# The ``FileAgentCardResolver`` class supports loading Agent Cards from local JSON files, suitable for configuration file management scenarios.
-# An example of an Agent Card in JSON format is shown below:
-#
-# .. code-block:: json
-# :caption: Example Agent Card JSON file content
-#
-# {
-# "name": "RemoteAgent",
-# "url": "http://localhost:8000",
-# "description": "Remote A2A Agent",
-# "version": "1.0.0",
-# "capabilities": {},
-# "default_input_modes": ["text/plain"],
-# "default_output_modes": ["text/plain"],
-# "skills": []
-# }
-#
-# You can easily load this file using ``FileAgentCardResolver``:
-#
-
-
-async def agent_card_from_file() -> AgentCard:
- """Example of loading an Agent Card from a local JSON file."""
- from agentscope.a2a import FileAgentCardResolver
-
- # Load Agent Card from JSON file
- resolver = FileAgentCardResolver(
- file_path="./agent_card.json", # JSON file path
- )
- # Fetch and return the Agent Card
- return await resolver.get_agent_card()
-
-
-# %%
-# Fetching Agent Cards from Nacos Registry
-# --------------------------------
-#
-# Nacos is an open-source dynamic service discovery, configuration management, and service management platform. In version 3.1.0, it introduced the Agent Registry feature, supporting distributed registration, discovery, and version management of A2A agents.
-#
-# .. important:: The prerequisite for using ``NacosAgentCardResolver`` is that the user has deployed a Nacos server version 3.1.0 or higher. For deployment and registration procedures, please refer to the `official documentation <https://nacos.io/docs/latest/quickstart/quick-start>`_.
-#
-
-
-async def agent_card_from_nacos() -> AgentCard:
- """Example of fetching an Agent Card from the Nacos registry."""
-
- # Create a Nacos Agent Card resolver
- resolver = NacosAgentCardResolver(
- remote_agent_name="my-remote-agent", # Agent name registered in Nacos
- nacos_client_config=ClientConfig(
- server_addresses="http://localhost:8848", # Nacos server address
- # Other optional configuration items
- ),
- )
- # Fetch and return the Agent Card
- return await resolver.get_agent_card()
-
-
-# %%
-# Building an A2A Agent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The ``A2AAgent`` class provided by AgentScope is used to communicate with remote A2A agents, and its usage is similar to regular agents.
-
-agent = A2AAgent(agent_card=agent_card)
-
-# %%
-# Using ``A2AAgent``, developers can build chatbot scenario conversations, or encapsulate it as a tool function to build more complex application scenarios such as handoff/router.
-# Currently, the format protocol conversion supported by ``A2AAgent`` is handled by ``agentscope.formatter.A2AChatFormatter``, which supports:
-#
-# - Converting AgentScope's ``Msg`` messages to A2A protocol's ``Message`` format
-# - Converting A2A protocol responses back to AgentScope's ``Msg`` format
-# - Converting A2A protocol's ``Task`` responses to AgentScope's ``Msg`` format
-# - Supporting multiple content types such as text, images, audio, and video
-#
-
-
-async def a2a_in_chatbot() -> None:
- """Example of chatting using A2AAgent."""
-
- user = UserAgent("user")
-
- msg = None
- while True:
- msg = await user(msg)
- if msg.get_text_content() == "exit":
- break
- msg = await agent(msg)
-
-
-# %%
-# Or encapsulate it as a tool function for invocation:
-
-
-async def create_worker(query: str) -> ToolResponse:
- """Complete a given task through a sub-agent
-
- Args:
- query (`str`):
- Description of the task to be completed by the sub-agent
- """
- res = await agent(
- Msg("user", query, "user"),
- )
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=res.get_text_content(),
- ),
- ],
- )
diff --git a/docs/tutorial/en/src/task_agent.py b/docs/tutorial/en/src/task_agent.py
deleted file mode 100644
index 3cd18b8b6..000000000
--- a/docs/tutorial/en/src/task_agent.py
+++ /dev/null
@@ -1,426 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _agent:
-
-Agent
-=========================
-
-In this tutorial, we first focus on introducing the ReAct agent in AgentScope,
-then we briefly introduce how to customize your own agent from scratch.
-
-ReAct Agent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-In AgentScope, the ``ReActAgent`` class integrates various features into a final implementation, including
-
-.. list-table:: Features of ``ReActAgent``
- :header-rows: 1
-
- * - Feature
- - Reference
- * - Support realtime steering
- -
- * - Support memory compression
- -
- * - Support parallel tool calls
- -
- * - Support structured output
- -
- * - Support fine-grained MCP control
- - :ref:`mcp`
- * - Support agent-controlled tools management (Meta tool)
- - :ref:`tool`
- * - Support self-controlled long-term memory
- - :ref:`long-term-memory`
- * - Support automatic state management
- - :ref:`state`
-
-
-Due to limited space, in this tutorial we only demonstrate the first three
-features of ``ReActAgent`` class, leaving the others to the corresponding sections
-listed above.
-
-"""
-
-import asyncio
-import json
-import os
-from datetime import datetime
-import time
-
-from pydantic import BaseModel, Field
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import TextBlock, Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit, ToolResponse
-
-
-# %%
-# Realtime Steering
-# ---------------------------------------
-#
-# The realtime steering allows user to interrupt the agent's reply at any time,
-# which is implemented based on the asyncio cancellation mechanism.
-#
-# Specifically, when calling the ``interrupt`` method of the agent, it will
-# cancel the current reply task, and execute the ``handle_interrupt`` method
-# for postprocessing.
-#
-# .. hint:: With the feature of supporting streaming tool results in
-# :ref:`tool`, users can interrupt the tool execution if it takes too long or
-# deviates from user expectations by Ctrl+C in the terminal or calling the
-# ``interrupt`` method of the agent in your code.
-#
-# The interruption logic has been implemented in the ``AgentBase`` class as a
-# basic feature, leaving a ``handle_interrupt`` method for users to customize the
-# post-processing of interruption as follows:
-#
-# .. code-block:: python
-#
-# # code snippet of AgentBase
-# class AgentBase:
-# ...
-# async def __call__(self, *args: Any, **kwargs: Any) -> Msg:
-# ...
-# reply_msg: Msg | None = None
-# try:
-# self._reply_task = asyncio.current_task()
-# reply_msg = await self.reply(*args, **kwargs)
-#
-# except asyncio.CancelledError:
-# # Catch the interruption and handle it by the handle_interrupt method
-# reply_msg = await self.handle_interrupt(*args, **kwargs)
-#
-# ...
-#
-# @abstractmethod
-# async def handle_interrupt(self, *args: Any, **kwargs: Any) -> Msg:
-# pass
-#
-#
-# In ``ReActAgent`` class, we return a fixed message "I noticed that you have
-# interrupted me. What can I do for you?" as follows:
-#
-# .. figure:: ../../_static/images/interruption_en.gif
-# :width: 100%
-# :align: center
-# :class: bordered-image
-# :alt: Example of interruption
-#
-# Example of interruption
-#
-# You can override it with your own implementation, for example, calling the LLM
-# to generate a simple response to the interruption.
-#
-#
-# Memory Compression
-# ----------------------------------------
-# As conversations grow longer, the token count in memory can exceed model context
-# limits or slow down inference. ``ReActAgent`` provides an automatic memory compression
-# feature to address this issue.
-#
-# **Basic Usage**
-#
-# To enable memory compression, provide a ``CompressionConfig`` instance when initializing
-# the ``ReActAgent``:
-#
-# .. code-block:: python
-#
-# from agentscope.agent import ReActAgent
-# from agentscope.token import CharTokenCounter
-#
-# agent = ReActAgent(
-# name="Assistant",
-# sys_prompt="You are a helpful assistant.",
-# model=model,
-# formatter=formatter,
-# compression_config=ReActAgent.CompressionConfig(
-# enable=True,
-# agent_token_counter=CharTokenCounter(), # The token counter for the agent
-# trigger_threshold=10000, # Trigger compression when exceeding 10000 tokens
-# keep_recent=3, # Keep the most recent 3 messages uncompressed
-# ),
-# )
-#
-# When memory compression is enabled, the agent monitors the token count in its memory.
-# Once it exceeds the ``trigger_threshold``, the agent automatically:
-#
-# 1. Identifies messages that haven't been compressed yet (via ``exclude_mark``)
-# 2. Keeps the most recent ``keep_recent`` messages uncompressed (to preserve recent context)
-# 3. Sends older messages to an LLM to generate a structured summary
-# 4. Marks the compressed messages with ``MemoryMark.COMPRESSED`` (via ``update_messages_mark``)
-# 5. Stores the summary in memory (via ``update_compressed_summary``)
-#
-# .. important:: The compression uses a **marking mechanism** rather than replacing messages. Old messages are marked as compressed and excluded from future retrievals via ``exclude_mark=MemoryMark.COMPRESSED``, while the generated summary is stored separately and retrieved when needed. This approach preserves the original messages and allows flexible memory management. For more details about the mark functionality, please refer to :ref:`memory`.
-#
-# By default, the compressed summary is structured into five key fields:
-#
-# - **task_overview**: The user's core request and success criteria
-# - **current_state**: What has been completed so far, including files and outputs
-# - **important_discoveries**: Technical constraints, decisions, errors, and failed approaches
-# - **next_steps**: Specific actions needed to complete the task
-# - **context_to_preserve**: User preferences, domain details, and promises made
-#
-# **Customizing Compression**
-#
-# You can customize how compression works by specifying ``summary_schema``,
-# ``summary_template``, and ``compression_prompt`` parameters.
-#
-# - **compression_prompt**: Guides the LLM on how to generate the summary
-# - **summary_schema**: Defines the structure of the compressed summary using a Pydantic model
-# - **summary_template**: Formats how the compressed summary is presented back to the agent
-#
-# Here's an example of customizing the compression:
-#
-# .. code-block:: python
-#
-# from pydantic import BaseModel, Field
-#
-# # Define a custom summary structure
-# class CustomSummary(BaseModel):
-# main_topic: str = Field(
-# max_length=200,
-# description="The main topic of the conversation"
-# )
-# key_points: str = Field(
-# max_length=400,
-# description="Important points discussed"
-# )
-# pending_tasks: str = Field(
-# max_length=200,
-# description="Tasks that remain to be done"
-# )
-#
-# # Create agent with custom compression configuration
-# agent = ReActAgent(
-# name="Assistant",
-# sys_prompt="You are a helpful assistant.",
-# model=model,
-# formatter=formatter,
-# compression_config=ReActAgent.CompressionConfig(
-# enable=True,
-# agent_token_counter=CharTokenCounter(),
-# trigger_threshold=10000,
-# keep_recent=3,
-# # Custom schema for structured summary
-# summary_schema=CustomSummary,
-# # Custom prompt to guide compression
-# compression_prompt=(
-# "<system-hint>Please summarize the above conversation "
-# "focusing on the main topic, key discussion points, "
-# "and any pending tasks.</system-hint>"
-# ),
-# # Custom template to format the summary
-# summary_template=(
-# "<system-info>Conversation Summary:\n"
-# "Main Topic: {main_topic}\n\n"
-# "Key Points:\n{key_points}\n\n"
-# "Pending Tasks:\n{pending_tasks}"
-# "</system-info>"
-# ),
-# ),
-# )
-#
-# The ``summary_template`` uses the fields defined in ``summary_schema`` as placeholders
-# (e.g., ``{main_topic}``, ``{key_points}``). After the LLM generates the structured summary,
-# these placeholders will be replaced with the actual values.
-#
-# .. note:: The agent ensures that tool use and tool result pairs are kept together during compression to maintain the integrity of the conversation flow.
-#
-# .. tip:: You can use a smaller, faster model for compression by specifying a different ``compression_model`` and ``compression_formatter`` to reduce costs and latency.
-#
-#
-#
-# Parallel Tool Calls
-# ----------------------------------------
-# ``ReActAgent`` supports parallel tool calls by providing a ``parallel_tool_calls``
-# argument in its constructor.
-# When multiple tool calls are generated, and ``parallel_tool_calls`` is set to ``True``,
-# they will be executed in parallel by the ``asyncio.gather`` function.
-#
-# .. note:: The parallel tool execution in ``ReActAgent`` is implemented based on ``asyncio.gather``. Therefore, to maximize the effect of parallel tool execution, both the tool function itself and the logic within it must be asynchronous.
-#
-# .. note:: When running, please ensure that parallel tool calling is supported at the model level and the corresponding parameters are set correctly (can be passed through ``generate_kwargs``). For example, for the DashScope API, you need to set ``parallel_tool_calls`` to ``True``, otherwise parallel tool calling will not be possible.
-
-
-# prepare a tool function
-async def example_tool_function(tag: str) -> ToolResponse:
- """A sample example tool function"""
- start_time = datetime.now().strftime("%H:%M:%S.%f")
-
- # Sleep for 3 seconds to simulate a long-running task
- await asyncio.sleep(3)
-
- end_time = datetime.now().strftime("%H:%M:%S.%f")
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"Tag {tag} started at {start_time} and ended at {end_time}. ",
- ),
- ],
- )
-
-
-toolkit = Toolkit()
-toolkit.register_tool_function(example_tool_function)
-
-# Create an ReAct agent
-agent = ReActAgent(
- name="Jarvis",
- sys_prompt="You're a helpful assistant named Jarvis.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- # Preset the generation kwargs to enable parallel tool calls
- generate_kwargs={
- "parallel_tool_calls": True,
- },
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- parallel_tool_calls=True,
-)
-
-
-async def example_parallel_tool_calls() -> None:
- """Example of parallel tool calls"""
- # prompt the agent to generate two tool calls at once
- await agent(
- Msg(
- "user",
- "Generate two tool calls of the 'example_tool_function' function with tag as 'tag1' and 'tag2' AT ONCE so that they can execute in parallel.",
- "user",
- ),
- )
-
-
-asyncio.run(example_parallel_tool_calls())
-
-# %%
-# Structured Output
-# ----------------------------------------
-# To generate a structured output, the ``ReActAgent`` instance receives a child class
-# of the ``pydantic.BaseModel`` as the ``structured_model`` argument in its ``__call__`` function.
-# Then we can get the structured output from the ``metadata`` field of the returned message.
-#
-#
-# Taking introducing Einstein as an example:
-#
-
-# Create an ReAct agent
-agent = ReActAgent(
- name="Jarvis",
- sys_prompt="You're a helpful assistant named Jarvis.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- # Preset the generation kwargs to enable parallel tool calls
- generate_kwargs={
- "parallel_tool_calls": True,
- },
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=Toolkit(),
- parallel_tool_calls=True,
-)
-
-
-# The structured model
-class Model(BaseModel):
- name: str = Field(description="The name of the person")
- description: str = Field(
- description="A one-sentence description of the person",
- )
- age: int = Field(description="The age")
- honor: list[str] = Field(description="A list of honors of the person")
-
-
-async def example_structured_output() -> None:
- """The example structured output"""
- res = await agent(
- Msg(
- "user",
- "Introduce Einstein",
- "user",
- ),
- structured_model=Model,
- )
- print("\nThe structured output:")
- print(json.dumps(res.metadata, indent=4))
-
-
-asyncio.run(example_structured_output())
-
-# %%
-# Customizing Agent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope provides two base classes, ``AgentBase`` and ``ReActAgentBase``, which
-# differ in the abstract methods they define and the hooks they support.
-# Specifically, the ``ReActAgentBase`` extends ``AgentBase`` with additional ``_reasoning`` and ``_acting``
-# abstract methods, as well as their pre- and post- hooks.
-#
-# Developers can choose to inherit from either of these base classes based on their needs.
-# We summarize the agent under ``agentscope.agent`` module as follows:
-#
-# .. list-table:: Agent classes in AgentScope
-# :header-rows: 1
-#
-# * - Class
-# - Abstract Method
-# - Support Hooks
-# - Description
-# * - ``AgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``print``
-# | ``handle_interrupt``
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# - The base class for all agents, providing the basic interface and hooks.
-# * - ``ReActAgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``print``
-# | ``handle_interrupt``
-# | ``_reasoning``
-# | ``_acting``
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# | pre\_/post_reasoning
-# | pre\_/post_acting
-# - The abstract class for ReAct agent, extending ``AgentBase`` with reasoning and acting abstract methods and their hooks.
-# * - ``ReActAgent``
-# - \-
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# | pre\_/post_reasoning
-# | pre\_/post_acting
-# - An implementation of ``ReActAgentBase``
-# * - ``UserAgent``
-# -
-# -
-# - A special agent that represents the user, used to interact with the agent
-# * - ``A2aAgent``
-# - \-
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# - Agent for communicating with remote A2A agents, see :ref:`a2a`
-#
-#
-#
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`tool`
-# - :ref:`hook`
-# - :ref:`a2a`
-#
diff --git a/docs/tutorial/en/src/task_agent_skill.py b/docs/tutorial/en/src/task_agent_skill.py
deleted file mode 100644
index ad1d10928..000000000
--- a/docs/tutorial/en/src/task_agent_skill.py
+++ /dev/null
@@ -1,137 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _agent_skill:
-
-Agent Skill
-============================
-
-`Agent skill <https://claude.com/blog/skills>`_ is an approach proposed by
-Anthropic to improve agent capabilities on specific tasks.
-
-AgentScope provides built-in support for Agent Skills through the ``Toolkit``
-class, allowing users to easily register and manage agent skills.
-
-The related APIs are as follows:
-
-.. list-table:: Agent skill API in ``Toolkit`` class
- :header-rows: 1
-
- * - API
- - Description
- * - ``register_agent_skill``
- - Register agent skills from a given directory.
- * - ``remove_agent_skill``
- - Remove a registered agent skill by name.
- * - ``get_agent_skill_prompt``
- - Get the prompt for all registered agent skills, which can be
- attached to the system prompt for the agent.
-
-In this section we demonstrate how to register agent skills and use them in an
-ReAct agent.
-"""
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit
-
-# %%
-# Registering Agent Skills
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# First, we need to prepare an agent skill directory, which follows the
-# requirements specified in the `Anthropic blog <https://claude.com/blog/skills>`_.
-#
-# .. note:: The skill directory must contain a ``SKILL.md`` file containing
-# YAML frontmatter and instructions.
-#
-# Here, we fake an example skill directory ``sample_skill`` with the following files:
-#
-# .. code-block:: markdown
-#
-# ---
-# name: sample_skill
-# description: A sample agent skill for demonstration.
-# ---
-#
-# # Sample Skill
-# ...
-#
-
-os.makedirs("sample_skill", exist_ok=True)
-with open("sample_skill/SKILL.md", "w", encoding="utf-8") as f:
- f.write(
- """---
-name: sample_skill
-description: A sample agent skill for demonstration.
----
-
-# Sample Skill
-...
-""",
- )
-
-# %%
-# Then, we can register the skill using the ``register_agent_skill`` API of
-# the ``Toolkit`` class.
-#
-
-toolkit = Toolkit()
-
-toolkit.register_agent_skill("sample_skill")
-
-# %%
-# After that, we can get the prompt for all registered agent skills using the
-# ``get_agent_skill_prompt`` API
-
-agent_skill_prompt = toolkit.get_agent_skill_prompt()
-print("Agent Skill Prompt:")
-print(agent_skill_prompt)
-
-# %%
-# Of course, we can customize the prompt template when creating the ``Toolkit``
-# instance.
-
-toolkit = Toolkit(
- # The instruction that introduces how to use the skill to the agent/llm
- agent_skill_instruction="<system-info>You're provided a collection of skills, each in a directory and described by a SKILL.md file.</system-info>\n",
- # The template for formatting each skill's prompt, must contain
- # {name}, {description}, and {dir} fields
- agent_skill_template="- {name}({dir}): {description}",
-)
-
-toolkit.register_agent_skill("sample_skill")
-agent_skill_prompt = toolkit.get_agent_skill_prompt()
-print("Customized Agent Skill Prompt:")
-print(agent_skill_prompt)
-
-# %%
-# Integrating Agent Skills with ReActAgent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The `ReActAgent` class in AgentScope will attach the agent skill prompt to
-# the system prompt automatically.
-#
-# We can create a ReAct agent with the registered agent skills as follows:
-#
-# .. important:: When using agent skills, the agent must be equipped with text
-# file reading or shell command tools to access the skill instructions in
-# `SKILL.md` files.
-#
-
-agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday.",
- model=DashScopeChatModel(
- model_name="qwen3-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
-)
-
-print("Agent's System Prompt with Agent Skills:")
-print(agent.sys_prompt)
diff --git a/docs/tutorial/en/src/task_embedding.py b/docs/tutorial/en/src/task_embedding.py
deleted file mode 100644
index fce9363d1..000000000
--- a/docs/tutorial/en/src/task_embedding.py
+++ /dev/null
@@ -1,132 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _embedding:
-
-Embedding
-=========================
-
-In AgentScope, the embedding module provides a unified interface for vector representation generation, which features:
-
-- Support **caching embeddings** to avoid redundant API calls
-- Support **multiple embedding providers** with a consistent API
-
-AgentScope has built-in embedding classes for the following API providers:
-
-.. list-table::
- :header-rows: 1
-
- * - Provider
- - Class
- * - OpenAI
- - ``OpenAITextEmbedding``
- * - Gemini
- - ``GeminiTextEmbedding``
- * - DashScope
- - ``DashScopeTextEmbedding``, ``DashScopeMultiModalEmbedding``
- * - Ollama
- - ``OllamaTextEmbedding``
-
-All classes inherit from ``EmbeddingModelBase``, implementing the ``__call__`` method and generating ``EmbeddingResponse`` object with the embeddings and usage information.
-The ``DashScopeMultiModalEmbedding`` supports multi-modal embeddings for text, images, and videos.
-
-Taking the DashScope embedding class as an example, you can use it as follows:
-"""
-
-import asyncio
-import os
-import tempfile
-
-from agentscope.embedding import DashScopeTextEmbedding, FileEmbeddingCache
-
-
-async def example_dashscope_embedding() -> None:
- """Example usage of DashScope text embedding."""
- texts = [
- "What is the capital of France?",
- "Paris is the capital city of France.",
- ]
-
- # Initialize the DashScope text embedding instance
- embedding_model = DashScopeTextEmbedding(
- model_name="text-embedding-v2",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- )
-
- # Get the embedding from the model
- response = await embedding_model(texts)
-
- print("The embedding ID: ", response.id)
- print("The embedding create at: ", response.created_at)
- print("The embedding usage: ", response.usage)
- print("The embedding:")
- print(response.embeddings)
-
-
-asyncio.run(example_dashscope_embedding())
-
-# %%
-# You can customize your embedding model by subclassing ``EmbeddingModelBase`` and implementing the ``__call__`` method.
-#
-# Embedding Cache
-# ---------------------
-# AgentScope provides a base class ``EmbeddingCacheBase`` for caching embeddings, as well as a file-based implementation ``FileEmbeddingCache``.
-# It works as follows in the embedding module:
-#
-# .. image:: ../../_static/images/embedding_cache.png
-# :align: center
-# :width: 90%
-#
-# To use caching, just pass an instance of ``FileEmbeddingCache`` (or your custom cache) to the embedding model's constructor as follows:
-#
-
-
-async def example_embedding_cache() -> None:
- """Demonstrate embedding with cache functionality."""
- # Example texts
- texts = [
- "What is the capital of France?",
- "Paris is the capital city of France.",
- ]
-
- # Create a temporary directory for cache demonstration
- # In real applications, you might want to use a persistent directory
- cache_dir = tempfile.mkdtemp(prefix="embedding_cache_")
- print(f"Using cache directory: {cache_dir}")
-
- # Initialize the embedding model with cache
- # We limit the cache to 100 files and 10MB for demonstration purposes
- embedder = DashScopeTextEmbedding(
- model_name="text-embedding-v3",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- embedding_cache=FileEmbeddingCache(
- cache_dir=cache_dir,
- max_file_number=100,
- max_cache_size=10, # Maximum cache size in MB
- ),
- )
-
- # First call - will fetch from API and store in cache
- print("\n=== First API Call (No Cache Hit) ===")
- start_time = asyncio.get_event_loop().time()
- response1 = await embedder(texts)
- elapsed_time1 = asyncio.get_event_loop().time() - start_time
- print(f"Source: {response1.source}") # Should be 'api'
- print(f"Time taken: {elapsed_time1:.4f} seconds")
- print(f"Tokens used: {response1.usage.tokens}")
-
- # Second call with the same texts - should use cache
- print("\n=== Second API Call (Cache Hit Expected) ===")
- start_time = asyncio.get_event_loop().time()
- response2 = await embedder(texts)
- elapsed_time2 = asyncio.get_event_loop().time() - start_time
- print(f"Source: {response2.source}") # Should be 'cache'
- print(f"Time taken: {elapsed_time2:.4f} seconds")
- print(
- f"Tokens used: {response2.usage.tokens}",
- ) # Should be 0 for cached results
- print(
- f"Speed improvement: {elapsed_time1 / elapsed_time2:.1f}x faster with cache",
- )
-
-
-asyncio.run(example_embedding_cache())
diff --git a/docs/tutorial/en/src/task_eval.py b/docs/tutorial/en/src/task_eval.py
deleted file mode 100644
index 43b50a8d4..000000000
--- a/docs/tutorial/en/src/task_eval.py
+++ /dev/null
@@ -1,257 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _eval:
-
-Evaluation
-=========================
-
-AgentScope provides a built-in evaluation framework for assessing agent performance across different tasks and benchmarks, featuring:
-
-- `Ray <https://github.com/ray-project/ray>`_-based parallel and distributed evaluation
-- Support continuation after interruption
-- 🚧 Visualization of evaluation results
-
-.. note:: We are keeping integrating new benchmarks into AgentScope:
-
- - ✅ `ACEBench <https://github.com/ACEBench/ACEBench>`_
- - 🚧 `GAIA <https://huggingface.co/datasets/gaia-benchmark/GAIA/tree/main>`_ Benchmark
-
-
-Overview
----------------------------
-
-The AgentScope evaluation framework consists of several key components:
-
-- **Benchmark**: Collections of tasks for systematic evaluation
- - **Task**: Individual evaluation units with inputs, ground truth, and metrics
- - **Metric**: Measurement functions that assess solution quality
-- **Evaluator**: Engine that runs evaluation, aggregates results, and analyzes performance
- - **Evaluator Storage**: Persistent storage for recording and retrieving evaluation results
-- **Solution**: The user-defined solution
-
-.. figure:: ../../_static/images/evaluation.png
- :width: 90%
- :alt: AgentScope Evaluation Framework
-
- *AgentScope Evaluation Framework*
-
-The current implementation in AgentScope includes:
-
-- Evaluator:
- - ``RayEvaluator``: A ray-based evaluator that supports parallel and distributed evaluation.
- - ``GeneralEvaluator``: A general evaluator that runs tasks sequentially, friendly for debugging.
-- Benchmark:
- - ``ACEBench``: A benchmark for evaluating agent capabilities.
-
-We have provided a toy example in our `GitHub repository <https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench>`_ with ``RayEvaluator`` and the agent multistep tasks in ACEBench.
-
-Core Components
----------------
-We are going to build a simple toy math question benchmark to demonstrate
-how to use the AgentScope evaluation module.
-"""
-
-TOY_BENCHMARK = [
- {
- "id": "math_problem_1",
- "question": "What is 2 + 2?",
- "ground_truth": 4.0,
- "tags": {
- "difficulty": "easy",
- "category": "math",
- },
- },
- {
- "id": "math_problem_2",
- "question": "What is 12345 + 54321 + 6789 + 9876?",
- "ground_truth": 83331,
- "tags": {
- "difficulty": "medium",
- "category": "math",
- },
- },
-]
-
-# %%
-# From Tasks, Solutions and Metrics to Benchmark
-# ~~~~~~~~~~~~~~~~~~~
-#
-# - A ``SolutionOutput`` contains all information generated by the agent, including the trajectory and final output.
-# - A ``Metric`` represents a single evaluation callable instance that compares the generated solution (e.g., trajectory or final output) to the ground truth.
-# In the toy example, we define a metric that simply checks whether the ``output`` field in the solution matches the ground truth.
-
-from agentscope.evaluate import (
- SolutionOutput,
- MetricBase,
- MetricResult,
- MetricType,
-)
-
-
-class CheckEqual(MetricBase):
- def __init__(
- self,
- ground_truth: float,
- ):
- super().__init__(
- name="math check number equal",
- metric_type=MetricType.NUMERICAL,
- description="Toy metric checking if two numbers are equal",
- categories=[],
- )
- self.ground_truth = ground_truth
-
- async def __call__(
- self,
- solution: SolutionOutput,
- ) -> MetricResult:
- if solution.output == self.ground_truth:
- return MetricResult(
- name=self.name,
- result=1.0,
- message="Correct",
- )
- else:
- return MetricResult(
- name=self.name,
- result=0.0,
- message="Incorrect",
- )
-
-
-# %%
-# - A ``Task`` is a unit in the benchmark that includes all information for the agent to execute and evaluate (e.g., input/query and its ground truth).
-# - A ``Benchmark`` organizes multiple tasks for systematic evaluation.
-
-from typing import Generator
-from agentscope.evaluate import (
- Task,
- BenchmarkBase,
-)
-
-
-class ToyBenchmark(BenchmarkBase):
- def __init__(self):
- super().__init__(
- name="Toy bench",
- description="A toy benchmark for demonstrating the evaluation module.",
- )
- self.dataset = self._load_data()
-
- @staticmethod
- def _load_data() -> list[Task]:
- dataset = []
- for item in TOY_BENCHMARK:
- dataset.append(
- Task(
- id=item["id"],
- input=item["question"],
- ground_truth=item["ground_truth"],
- tags=item.get("tags", {}),
- metrics=[
- CheckEqual(item["ground_truth"]),
- ],
- metadata={},
- ),
- )
- return dataset
-
- def __iter__(self) -> Generator[Task, None, None]:
- """Iterate over the benchmark."""
- for task in self.dataset:
- yield task
-
- def __getitem__(self, index: int) -> Task:
- """Get a task by index."""
- return self.dataset[index]
-
- def __len__(self) -> int:
- """Get the length of the benchmark."""
- return len(self.dataset)
-
-
-# %%
-# Evaluators
-# ~~~~~~~~~~
-#
-# Evaluators manage the evaluation process. They can automatically iterate through the
-# tasks in the benchmark and feed each task into a solution-generation function,
-# where developers need to define the logic for running agents and retrieving
-# the execution result and trajectory. Below is an example of
-# running ``GeneralEvaluator`` with our toy benchmark. If there is a large
-# benchmark and the developer wants to get the evaluation more efficiently
-# through parallelization, ``RayEvaluator`` is available as a built-in solution
-# as well.
-
-
-import os
-import asyncio
-from typing import Callable
-from pydantic import BaseModel
-
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.agent import ReActAgent
-
-from agentscope.evaluate import (
- GeneralEvaluator,
- FileEvaluatorStorage,
-)
-
-
-class ToyBenchAnswerFormat(BaseModel):
- answer_as_number: float
-
-
-async def toy_solution_generation(
- task: Task,
- pre_hook: Callable,
-) -> SolutionOutput:
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday. "
- "Your target is to solve the given task with your tools. "
- "Try to solve the task as best as you can.",
- model=DashScopeChatModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- model_name="qwen-max",
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
- )
- agent.register_instance_hook(
- "pre_print",
- "save_logging",
- pre_hook,
- )
- msg_input = Msg("user", task.input, role="user")
- res = await agent(
- msg_input,
- structured_model=ToyBenchAnswerFormat,
- )
- return SolutionOutput(
- success=True,
- output=res.metadata.get("answer_as_number", None),
- trajectory=[],
- )
-
-
-async def main() -> None:
- evaluator = GeneralEvaluator(
- name="Toy benchmark evaluation",
- benchmark=ToyBenchmark(),
- # Repeat how many times
- n_repeat=1,
- storage=FileEvaluatorStorage(
- save_dir="./results",
- ),
- # How many workers to use
- n_workers=1,
- )
-
- # Run the evaluation
- await evaluator.run(toy_solution_generation)
-
-
-asyncio.run(main())
diff --git a/docs/tutorial/en/src/task_eval_openjudge.py b/docs/tutorial/en/src/task_eval_openjudge.py
deleted file mode 100644
index 704e1ccae..000000000
--- a/docs/tutorial/en/src/task_eval_openjudge.py
+++ /dev/null
@@ -1,341 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Evaluation with OpenJudge
-=========================
-
-This guide introduces how to use [OpenJudge](https://github.com/agentscope-ai/OpenJudge) graders as AgentScope metrics to evaluate your multi-agent applications.
-OpenJudge is a comprehensive evaluation system designed to assess the quality of LLM applications. By integrating OpenJudge into AgentScope, you can extend AgentScope's native evaluation capabilities from basic execution checks to deep, semantic quality analysis.
-
-
-.. note::
- Install dependencies before running:
-
- .. code-block:: bash
-
- pip install agentscope py-openjudge
-
-
-Overview
---------
-While AgentScope provides a robust `MetricBase` for defining evaluation logic, implementing complex, semantic-level metrics (like "Hallucination Detection" or "Response Relevance") often requires
-significant effort in prompt engineering and pipeline construction.
-
-Integrating OpenJudge brings three dimensions of capability extension to AgentScope:
-
-1. **Enhance Evaluation Depth:**: Move beyond simple success/failure checks to multi-dimensional assessments (Accuracy, Safety, Tone, etc.).
-2. **Leverage Verified Graders**: Instantly access 50+ pre-built, expert-level graders without writing custom evaluation prompts, see the [OpenJudge documentation](https://agentscope-ai.github.io/OpenJudge/built_in_graders/overview/) for details.
-3. **Closed-loop Iteration**: Seamlessly embed OpenJudge into AgentScope's `Benchmark`, obtaining quantitative scores and qualitative reasoning.
-
-
-How to Evaluate with OpenJudge
---------------------
-
-We are going to build a simple QA benchmark to demonstrate how to use the AgentScope evaluation module by integrating OpenJudge's graders.
-"""
-
-# %%
-QA_BENCHMARK_DATASET = [
- {
- "id": "qa_task_1",
- "question": "What are the health benefits of regular exercise?",
- "reference_output": "Regular exercise improves cardiovascular health, strengthens muscles and bones, "
- "helps maintain a healthy weight, and can improve mental health by reducing anxiety and depression.",
- "ground_truth": "Answers should cover physical and mental health benefits",
- "difficulty": "medium",
- "category": "health",
- },
- {
- "id": "qa_task_2",
- "question": "Describe the main causes of climate change.",
- "reference_output": "Climate change is primarily caused by increased concentrations of greenhouse gases "
- "in the atmosphere due to human activities like burning fossil fuels, deforestation, and industrial processes.",
- "ground_truth": "Answers should mention greenhouse gases and human activities",
- "difficulty": "hard",
- "category": "environment",
- },
- {
- "id": "qa_task_3",
- "question": "What is the significance of the Turing Test in AI?",
- "reference_output": "The Turing Test, proposed by Alan Turing, is a measure of a machine's ability to exhibit"
- " intelligent behavior equivalent to, or indistinguishable from, that of a human.",
- "ground_truth": "Should mention Alan Turing, purpose of the test, and its implications for AI",
- "difficulty": "hard",
- "category": "technology",
- },
-]
-
-
-# %% [markdown]
-# AgentScope Metric vs. OpenJudge Grader
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# To make OpenJudge compatible with AgentScope, we need an adapter that inherits from
-# AgentScope's ``MetricBase`` and acts as a bridge to OpenJudge's ``BaseGrader``.
-#
-# * **AgentScope Metric**: A generic unit of evaluation that accepts a ``SolutionOutput`` and returns a ``MetricResult``.
-# * **OpenJudge Grader**: A specialized evaluation unit (e.g., ``RelevanceGrader``) that requires specific, semantic inputs (like ``query``, ``response``, ``context``), and returns a ``GraderResult``.
-#
-# This "Adapter" allows you to plug *any* OpenJudge grader into your AgentScope benchmark seamlessly.
-#
-
-# %%
-from openjudge.graders.base_grader import BaseGrader
-from openjudge.graders.schema import GraderScore, GraderError
-from openjudge.utils.mapping import parse_data_with_mapper
-from agentscope.evaluate import (
- MetricBase,
- MetricType,
- MetricResult,
- SolutionOutput,
-)
-
-
-class OpenJudgeMetric(MetricBase):
- """
- A wrapper that converts an OpenJudge grader into an AgentScope Metric.
- """
-
- def __init__(
- self,
- grader_cls: type[BaseGrader],
- data: dict,
- mapper: dict,
- name: str | None = None,
- description: str | None = None,
- **grader_kwargs,
- ):
- # Initialize the OpenJudge grader
- self.grader = grader_cls(**grader_kwargs)
-
- super().__init__(
- name=name or self.grader.name,
- metric_type=MetricType.NUMERICAL,
- description=description or self.grader.description,
- )
-
- self.data = data
- self.mapper = mapper
-
- async def __call__(self, solution: SolutionOutput) -> MetricResult:
- """Execute the wrapped OpenJudge grader against the agent solution."""
- if not solution.success:
- return MetricResult(
- name=self.name,
- result=0.0,
- message="Solution failed",
- )
-
- try:
- # 1. Context Construction
- # Combine Static Task Context (item) and Dynamic Agent Output (solution)
- combined_data = {
- "data": self.data,
- "solution": {
- "output": solution.output,
- "meta": solution.meta,
- "trajectory": getattr(solution, "trajectory", []),
- },
- }
-
- # 2. Data Mapping
- # Use the mapper to extract 'query', 'response', 'context' from the combined data
- grader_inputs = parse_data_with_mapper(
- combined_data,
- self.mapper,
- )
-
- # 3. Evaluation Execution
- result = await self.grader.aevaluate(**grader_inputs)
-
- # 4. Result Formatting
- if isinstance(result, GraderScore):
- return MetricResult(
- name=self.name,
- result=result.score,
- # We preserve the detailed reasoning provided by OpenJudge
- message=result.reason or "",
- )
- elif isinstance(result, GraderError):
- return MetricResult(
- name=self.name,
- result=0.0,
- message=f"Error: {result.error}",
- )
- else:
- return MetricResult(
- name=self.name,
- result=0.0,
- message="Unknown result type",
- )
-
- except Exception as e:
- return MetricResult(
- name=self.name,
- result=0.0,
- message=f"Exception: {str(e)}",
- )
-
-
-# %% [markdown]
-# From OpenJudge's Graders to AgentScope's Benchmark
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# OpenJudge provides a rich collection of built-in graders. In this example, we select two
-# common graders suitable for Question-Answering tasks:
-#
-# * **RelevanceGrader**: Evaluates whether the agent's response directly addresses the user's query.
-# * **CorrectnessGrader**: Verifies the factual accuracy of the response against a provided ground truth.
-#
-# .. tip::
-# OpenJudge offers 50+ built-in graders covering diverse dimensions like **Hallucination**, **Safety**, **Code Quality**,
-# and **JSON Formatting**. Please refer to the `OpenJudge Documentation <https://agentscope-ai.github.io/OpenJudge/built_in_graders/overview/>`_
-# for the full list of available graders.
-#
-# .. note::
-# Ensure you have set your ``DASHSCOPE_API_KEY`` environment variable before running the example below.
-
-# %%
-import os
-from typing import Generator
-from openjudge.graders.common.relevance import RelevanceGrader
-from openjudge.graders.common.correctness import CorrectnessGrader
-from agentscope.evaluate import (
- Task,
- BenchmarkBase,
-)
-
-
-class QABenchmark(BenchmarkBase):
- """A benchmark for QA tasks using OpenJudge metrics."""
-
- def __init__(self):
- super().__init__(
- name="QA Quality Benchmark",
- description="Benchmark to evaluate QA systems using OpenJudge grader classes",
- )
- self.dataset = self._load_data()
-
- def _load_data(self):
- tasks = []
- # Configuration for LLM-based graders
- # Ensure OPENAI_API_KEY is set in your environment variables
- model_config = {
- "model": "qwen3-32b",
- "api_key": os.environ.get("DASHSCOPE_API_KEY"),
- "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- }
-
- for data in QA_BENCHMARK_DATASET:
- # Define the Mapping: Left is OpenJudge key, Right is AgentScope path
- mapper = {
- "query": "data.input",
- "response": "solution.output",
- "context": "data.ground_truth",
- "reference_response": "data.reference_output",
- }
-
- # Instantiate Metrics via Wrapper
- metrics = [
- OpenJudgeMetric(
- grader_cls=RelevanceGrader,
- data=data,
- mapper=mapper,
- name="Relevance",
- model=model_config,
- ),
- OpenJudgeMetric(
- grader_cls=CorrectnessGrader,
- data=data,
- mapper=mapper,
- name="Correctness",
- model=model_config,
- ),
- ]
-
- # Create Task
- task = Task(
- id=data["id"],
- input=data["question"],
- ground_truth=data["ground_truth"],
- metrics=metrics,
- )
-
- tasks.append(task)
-
- return tasks
-
- def __iter__(self) -> Generator[Task, None, None]:
- """Iterate over the benchmark."""
- yield from self.dataset
-
- def __getitem__(self, index: int) -> Task:
- """Get a task by index."""
- return self.dataset[index]
-
- def __len__(self) -> int:
- """Get the length of the benchmark."""
- return len(self.dataset)
-
-
-# %% [markdown]
-# Run Evaluation
-# ~~~~~~~~~~
-# Finally, use AgentScope's ``GeneralEvaluator`` to run the benchmark on a QA agent.
-# The results will include both the **Quantitative Score** and the **Qualitative Reasoning**
-# from the OpenJudge graders.
-
-# %%
-
-from typing import Callable
-
-from agentscope.agent import ReActAgent
-from agentscope.evaluate import GeneralEvaluator
-from agentscope.evaluate import FileEvaluatorStorage
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.message import Msg
-from agentscope.model import OpenAIChatModel
-
-
-async def qa_agent(task: Task, pre_hook: Callable) -> SolutionOutput:
- """Solution function that generates answers to QA tasks."""
-
- model = OpenAIChatModel(
- model_name="qwen3-32b",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- )
-
- # Create a QA agent
- agent = ReActAgent(
- name="QAAgent",
- sys_prompt="You are an expert at answering questions. Provide clear, accurate, and comprehensive answers.",
- model=model,
- formatter=DashScopeChatFormatter(),
- )
-
- # Generate response
- msg_input = Msg(name="User", content=task.input, role="user")
- response = await agent(msg_input)
- response_text = response.content
-
- return SolutionOutput(
- success=True,
- output=response_text,
- trajectory=[
- task.input,
- response_text,
- ], # Store the interaction trajectory
- )
-
-
-async def main() -> None:
- evaluator = GeneralEvaluator(
- name="OpenJudge Integration Demo",
- benchmark=QABenchmark(),
- # Repeat how many times
- n_repeat=1,
- storage=FileEvaluatorStorage(
- save_dir="./results",
- ),
- # How many workers to use
- n_workers=1,
- )
-
- await evaluator.run(qa_agent)
diff --git a/docs/tutorial/en/src/task_hook.py b/docs/tutorial/en/src/task_hook.py
deleted file mode 100644
index 410691c0f..000000000
--- a/docs/tutorial/en/src/task_hook.py
+++ /dev/null
@@ -1,291 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _hook:
-
-Agent Hooks
-===========================
-
-Hooks are extension points in AgentScope that allow developers to customize agent behaviors at specific execution points, providing a flexible way to modify or extend the agent's functionality without changing its core implementation.
-
-In AgentScope, hooks are implemented around the agent's core functions:
-
-
-.. list-table:: Supported hook types in AgentScope
- :header-rows: 1
-
- * - Agent Class
- - Core Function
- - Hook Types
- - Description
- * - | ``AgentBase`` &
- | its child classes
- - ``reply``
- - | ``pre_reply``
- | ``post_reply``
- - The hooks before/after agent replying to a message
- * -
- - ``print``
- - | ``pre_print``
- | ``post_print``
- - The hook before/after printing a message to the target output (e.g., terminal, web interface)
- * -
- - ``observe``
- - | ``pre_observe``
- | ``post_observe``
- - The hooks before/after observing a message from the environment or other agents
- * - | ``ReActAgentBase`` &
- | its child classes
- - | ``reply``
- | ``print``
- | ``observe``
- - | ``pre_reply``
- | ``post_reply``
- | ``pre_print``
- | ``post_print``
- | ``pre_observe``
- | ``post_observe``
- -
- * -
- - ``_reasoning``
- - | ``pre_reasoning``
- | ``post_reasoning``
- - The hooks before/after the agent's reasoning process
- * -
- - ``_acting``
- - | ``pre_acting``
- | ``post_acting``
- - The hooks before/after the agent's acting process
-
-.. tip:: Since hooks in AgentScope are implemented using a metaclass, they support inheritance.
-
-To simplify the usage, AgentScope provides unified signatures for all hooks.
-
-"""
-import asyncio
-from typing import Any, Type
-
-from agentscope.agent import ReActAgentBase, AgentBase
-from agentscope.message import Msg
-
-
-# %%
-# Hook Signature
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope provides unified hook signatures for all pre- and post-hooks as follows:
-#
-# **Pre-Hook Signature**
-#
-# .. list-table:: The signature of all pre-hooks
-# :header-rows: 1
-#
-# * -
-# - Name
-# - Description
-# * - Arguments
-# - ``self: AgentBase | ReActAgentBase``
-# - The agent instance
-# * -
-# - ``kwargs: dict[str, Any]``
-# - | The input arguments of the target
-# | function, or the modified arguments
-# | from the most recent non-None return
-# | value of previous hooks
-# * - Returns
-# - ``dict[str, Any] | None``
-# - The modified arguments or None
-#
-# .. note:: All positional arguments and keyword arguments of the core function are passed as a single ``kwargs`` dict to the hook functions
-#
-# A pre-hook template is defined as follows:
-#
-
-
-def pre_hook_template(
- self: AgentBase | ReActAgentBase,
- kwargs: dict[str, Any],
-) -> dict[str, Any] | None: # The modified displayed message
- """Pre hook template."""
- pass
-
-
-# %%
-# **Post-Hook Signature**
-#
-# For post hooks, an additional ``output`` argument is added to the signature, which represents the output of the target function.
-# If the core function has no output, the ``output`` argument will be ``None``.
-#
-# .. list-table:: The signature of all post-hooks
-# :header-rows: 1
-#
-# * -
-# - Name
-# - Description
-# * - Arguments
-# - ``self: AgentBase | ReActAgentBase``
-# - The agent instance
-# * -
-# - ``kwargs: dict[str, Any]``
-# - | A dict that contains all the arguments
-# | of the target function
-# * -
-# - ``output: Any``
-# - | The output of the target function or
-# | the most recent non-None return value
-# | from previous hooks
-# * - Returns
-# - ``dict[str, Any] | None``
-# - The modified arguments or None
-#
-
-
-def post_hook_template(
- self: AgentBase | ReActAgentBase,
- kwargs: dict[str, Any],
- output: Any, # The output of the target function
-) -> Any: # The modified output
- """Post hook template."""
- pass
-
-
-# %%
-# Hook Management
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope provides both instance- and class-level hooks, depending on the effective scope of the hooks.
-# They execute in the following order:
-#
-# .. image:: ../../_static/images/sequential_hook.png
-# :width: 90%
-# :align: center
-# :alt: Hooks in AgentScope
-# :class: bordered-image
-#
-# AgentScope provides built-in methods to manage hooks at both instance and class levels as follows:
-#
-# .. list-table:: Hook management methods in AgentScope
-# :header-rows: 1
-#
-# * - Level
-# - Method
-# - Description
-# * - Instance-level
-# - ``register_instance_hook``
-# - | Register a hook for the current object with
-# | given hook type and name.
-# * -
-# - ``remove_instance_hook``
-# - | Remove a hook for the current object with
-# | given hook type and name.
-# * -
-# - ``clear_instance_hooks``
-# - | Clear all hooks for the current object with
-# | given hook type.
-# * - Class-level
-# - ``register_class_hook``
-# - | Register a hook for all objects of the class
-# | with given hook type and name.
-# * -
-# - ``remove_class_hook``
-# - | Remove a hook for all objects of the class
-# | with given hook type and name.
-# * -
-# - ``clear_class_hooks``
-# - | Clear all hooks for all objects of the
-# | class with given hook type.
-#
-# When using hooks, you MUST follow these rules:
-#
-# .. important:: **Execution Order**
-#
-# - Hooks are executed in registration order
-# - Multiple hooks can be chained together
-# **Return Value Handling**
-#
-# - For pre-hooks: Non-None return values are passed to the next hook or core function
-# - When a hook returns None, the next hook will use the most recent non-None return value from previous hooks
-# - If all previous hooks return None, the next hook receives a copy of the original arguments
-# - The final non-None return value (or original arguments if all hooks return None) is passed to the core function
-# - For post-hooks: Works the same way as pre-hooks.
-# **Important**: Never call the core function (reply/speak/observe/_reasoning/_acting) within a hook to avoid infinite loops
-#
-# Taking the following agent as an example, we can see how to register, remove and clear hooks:
-#
-
-
-# Create a simple test agent class
-class TestAgent(AgentBase):
- """A test agent for demonstrating hooks."""
-
- async def reply(self, msg: Msg) -> Msg:
- """Reply to the message."""
- return msg
-
-
-# %%
-# We create an instance-level hook and a class-level hook to modify the message content before replying.
-#
-
-
-# Create two pre-reply hooks
-def instance_pre_reply_hook(
- self: AgentBase,
- kwargs: dict[str, Any],
-) -> dict[str, Any]:
- """A pre-reply hook that modifies the message content."""
- msg = kwargs["msg"]
- msg.content += "[instance-pre-reply]"
- # return modified kwargs
- return {
- **kwargs,
- "msg": msg,
- }
-
-
-def cls_pre_reply_hook(
- self: AgentBase,
- kwargs: dict[str, Any],
-) -> dict[str, Any]:
- """A pre-reply hook that modifies the message content."""
- msg = kwargs["msg"]
- msg.content += "[cls-pre-reply]"
- # return modified kwargs
- return {
- **kwargs,
- "msg": msg,
- }
-
-
-# Register class hook
-TestAgent.register_class_hook(
- hook_type="pre_reply",
- hook_name="test_pre_reply",
- hook=cls_pre_reply_hook,
-)
-
-# Register instance hook
-agent = TestAgent()
-agent.register_instance_hook(
- hook_type="pre_reply",
- hook_name="test_pre_reply",
- hook=instance_pre_reply_hook,
-)
-
-
-async def example_test_hook() -> None:
- """An example function to test the hooks."""
- msg = Msg(
- name="user",
- content="Hello, world!",
- role="user",
- )
- res = await agent(msg)
- print("Response content:", res.content)
- TestAgent.clear_class_hooks()
-
-
-asyncio.run(example_test_hook())
-
-# %%
-# We can see that a "[instance-pre-reply]" and a "[cls-pre-reply]" are added to the message content.
-#
diff --git a/docs/tutorial/en/src/task_long_term_memory.py b/docs/tutorial/en/src/task_long_term_memory.py
deleted file mode 100644
index 055403055..000000000
--- a/docs/tutorial/en/src/task_long_term_memory.py
+++ /dev/null
@@ -1,435 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _long-term-memory:
-
-Long-Term Memory
-========================
-
-In AgentScope, we provide a basic class for long-term memory (``LongTermMemoryBase``) and an implementation based on the `mem0 <https://github.com/mem0ai/mem0>`_ library (``Mem0LongTermMemory``).
-Together with the design of ``ReActAgent`` class in :ref:`agent` section, we provide two long-term memory modes:
-
-- ``agent_control``: the agent autonomously manages long-term memory by tool calls, and
-- ``static_control``: the developer explicitly controls long-term memory operations.
-
-Developers can also use the ``both`` mode, which activates both memory management modes.
-
-.. hint:: These memory modes are suitable for different usage scenarios. Developers can choose the appropriate mode based on their needs.
-
-Using mem0 Long-Term Memory
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. note:: We provide an example of using mem0 long-term memory in the GitHub repository under the ``examples/long_term_memory/mem0`` directory.
-
-"""
-
-import os
-import asyncio
-
-from agentscope.message import Msg
-from agentscope.memory import InMemoryMemory
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit
-
-
-# Create mem0 long-term memory instance
-from agentscope.memory import Mem0LongTermMemory
-from agentscope.embedding import DashScopeTextEmbedding
-
-
-long_term_memory = Mem0LongTermMemory(
- agent_name="Friday",
- user_name="user_123",
- model=DashScopeChatModel(
- model_name="qwen-max-latest",
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- stream=False,
- ),
- embedding_model=DashScopeTextEmbedding(
- model_name="text-embedding-v2",
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- ),
- on_disk=False,
-)
-
-# %%
-# The ``Mem0LongTermMemory`` class provides two main methods for long-term memory operations:
-# ``record`` and ``retrieve``.
-# They take a list of messages as input and record/retrieve information from long-term memory.
-#
-# As an example, we first store a user preference and then retrieve related information from long-term memory.
-#
-
-
-# Basic usage example
-async def basic_usage():
- """Basic usage example"""
- # Record memory
- await long_term_memory.record(
- [Msg("user", "I like staying in homestays", "user")],
- )
-
- # Retrieve memory
- results = await long_term_memory.retrieve(
- [Msg("user", "My accommodation preferences", "user")],
- )
- print(f"Retrieval results: {results}")
-
-
-asyncio.run(basic_usage())
-
-# %%
-# Integration with ReAct Agent
-# ----------------------------------------
-# In AgentScope, the ``ReActAgent`` class receives a ``long_term_memory``
-# parameter in its constructor, as well as a ``long_term_memory_mode`` parameter
-# that specifies the long-term memory mode.
-#
-# If ``long_term_memory_mode`` is set to ``agent_control`` or ``both``, two
-# tool functions ``record_to_memory`` and ``retrieve_from_memory`` will be
-# registered in the agent's toolkit, allowing the agent to autonomously
-# manage long-term memory through tool calls.
-#
-# .. note:: To achieve the best results, the ``"agent_control"`` mode may require
-# additional instructions in the system prompt.
-#
-
-# Create ReAct agent with long-term memory
-agent = ReActAgent(
- name="Friday",
- sys_prompt="You are an assistant with long-term memory capabilities.",
- model=DashScopeChatModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- model_name="qwen-max-latest",
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=Toolkit(),
- memory=InMemoryMemory(),
- long_term_memory=long_term_memory,
- long_term_memory_mode="static_control", # Use static_control mode
-)
-
-
-async def record_preferences():
- """ReAct agent integration example"""
- # Conversation example
- msg = Msg(
- "user",
- "When I travel to Hangzhou, I like staying in homestays",
- "user",
- )
- await agent(msg)
-
-
-asyncio.run(record_preferences())
-
-# %%
-# Then we clear the short-term memory and ask the agent about the user's preferences.
-#
-
-
-async def retrieve_preferences():
- """Retrieve user preferences from long-term memory"""
- # Clear short-term memory
- await agent.memory.clear()
- # The agent will remember previous conversations
- msg2 = Msg("user", "What are my preferences? Answer briefly.", "user")
- await agent(msg2)
-
-
-asyncio.run(retrieve_preferences())
-
-
-# %%
-# Using ReMe Long-Term Memory
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# .. note:: We provide an example of using ReMe long-term memory in the GitHub repository under the ``examples/long_term_memory/reme`` directory.
-#
-# .. code-block:: python
-# :caption: Example of ReMe long-term memory setup
-#
-# from agentscope.memory import ReMePersonalLongTermMemory
-#
-# # Create ReMe personal long-term memory instance
-# reme_long_term_memory = ReMePersonalLongTermMemory(
-# agent_name="Friday",
-# user_name="user_123",
-# model=DashScopeChatModel(
-# model_name="qwen3-max",
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# stream=False,
-# ),
-# embedding_model=DashScopeTextEmbedding(
-# model_name="text-embedding-v4",
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# dimensions=1024,
-# ),
-# )
-#
-#
-# The ``ReMePersonalLongTermMemory`` class provides four main methods for long-term memory operations.
-# They include ``record_to_memory`` and ``retrieve_from_memory`` for tool calls,
-# as well as ``record`` and ``retrieve`` for direct calls.
-#
-# As an example, we use ``record_to_memory`` to record user preferences.
-#
-# .. code-block:: python
-# :caption: Example of recording to ReMe long-term memory
-#
-# async def test_record_to_memory():
-# """Test record_to_memory tool function interface"""
-# async with reme_long_term_memory:
-# result = await reme_long_term_memory.record_to_memory(
-# thinking="The user is sharing their travel preferences and habits",
-# content=[
-# "I prefer to stay in homestays when traveling to Hangzhou",
-# "I like to visit the West Lake in the morning",
-# "I enjoy drinking Longjing tea",
-# ],
-# )
-# # Extract result text
-# result_text = " ".join(
-# block.get("text", "")
-# for block in result.content
-# if block.get("type") == "text"
-# )
-# print(f"Recording result: {result_text}")
-#
-#
-#
-# Then we use ``retrieve_from_memory`` to retrieve related memories.
-#
-# .. code-block:: python
-# :caption: Example of retrieving from ReMe long-term memory
-#
-# async def test_retrieve_from_memory():
-# """Test retrieve_from_memory tool function interface"""
-# async with reme_long_term_memory:
-# # First record some content
-# await reme_long_term_memory.record_to_memory(
-# thinking="User is sharing travel preferences",
-# content=[
-# "I prefer to stay in homestays when traveling to Hangzhou",
-# ],
-# )
-#
-# # Then retrieve
-# result = await reme_long_term_memory.retrieve_from_memory(
-# keywords=["Hangzhou travel", "tea preference"],
-# )
-# retrieved_text = " ".join(
-# block.get("text", "")
-# for block in result.content
-# if block.get("type") == "text"
-# )
-# print(f"Retrieved memories: {retrieved_text}")
-#
-#
-# Besides the tool function interface, we can also use the ``record`` method to directly record message conversations.
-#
-# .. code-block:: python
-# :caption: Example of direct recording to ReMe long-term memory
-#
-# async def test_record_direct():
-# """Test record direct recording method"""
-# async with reme_long_term_memory:
-# await reme_long_term_memory.record(
-# msgs=[
-# Msg(
-# role="user",
-# content="I work as a software engineer and prefer remote work",
-# name="user",
-# ),
-# Msg(
-# role="assistant",
-# content="Understood! You're a software engineer who values remote work flexibility.",
-# name="assistant",
-# ),
-# Msg(
-# role="user",
-# content="I usually start my day at 9 AM with a cup of coffee",
-# name="user",
-# ),
-# ],
-# )
-# print("Successfully recorded conversation messages")
-#
-#
-# Similarly, we use the ``retrieve`` method to retrieve related memories.
-#
-# .. code-block:: python
-# :caption: Example of direct retrieval from ReMe long-term memory
-#
-# async def test_retrieve_direct():
-# """Test retrieve direct retrieval method"""
-# async with reme_long_term_memory:
-# # First record some content
-# await reme_long_term_memory.record(
-# msgs=[
-# Msg(
-# role="user",
-# content="I work as a software engineer and prefer remote work",
-# name="user",
-# ),
-# ],
-# )
-#
-# # Then retrieve
-# memories = await reme_long_term_memory.retrieve(
-# msg=Msg(
-# role="user",
-# content="What do you know about my work preferences?",
-# name="user",
-# ),
-# )
-# print(
-# f"Retrieved memories: {memories if memories else 'No memories found'}",
-# )
-#
-#
-# Integration with ReAct Agent
-# ----------------------------------------
-# In AgentScope, the ``ReActAgent`` class receives a ``long_term_memory``
-# parameter in its constructor, as well as a ``long_term_memory_mode`` parameter.
-#
-# If ``long_term_memory_mode`` is set to ``agent_control`` or ``both``,
-# ``record_to_memory`` and ``retrieve_from_memory`` tool functions will be
-# registered, allowing the agent to autonomously manage long-term memory through tool calls.
-#
-# .. note:: To achieve the best results, the ``"agent_control"`` mode may require
-# additional instructions in the system prompt.
-#
-# .. code-block:: python
-# :caption: Example of ReAct agent with ReMe long-term memory
-#
-# # Create ReAct agent with long-term memory (agent_control mode)
-# async def test_react_agent_with_reme():
-# """Test ReActAgent integration with ReMe personal memory"""
-# async with reme_long_term_memory:
-# agent_with_reme = ReActAgent(
-# name="Friday",
-# sys_prompt=(
-# "You are a helpful assistant named Friday with long-term memory capabilities. "
-# "\n\n## Memory Management Guidelines:\n"
-# "1. **Recording Memories**: When users share personal information, preferences, "
-# "habits, or facts about themselves, ALWAYS record them using `record_to_memory` "
-# "for future reference.\n"
-# "\n2. **Retrieving Memories**: BEFORE answering questions about the user's preferences, "
-# "past information, or personal details, you MUST FIRST call `retrieve_from_memory` "
-# "to check if you have any relevant stored information. Do NOT rely solely on the "
-# "current conversation context.\n"
-# "\n3. **When to Retrieve**: Call `retrieve_from_memory` when:\n"
-# " - User asks questions like 'what do I like?', 'what are my preferences?', "
-# "'what do you know about me?'\n"
-# " - User asks about their past behaviors, habits, or preferences\n"
-# " - User refers to information they mentioned before\n"
-# " - You need context about the user to provide personalized responses\n"
-# "\nAlways check your memory first before claiming you don't know something about the user."
-# ),
-# model=DashScopeChatModel(
-# model_name="qwen3-max",
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# stream=False,
-# ),
-# formatter=DashScopeChatFormatter(),
-# toolkit=Toolkit(),
-# memory=InMemoryMemory(),
-# long_term_memory=reme_long_term_memory,
-# long_term_memory_mode="agent_control", # Use agent_control mode
-# )
-#
-# # User shares preferences
-# msg = Msg(
-# role="user",
-# content="When I travel to Hangzhou, I prefer to stay in a homestay",
-# name="user",
-# )
-# response = await agent_with_reme(msg)
-# print(f"Agent response: {response.get_text_content()}")
-#
-# # Clear short-term memory to test long-term memory
-# await agent_with_reme.memory.clear()
-#
-# # Query preferences
-# msg2 = Msg(
-# role="user",
-# content="what preference do I have?",
-# name="user",
-# )
-# response2 = await agent_with_reme(msg2)
-# print(f"Agent response: {response2.get_text_content()}")
-#
-#
-# Then we clear the short-term memory and ask the agent about the user's preferences.
-#
-# .. code-block:: python
-# :caption: Example of retrieving preferences with ReAct agent and ReMe long-term memory
-#
-# async def retrieve_reme_preferences():
-# """Retrieve user preferences from long-term memory"""
-# async with reme_long_term_memory:
-# # Create agent (reusing for demonstration completeness)
-# agent_with_reme = ReActAgent(
-# name="Friday",
-# sys_prompt="You are an assistant with long-term memory capabilities.",
-# model=DashScopeChatModel(
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# model_name="qwen3-max",
-# stream=False,
-# ),
-# formatter=DashScopeChatFormatter(),
-# toolkit=Toolkit(),
-# memory=InMemoryMemory(),
-# long_term_memory=reme_long_term_memory,
-# long_term_memory_mode="agent_control",
-# )
-#
-# # Clear short-term memory
-# await agent_with_reme.memory.clear()
-# # The agent will remember previous conversations
-# msg2 = Msg("user", "What are my preferences? Answer briefly.", "user")
-# await agent_with_reme(msg2)
-#
-# Customizing Long-Term Memory
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope provides the ``LongTermMemoryBase`` base class, which defines the basic
-#
-# Developers can inherit from ``LongTermMemoryBase`` to implement custom long-term
-# memory systems according to their needs:
-#
-# .. list-table:: Long-term memory classes in AgentScope
-# :header-rows: 1
-#
-# * - Class
-# - Abstract Methods
-# - Description
-# * - ``LongTermMemoryBase``
-# - | ``record``
-# | ``retrieve``
-# | ``record_to_memory``
-# | ``retrieve_from_memory``
-# - - For ``"static_control"`` mode, you must implement the ``record`` and ``retrieve`` methods.
-# - For ``"agent_control"`` mode, the ``record_to_memory`` and ``retrieve_from_memory`` methods must be implemented.
-# * - ``Mem0LongTermMemory``
-# - | ``record``
-# | ``retrieve``
-# | ``record_to_memory``
-# | ``retrieve_from_memory``
-# - Long-term memory implementation based on the mem0 library, supporting vector storage and retrieval.
-# * - ``ReMePersonalLongTermMemory``
-# - | ``record``
-# | ``retrieve``
-# | ``record_to_memory``
-# | ``retrieve_from_memory``
-# - Personal memory implementation based on the ReMe framework, providing powerful memory management and retrieval capabilities.
-#
-#
-#
-#
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`memory` - Basic memory system
-# - :ref:`agent` - ReAct agent
-# - :ref:`tool` - Tool system
diff --git a/docs/tutorial/en/src/task_mcp.py b/docs/tutorial/en/src/task_mcp.py
deleted file mode 100644
index d44320032..000000000
--- a/docs/tutorial/en/src/task_mcp.py
+++ /dev/null
@@ -1,207 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _mcp:
-
-MCP
-=========================
-
-The tutorial covers the following features of AgentScope in support of the MCP (Model Context Protocol):
-
-- Support both **HTTP** (streamable HTTP and SSE) and **StdIO** MCP servers
-- Provide both **stateful** and **stateless** MCP clients
-- Provide both **server-level** and **function-level** MCP tool management
-
-Here the stateful/stateless distinction refers to whether the client maintains a persistent session with the MCP server or not.
-The table below summarizes the supported MCP client types and protocols:
-
-.. list-table:: Supported MCP client types and protocols
- :header-rows: 1
-
- * - Client Type
- - HTTP (Streamable HTTP and SSE)
- - StdIO
- * - Stateful Client
- - ``HttpStatefulClient``
- - ``HttpStatelessClient``
- * - Stateless Client
- - ``StdIOStatefulClient``
- -
-
-"""
-import asyncio
-import json
-import os
-
-from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
-from agentscope.tool import Toolkit
-
-# %%
-# MCP Client
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# In AgentScope, MCP clients are responsible for
-#
-# - connecting to the MCP server,
-# - obtaining tool functions from the server, and
-# - calling tool functions in the MCP server.
-#
-# There are two types of MCP clients in AgentScope: **Stateful** and **Stateless**.
-# They only differ in how to manage the session with the MCP server.
-#
-# - Stateful Client: The stateful MCP client **maintains a persistent session** with the MCP server within its lifetime. The developers should explicitly call ``connect()`` and ``close()`` methods to manage the connection lifecycle.
-# - Stateless Client: The stateless MCP client creates a new session when calling the tool function, and destroys the session right after the tool function call, which is much more lightweight.
-#
-# .. note:: - The StdIO MCP server only has stateful client, when ``connect()`` is called, it will start the MCP server locally and then connect to it.
-# - For stateful clients, developers must ensure the client is connected when calling the tool functions.
-# - When multiple `HttpStatefulClients` or `StdIOStatefulClients` are connected, they should be closed in Last In First Out (LIFO) order to prevent errors.
-#
-# Taking Gaode map MCP server as an example, the creation of stateful and stateless clients are very similar:
-#
-
-stateful_client = HttpStatefulClient(
- # The name to identify the MCP
- name="mcp_services_stateful",
- transport="streamable_http",
- url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
-)
-
-stateless_client = HttpStatelessClient(
- # The name to identify the MCP
- name="mcp_services_stateless",
- transport="streamable_http",
- url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
-)
-
-# %%
-# Both stateful and stateless clients provide the following methods:
-#
-# .. list-table:: MCP Client Methods
-# :header-rows: 1
-#
-# * - Method
-# - Description
-# * - ``list_tools``
-# - List all tools available in the MCP server.
-# * - ``get_callable_function``
-# - Get a callable function object from the MCP server by its name.
-#
-# MCP as Tool
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope provides fine-grained management of MCP tools, including both server-level and function-level management.
-#
-# Server-Level Management
-# --------------------------------
-# You can register all tools from an MCP server into ``Toolkit`` as follows.
-#
-# .. tip:: Optionally, you can specify a group name to organize the tools. Refer to :ref:`tool` section for group-wise tools management.
-#
-
-toolkit = Toolkit()
-
-
-async def example_register_stateless_mcp() -> None:
- """Example of registering MCP tools from a stateless client."""
- # Register all tools from the MCP server
- await toolkit.register_mcp(
- stateless_client,
- # group_name="map_services", # Optional group name
- )
-
- print(
- "Total number of MCP tools registered:",
- len(toolkit.get_json_schemas()),
- )
-
- maps_geo = next(
- tool
- for tool in toolkit.get_json_schemas()
- if tool["function"]["name"] == "maps_geo"
- )
- print("\nThe example ``maps_geo`` function:")
- print(
- json.dumps(
- maps_geo,
- indent=4,
- ensure_ascii=False,
- ),
- )
-
-
-asyncio.run(example_register_stateless_mcp())
-
-# %%
-# To remove the registered tools, you can use the ``remove_tool_function`` to remove a specific tool function, or ``remove_mcp_clients`` to remove all tools from a specific MCP.
-#
-
-
-async def example_remove_mcp_tools() -> None:
- """Example of removing MCP tools."""
- print(
- "Total number of tools before removal: ",
- len(toolkit.get_json_schemas()),
- )
-
- # Remove a specific tool function by its name
- toolkit.remove_tool_function("maps_geo")
- print("Number of tools: ", len(toolkit.get_json_schemas()))
-
- # Remove all tools from the MCP client by its name
- await toolkit.remove_mcp_clients(client_names=["mcp_services_stateless"])
- print("Number of tools: ", len(toolkit.get_json_schemas()))
-
-
-asyncio.run(example_remove_mcp_tools())
-
-# %%
-# Function-Level Management
-# --------------------------------
-# We notice the demand for more fine-grained control over MCP tools, such as post-processing the tool results, or use them to create a more complex tool function.
-#
-# Therefore, AgentScope supports to obtain the callable function object from MCP by its name, so that you can
-#
-# - call it directly,
-# - wrap it into your own function, or anyway you like.
-#
-# Additionally, you can specify whether to wrap the tool result into ``ToolResponse`` object in AgentScope, so that you can use it seamlessly with the ``Toolkit``.
-# If you set ``wrap_tool_result=False``, the raw result type ``mcp.types.CallToolResult`` will be returned.
-#
-# Taking the ``maps_geo`` function as an example, you can obtain it as a callable function object as follows:
-#
-
-
-async def example_function_level_usage() -> None:
- """Example of using function-level MCP tool."""
- func_obj = await stateless_client.get_callable_function(
- func_name="maps_geo",
- # Whether to wrap the tool result into ToolResponse in AgentScope
- wrap_tool_result=True,
- )
-
- # You can obtain its name, description and json schema
- print("Function name:", func_obj.name)
- print("Function description:", func_obj.description)
- print(
- "Function JSON schema:",
- json.dumps(func_obj.json_schema, indent=4, ensure_ascii=False),
- )
-
- # Call the function object directly
- res = await func_obj(
- address="Tiananmen Square",
- city="Beijing",
- )
- print("\nFunction call result:")
- print(res)
-
-
-asyncio.run(example_function_level_usage())
-
-# %%
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# For more details, see:
-#
-# - :ref:`tool`
-# - :ref:`agent`
-#
diff --git a/docs/tutorial/en/src/task_memory.py b/docs/tutorial/en/src/task_memory.py
deleted file mode 100644
index 8b9aedb37..000000000
--- a/docs/tutorial/en/src/task_memory.py
+++ /dev/null
@@ -1,446 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _memory:
-
-Memory
-========================
-
-The memory module in AgentScope is responsible for
-
-- storing the messages and
-- managing them with specific marks
-in different storage implementations.
-
-The **mark** is a string label associated with each message in the memory,
-which can be used to categorize, filter, and retrieve messages based on their
-context or purpose.
-
-It's powerful for high-level memory management in agents. For example,
-In `ReActAgent` class, the hint messages are stored with the
-mark "hint", and the memory compression functionality is also implemented
-based on marks.
-
-.. note:: The memory module only provides storage and management
- functionalities. The algorithm logic such as compression is implemented in
- the agent level.
-
-Currently, AgentScope provides the following memory storage implementations:
-
-.. list-table:: The built-in memory storage implementations in AgentScope
- :header-rows: 1
-
- * - Memory Class
- - Description
- * - ``InMemoryMemory``
- - A simple in-memory implementation of memory storage.
- * - ``AsyncSQLAlchemyMemory``
- - An asynchronous SQLAlchemy-based implementation of memory storage, which supports various databases such as SQLite, PostgreSQL, MySQL, etc.
- * - ``RedisMemory``
- - A Redis-based implementation of memory storage.
-
-.. tip:: If you're interested in contributing new memory storage implementations, please refer to the
- `Contribution Guide <https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md#types-of-contributions>`_.
-
-All the above memory classes inherit from the base class ``MemoryBase``, and
-provide the following methods to manage the messages in the memory:
-
-.. list-table:: The methods provided by the memory classes
- :header-rows: 1
-
- * - Method
- - Description
- * - ``add(
- memories: Msg | list[Msg] | None,
- marks: str | list[str] | None = None,
- ) -> None``
- - Add ``Msg`` object(s) to the memory storage with the given mark(s) (if provided).
- * - ``delete(msg_ids: list[str]) -> int``
- - Delete messages from the memory storage by their IDs.
- * - ``delete_by_mark(mark: str | list[str]) -> int``
- - Delete messages from the memory by their marks.
- * - ``size() -> int``
- - Get the size of the memory storage.
- * - ``clear() -> None``
- - Clear the memory storage.
- * - ``get_memory(
- mark: str | None = None,
- exclude_mark: str | None = None,
- ) -> list[Msg]``
- - Get the messages from the memory by mark (if provided). Otherwise, get all messages. If the ``update_compressed_summary`` method is used to store a compressed summary, it will be attached to the head of the returned messages.
- * - ``update_messages_mark(
- new_mark: str | None,
- old_mark: str | None = None,
- msg_ids: list[str] | None = None,
- ) -> int``
- - A unified method to update marks of messages in the storage (add, remove, or change marks).
- * - ``update_compressed_summary(
- summary: str,
- ) -> None``
- - Update the summary attribute stored in the memory.
-"""
-import asyncio
-import json
-
-import fakeredis
-from sqlalchemy.ext.asyncio import create_async_engine
-
-from agentscope.memory import (
- InMemoryMemory,
- AsyncSQLAlchemyMemory,
- RedisMemory,
-)
-from agentscope.message import Msg
-
-
-# %%
-# In-Memory Memory
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The in-memory memory provides a simple way to store messages in memory.
-# Together with the :ref:`state` module, it can persist the memory content across
-# different users and sessions.
-
-
-async def in_memory_example():
- """An example of using InMemoryMemory to store messages in memory."""
- memory = InMemoryMemory()
- await memory.add(
- Msg("Alice", "Generate a report about AgentScope", "user"),
- )
-
- # Add a hint message with the mark "hint"
- await memory.add(
- [
- Msg(
- "system",
- "<system-hint>Create a plan first to collect information and "
- "generate the report step by step.</system-hint>",
- "system",
- ),
- ],
- marks="hint",
- )
-
- msgs = await memory.get_memory(mark="hint")
- print("The messages with mark 'hint':")
- for msg in msgs:
- print(f"- {msg}")
-
- # All the stored messages can be exported and loaded via ``state_dict`` and ``load_state_dict`` methods.
- state = memory.state_dict()
- print("The state dict of the memory:")
- print(json.dumps(state, indent=2))
-
- # delete messages by mark
- deleted_count = await memory.delete_by_mark("hint")
- print(f"Deleted {deleted_count} messages with mark 'hint'.")
-
- print("The state dict of the memory after deletion:")
- state = memory.state_dict()
- print(json.dumps(state, indent=2))
-
-
-asyncio.run(in_memory_example())
-
-# %%
-# Relational Database Memory
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope provides a unified interface to work with relational databases via SQLAlchemy, supporting
-#
-# - various databases such as SQLite, PostgreSQL, MySQL, etc.
-# - user and session management, and
-# - connection pooling in the production environment
-#
-# Specifically, here we use a memory backed by SQLite as an example.
-
-
-async def sqlalchemy_example() -> None:
- """An example of using AsyncSQLAlchemyMemory to store messages in a SQLite database."""
-
- # Create an async SQLAlchemy engine first
- engine = create_async_engine("sqlite+aiosqlite:///./test_memory.db")
-
- # Then create the memory with the engine
- memory = AsyncSQLAlchemyMemory(
- engine_or_session=engine,
- # Optionally specify user_id and session_id
- user_id="user_1",
- session_id="session_1",
- )
-
- await memory.add(
- Msg("Alice", "Generate a report about AgentScope", "user"),
- )
-
- await memory.add(
- [
- Msg(
- "system",
- "<system-hint>Create a plan first to collect information and "
- "generate the report step by step.</system-hint>",
- "system",
- ),
- ],
- marks="hint",
- )
-
- msgs = await memory.get_memory(mark="hint")
- print("The messages with mark 'hint':")
- for msg in msgs:
- print(f"- {msg}")
-
- # Close the engine when done
- await memory.close()
-
-
-asyncio.run(sqlalchemy_example())
-
-# %%
-# Optionally, you can also use the ``AsyncSQLAlchemyMemory`` as an async context manager, and the session will be closed automatically when exiting the context.
-
-
-async def sqlalchemy_context_example() -> None:
- """Example of using AsyncSQLAlchemyMemory as an async context manager."""
- engine = create_async_engine("sqlite+aiosqlite:///./test_memory.db")
- async with AsyncSQLAlchemyMemory(
- engine_or_session=engine,
- user_id="user_1",
- session_id="session_1",
- ) as memory:
- await memory.add(
- Msg("Alice", "Generate a report about AgentScope", "user"),
- )
-
- msgs = await memory.get_memory()
- print("All messages in the memory:")
- for msg in msgs:
- print(f"- {msg}")
-
-
-asyncio.run(sqlalchemy_context_example())
-
-# %%
-# In production environment e.g. with FastAPI, the connection pooling can be enabled as follows:
-#
-# .. code-block:: python
-# :caption: SQLAlchemy Memory with Connection Pooling in FastAPI
-#
-# from typing import AsyncGenerator
-#
-# from fastapi import FastAPI, Depends
-# from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
-#
-# from agentscope.agent import ReActAgent
-# from agentscope.pipeline import stream_printing_messages
-#
-#
-# app = FastAPI()
-#
-# # Create an async SQLAlchemy engine with connection pooling
-# engine = create_async_engine(
-# "sqlite+aiosqlite:///./test_memory.db",
-# pool_size=10,
-# max_overflow=20,
-# pool_timeout=30,
-# # ... The other pool settings
-# )
-#
-# # Create a session maker
-# async_session_marker = async_sessionmaker(
-# engine,
-# expire_on_commit=False,
-# autocommit=False,
-# autoflush=False,
-# )
-#
-# async def get_db() -> AsyncGenerator[AsyncSession, None]:
-# async with async_session_marker() as session:
-# try:
-# yield session
-# await session.commit()
-# except Exception:
-# await session.rollback()
-# raise
-# finally:
-# await session.close()
-#
-# @app.post("/chat")
-# async def chat_endpoint(
-# user_id: str,
-# session_id: str,
-# input: str,
-# db_session: AsyncSession = Depends(get_db),
-# ):
-# # Some setup for the agent
-# ...
-#
-# # Create the agent with the SQLAlchemy memory
-# agent = ReActAgent(
-# # ...
-# memory=AsyncSQLAlchemyMemory(
-# engine_or_session=db_session,
-# user_id=user_id,
-# session_id=session_id,
-# ),
-# )
-#
-# # Handle the chat with the agent
-# async for msg, _ in stream_printing_messages(
-# agents=[agent],
-# coroutine_task=agent(Msg("user", input, "user")),
-# ):
-# # yield msg to the client
-# ...
-#
-#
-# NoSQL Database Memory
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope also provides memory implementations based on NoSQL databases such as Redis.
-# It also supports user and session management, and connection pooling in the production environment.
-#
-# First, we can initialize the Redis memory as follows:
-
-
-async def redis_memory_example() -> None:
- """An example of using RedisMemory to store messages in Redis."""
- # Use fakeredis for in-memory testing without a real Redis server
- fake_redis = fakeredis.aioredis.FakeRedis(decode_responses=True)
- # Create the Redis memory
- memory = RedisMemory(
- # Using fake redis for demonstration
- connection_pool=fake_redis.connection_pool,
- # You can also connect to a real Redis server by specifying host and port
- # host="localhost",
- # port=6379,
- # Optionally specify user_id and session_id
- user_id="user_1",
- session_id="session_1",
- )
-
- # Add a message to the memory
- await memory.add(
- Msg(
- "Alice",
- "Generate a report about AgentScope",
- "user",
- ),
- )
-
- # Add a hint message with the mark "hint"
- await memory.add(
- Msg(
- "system",
- "<system-hint>Create a plan first to collect information and "
- "generate the report step by step.</system-hint>",
- "system",
- ),
- marks="hint",
- )
-
- # Retrieve messages with the mark "hint"
- msgs = await memory.get_memory(mark="hint")
- print("The messages with mark 'hint':")
- for msg in msgs:
- print(f"- {msg}")
-
-
-asyncio.run(redis_memory_example())
-
-# %%
-# Similarly, the `RedisMemory` can also be used with connection pooling in the production environment, e.g., with FastAPI.
-#
-# .. code-block:: python
-# :caption: Redis Memory with Connection Pooling in FastAPI
-#
-# from fastapi import FastAPI, HTTPException
-# from redis.asyncio import ConnectionPool
-# from contextlib import asynccontextmanager
-#
-# # Global Redis connection pool
-# redis_pool: ConnectionPool | None = None
-#
-#
-# # Use the lifespan event to manage the Redis connection pool
-# @asynccontextmanager
-# async def lifespan(app: FastAPI):
-# global redis_pool
-# redis_pool = ConnectionPool(
-# host="localhost",
-# port=6379,
-# db=0,
-# password=None,
-# decode_responses=True,
-# max_connections=10,
-# encoding="utf-8",
-# )
-# print("✅ Redis connection established")
-#
-# yield
-#
-# await redis_pool.disconnect()
-# print("✅ Redis connection closed")
-#
-#
-# app = FastAPI(lifespan=lifespan)
-#
-#
-# @app.post("/chat_endpoint")
-# async def chat_endpoint(
-# user_id: str, session_id: str, input: str
-# ): # ✅ 直接使用BaseModel
-# """A chat endpoint"""
-# global redis_pool
-# if redis_pool is None:
-# raise HTTPException(
-# status_code=500,
-# detail="Redis connection pool is not initialized.",
-# )
-#
-# # Create the Redis memory
-# memory = RedisMemory(
-# connection_pool=redis_pool,
-# user_id=user_id,
-# session_id=session_id,
-# )
-#
-# ...
-#
-# # Close the Redis client connection when done
-# client = memory.get_client()
-# await client.aclose()
-#
-#
-#
-# Customizing Memory
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# To customize your own memory, just inherit from ``MemoryBase`` and implement the following methods:
-#
-# .. list-table::
-# :header-rows: 1
-#
-# * - Method
-# - Description
-# * - ``add``
-# - Add ``Msg`` objects to the memory
-# * - ``delete``
-# - Delete ``Msg`` objects from the memory
-# * - ``delete_by_mark``
-# - Delete ``Msg`` objects from the memory by their marks
-# * - ``size``
-# - The size of the memory
-# * - ``clear``
-# - Clear the memory content
-# * - ``get_memory``
-# - Get the memory content as a list of ``Msg`` objects
-# * - ``update_messages_mark``
-# - Update marks of messages in the memory
-# * - ``state_dict``
-# - Get the state dictionary of the memory
-# * - ``load_state_dict``
-# - Load the state dictionary of the memory
-#
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`agent`
-# - :ref:`long-term-memory`
diff --git a/docs/tutorial/en/src/task_middleware.py b/docs/tutorial/en/src/task_middleware.py
deleted file mode 100644
index 1c7880ac3..000000000
--- a/docs/tutorial/en/src/task_middleware.py
+++ /dev/null
@@ -1,403 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _middleware:
-
-Middleware
-===========================
-
-AgentScope provides a flexible middleware system that allows developers to intercept and modify the execution of various operations.
-Currently, middleware support is available for **tool execution** in the ``Toolkit`` class.
-
-The middleware system follows an **onion model**, where each middleware wraps around the previous one, forming layers.
-This allows developers to:
-
-- Perform **pre-processing** before the operation
-- **Intercept and modify** responses during execution
-- Perform **post-processing** after the operation completes
-- **Skip** the operation execution entirely based on conditions
-
-.. tip:: Future versions of AgentScope will expand middleware support to other components such as agents and models.
-
-"""
-import asyncio
-from typing import AsyncGenerator, Callable
-
-from agentscope.message import TextBlock, ToolUseBlock
-from agentscope.tool import ToolResponse, Toolkit
-
-
-# %%
-# Tool Execution Middleware
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The ``Toolkit`` class supports middleware for tool execution via the ``register_middleware`` method.
-# Each middleware can intercept the tool call and modify the input or output.
-#
-# Middleware Signature
-# ------------------------------
-#
-# A middleware function should have the following signature:
-#
-# .. code-block:: python
-#
-# async def middleware(
-# kwargs: dict,
-# next_handler: Callable,
-# ) -> AsyncGenerator[ToolResponse, None]:
-# # Access parameters from kwargs
-# tool_call = kwargs["tool_call"]
-#
-# # Pre-processing
-# # ...
-#
-# # Call the next middleware or tool function
-# async for response in await next_handler(**kwargs):
-# # Post-processing
-# yield response
-#
-# .. list-table:: Middleware Parameters
-# :header-rows: 1
-#
-# * - Parameter
-# - Type
-# - Description
-# * - ``kwargs``
-# - ``dict``
-# - Context parameters. Currently, includes ``tool_call`` (ToolUseBlock). May include additional parameters in future versions.
-# * - ``next_handler``
-# - ``Callable``
-# - A callable that accepts kwargs dict and returns a coroutine yielding AsyncGenerator of ToolResponse objects
-# * - **Returns**
-# - ``AsyncGenerator[ToolResponse, None]``
-# - An async generator that yields ToolResponse objects
-#
-# Basic Example
-# ------------------------------
-#
-# Here is a simple middleware that logs tool calls:
-#
-
-
-async def logging_middleware(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """A middleware that logs tool execution."""
- # Access the tool call from kwargs
- tool_call = kwargs["tool_call"]
-
- # Pre-processing: log before tool execution
- print(f"[Middleware] Calling tool: {tool_call['name']}")
- print(f"[Middleware] Input: {tool_call['input']}")
-
- # Call the next handler (either another middleware or the actual tool)
- async for response in await next_handler(**kwargs):
- # Post-processing: log the response
- print(f"[Middleware] Response: {response.content[0]['text']}")
- yield response
-
- # This will execute after all responses are yielded
- print(f"[Middleware] Tool {tool_call['name']} completed")
-
-
-# %%
-# Let's register this middleware with a toolkit and test it:
-#
-
-
-async def search_tool(query: str) -> ToolResponse:
- """A simple search tool.
-
- Args:
- query (`str`):
- The search query.
-
- Returns:
- `ToolResponse`:
- The search result.
- """
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"Search results for '{query}'",
- ),
- ],
- )
-
-
-async def example_logging_middleware() -> None:
- """Example of using logging middleware."""
- # Create a toolkit and register the tool
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
-
- # Register the middleware
- toolkit.register_middleware(logging_middleware)
-
- # Call the tool
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="1",
- name="search_tool",
- input={"query": "AgentScope"},
- ),
- )
-
- async for response in result:
- print(f"\n[Final] {response.content[0]['text']}\n")
-
-
-print("=" * 60)
-print("Example 1: Logging Middleware")
-print("=" * 60)
-asyncio.run(example_logging_middleware())
-
-# %%
-# Modifying Input and Output
-# ------------------------------
-#
-# Middleware can also modify the tool call input and the response content:
-#
-
-
-async def transform_middleware(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """A middleware that transforms input and output."""
- # Access the tool call from kwargs
- tool_call = kwargs["tool_call"]
-
- # Pre-processing: modify the input
- original_query = tool_call["input"]["query"]
- tool_call["input"]["query"] = f"[TRANSFORMED] {original_query}"
-
- async for response in await next_handler(**kwargs):
- # Post-processing: modify the response
- original_text = response.content[0]["text"]
- response.content[0]["text"] = f"{original_text} [MODIFIED]"
- yield response
-
-
-async def example_transform_middleware() -> None:
- """Example of transforming middleware."""
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
- toolkit.register_middleware(transform_middleware)
-
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="2",
- name="search_tool",
- input={"query": "middleware"},
- ),
- )
-
- async for response in result:
- print(f"Result: {response.content[0]['text']}")
-
-
-print("\n" + "=" * 60)
-print("Example 2: Transform Middleware")
-print("=" * 60)
-asyncio.run(example_transform_middleware())
-
-# %%
-# Authorization Middleware
-# ------------------------------
-#
-# You can use middleware to implement authorization checks and skip tool execution if not authorized:
-#
-
-
-async def authorization_middleware(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """A middleware that checks authorization."""
- # Access the tool call from kwargs
- tool_call = kwargs["tool_call"]
-
- # Check if the tool is authorized (simple example)
- authorized_tools = {"search_tool"}
-
- if tool_call["name"] not in authorized_tools:
- # Skip execution and return error directly
- print(f"[Auth] Tool {tool_call['name']} is not authorized")
- yield ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"Error: Tool '{tool_call['name']}' is not authorized", # noqa: E501
- ),
- ],
- )
- return
-
- # Tool is authorized, proceed
- print(f"[Auth] Tool {tool_call['name']} is authorized")
- async for response in await next_handler(**kwargs):
- yield response
-
-
-async def unauthorized_tool(data: str) -> ToolResponse:
- """An unauthorized tool.
-
- Args:
- data (`str`):
- Some data.
-
- Returns:
- `ToolResponse`:
- The result.
- """
- return ToolResponse(
- content=[TextBlock(type="text", text=f"Processing {data}")],
- )
-
-
-async def example_authorization_middleware() -> None:
- """Example of authorization middleware."""
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
- toolkit.register_tool_function(unauthorized_tool)
- toolkit.register_middleware(authorization_middleware)
-
- # Try authorized tool
- print("\nCalling authorized tool:")
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="3",
- name="search_tool",
- input={"query": "test"},
- ),
- )
- async for response in result:
- print(f"Result: {response.content[0]['text']}")
-
- # Try unauthorized tool
- print("\nCalling unauthorized tool:")
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="4",
- name="unauthorized_tool",
- input={"data": "test"},
- ),
- )
- async for response in result:
- print(f"Result: {response.content[0]['text']}")
-
-
-print("\n" + "=" * 60)
-print("Example 3: Authorization Middleware")
-print("=" * 60)
-asyncio.run(example_authorization_middleware())
-
-# %%
-# Multiple Middleware (Onion Model)
-# ------------------------------
-#
-# When multiple middleware are registered, they form an onion-like structure.
-# The execution order follows the onion model:
-#
-# - **Pre-processing**: Executes in the order middleware are registered
-# - **Post-processing**: Executes in reverse order (inner to outer)
-#
-# This is because the actual tool response object is passed through the middleware chain,
-# and each middleware modifies it in place.
-#
-
-
-async def middleware_1(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """First middleware."""
- # Access the tool call from kwargs
- tool_call = kwargs["tool_call"]
-
- # Pre-processing
- print("[M1] Pre-processing")
- tool_call["input"]["query"] += " [M1]"
-
- async for response in await next_handler(**kwargs):
- # Post-processing
- response.content[0]["text"] += " [M1]"
- print("[M1] Post-processing")
- yield response
-
-
-async def middleware_2(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """Second middleware."""
- # Access the tool call from kwargs
- tool_call = kwargs["tool_call"]
-
- # Pre-processing
- print("[M2] Pre-processing")
- tool_call["input"]["query"] += " [M2]"
-
- async for response in await next_handler(**kwargs):
- # Post-processing
- response.content[0]["text"] += " [M2]"
- print("[M2] Post-processing")
- yield response
-
-
-async def example_multiple_middleware() -> None:
- """Example of multiple middleware."""
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
-
- # Register middleware in order
- toolkit.register_middleware(middleware_1)
- toolkit.register_middleware(middleware_2)
-
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="5",
- name="search_tool",
- input={"query": "test"},
- ),
- )
-
- async for response in result:
- print(f"\nFinal result: {response.content[0]['text']}")
-
-
-print("\n" + "=" * 60)
-print("Example 4: Multiple Middleware (Onion Model)")
-print("=" * 60)
-print("\nExecution flow:")
-print("M1 Pre → M2 Pre → Tool → M2 Post → M1 Post")
-print()
-asyncio.run(example_multiple_middleware())
-
-# %%
-# Use Cases
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The middleware system is useful for various scenarios:
-#
-# - **Logging and Monitoring**: Track tool usage and performance
-# - **Authorization**: Control access to specific tools
-# - **Rate Limiting**: Limit the frequency of tool calls
-# - **Caching**: Cache tool responses for repeated calls
-# - **Error Handling**: Add retry logic or graceful degradation
-# - **Input Validation**: Validate and sanitize tool inputs
-# - **Output Transformation**: Format or filter tool outputs
-# - **Metrics Collection**: Collect statistics about tool usage
-#
-# .. note::
-# - Middleware are applied in the order they are registered
-# - The same ``ToolResponse`` object is passed through the middleware chain and modified in place
-# - Middleware can completely skip tool execution by not calling ``next_handler``
-# - All middleware must be async generator functions that yield ``ToolResponse`` objects
diff --git a/docs/tutorial/en/src/task_model.py b/docs/tutorial/en/src/task_model.py
deleted file mode 100644
index 381ca130a..000000000
--- a/docs/tutorial/en/src/task_model.py
+++ /dev/null
@@ -1,235 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _model:
-
-Model
-====================
-
-In this tutorial, we introduce the model APIs integrated in AgentScope, how to use them and how to integrate new model APIs.
-The supported model APIs and providers include:
-
-.. list-table::
- :header-rows: 1
-
- * - API
- - Class
- - Compatible
- - Streaming
- - Tools
- - Vision
- - Reasoning
- * - OpenAI
- - ``OpenAIChatModel``
- - vLLM, DeepSeek
- - ✅
- - ✅
- - ✅
- - ✅
- * - DashScope
- - ``DashScopeChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
- * - Anthropic
- - ``AnthropicChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
- * - Gemini
- - ``GeminiChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
- * - Ollama
- - ``OllamaChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
-
-.. note:: When using vLLM, you need to configure the appropriate tool calling parameters for different models during deployment, such as ``--enable-auto-tool-choice``, ``--tool-call-parser``, etc. For more details, refer to the `official vLLM documentation <https://docs.vllm.ai/en/latest/features/tool_calling.html>`_.
-
-.. note:: For OpenAI-compatible models (e.g. vLLM, Deepseek), developers can use the ``OpenAIChatModel`` class, and specify the API endpoint by the ``client_kwargs`` parameter: ``client_kwargs={"base_url": "http://your-api-endpoint"}``. For example:
-
- .. code-block:: python
-
- OpenAIChatModel(client_kwargs={"base_url": "http://localhost:8000/v1"})
-
-.. note:: Model behavior parameters (such as temperature, maximum length, etc.) can be preset in the constructor function via the ``generate_kwargs`` parameter. For example:
-
- .. code-block:: python
-
- OpenAIChatModel(generate_kwargs={"temperature": 0.3, "max_tokens": 1000})
-
-To provide unified model interfaces, the above model classes has the following common methods:
-
-- The first three arguments of the ``__call__`` method are ``messages`` , ``tools`` and ``tool_choice``, representing the input messages, JSON schema of tool functions, and tool selection mode, respectively.
-- The return type are either a ``ChatResponse`` instance or an async generator of ``ChatResponse`` in streaming mode.
-
-.. note:: Different model APIs differ in the input message format, refer to :ref:`prompt` for more details.
-
-The ``ChatResponse`` instance contains the generated thinking/text/tool use content, identity, created time and usage information.
-"""
-import asyncio
-import json
-import os
-
-from agentscope.message import TextBlock, ToolUseBlock, ThinkingBlock, Msg
-from agentscope.model import ChatResponse, DashScopeChatModel
-
-response = ChatResponse(
- content=[
- ThinkingBlock(
- type="thinking",
- thinking="I should search for AgentScope on Google.",
- ),
- TextBlock(type="text", text="I'll search for AgentScope on Google."),
- ToolUseBlock(
- type="tool_use",
- id="642n298gjna",
- name="google_search",
- input={"query": "AgentScope?"},
- ),
- ],
-)
-
-print(response)
-
-# %%
-# Taking ``DashScopeChatModel`` as an example, we can use it to create a chat model instance and call it with messages and tools:
-
-
-async def example_model_call() -> None:
- """An example of using the DashScopeChatModel."""
- model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- )
-
- res = await model(
- messages=[
- {"role": "user", "content": "Hi!"},
- ],
- )
-
- # You can directly create a ``Msg`` object with the response content
- msg_res = Msg("Friday", res.content, "assistant")
-
- print("The response:", res)
- print("The response as Msg:", msg_res)
-
-
-asyncio.run(example_model_call())
-
-# %%
-# Streaming
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# To enable streaming model, set the ``stream`` parameter in the model constructor to ``True``.
-# When streaming is enabled, the ``__call__`` method will return an **async generator** that yields ``ChatResponse`` instances as they are generated by the model.
-#
-# .. note:: The streaming mode in AgentScope is designed to be **cumulative**, meaning the content in each chunk contains all the previous content plus the newly generated content.
-#
-
-
-async def example_streaming() -> None:
- """An example of using the streaming model."""
- model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=True,
- )
-
- generator = await model(
- messages=[
- {
- "role": "user",
- "content": "Count from 1 to 20, and just report the number without any other information.",
- },
- ],
- )
- print("The type of the response:", type(generator))
-
- i = 0
- async for chunk in generator:
- print(f"Chunk {i}")
- print(f"\ttype: {type(chunk.content)}")
- print(f"\t{chunk}\n")
- i += 1
-
-
-asyncio.run(example_streaming())
-
-# %%
-# Reasoning
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope supports reasoning models by providing the ``ThinkingBlock``.
-#
-
-
-async def example_reasoning() -> None:
- """An example of using the reasoning model."""
- model = DashScopeChatModel(
- model_name="qwen-turbo",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- enable_thinking=True,
- )
-
- res = await model(
- messages=[
- {"role": "user", "content": "Who am I?"},
- ],
- )
-
- last_chunk = None
- async for chunk in res:
- last_chunk = chunk
- print("The final response:")
- print(last_chunk)
-
-
-asyncio.run(example_reasoning())
-
-# %%
-# Tools API
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Different model providers differ in their tools APIs, e.g. the tools JSON schema, the tool call/response format.
-# To provide a unified interface, AgentScope solves the problem by:
-#
-# - Providing unified tool call block :ref:`ToolUseBlock <tool-block>` and tool response block :ref:`ToolResultBlock <tool-block>`, respectively.
-# - Providing a unified tools interface in the ``__call__`` method of the model classes, that accepts a list of tools JSON schemas as follows:
-#
-
-json_schemas = [
- {
- "type": "function",
- "function": {
- "name": "google_search",
- "description": "Search for a query on Google.",
- "parameters": {
- "type": "object",
- "properties": {
- "query": {
- "type": "string",
- "description": "The search query.",
- },
- },
- "required": ["query"],
- },
- },
- },
-]
-
-# %%
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`message`
-# - :ref:`prompt`
-#
diff --git a/docs/tutorial/en/src/task_pipeline.py b/docs/tutorial/en/src/task_pipeline.py
deleted file mode 100644
index 34a41faed..000000000
--- a/docs/tutorial/en/src/task_pipeline.py
+++ /dev/null
@@ -1,288 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _pipeline:
-
-Pipeline
-========================
-
-For multi-agent orchestration, AgentScope provides the ``agentscope.pipeline`` module
-as syntax sugar for chaining agents together, including
-
-- **MsgHub**: a message hub for broadcasting messages among multiple agents
-- **sequential_pipeline** and **SequentialPipeline**: a functional and class-based implementation that chains agents in a sequential manner
-- **fanout_pipeline** and **FanoutPipeline**: a functional and class-based implementation that distributes the same input to multiple agents
-- **stream_printing_messages**: a utility function that convert the printing messages from agent(s) into an async generator
-
-"""
-
-import os, asyncio
-
-from agentscope.formatter import DashScopeMultiAgentFormatter
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.agent import ReActAgent
-from agentscope.pipeline import MsgHub, stream_printing_messages
-
-
-# %%
-# Broadcasting with MsgHub
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The ``MsgHub`` class is an **async context manager**, receiving a list of agents as its participants.
-# When one participant generates a replying message, all other participants will receive this message by calling their ``observe`` method.
-#
-# That means within a ``MsgHub`` context, developers don't need to manually send a replying message from one agent to another.
-# The broadcasting is automatically handled.
-#
-# Here we create four agents: Alice, Bob, Charlie and David.
-# Then we start a meeting with Alice, Bob and Charlie by introducing themselves.
-# Note David is not included in this meeting.
-
-
-def create_agent(name: str, age: int, career: str) -> ReActAgent:
- """Create agent object by the given information."""
- return ReActAgent(
- name=name,
- sys_prompt=f"You're {name}, a {age}-year-old {career}",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeMultiAgentFormatter(),
- )
-
-
-alice = create_agent("Alice", 50, "teacher")
-bob = create_agent("Bob", 35, "engineer")
-charlie = create_agent("Charlie", 28, "designer")
-david = create_agent("David", 30, "developer")
-
-# %%
-# Then we start a meeting and let them introduce themselves without manual message passing:
-#
-# .. hint:: The message in ``announcement`` will be broadcasted to all participants when entering the ``MsgHub`` context.
-#
-
-
-async def example_broadcast_message():
- """Example of broadcasting messages with MsgHub."""
-
- # Create a message hub
- async with MsgHub(
- participants=[alice, bob, charlie],
- announcement=Msg(
- "user",
- "Now introduce yourself in one sentence, including your name, age and career.",
- "user",
- ),
- ) as hub:
- # Group chat without manual message passing
- await alice()
- await bob()
- await charlie()
-
-
-asyncio.run(example_broadcast_message())
-
-# %%
-# Now let's check if Bob, Charlie and David received Alice's message.
-#
-
-
-async def check_broadcast_message():
- """Check if the messages are broadcast correctly."""
- user_msg = Msg(
- "user",
- "Do you know who's Alice, and what she does? Answer me briefly.",
- "user",
- )
-
- await bob(user_msg)
- await charlie(user_msg)
- await david(user_msg)
-
-
-asyncio.run(check_broadcast_message())
-
-# %%
-# Now we observe that Bob and Charlie know Alice and her profession, while David has no idea
-# about Alice since he is not included in the ``MsgHub`` context.
-#
-#
-# Dynamic Participant Management
-# ---------------------------------------
-# Additionally, ``MsgHub`` supports to dynamically manage participants by the following methods:
-#
-# - ``add``: add one or multiple agents as new participants
-# - ``delete``: remove one or multiple agents from participants, and they will no longer receive broadcasted messages
-# - ``broadcast``: broadcast a message to all current participants
-#
-# .. note:: The newly added participants will not receive the previous messages.
-#
-# .. code-block:: python
-#
-# async with MsgHub(participants=[alice]) as hub:
-# # Add new participants
-# hub.add(david)
-#
-# # Remove participants
-# hub.delete(alice)
-#
-# # Broadcast to all current participants
-# await hub.broadcast(
-# Msg("system", "Now we begin to ...", "system"),
-# )
-#
-#
-# Pipeline
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Pipeline serves as a syntax sugar for multi-agent orchestration.
-#
-# Currently, AgentScope provides three main pipeline implementations:
-#
-# 1. **Sequential Pipeline**: Execute agents one by one in a predefined order
-# 2. **Fanout Pipeline**: Distribute the same input to multiple agents and collect their responses
-# 3. **Stream Printing Messages**: Convert the printing messages from an agent into an async generator
-#
-# Sequential Pipeline
-# ------------------------
-# The sequential pipeline executes agents one by one, where the output of the previous agent
-# becomes the input of the next agent.
-#
-# For example, the two following code snippets are equivalent:
-#
-#
-# .. code-block:: python
-# :caption: Code snippet 1: Manually call agents one by one
-#
-# msg = None
-# msg = await alice(msg)
-# msg = await bob(msg)
-# msg = await charlie(msg)
-# msg = await david(msg)
-#
-#
-# .. code-block:: python
-# :caption: Code snippet 2: Use sequential pipeline
-#
-# from agentscope.pipeline import sequential_pipeline
-# msg = await sequential_pipeline(
-# # List of agents to be executed in order
-# agents=[alice, bob, charlie, david],
-# # The first input message, can be None
-# msg=None
-# )
-#
-
-# %%
-# Fanout Pipeline
-# ------------------------
-# The fanout pipeline distributes the same input message to multiple agents simultaneously and collects all their responses. This is useful when you want to gather different perspectives or expertise on the same topic.
-#
-# For example, the two following code snippets are equivalent:
-#
-#
-# .. code-block:: python
-# :caption: Code snippet 3: Manually call agents one by one
-#
-# from copy import deepcopy
-#
-# msgs = []
-# msg = None
-# for agent in [alice, bob, charlie, david]:
-# msgs.append(await agent(deepcopy(msg)))
-#
-#
-# .. code-block:: python
-# :caption: Code snippet 4: Use fanout pipeline
-#
-# from agentscope.pipeline import fanout_pipeline
-# msgs = await fanout_pipeline(
-# # List of agents to be executed in order
-# agents=[alice, bob, charlie, david],
-# # The first input message, can be None
-# msg=None,
-# enable_gather=False,
-# )
-#
-# .. note::
-# The ``enable_gather`` parameter controls the execution mode of the fanout pipeline:
-#
-# - ``enable_gather=True`` (default): Executes all agents **concurrently** using ``asyncio.gather()``. This provides better performance for I/O-bound operations like API calls, as agents run in parallel.
-# - ``enable_gather=False``: Executes agents **sequentially** one by one. This is useful when you need deterministic execution order or want to avoid overwhelming external services with concurrent requests.
-#
-# Choose concurrent execution for better performance, or sequential execution for predictable ordering and resource control.
-#
-# .. tip::
-# By combining ``MsgHub`` and ``sequential_pipeline`` or ``fanout_pipeline``, you can create more complex workflows very easily.
-#
-#
-# Stream Printing Messages
-# -------------------------------------
-# The ``stream_printing_messages`` function converts the printing messages from agent(s) into an async generator.
-# It will help you to obtain the intermediate messages from the agent(s) in a streaming way.
-#
-# It accepts a list of agents and a coroutine task, then returns an async generator that yields tuples of ``(Msg, bool)``,
-# containing the printing message during execution of the coroutine task.
-#
-# Note the messages with the same ``id`` are considered as the same message, and the ``last`` flag indicates whether it's the last chunk of this message.
-#
-# Taking the following code snippet as an example:
-
-
-async def run_example_pipeline() -> None:
- """Run an example of streaming printing messages."""
- agent = create_agent("Alice", 20, "student")
-
- # We disable the terminal printing to avoid messy outputs
- agent.set_console_output_enabled(False)
-
- async for msg, last in stream_printing_messages(
- agents=[agent],
- coroutine_task=agent(
- Msg("user", "Hello, who are you?", "user"),
- ),
- ):
- print(msg, last)
- if last:
- print()
-
-
-asyncio.run(run_example_pipeline())
-
-
-# %%
-# Advanced Pipeline Features
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# Additionally, for reusability, we also provide a class-based implementation:
-#
-# .. code-block:: python
-# :caption: Using SequentialPipeline class
-#
-# from agentscope.pipeline import SequentialPipeline
-#
-# # Create a pipeline object
-# pipeline = SequentialPipeline(agents=[alice, bob, charlie, david])
-#
-# # Call the pipeline
-# msg = await pipeline(msg=None)
-#
-# # Reuse the pipeline with different input
-# msg = await pipeline(msg=Msg("user", "Hello!", "user"))
-#
-#
-# .. code-block:: python
-# :caption: Using FanoutPipeline class
-#
-# from agentscope.pipeline import FanoutPipeline
-#
-# # Create a pipeline object
-# pipeline = FanoutPipeline(agents=[alice, bob, charlie, david])
-#
-# # Call the pipeline
-# msgs = await pipeline(msg=None)
-#
-# # Reuse the pipeline with different input
-# msgs = await pipeline(msg=Msg("user", "Hello!", "user"))
-#
diff --git a/docs/tutorial/en/src/task_plan.py b/docs/tutorial/en/src/task_plan.py
deleted file mode 100644
index 556408a82..000000000
--- a/docs/tutorial/en/src/task_plan.py
+++ /dev/null
@@ -1,293 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _plan:
-
-Plan
-=========================
-
-The Plan Module enables agents to formally break down complex tasks into manageable sub-tasks and execute them systematically. Key features include:
-
-- Support **manual plan specification**
-- Comprehensive plan management capabilities:
- - **Creating, modifying, abandoning, and restoring** plans
- - **Switching** between multiple plans
- - **Gracefully handling interruptions** by temporarily suspending plans to address user queries or urgent tasks
-- **Real-time visualization and monitoring** of plan execution
-
-.. note:: The current plan module has the following limitations, and we are working on improving them:
-
- - The subtasks in a plan must be executed sequentially
-
-Specifically, the plan module works by
-
-- providing tool functions for plan management
-- inserting hint messages to guide the ReAct agent to complete the plan
-
-The following figure illustrates how the plan module works with the ReAct agent:
-
-.. figure:: ../../_static/images/plan.png
- :width: 90%
- :alt: Plan module
- :class: bordered-image
- :align: center
-
- How the plan module works with the ReAct agent
-
-"""
-import asyncio
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.model import DashScopeChatModel
-from agentscope.plan import PlanNotebook, Plan, SubTask
-
-# %%
-# PlanNotebook
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The `PlanNotebook` class is the core of the plan module, responsible for providing
-#
-# - plan-related tool functions
-# - hint messages to guide the agent to finish the plan
-#
-# The `PlanNotebook` class can be instantiated with the following parameters:
-#
-# .. list-table:: Parameters of the `PlanNotebook` constructor
-# :header-rows: 1
-#
-# * - Name
-# - Type
-# - Description
-# * - ``max_subtasks``
-# - ``int | None``
-# - The maximum number of subtasks allowed in a plan, infinite if None
-# * - ``plan_to_hint``
-# - ``Callable[[Plan | None], str | None] | None``
-# - The function to generate hint message based on the current plan. If not provided, a default `DefaultPlanToHint` object will be used.
-# * - ``storage``
-# - ``PlanStorageBase | None``
-# - The plan storage. If not provided, a default in-memory storage will be used.
-#
-# The ``plan_to_hint`` callable object is the most important part of the
-# `PlanNotebook` class, also serves as the interface for prompt engineering.
-# We have built a default `DefaultPlanToHint` class that can be used directly.
-# Developers are encouraged to providing their own ``plan_to_hint`` function
-# for better performance.
-#
-# The ``storage`` is to store historical plans, allowing agent to
-# retrieve and restore historical plans. Developers are encouraged to
-# implement their own plan storage by inheriting the ``PlanStorageBase`` class.
-# If not provided, a default in-memory storage will be used.
-#
-# .. tip:: The ``PlanStorageBase`` class inherits from the ``StateModule``
-# class, so that the plan storage will also be saved and loaded by the
-# session management.
-#
-# The core attributes and methods of the `PlanNotebook` class are summarized
-# as follows:
-#
-# .. list-table:: Core attributes and methods of the `PlanNotebook` class
-# :header-rows: 1
-#
-# * - Type
-# - Name
-# - Description
-# * - attribute
-# - ``current_plan``
-# - The current plan that the agent is executing
-# * -
-# - ``storage``
-# - The storage for historical plans, used for retrieving and restoring historical plans
-# * -
-# - ``plan_to_hint``
-# - A callable object that takes the current plan as input and generates a hint message to guide the agent to finish the plan
-# * - method
-# - ``list_tools``
-# - List all the tool functions provided by the `PlanNotebook` class
-# * -
-# - ``get_current_hint``
-# - Get the hint message for the current plan, which will call the ``plan_to_hint`` function
-# * -
-# - | ``create_plan``,
-# | ``view_subtasks``,
-# | ``revise_current_plan``,
-# | ``update_subtask_state``,
-# | ``finish_subtask``,
-# | ``finish_plan``,
-# | ``view_historical_plans``,
-# | ``recover_historical_plan``
-# - The tool functions that allows the agent to manage the plan and subtasks
-# * -
-# - ``register_plan_change_hook``
-# - Register a hook function that will be called when the plan is changed, used to plan visualization and monitoring
-# * -
-# - ``remove_plan_change_hook``
-# - Remove a registered plan change hook function
-#
-# The ``list_tools`` method is a quick way to obtain all tool functions, so that you can register them to the agent's toolkit.
-
-plan_notebook = PlanNotebook()
-
-
-async def list_tools() -> None:
- """List the tool functions provided by PlanNotebook."""
- print("The tools provided by PlanNotebook:")
- for tool in plan_notebook.list_tools():
- print(tool.__name__)
-
-
-asyncio.run(list_tools())
-
-
-# %%
-# Working with ReActAgent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# The `ReActAgent` in AgentScope has integrated the plan module by a ``plan_notebook`` parameter in its constructor.
-# Once provided, the agent will
-#
-# - be equipped with the plan management tool functions, and
-# - be inserted with the hint messages at the beginning of each reasoning step
-#
-# There are two ways to use the plan module with the `ReActAgent`:
-#
-# - Manual plan specification: Users can manually create a plan by calling the ``create_plan`` tool function, and initialize the `ReActAgent` with the plan notebook.
-# - Agent-managed plan execution: The agent will create and manage the plan by itself, by calling the plan management tool functions.
-#
-# Manual Plan Specification
-# ---------------------------------
-# Manually creating a plan is straightforward by calling the ``create_plan`` tool function.
-# The following is an example of manually creating a plan to conduct a comprehensive research on the LLM-empowered agent.
-#
-async def manual_plan_specification() -> None:
- """Manual plan specification example."""
- await plan_notebook.create_plan(
- name="Research on Agent",
- description="Conduct a comprehensive research on the LLM-empowered agent.",
- expected_outcome="A Markdown format report answer three questions: 1. What's agent? 2. What's the current state of the art of agent? 3. What's the future trend of agent?",
- subtasks=[
- SubTask(
- name="Search agent-related survey papers",
- description=(
- "Search for survey parers on multiple sources, including "
- "Google Scholar, arXiv, and Semantic Scholar. Must be "
- "published after 2021 and have more than 50 citations."
- ),
- expected_outcome="A paper list in Markdown format",
- ),
- SubTask(
- name="Read and summarize the papers",
- description=(
- "Read the papers found in the previous step, and "
- "summarize the key points, including the definition, "
- "taxonomy, challenges, and key directions."
- ),
- expected_outcome="A summary of the key points in Markdown format",
- ),
- SubTask(
- name="Research on recent advances of large company",
- description=(
- "Research on the recent advances of large companies, "
- "including Google, Microsoft, OpenAI, Anthropic, Alibaba "
- "and Meta. Find the official blogs or news articles."
- ),
- expected_outcome="A recent advances of large company ",
- ),
- SubTask(
- name="Write a report",
- description=(
- "Write a report based on the previous steps, and answer "
- "the three questions in the expected outcome."
- ),
- expected_outcome=(
- "A Markdown format report answer three questions: 1. "
- "What's agent? 2. What's the current state of the art of "
- "agent? 3. What's the future trend of agent?"
- ),
- ),
- ],
- )
-
- print("The current hint message:\n")
- msg = await plan_notebook.get_current_hint()
- print(f"{msg.name}: {msg.content}")
-
-
-asyncio.run(manual_plan_specification())
-
-# %%
-# After creating the plan, you can initialize the `ReActAgent` with the
-# plan notebook as follows:
-
-agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
- plan_notebook=plan_notebook,
-)
-
-# %%
-# Agent-Managed Plan Execution
-# ---------------------------------
-# Agent can also create and manage the plan by itself, by calling the plan management tool functions.
-# We just need to initialize the `ReActAgent` with the plan notebook as follows:
-#
-
-agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
- plan_notebook=PlanNotebook(),
-)
-
-# %%
-# After that, we can build a loop to interact with the agent as follows.
-# Once the task is complex, the agent will create a plan by itself and
-# execute the plan step by step.
-#
-# .. code-block:: python
-# :caption: Build conversation with the plan agent
-#
-# async def interact_with_agent() -> None:
-# """Interact with the plan agent."""
-# user = UserAgent(name="user")
-#
-# msg = None
-# while True:
-# msg = await user(msg)
-# if msg.get_text_content() == "exit":
-# break
-# msg = await agent(msg)
-#
-# asyncio.run(interact_with_agent())
-#
-#
-# Plan Visualization and Monitoring
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope supports real-time visualization and monitoring of the plan
-# execution by the plan change hook function.
-#
-# They will be triggered when the plan is changed by calling the tool
-# functions. A template of the plan change hook function is as follows:
-#
-
-
-def plan_change_hook_template(self: PlanNotebook, plan: Plan) -> None:
- """A template of the plan change hook function.
-
- Args:
- self (`PlanNotebook`):
- The PlanNotebook instance.
- plan (`Plan`):
- The current plan instance (after the change).
- """
- # Forward the plan to the frontend for visualization or other processing
diff --git a/docs/tutorial/en/src/task_prompt.py b/docs/tutorial/en/src/task_prompt.py
deleted file mode 100644
index d2a925469..000000000
--- a/docs/tutorial/en/src/task_prompt.py
+++ /dev/null
@@ -1,328 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _prompt:
-
-Prompt Formatter
-=========================
-
-The formatter module in AgentScope is responsible for
-
-- converting messages into the expected format for different LLM APIs,
-- (optional) truncating messages to fit within token limits,
-- (optional) prompt engineering, e.g. summarizing long conversations.
-
-The last two are optional and can also be handled by developers within the memory or at the agent level.
-
-In AgentScope, there are two types of formatters, "ChatFormatter" and "MultiAgentFormatter", distinguished by the agent identities in their input messages.
-
-- **ChatFormatter**: Designed for standard user-assistant scenario (chatbot), using the ``role`` field to identify the user and assistant.
-- **MultiAgentFormatter**: Designed for multi-agent scenario, use the ``name`` field to identify different agents, which will combine conversation history into a single user message dictionary.
-
-The built-in formatters are listed below
-
-.. list-table:: The built-in formatters in AgentScope
- :header-rows: 1
-
- * - API Provider
- - User-assistant Scenario
- - Multi-Agent Scenario
- * - OpenAI
- - ``OpenAIChatFormatter``
- - ``OpenAIMultiAgentFormatter``
- * - Anthropic
- - ``AnthropicChatFormatter``
- - ``AnthropicMultiAgentFormatter``
- * - DashScope
- - ``DashScopeChatFormatter``
- - ``DashScopeMultiAgentFormatter``
- * - Gemini
- - ``GeminiChatFormatter``
- - ``GeminiChatFormatter``
- * - Ollama
- - ``OllamaChatFormatter``
- - ``OllamaMultiAgentFormatter``
- * - DeepSeek
- - ``DeepSeekChatFormatter``
- - ``DeepSeekMultiAgentFormatter``
- * - vLLM
- - ``OpenAIChatFormatter``
- - ``OpenAIMultiAgentFormatter``
-
-.. tip:: The OpenAI API supports the `name` field, so that `OpenAIChatFormatter` can also be used in multi-agent scenario. You can also use the `OpenAIMultiAgentFormatter` instead, which combine conversation history into a single user message.
-
-Besides, the built-in formatters support to convert different message blocks into the expected format for the target API, which are list below:
-
-.. list-table:: The supported message blocks in the built-in formatters
- :header-rows: 1
-
- * - Formatter
- - tool_use/result
- - image
- - audio
- - video
- - thinking
- * - ``OpenAIChatFormatter``
- - ✅
- - ✅
- - ✅
- - ❌
- -
- * - ``DashScopeChatFormatter``
- - ✅
- - ✅
- - ✅
- - ❌
- -
- * - ``DashScopeMultiAgentFormatter``
- - ✅
- - ✅
- - ✅
- - ❌
- -
- * - ``AnthropicChatFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- - ✅
- * - ``AnthropicMultiAgentFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- - ✅
- * - ``GeminiChatFormatter``
- - ✅
- - ✅
- - ✅
- - ✅
- -
- * - ``GeminiMultiAgentFormatter``
- - ✅
- - ✅
- - ✅
- - ✅
- -
- * - ``OllamaChatFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- -
- * - ``OllamaMultiAgentFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- -
- * - ``DeepSeekChatFormatter``
- - ✅
- - ❌
- - ❌
- - ❌
- -
- * - ``DeepSeekMultiAgentFormatter``
- - ✅
- - ❌
- - ❌
- - ❌
- -
-
-.. note:: As stated in the `official documentation <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_, only Anthropic suggests to preserve the thinking blocks in prompt formatting. For the others, we just ignore the thinking blocks in the input messages.
-
-ReAct-Oriented Formatting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The built-in formatters are all designed to support ReAct-style agents, where the input messages **consist of alternating conversation history and tool call sequences**.
-
-In user-assistant scenario, the conversation history includes the user and assistant messages, we just convert them into the expected format directly.
-However, in multi-agent scenario, the conversation history is a list of messages from different agents as follows:
-
-.. figure:: ../../_static/images/multiagent_msgs.png
- :alt: example of multiagent messages
- :width: 85%
- :align: center
-
- *Example of multi-agent messages*
-
-
-Therefore, we have to merge the conversation history into a single user message with tags "<history>" and "</history>".
-Taking DashScope as an example, the formatted message will look like this:
-"""
-
-from agentscope.token import HuggingFaceTokenCounter
-from agentscope.formatter import DashScopeMultiAgentFormatter
-from agentscope.message import Msg, ToolResultBlock, ToolUseBlock, TextBlock
-import asyncio, json
-
-
-input_msgs = [
- # System prompt
- Msg("system", "You're a helpful assistant named Friday", "system"),
- # Conversation history
- Msg("Bob", "Hi, Alice, do you know the nearest library?", "assistant"),
- Msg(
- "Alice",
- "Sorry, I don't know. Do you have any idea, Charlie?",
- "assistant",
- ),
- Msg(
- "Charlie",
- "No, let's ask Friday. Friday, get me the nearest library.",
- "assistant",
- ),
- # Tool sequence
- Msg(
- "Friday",
- [
- ToolUseBlock(
- type="tool_use",
- name="get_current_location",
- id="1",
- input={},
- ),
- ],
- "assistant",
- ),
- Msg(
- "system",
- [
- ToolResultBlock(
- type="tool_result",
- name="get_current_location",
- id="1",
- output=[TextBlock(type="text", text="104.48, 36.30")],
- ),
- ],
- "system",
- ),
- Msg(
- "Friday",
- [
- ToolUseBlock(
- type="tool_use",
- name="search_around",
- id="2",
- input={"location": [104.48, 36.30], "keyword": "library"},
- ),
- ],
- "assistant",
- ),
- Msg(
- "system",
- [
- ToolResultBlock(
- type="tool_result",
- name="search_around",
- id="2",
- output=[TextBlock(type="text", text="[...]")],
- ),
- ],
- "system",
- ),
- # Conversation history continues
- Msg("Friday", "The nearest library is ...", "assistant"),
- Msg("Bob", "Thanks, Friday!", "assistant"),
- Msg("Alice", "Let's go together.", "assistant"),
-]
-
-
-async def run_formatter_example() -> list[dict]:
- """Example of how to format multi-agent messages."""
- formatter = DashScopeMultiAgentFormatter()
- formatted_message = await formatter.format(input_msgs)
- print("The formatted message:")
- print(json.dumps(formatted_message, indent=4))
- return formatted_message
-
-
-formatted_message = asyncio.run(run_formatter_example())
-
-# %%
-# Specifically, the conversation histories are formatted into:
-#
-print("The first conversation history:")
-print(formatted_message[1]["content"])
-
-print("\nThe second conversation history:")
-print(formatted_message[-1]["content"])
-
-# %%
-# Truncation-based Formatting
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# With the token module in AgentScope, the built-in formatters support to truncate the input messages by **deleting the oldest messages** (except the system prompt message) when the token exceeds the limit.
-#
-# Taking OpenAIFormatter as an example, we first calculate the total number of tokens of the input messages.
-#
-
-
-async def run_token_counter() -> int:
- """Compute the token number of the input messages."""
- # We use huggingface token counter for dashscope models.
- token_counter = HuggingFaceTokenCounter(
- "Qwen/Qwen2.5-VL-3B-Instruct",
- use_mirror=False,
- )
-
- return await token_counter.count(formatted_message)
-
-
-# %%
-# Then we set the maximum token limit to 20 tokens less than the total number of tokens and run the formatter.
-#
-
-
-async def run_truncated_formatter() -> None:
- """Example of how to format messages with truncation."""
- token_counter = HuggingFaceTokenCounter(
- pretrained_model_name_or_path="Qwen/Qwen2.5-VL-3B-Instruct",
- use_mirror=False,
- )
- formatter = DashScopeMultiAgentFormatter(
- token_counter=token_counter,
- max_tokens=n_tokens - 20,
- )
- truncated_formatted_message = await formatter.format(input_msgs)
- n_truncated_tokens = await token_counter.count(truncated_formatted_message)
- print("The tokens after truncation: ", n_truncated_tokens)
-
- print("\nThe conversation history after truncation:")
- print(truncated_formatted_message[1]["content"])
-
-
-# %%
-# We can see the first two messages from Bob and Alice are removed to fit within the context length limits.
-#
-#
-# Customizing Formatter
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope provides two base classes ``FormatterBase`` and its child class ``TruncatedFormatterBase``.
-# The ``TruncatedFormatterBase`` class provides the FIFO truncation strategy, and all the built-in formatters are inherited from it.
-#
-# .. list-table:: The base classes of formatters in AgentScope
-# :header-rows: 1
-#
-# * - Class
-# - Abstract Method
-# - Description
-# * - ``FormatterBase``
-# - ``format``
-# - Format the input ``Msg`` objects into the expected format for the target API
-# * - ``TruncatedFormatterBase``
-# - ``_format_agent_message``
-# - Format the agent messages, which may contain multiple identities in multi-agent scenario
-# * -
-# - ``_format_tool_sequence``
-# - Format the tool use and result sequence into the expected format
-# * -
-# - ``_format`` (optional)
-# - Format the input ``Msg`` objects into the expected format for the target API
-#
-# .. tip:: - The ``_format`` in ``TruncatedFormatterBase`` groups input messages into agent messages and tool sequences, and then format them by calling ``_format_agent_message`` and ``_format_tool_sequence`` respectively. You can override it to implement your own formatting strategy.
-# - Optionally, you can override the ``_truncate`` method in ``TruncatedFormatterBase`` to implement your own truncation strategy.
-#
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# - :ref:`token`
-# - :ref:`model`
-#
diff --git a/docs/tutorial/en/src/task_rag.py b/docs/tutorial/en/src/task_rag.py
deleted file mode 100644
index 9c61c4117..000000000
--- a/docs/tutorial/en/src/task_rag.py
+++ /dev/null
@@ -1,422 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _rag:
-
-RAG
-===========================
-
-AgentScope provides built-in support for Retrieval-Augmented Generation (RAG)
-tasks. This tutorial demonstrates
-
-- how to use the RAG module in AgentScope,
-- how to use **multimodal** RAG,
-- how to integrate the RAG module with the ``ReActAgent`` in
- - **agentic manner** and
- - **generic manner**:
-
-.. list-table:: RAG module integration methods
- :header-rows: 1
-
- * - Integration Manner
- - Description
- - Advantages
- - Disadvantages
- * - Agentic Manner
- - The RAG module is integrated with the agent as a tool, and the agent can decide when to retrieve knowledge and the queries to be retrieved.
- - - The query rewriting and knowledge retrieval are integrated into the ReAct process, which is more flexible,
- - the agent can rewrite the query based on all the available information,
- - only retrieve knowledge when necessary.
- - High requirements for the LLM's reasoning and tool-use capabilities.
- * - Generic Manner
- - Retrieve knowledge at the beginning of each reply, and attach the retrieved knowledge to the prompt in a user message.
- - - Simple, easy to implement,
- - does not require high reasoning and tool-use capabilities from the LLM.
- - - Still retrieve knowledge even when not necessary, and
- - if the retrieval is imperceptible to the user, the waiting time may be longer.
-
-.. note:: As an open-source project, AgentScope doesn't insist that developers
- use the built-in RAG module. Our target is make the development easier and
- more enjoyable, so integrating other RAG implementations, frameworks, or
- services are welcome and encouraged!
-
-"""
-import asyncio
-import json
-import os
-
-from matplotlib import pyplot as plt
-
-import agentscope
-from agentscope.agent import ReActAgent
-from agentscope.embedding import (
- DashScopeTextEmbedding,
- DashScopeMultiModalEmbedding,
-)
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.rag import (
- TextReader,
- SimpleKnowledge,
- QdrantStore,
- Document,
- ImageReader,
-)
-from agentscope.tool import Toolkit
-
-# %%
-# Using RAG Module
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# The RAG module in AgentScope is composed of two core components:
-#
-# - **Reader**: responsible for reading and chunking the input documents.
-# - **Knowledge**: responsible for algorithm implementation of knowledge retrieval and updating.
-#
-# .. note:: We're integrating more vector databases and readers into AgentScope. Contributions are welcome!
-#
-# The currently built-in readers include:
-#
-
-for _ in agentscope.rag.__all__:
- if _.endswith("Reader"):
- print(f"- {_}")
-
-# %%
-# they are responsible for reading data and chunking them into ``Document`` objects.
-# The ``Document`` class has the following fields:
-#
-# - ``metadata``: the metadata of the document, including the content, doc_id, chunk_id, and total_chunks.
-# - ``embedding``: the embedding vector of the document, which will be filled when the document is added to or retrieved from the knowledge base.
-# - ``score``: the relevance score of the document, which will be filled when the document is retrieved from the knowledge base.
-#
-# Taking the ``TextReader`` as an example, it can read and chunk documents from text strings.
-#
-
-
-async def example_text_reader(print_docs: bool) -> list[Document]:
- """The example of using TextReader."""
- # Create a text reader with chunk size of 512 characters, split by characters
- reader = TextReader(chunk_size=512, split_by="paragraph")
-
- # Read documents from a text string
- documents = await reader(
- text=(
- # Fake personal profile for demonstration
- "I'm John Doe, 28 years old.\n"
- "I live in San Francisco. I work at OpenAI as a "
- "software engineer. I love hiking and photography.\n"
- "My father is Michael Doe, a doctor. I'm very proud of him. "
- "My mother is Sarah Doe, a teacher. She is very kind and "
- "always helps me with my studies.\n"
- "I'm now a PhD student at Stanford University, majoring in "
- "Computer Science. My advisor is Prof. Jane Williams, who is "
- "a leading expert in artificial intelligence. I have published "
- "several papers in top conferences, such as NeurIPS and ICML.\n"
- "My best friend is James Smith.\n"
- ),
- )
-
- if print_docs:
- print("The length of the documents:", len(documents))
- for idx, doc in enumerate(documents):
- print("Document #", idx)
- print("\tScore: ", doc.score)
- print("\tMetadata: ", json.dumps(doc.metadata, indent=2), "\n")
-
- return documents
-
-
-docs = asyncio.run(example_text_reader(print_docs=True))
-
-# %%
-# Note there doesn't exist a universally best chunk size and splitting method, especially for PDF files, we highly
-# encourage developers to implement or contribute their own readers according to their specific scenarios.
-# To create a custom reader, you only need to inherit the ``ReaderBase`` class and implement the ``__call__`` method.
-#
-# After chunking the documents, we can create a knowledge base to store the documents and perform retrieval.
-# Such a knowledge base is initialized by providing **an embedding model** and **an embedding store** (also known as a vector database).
-# Agentscope provides built-in support for `Qdrant <https://qdrant.tech/>`_ as the embedding store and a simple knowledge base implementation ``SimpleKnowledge``.
-# They can be used as follows:
-#
-# .. note::
-#
-# - We're integrating more vector databases into AgentScope. Contributions are welcome!
-# - The Qdrant store supports various storage backends by the ``location`` parameter, including in-memory, local file, and remote server. Refer to the `Qdrant documentation <https://qdrant.tech/>`_ for more details.
-#
-
-
-async def build_knowledge_base() -> SimpleKnowledge:
- """Build a knowledge base with sample documents."""
- # Read documents using the text reader
- documents = await example_text_reader(print_docs=False)
-
- # Create an in-memory knowledge base instance
- knowledge = SimpleKnowledge(
- # Choose an embedding model to convert text to embedding vectors
- embedding_model=DashScopeTextEmbedding(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="text-embedding-v4",
- dimensions=1024,
- ),
- # Choose Qdrant as the embedding store
- embedding_store=QdrantStore(
- location=":memory:", # Use in-memory storage for demonstration
- collection_name="test_collection",
- dimensions=1024, # The dimension of the embedding vectors
- ),
- )
-
- # Insert documents into the knowledge base
- await knowledge.add_documents(documents)
-
- # Retrieve relevant documents based on a given query
- docs = await knowledge.retrieve(
- query="Who is John Doe's father?",
- limit=3,
- score_threshold=0.5,
- )
-
- print("Retrieved Documents:")
- for doc in docs:
- print(doc, "\n")
-
- return knowledge
-
-
-knowledge = asyncio.run(build_knowledge_base())
-
-# %%
-# The knowledge base class provides two main methods: ``add_documents`` and
-# ``retrieve``, which are used to add documents to the knowledge base and
-# retrieve relevant documents based on a given query, respectively.
-#
-# In addition, the knowledge base class also provides a convenient method
-# ``retrieve_knowledge``, which wraps the ``retrieve`` method into a tool
-# function that can be directly registered in the toolkit of an agent.
-#
-#
-# Customizing RAG Components
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope supports and encourages developers to customize their own RAG components, including readers, knowledge bases and embedding stores.
-# Specifically, we provide the following base classes for customization:
-#
-# .. list-table:: RAG Base Classes
-# :header-rows: 1
-#
-# * - Base Class
-# - Description
-# - Abstract Methods
-# * - ``ReaderBase``
-# - The base class for all readers.
-# - ``__call__``
-# * - ``VDBStoreBase``
-# - The base class for embedding stores (vector databases).
-# - | ``add``
-# | ``search``
-# | ``get_client`` (optional)
-# | ``delete`` (optional)
-# * - ``KnowledgeBase``
-# - The base class for knowledge bases.
-# - | ``retrieve``
-# | ``add_documents``
-#
-#
-# The `get_client` method in the ``VDBStoreBase`` allows developers to access the full functionality of the underlying vector database.
-# So that they can implement more advanced features based on the vector database, e.g. index management, advanced search, etc.
-#
-# Integrating with ReActAgent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Next we demonstrate how to integrate the RAG module with the ``ReActAgent``
-# class in AgentScope in agentic and generic manners.
-#
-# Agentic Manner
-# --------------------------------
-# In agentic manner, the ReAct agent is empowered with the ability to decide when to retrieve knowledge and the queries to be retrieved.
-# It's very easy to integrate the RAG module with the ``ReActAgent`` class in AgentScope, just by registering the ``retrieve_knowledge`` method of the knowledge base as a tool,
-# and providing a proper description for the tool.
-
-
-async def example_agentic_manner() -> None:
- """The example of integrating RAG module with ReActAgent in agentic manner."""
- # Create a ReAct agent
- toolkit = Toolkit()
-
- # Create the ReAct agent with DashScope as the model
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday.",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen-max",
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- )
-
- print("The first response: ")
- # Ask some questions about Tony Stank
- await agent(
- Msg(
- "user",
- "John Doe is my best friend.",
- "user",
- ),
- )
-
- # Register the retrieve_knowledge method as a tool function in the toolkit
- toolkit.register_tool_function(
- knowledge.retrieve_knowledge,
- func_description=( # Provide a clear description for the tool
- "The tool used to retrieve documents relevant to the given query. "
- "Use this tool when you need to find some information about John Doe."
- ),
- )
-
- print("\n\nThe second response: ")
- # We hope the agent can rewrite the query to be more specific, e.g.
- # "Who is Tony Stank's father?" or "Tony Stank's father"
- await agent(
- Msg(
- "user",
- "Do you know who his father is?",
- "user",
- ),
- )
-
-
-asyncio.run(example_agentic_manner())
-
-# %%
-# In the above example, our question is "Do you know who his father is?".
-# We hope the agent can rewrite the query with the historical information, and
-# rewrite it to be more specific, e.g. "Who is John Doe's father?" or "John Doe's father".
-#
-#
-# Generic Manner
-# --------------------------------
-# The ``ReActAgent`` also integrates the RAG module in a generic manner, which
-# retrieves knowledge at the beginning of each reply, and attaches the
-# retrieved knowledge to the prompt in a user message.
-#
-# Just set the ``knowledge`` parameter of the ``ReActAgent``, and the agent
-# will automatically retrieve knowledge at the beginning of each reply.
-#
-
-
-async def example_generic_manner() -> None:
- """The example of integrating RAG module with ReActAgent in generic manner."""
- # Create a ReAct agent
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday.",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen-max",
- ),
- formatter=DashScopeChatFormatter(),
- #
- knowledge=knowledge,
- )
-
- await agent(
- Msg(
- "user",
- "Do you know who John Doe's father is?",
- "user",
- ),
- )
-
- print("Take a look at the agent's memory:")
- content = (await agent.memory.get_memory())[1].content
- print(json.dumps(content, indent=2, ensure_ascii=False))
-
-
-asyncio.run(example_generic_manner())
-
-
-# %%
-# Multimodal RAG
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# The RAG module in AgentScope supports multimodal RAG natively, as
-#
-# - AgentScope supports multimodal embedding API, e.g. ``DashScopeMultimodalEmbedding``.
-# - The ``Document`` class supports text, image, and other modalities in its ``metadata`` field.
-#
-# Thus, we can directly use the multimodal reader and embedding model to build
-# a multimodal knowledge base as follows.
-#
-# First we prepare an image with some text about my name.
-
-# Prepare an image with the text "John Doe's father is Michael Doe."
-path_image = "./example.jpg"
-plt.figure(figsize=(8, 3))
-plt.text(
- 0.5,
- 0.5,
- "My name is Tony Stank",
- ha="center",
- va="center",
- fontsize=30,
-)
-plt.axis("off")
-plt.savefig(path_image, bbox_inches="tight", pad_inches=0.1)
-plt.close()
-
-# %%
-# Then we can build a multimodal knowledge base with the image document.
-# The example is the same as before, just using the ``ImageReader`` and
-# ``DashScopeMultiModalEmbedding`` instead of the text counterparts.
-#
-
-
-async def example_multimodal_rag() -> None:
- """The example of using multimodal RAG."""
- # Read the image using the ImageReader
- reader = ImageReader()
- docs = await reader(image_url=path_image)
-
- # Create a knowledge base with the new image document
- knowledge = SimpleKnowledge(
- embedding_model=DashScopeMultiModalEmbedding(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="multimodal-embedding-v1",
- dimensions=1024,
- ),
- embedding_store=QdrantStore(
- location=":memory:",
- collection_name="test_collection",
- dimensions=1024,
- ),
- )
-
- await knowledge.add_documents(docs)
-
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday.",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen-vl-max",
- ),
- formatter=DashScopeChatFormatter(),
- knowledge=knowledge,
- )
-
- await agent(
- Msg(
- "user",
- "What's my name?",
- "user",
- ),
- )
-
- # Let's see the last message from the agent
- print("\nThe image is attached in the agent's memory:")
- print((await agent.memory.get_memory())[1])
-
-
-asyncio.run(example_multimodal_rag())
-
-# %%
-# We can see that the agent can answer the question based on the retrieved
-# image.
diff --git a/docs/tutorial/en/src/task_realtime.py b/docs/tutorial/en/src/task_realtime.py
deleted file mode 100644
index 9f98077d1..000000000
--- a/docs/tutorial/en/src/task_realtime.py
+++ /dev/null
@@ -1,496 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _realtime:
-
-Realtime Agent
-====================
-
-The **realtime** agent is designed to handle real-time interactions, such as
-voice conversations or live chat sessions.
-The realtime agent in AgentScope features:
-
-- Integration with OpenAI, DashScope, Gemini, and other realtime model APIs
-- Unified event interface to simplify interactions with different realtime models
-- Support for tool calling capabilities
-- Support for multi-agent interactions
-
-.. note:: The realtime agent is currently under active development. We welcome
- community contributions, discussions, and feedback! If you're interested in
- realtime agents, please join our discussion and development.
-
-"""
-
-import asyncio
-import os
-from agentscope.agent import RealtimeAgent
-from agentscope.realtime import (
- DashScopeRealtimeModel,
- OpenAIRealtimeModel,
- GeminiRealtimeModel,
-)
-
-# %%
-# Creating Realtime Models
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope currently supports the following realtime model APIs:
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 15 25 25 15 20
-#
-# * - Provider
-# - Class
-# - Supported Models
-# - Input Modalities
-# - Tool Support
-# * - DashScope
-# - ``DashScopeRealtimeModel``
-# - ``qwen3-omni-flash-realtime``
-# - Text, Audio, Image
-# - No
-# * - OpenAI
-# - ``OpenAIRealtimeModel``
-# - ``gpt-4o-realtime-preview``
-# - Text, Audio
-# - Yes
-# * - Gemini
-# - ``GeminiRealtimeModel``
-# - ``gemini-2.5-flash-native-audio-preview-09-2025``
-# - Text, Audio, Image
-# - Yes
-#
-#
-# Here are examples of initializing different realtime models:
-#
-# .. code-block:: python
-# :caption: Example of initializing different realtime models
-# # DashScope realtime model
-# dashscope_model = DashScopeRealtimeModel(
-# model_name="qwen3-omni-flash-realtime",
-# api_key=os.getenv("DASHSCOPE_API_KEY"),
-# voice="Cherry", # Options: "Cherry", "Serena", "Ethan", "Chelsie"
-# enable_input_audio_transcription=True,
-# )
-#
-# # OpenAI realtime model
-# openai_model = OpenAIRealtimeModel(
-# model_name="gpt-4o-realtime-preview",
-# api_key=os.getenv("OPENAI_API_KEY"),
-# voice="alloy", # Options: "alloy", "echo", "marin", "cedar"
-# enable_input_audio_transcription=True,
-# )
-#
-# # Gemini realtime model
-# gemini_model = GeminiRealtimeModel(
-# model_name="gemini-2.5-flash-native-audio-preview-09-2025",
-# api_key=os.getenv("GEMINI_API_KEY"),
-# voice="Puck", # Options: "Puck", "Charon", "Kore", "Fenrir"
-# enable_input_audio_transcription=True,
-# )
-#
-# The realtime model provides the following key methods:
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 30 70
-#
-# * - Method
-# - Description
-# * - ``connect(outgoing_queue, instructions, tools)``
-# - Establish WebSocket connection to the realtime model API
-# * - ``disconnect()``
-# - Close the WebSocket connection
-# * - ``send(data)``
-# - Send audio/text/image data to the realtime model for processing
-#
-# The ``outgoing_queue`` parameter in ``connect()`` is an asyncio queue used to
-# forward events from the realtime model to the outside (e.g., the agent or frontend).
-#
-#
-# Model Events Interface
-# -----------------------
-#
-# AgentScope provides a unified ``agentscope.realtime.ModelEvents`` interface to simplify
-# interactions with different realtime models. The following events are
-# supported:
-#
-# .. note:: The "session" in ModelEvents refers to the WebSocket connection
-# session between the realtime model and the model API, not the session
-# between the frontend and backend.
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 40 60
-#
-# * - Event
-# - Description
-# * - ``ModelEvents.ModelSessionCreatedEvent``
-# - Session is successfully created
-# * - ``ModelEvents.ModelSessionEndedEvent``
-# - Session has ended
-# * - ``ModelEvents.ModelResponseCreatedEvent``
-# - Model begins generating a response
-# * - ``ModelEvents.ModelResponseDoneEvent``
-# - Model finished generating a response
-# * - ``ModelEvents.ModelResponseAudioDeltaEvent``
-# - Streaming audio data chunk from the model
-# * - ``ModelEvents.ModelResponseAudioDoneEvent``
-# - Audio response is complete
-# * - ``ModelEvents.ModelResponseAudioTranscriptDeltaEvent``
-# - Streaming transcription chunk of audio response
-# * - ``ModelEvents.ModelResponseAudioTranscriptDoneEvent``
-# - Audio transcription is complete
-# * - ``ModelEvents.ModelResponseToolUseDeltaEvent``
-# - Streaming tool call parameters
-# * - ``ModelEvents.ModelResponseToolUseDoneEvent``
-# - Tool call parameters are complete
-# * - ``ModelEvents.ModelInputTranscriptionDeltaEvent``
-# - Streaming transcription chunk of user input
-# * - ``ModelEvents.ModelInputTranscriptionDoneEvent``
-# - User input transcription is complete
-# * - ``ModelEvents.ModelInputStartedEvent``
-# - Detected start of user audio input (VAD)
-# * - ``ModelEvents.ModelInputDoneEvent``
-# - Detected end of user audio input (VAD)
-# * - ``ModelEvents.ModelErrorEvent``
-# - An error occurred
-#
-#
-#
-# Creating a Realtime Agent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The ``RealtimeAgent`` serves as a bridge layer that:
-#
-# - Converts ``ModelEvents`` from realtime models into ``ServerEvents`` for
-# frontend and other agents
-# - Receives ``ClientEvents`` from frontend or other agents and forwards them
-# to the realtime model API
-# - Manages the agent's lifecycle and event queues
-#
-# Server and Client Events
-# -------------------------
-#
-# AgentScope provides unified ``ServerEvents`` and ``ClientEvents`` for
-# communication between backend and frontend:
-#
-# **ServerEvents** (Backend → Frontend):
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 40 60
-#
-# * - Event
-# - Description
-# * - ``ServerEvents.ServerSessionCreatedEvent``
-# - Session created in backend
-# * - ``ServerEvents.ServerSessionUpdatedEvent``
-# - Session updated in backend
-# * - ``ServerEvents.ServerSessionEndedEvent``
-# - Session ended in backend
-# * - ``ServerEvents.AgentReadyEvent``
-# - Agent is ready to receive inputs
-# * - ``ServerEvents.AgentEndedEvent``
-# - Agent has ended
-# * - ``ServerEvents.AgentResponseCreatedEvent``
-# - Agent starts generating response
-# * - ``ServerEvents.AgentResponseDoneEvent``
-# - Agent finished generating response
-# * - ``ServerEvents.AgentResponseAudioDeltaEvent``
-# - Streaming audio chunk from agent
-# * - ``ServerEvents.AgentResponseAudioDoneEvent``
-# - Audio response complete
-# * - ``ServerEvents.AgentResponseAudioTranscriptDeltaEvent``
-# - Streaming transcription of agent response
-# * - ``ServerEvents.AgentResponseAudioTranscriptDoneEvent``
-# - Transcription complete
-# * - ``ServerEvents.AgentResponseToolUseDeltaEvent``
-# - Streaming tool call data
-# * - ``ServerEvents.AgentResponseToolUseDoneEvent``
-# - Tool call complete
-# * - ``ServerEvents.AgentResponseToolResultEvent``
-# - Tool execution result
-# * - ``ServerEvents.AgentInputTranscriptionDeltaEvent``
-# - Streaming transcription of user input
-# * - ``ServerEvents.AgentInputTranscriptionDoneEvent``
-# - Input transcription complete
-# * - ``ServerEvents.AgentInputStartedEvent``
-# - User audio input started
-# * - ``ServerEvents.AgentInputDoneEvent``
-# - User audio input ended
-# * - ``ServerEvents.AgentErrorEvent``
-# - An error occurred
-#
-# **ClientEvents** (Frontend → Backend):
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 40 60
-#
-# * - Event
-# - Description
-# * - ``ClientEvents.ClientSessionCreateEvent``
-# - Create a new session with specified configuration
-# * - ``ClientEvents.ClientSessionEndEvent``
-# - End current session
-# * - ``ClientEvents.ClientResponseCreateEvent``
-# - Request agent to generate response immediately
-# * - ``ClientEvents.ClientResponseCancelEvent``
-# - Interrupt agent's current response
-# * - ``ClientEvents.ClientTextAppendEvent``
-# - Append text input
-# * - ``ClientEvents.ClientAudioAppendEvent``
-# - Append audio input
-# * - ``ClientEvents.ClientAudioCommitEvent``
-# - Commit audio input (signal end of input)
-# * - ``ClientEvents.ClientImageAppendEvent``
-# - Append image input
-# * - ``ClientEvents.ClientToolResultEvent``
-# - Send tool execution result
-#
-# Initializing a Realtime Agent
-# ------------------------------
-#
-# Here's how to create and use a realtime agent:
-
-
-async def example_realtime_agent() -> None:
- """Example of creating and using a realtime agent."""
- agent = RealtimeAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday.",
- model=DashScopeRealtimeModel(
- model_name="qwen3-omni-flash-realtime",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- ),
- )
-
- # Create a queue to receive messages from the agent
- outgoing_queue = asyncio.Queue()
-
- # The agent is now ready to handle inputs
- # Handle outgoing messages in a separate task
- async def handle_agent_messages():
- while True:
- event = await outgoing_queue.get()
- # Process the event (e.g., send to frontend via WebSocket)
- print(f"Agent event: {event.type}")
-
- # Start the message handling task
- asyncio.create_task(handle_agent_messages())
-
- # Start the agent (establishes connection)
- await agent.start(outgoing_queue)
-
- # Stop the agent when done
- await agent.stop()
-
-
-# %%
-# Starting Realtime Conversation
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Now we can set up a realtime conversation between a user and a realtime agent.
-#
-# Here we take FastAPI as an example backend framework to demonstrate how to set up
-# a realtime conversation.
-#
-# **Backend Setup (Server-side):**
-#
-# The backend needs to:
-#
-# 1. Create a WebSocket endpoint to accept frontend connections
-# 2. Create a ``RealtimeAgent`` when the session starts
-# 3. Forward ``ClientEvents`` from frontend to the agent
-# 4. Forward ``ServerEvents`` from agent to the frontend
-#
-# .. code-block:: python
-#
-# from fastapi import FastAPI, WebSocket
-# from agentscope.agent import RealtimeAgent
-# from agentscope.realtime import (
-# DashScopeRealtimeModel,
-# ClientEvents,
-# ServerEvents,
-# )
-#
-# app = FastAPI()
-#
-# @app.websocket("/ws/{user_id}/{session_id}")
-# async def websocket_endpoint(
-# websocket: WebSocket,
-# user_id: str,
-# session_id: str,
-# ):
-# await websocket.accept()
-#
-# # Create queue for agent messages
-# frontend_queue = asyncio.Queue()
-#
-# # Create agent
-# agent = RealtimeAgent(
-# name="Assistant",
-# sys_prompt="You are a helpful assistant.",
-# model=DashScopeRealtimeModel(
-# model_name="qwen3-omni-flash-realtime",
-# api_key=os.getenv("DASHSCOPE_API_KEY"),
-# ),
-# )
-#
-# # Start agent
-# await agent.start(frontend_queue)
-#
-# # Forward messages from agent to frontend
-# async def send_to_frontend():
-# while True:
-# msg = await frontend_queue.get()
-# await websocket.send_json(msg.model_dump())
-#
-# asyncio.create_task(send_to_frontend())
-#
-# # Receive messages from frontend and forward to agent
-# while True:
-# data = await websocket.receive_json()
-# client_event = ClientEvents.from_json(data)
-# await agent.handle_input(client_event)
-#
-# **Frontend Setup (Client-side):**
-#
-# The frontend needs to:
-#
-# 1. Establish WebSocket connection to the backend
-# 2. Send ``CLIENT_SESSION_CREATE`` event to initialize the session
-# 3. Capture audio from microphone and send via ``CLIENT_AUDIO_APPEND`` events
-# 4. Receive and handle ``ServerEvents`` (e.g., play audio, display transcripts)
-#
-# .. code-block:: javascript
-#
-# // Connect to WebSocket
-# const ws = new WebSocket('ws://localhost:8000/ws/user1/session1');
-#
-# ws.onopen = () => {
-# // Create session
-# ws.send(JSON.stringify({
-# type: 'client_session_create',
-# config: {
-# instructions: 'You are a helpful assistant.',
-# user_name: 'User1'
-# }
-# }));
-# };
-#
-# // Handle messages from backend
-# ws.onmessage = (event) => {
-# const data = JSON.parse(event.data);
-# if (data.type === 'response_audio_delta') {
-# // Play audio chunk
-# playAudio(data.delta);
-# }
-# };
-#
-# // Send audio data
-# function sendAudioChunk(audioData) {
-# ws.send(JSON.stringify({
-# type: 'client_audio_append',
-# session_id: 'session1',
-# audio: audioData, // base64 encoded
-# format: { encoding: 'pcm16', sample_rate: 16000 }
-# }));
-# }
-#
-# For a complete working example, see
-# ``examples/agent/realtime_voice_agent/`` in the AgentScope repository.
-
-# %%
-# Multi-Agent Realtime Conversation
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope supports multi-agent realtime interactions through the ``ChatRoom``
-# class.
-#
-# Note currently most realtime model APIs only support single-user interactions,
-# but AgentScope's architecture is designed to support multiple agents and users
-# when API capabilities expand.
-#
-# The Realtime ChatRoom
-# ----------------------------
-#
-# AgentScope introduces the ``ChatRoom`` class to manage multiple realtime
-# agents in a shared conversation space. The ChatRoom provides:
-#
-# - Centralized management of multiple ``RealtimeAgent`` instances
-# - Automatic message broadcasting between agents
-# - Unified message queue for frontend communication
-# - Lifecycle management for all agents in the room
-#
-# Using ChatRoom
-# --------------
-#
-# The usage of ``ChatRoom`` is similar to ``RealtimeAgent``:
-#
-
-
-async def example_chat_room() -> None:
- """Example of using ChatRoom with multiple realtime agents."""
- from agentscope.pipeline import ChatRoom
- from agentscope.agent import RealtimeAgent
- from agentscope.realtime import DashScopeRealtimeModel
-
- # Create multiple agents
- agent1 = RealtimeAgent(
- name="Agent1",
- sys_prompt="You are Agent1, a helpful assistant.",
- model=DashScopeRealtimeModel(
- model_name="qwen3-omni-flash-realtime",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- ),
- )
-
- agent2 = RealtimeAgent(
- name="Agent2",
- sys_prompt="You are Agent2, a helpful assistant.",
- model=DashScopeRealtimeModel(
- model_name="qwen3-omni-flash-realtime",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- ),
- )
-
- # Create a chat room with multiple agents
- chat_room = ChatRoom(agents=[agent1, agent2])
-
- # Create queue to receive messages from all agents
- outgoing_queue = asyncio.Queue()
-
- # Start the chat room
- await chat_room.start(outgoing_queue)
-
- # Handle input from frontend
- # The chat room will broadcast to all agents
- from agentscope.realtime import ClientEvents
-
- client_event = ClientEvents.ClientTextAppendEvent(
- session_id="session1",
- text="Hello everyone!",
- )
- await chat_room.handle_input(client_event)
-
- # Stop the chat room when done
- await chat_room.stop()
-
-
-# %%
-# Roadmap
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The realtime agent feature is currently experimental and under active
-# development. The future plans include:
-#
-# - Support for more realtime model APIs
-# - Enhanced memory management for conversation history
-# - Comprehensive tool calling support across all providers
-# - Multi-user voice interaction support
-# - Improved VAD (Voice Activity Detection) configuration
-# - Better error handling and recovery mechanisms
-#
-# We welcome contributions and feedback from the community to help shape the
-# future of realtime agents in AgentScope!
diff --git a/docs/tutorial/en/src/task_state.py b/docs/tutorial/en/src/task_state.py
deleted file mode 100644
index 3b54fadbf..000000000
--- a/docs/tutorial/en/src/task_state.py
+++ /dev/null
@@ -1,216 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _state:
-
-State/Session Management
-=================================
-
-In AgentScope, the **"state"** refers to the agent status in the running application, including its current system prompt, memory, context, equipped tools, and other information that **change over time**.
-
-To manage the state of an application, AgentScope designs an automatic state registration system and session-level state management, which features:
-
-- Support **automatic state registration** for all variables inherited from ``StateModule``
-- Support **manual state registration** with custom serialization/deserialization methods
-- Support **session/application-level management**
-"""
-import asyncio
-import json
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.module import StateModule
-from agentscope.session import JSONSession
-from agentscope.tool import Toolkit
-
-# %%
-# State Module
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# The ``StateModule`` class is the foundation for state management in AgentScope and provides three basic functions:
-#
-# .. list-table:: Methods of ``StateModule``
-# :header-rows: 1
-#
-# * - Method
-# - Arguments
-# - Description
-# * - ``register_state``
-# - | ``attr_name``,
-# | ``custom_to_json`` (optional),
-# | ``custom_from_json`` (optional)
-# - Register an attribute as its state, with optional serialization/deserialization function.
-# * - ``state_dict``
-# - \-
-# - Get the state dictionary of current object
-# * - ``load_state_dict``
-# - | ``state_dict``,
-# | ``strict`` (optional)
-# - Load the state dictionary to current object
-#
-# Within an object of ``StateModule``, all the following attributes will be treated as parts of its state:
-#
-# - the **attributes** that inherit from ``StateModule``
-# - the **attributes** registered by the ``register_state`` method
-#
-# Note the ``StateModule`` supports **NESTED** serialization and deserialization:
-#
-
-
-class ClassA(StateModule):
- def __init__(self) -> None:
- super().__init__()
- self.cnt = 123
- # register cnt attribute as state
- self.register_state("cnt")
-
-
-class ClassB(StateModule):
- def __init__(self) -> None:
- super().__init__()
-
- # attribute "a" inherits from StateModule
- self.a = ClassA()
-
- # register attribute "c" as state manually
- self.c = "Hello, world!"
- self.register_state("c")
-
-
-obj_b = ClassB()
-
-print("State of obj_b.a:")
-print(obj_b.a.state_dict())
-
-print("\nState of obj_b:")
-print(json.dumps(obj_b.state_dict(), indent=4))
-
-# %%
-# We can observe the state of ``obj_b`` contains the state of its attribute ``a`` automatically.
-#
-# In AgentScope, the ``AgentBase``, ``MemoryBase``, ``LongTermMemoryBase`` and ``Toolkit`` classes all inherit from ``StateModule``, thus supporting automatic and nested state management.
-#
-
-# Creating an agent
-agent = ReActAgent(
- name="Friday",
- sys_prompt="You're a assistant named Friday.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
- memory=InMemoryMemory(),
- toolkit=Toolkit(),
-)
-
-initial_state = agent.state_dict()
-
-print("Initial state of the agent:")
-print(json.dumps(initial_state, indent=4))
-
-# %%
-# Then we change its state by generating a reply message:
-#
-
-
-async def example_agent_state() -> None:
- """Example of agent state management"""
- await agent(Msg("user", "Hello, agent!", "user"))
-
- print("State of the agent after generating a reply:")
- print(json.dumps(agent.state_dict(), indent=4))
-
-
-asyncio.run(example_agent_state())
-
-# %%
-# Now we recover the state of the agent to its initial state:
-#
-
-agent.load_state_dict(initial_state)
-
-print("State after loading the initial state:")
-print(json.dumps(agent.state_dict(), indent=4))
-
-# %%
-# Session Management
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# In AgentScope, a session refers to a collection of ``StateModule`` in an application, e.g. multiple agents.
-#
-# AgentScope provides a ``SessionBase`` class with two abstract methods for session
-# management: ``save_session_state`` and ``load_session_state``.
-# Developers can implement these methods with their own storage solution.
-#
-# In AgentScope, we provide a JSON based session class ``JSONSession`` that
-# stores/loads the session state in/from a JSON file named with the session ID.
-#
-# Here we show how to use the JSON based session management in AgentScope.
-#
-# Saving Session State
-# -----------------------------------------
-#
-
-# change the agent state by generating a reply message
-asyncio.run(example_agent_state())
-
-print("\nState of agent:")
-print(json.dumps(agent.state_dict(), indent=4))
-
-# %%
-# Then we save it to a session file:
-
-
-session = JSONSession(
- save_dir="./", # The dir used to save the session files
-)
-
-
-async def example_session() -> None:
- """Example of session management."""
- await session.save_session_state(
- session_id="user_1", # Use the name as the session id
- agent=agent,
- )
-
- print("The saved state:")
- with open("./user_1.json", "r", encoding="utf-8") as f:
- print(json.dumps(json.load(f), indent=4))
-
-
-asyncio.run(example_session())
-
-# %%
-# Loading Session State
-# -----------------------------------------
-# Now we load the session state from the saved file:
-
-
-async def example_load_session() -> None:
- """Example of loading session state."""
-
- # we first clear the memory of the agent
- await agent.memory.clear()
-
- print("Current state of the agent:")
- print(json.dumps(agent.state_dict(), indent=4))
-
- # then we load the session state
- await session.load_session_state(
- session_id="user_1",
- # The keyword argument must be the same as the one used in `save_session_state`
- agent=agent,
- )
- print("After loading the session state:")
- print(json.dumps(agent.state_dict(), indent=4))
-
-
-asyncio.run(example_load_session())
-
-# %%
-# Now we can see the agent state is restored to the saved state.
-#
diff --git a/docs/tutorial/en/src/task_studio.py b/docs/tutorial/en/src/task_studio.py
deleted file mode 100644
index ee90c0e15..000000000
--- a/docs/tutorial/en/src/task_studio.py
+++ /dev/null
@@ -1,118 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _studio:
-
-AgentScope Studio
-=========================
-
-AgentScope Studio is a local-deployed web application that
-
-- provides **project management** for the development of agent applications
-- provides native **visualization** for running applications and tracing
-- provides a **built-in agent** named "Friday" that supports secondary development
-
-.. note:: The Studio is under fast development, more features are coming soon!
-
-.. figure:: ../../_static/images/studio_home.webp
- :width: 100%
- :alt: AgentScope Studio Home Page
- :class: bordered-image
- :align: center
-
- AgentScope Studio Home Page
-
-Quick Start
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-AgentScope Studio is installed via ``npm``:
-
-.. code-block:: bash
-
- npm install -g @agentscope/studio
-
-
-Start the Studio with the following command:
-
-.. code-block:: bash
-
- as_studio
-
-To connect your application to the Studio, use the ``agentscope.init`` function with the ``studio_url`` parameter:
-
-.. code-block:: python
-
- import agentscope
-
- agentscope.init(studio_url="http://localhost:3000")
-
- # your application code
- ...
-
-Then, you can see your application in the Studio as follows:
-
-.. figure:: ../../_static/images/studio_project.webp
- :width: 100%
- :alt: Project management
- :class: bordered-image
- :align: center
-
- Project management in AgentScope Studio
-
-The details about your running application, e.g. token usage, model invocations, and tracing information, can all be viewed in the Studio.
-
-.. figure:: ../../_static/images/studio_run.webp
- :width: 100%
- :alt: AgentScope Studio run Page
- :class: bordered-image
- :align: center
-
- Application visualization in AgentScope Studio
-
-
-Friday Agent
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Friday is an experimental local-deployed agent built by AgentScope, aims at
-
-- answering questions about the AgentScope,
-- providing a quick secondary development environment for developers,
-- integrating all available features in AgentScope to build a more powerful agent, and
-- testing and integrating the advanced features in AgentScope.
-
-.. note:: We highly greet contributions from the community to improve Friday! Feel free to open issues or pull requests on our `GitHub repository <https://github.com/agentscope-ai/agentscope>`_.
-
-We are keeping improving Friday, and currently it integrates the following features in AgentScope:
-
-.. list-table::
- :header-rows: 1
-
- * - Feature
- - Status
- - Further Reading
- - Description
- * - Meta tool
- - ✅
- - :ref:`tool`
- - Group-wise tool management, and allow agent to change equipped tools by itself.
- * - Agent Hook
- - ✅
- - :ref:`hook`
- - Use hook to forward the printing messages to the frontend.
- * - Agent Interruption
- - ✅
- - :ref:`agent`
- - Allow use to interrupt the agent's reply process with post-processing.
- * - Truncated Prompt
- - ✅
- - :ref:`prompt`
- - Support to truncate the prompt with the preset max token limit.
- * - State & Session Management
- - ✅
- - :ref:`state`
- - Auto state management and session management for agents, maintaining the state between different runs.
- * - Long-term Memory
- - 🚧
- - :ref:`memory`
- - Support long-term memory management.
-
-
-"""
diff --git a/docs/tutorial/en/src/task_token.py b/docs/tutorial/en/src/task_token.py
deleted file mode 100644
index 3c2c3f458..000000000
--- a/docs/tutorial/en/src/task_token.py
+++ /dev/null
@@ -1,71 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _token:
-
-Token
-=========================
-
-AgentScope provides a token counter module under ``agentscope.token`` to
-calculate the number of tokens in the given messages, allowing developers
-to estimate the number of tokens in a prompt before sending it to an API.
-
-Specifically, the following token counters are available:
-
-.. list-table::
- :header-rows: 1
-
- * - Provider
- - Class
- - Support Image Data
- - Support Tools
- * - Anthropic
- - ``AnthropicTokenCounter``
- - ✅
- - ✅
- * - OpenAI
- - ``OpenAITokenCounter``
- - ✅
- - ✅
- * - Gemini
- - ``GeminiTokenCounter``
- - ✅
- - ✅
- * - HuggingFace
- - ``HuggingFaceTokenCounter``
- - Depends on the model
- - Depends on the model
-
-.. tip:: The formatter module has integrated the token counters to support prompt truncation. Refer to the :ref:`prompt` section for more details.
-
-.. note:: For DashScope models, the dashscope library doesn't provide a token counting API. So we recommend using the HuggingFace token counter instead.
-
-We show an example of using the OpenAI token counter to count the number of tokens:
-"""
-
-import asyncio
-from agentscope.token import OpenAITokenCounter
-
-
-async def example_token_counting():
- # Example messages
- messages = [
- {"role": "user", "content": "Hello!"},
- {"role": "assistant", "content": "Hi, how can I help you?"},
- ]
-
- # OpenAI token counting
- openai_counter = OpenAITokenCounter(model_name="gpt-4.1")
- n_tokens = await openai_counter.count(messages)
-
- print(f"Number of tokens: {n_tokens}")
-
-
-asyncio.run(example_token_counting())
-
-
-# %%
-# Further Reading
-# ------------------------------
-#
-# - :ref:`prompt`
-#
diff --git a/docs/tutorial/en/src/task_tool.py b/docs/tutorial/en/src/task_tool.py
deleted file mode 100644
index aca7b5073..000000000
--- a/docs/tutorial/en/src/task_tool.py
+++ /dev/null
@@ -1,453 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tool:
-
-Tool
-=========================
-
-To ensure accurate and reliable tool parsing, AgentScope fully embraces the use of tools API with the following features:
-
-- Support **automatic** tool parsing from Python functions with their docstrings
-- Support both **synchronous and asynchronous** tool functions
-- Support **streaming** tool responses (either synchronous or asynchronous generators)
-- Support **dynamic extension** to the tool JSON Schema
-- Support **interrupting** the tool execution with proper signal handling
-- Support **autonomous tool management** by agents
-
-All above features are implemented by the ``Toolkit`` class in AgentScope, which is responsible for managing tool functions and their execution.
-
-.. tip:: The support of MCP (Model Context Protocol) refers to the :ref:`mcp` section.
-"""
-import asyncio
-import inspect
-import json
-from typing import Any, AsyncGenerator
-
-from pydantic import BaseModel, Field
-
-import agentscope
-from agentscope.message import TextBlock, ToolUseBlock
-from agentscope.tool import ToolResponse, Toolkit, execute_python_code
-
-
-# %%
-# Tool Function
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# In AgentScope, a tool function is a Python function that
-#
-# - returns a ``ToolResponse`` object or a generator that yields ``ToolResponse`` objects
-# - has a docstring that describes the tool's functionality and parameters
-#
-# A template of a tool function is as follows:
-
-
-def tool_function(a: int, b: str) -> ToolResponse:
- """{function description}
-
- Args:
- a (int):
- {description of the first parameter}
- b (str):
- {description of the second parameter}
- """
-
-
-# %%
-# .. tip:: Instance method and class method can also be used as tool functions, and the ``self`` and ``cls`` parameters will be ignored.
-#
-# AgentScope provides several built-in tool functions under the ``agentscope.tool`` module, such as ``execute_python_code``, ``execute_shell_command`` and text file write/read functions.
-#
-
-print("Built-in Tool Functions:")
-for _ in agentscope.tool.__all__:
- if _ not in ["Toolkit", "ToolResponse"]:
- print(_)
-
-# %%
-# Toolkit
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# The ``Toolkit`` class is designed to manage tool functions, extracting their JSON Schema from docstrings and providing a unified interface for tool execution.
-#
-# Basic Usage
-# ------------------------------
-# The basic functionality of the ``Toolkit`` class is to register tool functions and execute them.
-#
-
-
-# Prepare a custom tool function
-async def my_search(query: str, api_key: str) -> ToolResponse:
- """A simple example tool function.
-
- Args:
- query (str):
- The search query.
- api_key (str):
- The API key for authentication.
- """
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"Searching for '{query}' with API key '{api_key}'",
- ),
- ],
- )
-
-
-# Register the tool function in a toolkit
-toolkit = Toolkit()
-toolkit.register_tool_function(my_search)
-
-# %%
-# When registering a tool function, you can get its JSON Schema by calling the ``get_json_schemas`` method.
-#
-
-print("Tool JSON Schemas:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# ``Toolkit`` also allows developers to preset the arguments for tool functions, especially useful for API keys or other sensitive information.
-#
-
-# Clear the toolkit first
-toolkit.clear()
-
-# Register tool function with preset keyword arguments
-toolkit.register_tool_function(my_search, preset_kwargs={"api_key": "xxx"})
-
-print("Tool JSON Schemas with Preset Arguments:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# In ``Toolkit``, the ``call_tool_function`` method takes a tool use block as input and executes the corresponding tool function, returning **a unified asynchronous generator** that yields ``ToolResponse`` objects.
-#
-
-
-async def example_tool_execution() -> None:
- """Example of executing a tool call."""
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="123",
- name="my_search",
- input={"query": "AgentScope"},
- ),
- )
-
- # Only one tool response is expected in this case
- print("Tool Response:")
- async for tool_response in res:
- print(tool_response)
-
-
-asyncio.run(example_tool_execution())
-
-# %%
-# Extending JSON Schema Dynamically
-# --------------------------------------
-#
-# Toolkit allows to extend the JSON schemas of tool functions dynamically by calling the ``set_extended_model`` method.
-# Such feature allows to add more parameters to the tool function without modifying its original definition.
-#
-# .. tip:: Related scenarios include dynamic :ref:`structured-output` and CoT (Chain of Thought) reasoning
-#
-# .. note:: The function to be extended should accept variable keyword arguments (``**kwargs``), so that the additional fields can be passed to it.
-#
-# Taking the CoT reasoning as an example, we can extend all tool functions with a ``thinking`` field, allowing the agent to summarize the current state and then decide what to do next.
-#
-
-
-# Example tool function
-def tool_function(**kwargs: Any) -> ToolResponse:
- """A tool function"""
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"Received parameters: {kwargs}",
- ),
- ],
- )
-
-
-# Add a thinking field so that the agent could think before giving the other parameters.
-class ThinkingModel(BaseModel):
- """A Pydantic model for additional fields."""
-
- thinking: str = Field(
- description="Summarize the current state and decide what to do next.",
- )
-
-
-# Register
-toolkit.set_extended_model("my_search", ThinkingModel)
-
-print("The extended JSON Schema:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# Interrupting Tool Execution
-# ------------------------------
-# The ``Toolkit`` class supports **execution interruption** of **async tool functions** and provides a comprehensive **agent-oriented post-processing mechanism**.
-# Such interruption is implemented based on the asyncio cancellation mechanism, and the post-processing varies depending on the return type of tool function.
-#
-# .. note:: For synchronous tool functions, their execution cannot be interrupted by asyncio cancellation. So the interruption is handled within the agent rather than the toolkit.
-# Refer to the :ref:`agent` section for more information.
-#
-# Specifically, if the tool function returns a ``ToolResponse`` object, a predefined ``ToolResponse`` object with an interrupted message will be yielded.
-# So that the agent can observe the interruption and handle it accordingly.
-# Besides, a flag ``is_interrupted`` will be set to ``True`` in the response, and the external caller can decide whether to throw the ``CancelledError`` exception to the outer layer.
-#
-# An example of async tool function that can be interrupted is as follows:
-#
-
-
-async def non_streaming_function() -> ToolResponse:
- """A non-streaming tool function that can be interrupted."""
- await asyncio.sleep(1) # Simulate a long-running task
-
- # Fake interruption for demonstration
- raise asyncio.CancelledError()
-
- # The following code won't be executed due to the cancellation
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text="Run successfully!",
- ),
- ],
- )
-
-
-async def example_tool_interruption() -> None:
- """Example of tool interruption."""
- toolkit = Toolkit()
- toolkit.register_tool_function(non_streaming_function)
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="123",
- name="non_streaming_function",
- input={},
- ),
- )
-
- async for tool_response in res:
- print("Tool Response:")
- print(tool_response)
- print("The interrupted flag:")
- print(tool_response.is_interrupted)
-
-
-asyncio.run(example_tool_interruption())
-
-# %%
-# For streaming tool functions, which returns an asynchronous generator, the ``Toolkit`` will attach the interrupted message to the previous chunk of the response.
-# By this way, the agent can observe what the tool has returned before the interruption.
-#
-# The example of interrupting a streaming tool function is as follows:
-#
-
-
-async def streaming_function() -> AsyncGenerator[ToolResponse, None]:
- """A streaming tool function that can be interrupted."""
- # Simulate a chunk of response
- yield ToolResponse(
- content=[
- TextBlock(
- type="text",
- text="1234",
- ),
- ],
- stream=True,
- )
-
- # Simulate interruption
- raise asyncio.CancelledError()
-
- # The following code won't be executed due to the cancellation
- yield ToolResponse(
- content=[
- TextBlock(
- type="text",
- text="123456789",
- ),
- ],
- )
-
-
-async def example_streaming_tool_interruption() -> None:
- """Example of streaming tool interruption."""
- toolkit = Toolkit()
- toolkit.register_tool_function(streaming_function)
-
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="xxx",
- name="streaming_function",
- input={},
- ),
- )
-
- i = 0
- async for tool_response in res:
- print(f"Chunk {i}:")
- print(tool_response)
- print("The interrupted flag: ", tool_response.is_interrupted, "\n")
- i += 1
-
-
-asyncio.run(example_streaming_tool_interruption())
-
-# %%
-# Automatic Tool Management
-# -------------------------------------
-# .. image:: https://img.alicdn.com/imgextra/i3/O1CN013cvRpO27MfesMsTeh_!!6000000007783-2-tps-840-521.png
-# :width: 100%
-# :align: center
-# :alt: Automatic Tool Management
-#
-#
-# The ``Toolkit`` class supports **automatic tool management** by introducing the concept of **tool group**, as well as a **meta tool function** named ``reset_equipped_tools``.
-#
-# The tool group is a set of related tool functions, e.g. browser-use tools, map services tools, etc., which will be managed together.
-# Only the tools in the activated groups will be visible to agents, i.e. accessible by the ``toolkit.get_json_schemas()`` method.
-#
-# Note there is a special group called ``basic``, which is always activated and the tools registered without specifying the group name will be added to this group by default.
-#
-# .. tip:: The ``basic`` group ensures that the basic usage of tools won't be affected by the group features if you don't need them.
-#
-# Now we try to create a tool group named ``browser_use``, which contains some web browsing tools.
-#
-
-
-def navigate(url: str) -> ToolResponse:
- """Navigate to a web page.
-
- Args:
- url (str):
- The URL of the web page to navigate to.
- """
- pass
-
-
-def click_element(element_id: str) -> ToolResponse:
- """Click an element on the web page.
-
- Args:
- element_id (str):
- The ID of the element to click.
- """
- pass
-
-
-toolkit = Toolkit()
-
-# Create a tool group named browser_use
-toolkit.create_tool_group(
- group_name="browser_use",
- description="The tool functions for web browsing.",
- active=False,
- # The notes when using these tools
- notes="""1. Use ``navigate`` to open a web page.
-2. When requiring user authentication, ask the user for the credentials
-3. ...""",
-)
-
-toolkit.register_tool_function(navigate, group_name="browser_use")
-toolkit.register_tool_function(click_element, group_name="browser_use")
-
-# We can also register some basic tools
-toolkit.register_tool_function(execute_python_code)
-
-# %%
-# If we check the tools JSON schema, we can only see the ``execute_python_code`` tool, because the ``browser_use`` group is not activated yet:
-
-print("Tool JSON Schemas with Group:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# Use the ``update_tool_groups`` method to activate or deactivate tool groups:
-
-toolkit.update_tool_groups(group_names=["browser_use"], active=True)
-
-print("Tool JSON Schemas with Group:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# Additionally, ``Toolkit`` provides a meta tool function named ``reset_equipped_tools``, taking the current group names as the argument to indicate which groups to activate:
-#
-# .. note:: In ``ReActAgent`` class, you can enable the meta tool function by setting ``enable_meta_tool=True`` in the constructor.
-#
-
-# Register the meta tool function
-toolkit.register_tool_function(toolkit.reset_equipped_tools)
-
-reset_equipped = next(
- tool
- for tool in toolkit.get_json_schemas()
- if tool["function"]["name"] == "reset_equipped_tools"
-)
-print("JSON schema of the ``reset_equipped_tools`` function:")
-print(
- json.dumps(
- reset_equipped,
- indent=4,
- ensure_ascii=False,
- ),
-)
-
-# %%
-# When agent calls the ``reset_equipped_tools`` function, the corresponding tool groups will be activated, and the tool response will
-# contain the notes of the activated tool groups.
-#
-
-
-async def mock_agent_reset_tools() -> None:
- """Mock agent to reset tool groups."""
- # Call the meta tool function
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="154",
- name="reset_equipped_tools",
- input={
- "browser_user": True,
- },
- ),
- )
-
- async for tool_response in res:
- print("Text content in tool Response:")
- print(tool_response)
-
-
-asyncio.run(mock_agent_reset_tools())
-
-# %%
-# The toolkit also provides a method to gather the notes of the activated tool groups, and you can assemble it into your agent's system prompt.
-#
-# .. tip:: The automatic tool management feature is already implemented in the ``ReActAgent`` class, refer to the :ref:`agent` section for more details.
-#
-
-# Create one more tool group
-toolkit.create_tool_group(
- group_name="map_service",
- description="The google map service tools.",
- active=True,
- notes="""1. Use ``get_location`` to get the location of a place.
-2. ...""",
-)
-
-print("The gathered notes of the activated tool groups:")
-print(toolkit.get_activated_notes())
-
-# %%
-# Further Reading
-# ---------------------
-# - :ref:`agent`
-# - :ref:`state`
-# - :ref:`mcp`
-#
diff --git a/docs/tutorial/en/src/task_tracing.py b/docs/tutorial/en/src/task_tracing.py
deleted file mode 100644
index 7ce9d2a05..000000000
--- a/docs/tutorial/en/src/task_tracing.py
+++ /dev/null
@@ -1,221 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tracing:
-
-Tracing
-==============================
-
-AgentScope implements OpenTelemetry-based tracing to monitor and debug the
-execution of agent applications, which features
-
-- Provide built-in tracing for LLM, tool, agent, formatter, etc.
-- Support error and exception tracking
-- Provide native tracing **visualization** in AgentScope Studio
-- Support connecting to **third-party platforms** like Alibaba Cloud CloudMonitor, `Arize-Phoenix <https://github.com/Arize-ai/phoenix>`_, `Langfuse <https://langfuse.com/>`_, etc.
-
-Setting Up
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. note:: Connecting to the :ref:`studio` or third-party tracing endpoint should be done at the beginning of your application by the ``agentscope.init`` function.
-
-AgentScope Studio
----------------------------------------
-
-.. figure:: ../../_static/images/studio_tracing.webp
- :width: 100%
- :alt: AgentScope Studio tracing Page
- :class: bordered-image
- :align: center
-
- *Tracing in AgentScope Studio*
-
-When connecting to AgentScope Studio, just provide ``studio_url`` parameter in ``agentscope.init`` function.
-
-.. code-block:: python
-
- import agentscope
-
- agentscope.init(studio_url="http://xxx:port")
-
-
-Third-party Platforms
----------------------------------------
-
-To connect to third-party tracing platforms, set the ``tracing_url`` parameter in the ``agentscope.init`` function.
-The ``tracing_url`` is the URL of your OpenTelemetry collector or any compatible backend that supports OTLP (OpenTelemetry Protocol).
-
-.. code-block:: python
-
- import agentscope
-
- # Connect to OpenTelemetry-compatible backends
- agentscope.init(tracing_url="https://your-tracing-backend:port/traces")
-
-Taking Alibaba Cloud CloudMonitor, Arize-Phoenix, and Langfuse as examples:
-
-**Alibaba Cloud CloudMonitor**: A fully-managed observability platform.
-
-.. code-block:: python
- :caption: Connect to Alibaba Cloud CloudMonitor
-
- agentscope.init(tracing_url="https://tracing-cn-hangzhou.arms.aliyuncs.com/adapt_xxx/api/otlp/traces")
-
-.. tip::
- **Get your Endpoint:** In the `ARMS Console <https://arms.console.aliyun.com/>`_ under **Access Center** > **OpenTelemetry**,
- select the **Public Endpoint** matching your deployment region. Customize your app name via the ``OTEL_SERVICE_NAME`` environment variable.
- Alibaba Cloud CloudMonitor provides zero-code instrumentation through `LoongSuite <https://github.com/alibaba/loongsuite-python-agent>`_ agent.
- Learn more in the `CloudMonitor Documentation <https://www.alibabacloud.com/help/en/cms/cloudmonitor-2-0/user-guide/model-application>`_.
-
-**Arize-Phoenix**: You need to set the ``PHOENIX_API_KEY`` in your environment variables.
-
-.. code-block:: python
- :caption: Connect to Arize Phoenix
-
- # Arize Phoenix Integration
- import os
-
- PHOENIX_API_KEY = os.environ.get("PHOENIX_API_KEY")
- os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
-
- agentscope.init(tracing_url="https://app.phoenix.arize.com/v1/traces")
-
-**LangFuse**: You need to set the ``LANGFUSE_PUBLIC_KEY`` and
-``LANGFUSE_SECRET_KEY`` in your environment variables. The authorization
-header is constructed using these keys.
-
-.. code-block:: python
- :caption: Connect to LangFuse
-
- import os, base64
-
- LANGFUSE_PUBLIC_KEY = os.environ["LANGFUSE_PUBLIC_KEY"]
- LANGFUSE_SECRET_KEY = os.environ["LANGFUSE_SECRET_KEY"]
- LANGFUSE_AUTH_STRING = f"{LANGFUSE_PUBLIC_KEY}:{LANGFUSE_SECRET_KEY}"
-
- LANGFUSE_AUTH = base64.b64encode(LANGFUSE_AUTH_STRING.encode("utf-8")).decode("ascii")
- os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
-
- # EU data region
- agentscope.init(tracing_url="https://cloud.langfuse.com/api/public/otel/v1/traces")
- # US data region
- # agentscope.init(tracing_url="https://us.cloud.langfuse.com/api/public/otel/v1/traces")
-
-
-Customizing Tracing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-As stated above, the tracing in AgentScope is implemented based on OpenTelemetry.
-That means your own tracing code implemented by OpenTelemetry sdk is compatible with
-AgentScope natively.
-
-Besides, AgentScope has built-in the following decorators to trace the corresponding modules:
-
-- ``@trace_llm``: Trace the ``__call__`` function of classes inherit from ``ChatModelBase``
-- ``@trace_reply``: Trace the ``reply`` function of classes inherit from ``AgentBase``
-- ``@trace_format``: Trace the ``format`` function of classes inherit from ``FormatterBase``
-- ``@trace``: Trace general functions
-
-
-Tracing LLMs
-----------------------------------------
-
-
-The ``@trace_llm`` decorator is to trace the ``__call__`` function of ``ChatModelBase`` classes.
-
-.. note:: Your LLM class must inherit from ``ChatModelBase``
-
-.. code-block:: python
- :caption: Tracing new ChatModel class
-
- class ExampleChatModel(ChatModelBase):
- \"\"\"An example Model\"\"\"
-
- ...
-
- @trace_llm
- async def __call__(
- self,
- *args: Any,
- **kwargs: Any,
- ) -> AsyncGenerator[ChatResponse, None] | ChatResponse:
- \"\"\"LLM call\"\"\"
- ...
-
-
-Tracing Agent
-----------------------------------------
-
-The ``@trace_reply`` decorator is for agent implementations and tracing the `reply` function.
-
-.. note:: Your agent class must inherit from ``AgentBase``
-
-.. code-block:: python
- :caption: Tracing new Agent class
-
- class ExampleAgent(AgentBase):
- \"\"\"An example agent class\"\"\"
-
- @tracer_reply
- async def reply(self, *args: Any, **kwargs: Any) -> Msg:
- \"\"\"Reply to the message.\"\"\"
- ...
-
-
-Tracing Formatter
-----------------------------------------
-The ``@trace_format`` decorator is for formatters implementations and tracing the `format` function.
-
-.. note:: Your formatter class must inherit from ``FormatterBase``
-
-.. code-block:: python
- :caption: Tracing new Formatter class
-
- class ExampleFormatter(FormatterBase):
- \"\"\"A simple example formatter class\"\"\"
-
- @trace_format
- async def format(self, *args: Any, **kwargs: Any) -> list[dict]:
- \"\"\"Example formatting\"\"\"
-
-
-General Tracing
-----------------------------------------
-
-The ``@trace`` decorator is different from the above decorators, as it is a general-purpose tracing decorator that can be applied to any function.
-It requires a `name` parameter to identify the traced function, and can trace various types of functions, including:
-
-- synchronous functions
-- synchronous generator functions
-- asynchronous functions
-- asynchronous generator functions
-
-.. code-block:: python
- :caption: General tracing example
-
- # 1. Synchronous function
- @trace(name='simple_function')
- def simple_function(name: str, age: int) -> str:
- \"\"\"A simple function with automatic tracing.\"\"\"
- return f"Hello, {name}! You are {age} years old."
-
- # 2. Synchronous generator function
- @trace(name='number_generator')
- def number_generator(n: int) -> Generator[int, None, None]:
- \"\"\"Generate numbers from 0 to n-1.\"\"\"
- for i in range(n):
- yield i
-
- # 3. Asynchronous function
- @trace(name='async_function')
- async def async_function(data: dict) -> dict:
- \"\"\"Process data asynchronously.\"\"\"
- return {"processed": data}
-
- # 4. Asynchronous generator function
- @trace(name='async_stream')
- async def async_stream(n: int) -> AsyncGenerator[str, None]:
- \"\"\"Generate stream of data asynchronously.\"\"\"
- for i in range(n):
- yield f"data_{i}"
-
-"""
diff --git a/docs/tutorial/en/src/task_tts.py b/docs/tutorial/en/src/task_tts.py
deleted file mode 100644
index 4d0e18f51..000000000
--- a/docs/tutorial/en/src/task_tts.py
+++ /dev/null
@@ -1,255 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tts:
-
-TTS
-====================
-
-AgentScope provides a unified interface for Text-to-Speech (TTS) models across multiple API providers.
-This tutorial demonstrates how to use TTS models in AgentScope.
-
-AgentScope supports the following TTS APIs:
-
-.. list-table:: Built-in TTS Models
- :header-rows: 1
-
- * - API
- - Class
- - Streaming Input
- - Non-Streaming Input
- - Streaming Output
- - Non-Streaming Output
- * - DashScope Realtime API
- - ``DashScopeRealtimeTTSModel``
- - ✅
- - ✅
- - ✅
- - ✅
- * - DashScope CosyVoice Realtime API
- - ``DashScopeCosyVoiceRealtimeTTSModel``
- - ✅
- - ✅
- - ✅
- - ✅
- * - DashScope API
- - ``DashScopeTTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
- * - DashScope CosyVoice API
- - ``DashScopeCosyVoiceTTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
- * - OpenAI API
- - ``OpenAITTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
- * - Gemini API
- - ``GeminiTTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
-
-.. note:: The streaming input and output in AgentScope TTS models are all accumulative.
-
-**Choosing the Right Model:**
-
-- **Use Non-Realtime TTS** when you have complete text ready (e.g., pre-written
- responses, complete LLM outputs)
-- **Use Realtime TTS** when text is generated progressively (e.g., streaming
- LLM responses) for lower latency
-
-"""
-
-import asyncio
-import os
-
-from agentscope.agent import ReActAgent, UserAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tts import (
- DashScopeRealtimeTTSModel,
- DashScopeTTSModel,
-)
-
-# %%
-# Non-Realtime TTS
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Non-realtime TTS models process complete text inputs and are the simplest
-# to use. You can directly call their ``synthesize()`` method.
-#
-# Taking DashScope TTS model as an example:
-
-
-async def example_non_realtime_tts() -> None:
- """A basic example of using non-realtime TTS models."""
- # Example with DashScope TTS
- tts_model = DashScopeTTSModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
- model_name="qwen3-tts-flash",
- voice="Cherry",
- stream=False, # Non-streaming output
- )
-
- msg = Msg(
- name="assistant",
- content="Hello, this is DashScope TTS.",
- role="assistant",
- )
-
- # Directly synthesize without connecting
- tts_response = await tts_model.synthesize(msg)
-
- # tts_response.content contains an audio block with base64-encoded audio data
- print(
- "The length of audio data:",
- len(tts_response.content["source"]["data"]),
- )
-
-
-asyncio.run(example_non_realtime_tts())
-
-# %%
-# **Streaming Output for Lower Latency:**
-#
-# When ``stream=True``, the model returns audio chunks progressively, allowing
-# you to start playback before synthesis completes. This reduces perceived latency.
-#
-
-
-async def example_non_realtime_tts_streaming() -> None:
- """An example of using non-realtime TTS models with streaming output."""
- # Example with DashScope TTS with streaming output
- tts_model = DashScopeTTSModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
- model_name="qwen3-tts-flash",
- voice="Cherry",
- stream=True, # Enable streaming output
- )
-
- msg = Msg(
- name="assistant",
- content="Hello, this is DashScope TTS with streaming output.",
- role="assistant",
- )
-
- # Synthesize and receive an async generator for streaming output
- async for tts_response in await tts_model.synthesize(msg):
- # Process each audio chunk as it arrives
- print(
- "Received audio chunk of length:",
- len(tts_response.content["source"]["data"]),
- )
-
-
-asyncio.run(example_non_realtime_tts_streaming())
-
-
-# %%
-# Realtime TTS
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# Realtime TTS models are designed for scenarios where text is generated
-# incrementally, such as streaming LLM responses. This enables the lowest
-# possible latency by starting audio synthesis before the complete text is ready.
-#
-# **Key Concepts:**
-#
-# - **Stateful Processing**: Realtime TTS maintains state for a single streaming
-# session, identified by ``msg.id``. Only one streaming session can be active
-# at a time.
-# - **Two Methods**:
-#
-# - ``push(msg)``: Non-blocking method that submits text chunks and returns
-# immediately. May return partial audio if available.
-# - ``synthesize(msg)``: Blocking method that finalizes the session and returns
-# all remaining audio. When ``stream=True``, it returns an async generator.
-#
-# .. code-block:: python
-#
-# async def example_realtime_tts_streaming():
-# tts_model = DashScopeRealtimeTTSModel(
-# api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
-# model_name="qwen3-tts-flash-realtime",
-# voice="Cherry",
-# stream=False,
-# )
-#
-# # realtime tts model received accumulative text chunks
-# res = await tts_model.push(msg_chunk_1) # non-blocking
-# res = await tts_model.push(msg_chunk_2) # non-blocking
-# ...
-# res = await tts_model.synthesize(final_msg) # blocking, get all remaining audio
-#
-# When setting ``stream=True`` during initialization, the ``synthesize()`` method returns an async generator of ``TTSResponse`` objects, allowing you to process audio chunks as they arrive.
-#
-#
-# Integrating with ReActAgent
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope agents can automatically synthesize their responses to speech
-# when provided with a TTS model. This works seamlessly with both realtime
-# and non-realtime TTS models.
-#
-# **How It Works:**
-#
-# 1. The agent generates a text response (potentially streamed from an LLM)
-# 2. The TTS model synthesizes the text to audio automatically
-# 3. The synthesized audio is attached to the ``speech`` field of the ``Msg`` object
-# 4. The audio is played during the agent's ``self.print()`` method
-#
-
-
-async def example_agent_with_tts() -> None:
- """An example of using TTS with ReActAgent."""
- # Create an agent with TTS enabled
- agent = ReActAgent(
- name="Assistant",
- sys_prompt="You are a helpful assistant.",
- model=DashScopeChatModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
- model_name="qwen-max",
- stream=True,
- ),
- formatter=DashScopeChatFormatter(),
- # Enable TTS
- tts_model=DashScopeRealtimeTTSModel(
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- model_name="qwen3-tts-flash-realtime",
- voice="Cherry",
- ),
- )
- user = UserAgent("User")
-
- # Build a conversation just like normal
- msg = None
- while True:
- msg = await agent(msg)
- msg = await user(msg)
- if msg.get_text_content() == "exit":
- break
-
-
-# %%
-# Customizing TTS Model
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# You can create custom TTS implementations by inheriting from ``TTSModelBase``.
-# The base class provides a flexible interface for both realtime and non-realtime
-# TTS models.
-# We use an attribute ``supports_streaming_input`` to indicate if the TTS model is realtime or not.
-#
-# For realtime TTS models, you need to implement the ``connect``, ``close``, ``push`` and ``synthesize`` methods to handle the lifecycle and streaming input.
-#
-# While for non-realtime TTS models, you only need to implement the ``synthesize`` method.
-#
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`agent` - Learn more about agents in AgentScope
-# - :ref:`message` - Understand message format in AgentScope
-# - API Reference: :class:`agentscope.tts.TTSModelBase`
-#
diff --git a/docs/tutorial/en/src/task_tuner.py b/docs/tutorial/en/src/task_tuner.py
deleted file mode 100644
index d735b0753..000000000
--- a/docs/tutorial/en/src/task_tuner.py
+++ /dev/null
@@ -1,247 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tuner:
-
-Tuner
-=================
-
-AgentScope provides the ``tuner`` module for training agent applications using reinforcement learning (RL).
-This tutorial will guide you through how to leverage the ``tuner`` module to improve agent performance on specific tasks, including:
-
-- Introducing the core components of the ``tuner`` module
-- Demonstrating the key code required for the tuning workflow
-- Showing how to configure and run the tuning process
-
-Main Components
-~~~~~~~~~~~~~~~~~~~
-The ``tuner`` module introduces three core components essential for RL-based agent training:
-
-- **Task Dataset**: A collection of tasks for training and evaluating the agent.
-- **Workflow Function**: Encapsulates the agent's logic to be tuned.
-- **Judge Function**: Evaluates the agent's performance on tasks and provides reward signals for tuning.
-
-In addition, ``tuner`` provides several configuration classes for customizing the tuning process, including:
-
-- **TunerModelConfig**: Model configurations for tuning purposes.
-- **AlgorithmConfig**: Specifies the RL algorithm (e.g., GRPO, PPO) and its parameters.
-
-Implementation
-~~~~~~~~~~~~~~~~~~~
-This section demonstrates how to use ``tuner`` to train a simple math agent.
-
-Task Dataset
---------------------
-The task dataset contains tasks for training and evaluating your agent.
-
-You dataset should follow the Huggingface `datasets <https://huggingface.co/docs/datasets/quickstart>`_ format, which can be loaded with ``datasets.load_dataset``. For example:
-
-.. code-block:: text
-
- my_dataset/
- ├── train.jsonl # training samples
- └── test.jsonl # evaluation samples
-
-Suppose your `train.jsonl` contains:
-
-.. code-block:: json
-
- {"question": "What is 2 + 2?", "answer": "4"}
- {"question": "What is 4 + 4?", "answer": "8"}
-
-Before starting tuning, you can verify that your dataset is loaded correctly with:
-
-.. code-block:: python
-
- from agentscope.tuner import DatasetConfig
-
- dataset = DatasetConfig(path="my_dataset", split="train")
- dataset.preview(n=2)
- # Output the first two samples to verify correct loading
- # [
- # {
- # "question": "What is 2 + 2?",
- # "answer": "4"
- # },
- # {
- # "question": "What is 4 + 4?",
- # "answer": "8"
- # }
- # ]
-
-Workflow Function
---------------------
-The workflow function defines how the agent interacts with the environment and makes decisions. All workflow functions should follow the input/output signature defined in ``agentscope.tuner.WorkflowType``.
-
-Below is an example workflow function using a ReAct agent to answer math questions:
-"""
-
-from typing import Dict, Optional
-from agentscope.agent import ReActAgent
-from agentscope.formatter import OpenAIChatFormatter
-from agentscope.message import Msg
-from agentscope.model import ChatModelBase
-from agentscope.tuner import WorkflowOutput
-
-
-async def example_workflow_function(
- task: Dict,
- model: ChatModelBase,
- auxiliary_models: Optional[Dict[str, ChatModelBase]] = None,
-) -> WorkflowOutput:
- """An example workflow function for tuning.
-
- Args:
- task (`Dict`): The task information.
- model (`ChatModelBase`): The chat model used by the agent.
- auxiliary_models (`Optional[Dict[str, ChatModelBase]]`): Additional
- chat models, generally used to simulate the behavior of other
- non-training agents in multi-agent scenarios.
-
- Returns:
- `WorkflowOutput`: The output generated by the workflow.
- """
- agent = ReActAgent(
- name="react_agent",
- sys_prompt="You are a helpful math problem solving agent.",
- model=model,
- formatter=OpenAIChatFormatter(),
- )
-
- response = await agent.reply(
- msg=Msg(
- "user",
- task["question"],
- role="user",
- ), # extract question from task
- )
-
- return WorkflowOutput( # return the response
- response=response,
- )
-
-
-# %%
-# You can directly run this workflow function with a task dictionary and a ``DashScopeChatModel`` / ``OpenAIChatModel`` to test its correctness before formal training. For example:
-
-import asyncio
-import os
-from agentscope.model import DashScopeChatModel
-
-task = {"question": "What is 123 plus 456?", "answer": "579"}
-model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
-)
-workflow_output = asyncio.run(example_workflow_function(task, model))
-assert isinstance(
- workflow_output.response,
- Msg,
-), "In this example, the response should be a Msg instance."
-print("\nWorkflow response:", workflow_output.response.get_text_content())
-
-# %%
-#
-# Judge Function
-# --------------------
-# The judge function evaluates the agent's performance on a given task and provides a reward signal for tuning.
-# All judge functions should follow the input/output signature defined in ``agentscope.tuner.JudgeType``.
-# Below is a simple judge function that compares the agent's response with the ground truth answer:
-
-from typing import Any
-from agentscope.tuner import JudgeOutput
-
-
-async def example_judge_function(
- task: Dict,
- response: Any,
- auxiliary_models: Optional[Dict[str, ChatModelBase]] = None,
-) -> JudgeOutput:
- """A very simple judge function only for demonstration.
-
- Args:
- task (`Dict`): The task information.
- response (`Any`): The response field from the WorkflowOutput.
- auxiliary_models (`Optional[Dict[str, ChatModelBase]]`): Additional
- chat models for LLM-as-a-Judge purpose.
- Returns:
- `JudgeOutput`: The reward assigned by the judge.
- """
- ground_truth = task["answer"]
- reward = 1.0 if ground_truth in response.get_text_content() else 0.0
- return JudgeOutput(reward=reward)
-
-
-judge_output = asyncio.run(
- example_judge_function(
- task,
- workflow_output.response,
- ),
-)
-print(f"Judge reward: {judge_output.reward}")
-
-# %%
-# The judge function can also be locally tested in the same way as shown above before formal training to ensure its logic is correct.
-#
-# .. tip::
-# You can leverage existing `MetricBase <https://github.com/agentscope-ai/agentscope/blob/main/src/agentscope/evaluate/_metric_base.py>`_ implementations in your judge function to compute more sophisticated metrics and combine them into a composite reward.
-#
-# Configuration and Running
-# ~~~~~~~~~~~~~~~
-# Finally, you can configure and run the tuning process using the ``tuner`` module.
-# Before starting, ensure that `Trinity-RFT <https://github.com/agentscope-ai/Trinity-RFT>`_ is installed in your environment, as it is required for tuning.
-#
-# Below is an example of configuring and starting the tuning process:
-#
-# .. note::
-# This example is for demonstration only. For a complete runnable example, see `Tune ReActAgent <https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning>`_
-#
-# .. code-block:: python
-#
-# from agentscope.tuner import tune, AlgorithmConfig, DatasetConfig, TunerModelConfig
-# # your workflow / judge function here...
-#
-# if __name__ == "__main__":
-# dataset = DatasetConfig(path="my_dataset", split="train")
-# model = TunerModelConfig(model_path="Qwen/Qwen3-0.6B", max_model_len=16384)
-# algorithm = AlgorithmConfig(
-# algorithm_type="multi_step_grpo",
-# group_size=8,
-# batch_size=32,
-# learning_rate=1e-6,
-# )
-# tune(
-# workflow_func=example_workflow_function,
-# judge_func=example_judge_function,
-# model=model,
-# train_dataset=dataset,
-# algorithm=algorithm,
-# )
-#
-# Here, ``DatasetConfig`` configures the training dataset, ``TunerModelConfig`` sets the parameters for the trainable model, and ``AlgorithmConfig`` specifies the reinforcement learning algorithm and its hyperparameters.
-#
-# .. tip::
-# The ``tune`` function is based on `Trinity-RFT <https://github.com/agentscope-ai/Trinity-RFT>`_ and internally converts input parameters to a YAML configuration.
-# Advanced users can skip the ``model``, ``train_dataset``, and ``algorithm`` arguments and instead provide a YAML config file path via the ``config_path`` argument.
-# Using a configuration file is recommended for fine-grained control and to leverage advanced Trinity-RFT features. See the Trinity-RFT `Configuration Guide <https://agentscope-ai.github.io/Trinity-RFT/en/main/tutorial/trinity_configs.html>`_ for more options.
-#
-# Save the above code as ``main.py`` and run it with:
-#
-# .. code-block:: bash
-#
-# ray start --head
-# python main.py
-#
-# Checkpoints and logs are automatically saved to the ``checkpoints/AgentScope`` directory under your workspace, with each run in a timestamped sub-directory. Tensorboard logs can be found in ``monitor/tensorboard`` within the checkpoint directory.
-#
-# .. code-block:: text
-#
-# your_workspace/
-# └── checkpoints/
-# └──AgentScope/
-# └── Experiment-20260104185355/ # each run saved in a sub-directory with timestamp
-# ├── monitor/
-# │ └── tensorboard/ # tensorboard logs
-# └── global_step_x/ # saved model checkpoints at step x
-#
-# .. tip::
-# For more tuning examples, refer to the `tuner directory <https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner>`_ of the AgentScope-Samples repository.
diff --git a/docs/tutorial/en/src/workflow_concurrent_agents.py b/docs/tutorial/en/src/workflow_concurrent_agents.py
deleted file mode 100644
index af2bc575a..000000000
--- a/docs/tutorial/en/src/workflow_concurrent_agents.py
+++ /dev/null
@@ -1,41 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Concurrent Agents
-===================================
-With the help of asynchronous programming, the concurrent agents can be executed by ``asyncio.gather`` in Python.
-
-A simple example is shown below, where two agents are created and executed concurrently.
-"""
-import asyncio
-from datetime import datetime
-from typing import Any
-
-from agentscope.agent import AgentBase
-
-
-class ExampleAgent(AgentBase):
- """The example agent for concurrent execution."""
-
- def __init__(self, name: str) -> None:
- """Initialize the agent with its name."""
- super().__init__()
- self.name = name
-
- async def reply(self, *args: Any, **kwargs: Any) -> None:
- """Reply to the message."""
- start_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
- print(f"{self.name} started at {start_time}")
- await asyncio.sleep(3) # Simulate a long-running task
- end_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
- print(f"{self.name} finished at {end_time}")
-
-
-async def run_concurrent_agents() -> None:
- """Run the concurrent agents."""
- agent1 = ExampleAgent("Agent 1")
- agent2 = ExampleAgent("Agent 2")
-
- await asyncio.gather(agent1(), agent2())
-
-
-asyncio.run(run_concurrent_agents())
diff --git a/docs/tutorial/en/src/workflow_conversation.py b/docs/tutorial/en/src/workflow_conversation.py
deleted file mode 100644
index 47cb25c8c..000000000
--- a/docs/tutorial/en/src/workflow_conversation.py
+++ /dev/null
@@ -1,208 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _conversation:
-
-Conversation
-======================
-
-Conversation is a design pattern that agents exchange and share information
-between each other, most commonly in game playing, chatbot, and multi-agent
-discussion scenarios.
-
-In AgentScope, the conversation is built upon the **explicit message
-exchange**. In this tutorial, we will demonstrate how to build a conversation
-
-- between a user and an agent (chatbot)
-- between multiple agents (game playing, discussion, etc.)
-
-Their main difference lies in
-
-- how the **prompt is constructed**, and
-- how the information is **propagated/shared** among agents.
-"""
-import asyncio
-import json
-import os
-
-from agentscope.agent import ReActAgent, UserAgent
-from agentscope.memory import InMemoryMemory
-from agentscope.formatter import (
- DashScopeChatFormatter,
- DashScopeMultiAgentFormatter,
-)
-from agentscope.model import DashScopeChatModel
-from agentscope.message import Msg
-from agentscope.pipeline import MsgHub
-from agentscope.tool import Toolkit
-
-# %%
-# User-Agent Conversation
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# User-agent conversation, also known as chatbot, is the most common usage
-# scenario of LLM-empowered agents, and the design target of most LLM APIs.
-# Such conversation features only two participants: a user and an agent.
-#
-# In AgentScope, the formatters with **"Chat"** in its name are designed for
-# user-agent conversation, such as ``DashScopeChatFormatter``,
-# ``AnthropicChatFormatter``, etc.
-# They use the ``role`` field in the message to distinguish the user and the
-# agent, and format the messages accordingly.
-#
-# Here we build a simple conversation between agent ``Friday`` and user.
-#
-# .. tip:: AgentScope provides a built-in ``UserAgent`` class for human-in-the-loop (HITL) interaction. Refer to :ref:`user-agent` for more details.
-#
-
-friday = ReActAgent(
- name="Friday",
- sys_prompt="You're a helpful assistant named Friday",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(), # The formatter for user-agent conversation
- memory=InMemoryMemory(),
- toolkit=Toolkit(),
-)
-
-# Create a user agent
-user = UserAgent(name="User")
-
-# %%
-# Now, we can program the conversation by exchanging messages between these two agents until the user types "exit" to end the conversation.
-#
-# .. code-block:: python
-#
-# async def run_conversation() -> None:
-# """Run a simple conversation between Friday and User."""
-# msg = None
-# while True:
-# msg = await friday(msg)
-# msg = await user(msg)
-# if msg.get_text_content() == "exit":
-# break
-#
-# asyncio.run(run_conversation())
-#
-
-# %%
-# More than Two Agents
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# As stated in the beginning, we demonstrate how to build conversation with multiple agents in terms of **prompt construction** and **information sharing**.
-#
-# Prompt Construction
-# -------------------------------
-# In AgentScope, we provide built-in formatters for multi-agent conversation, featuring **"MultiAgent"** in their names, such as ``DashScopeMultiAgentFormatter``, ``AnthropicMultiAgentFormatter``, etc.
-#
-# Specifically, they use the ``name`` field in the message to distinguish different agents, and format the conversation history into a single user message.
-# Taking ``DashScopeMultiAgentFormatter`` as an example:
-#
-# .. tip:: More details about the formatter can be found in :ref:`prompt`.
-#
-
-
-async def example_multi_agent_prompt() -> None:
- msgs = [
- Msg("system", "You're a helpful assistant named Bob.", "system"),
- Msg("Alice", "Hi!", "user"),
- Msg("Bob", "Hi! Nice to meet you guys.", "assistant"),
- Msg("Charlie", "Me too! I'm Charlie, by the way.", "assistant"),
- ]
-
- formatter = DashScopeMultiAgentFormatter()
- prompt = await formatter.format(msgs)
-
- print("Formatted prompt:")
- print(json.dumps(prompt, indent=4, ensure_ascii=False))
-
- # We print the content of the combined user message here for better
- # understanding:
- print("-------------")
- print("Combined message")
- print(prompt[1]["content"])
-
-
-asyncio.run(example_multi_agent_prompt())
-
-
-# %%
-# Message Sharing
-# -------------------------------
-# In multi-agent conversation, exchanging messages explicitly may not be efficient and convenient, especially when broadcasting messages among multiple agents.
-#
-# Therefore, AgentScope provides an async context manager named ``MsgHub`` to simplify the operation of broadcasting messages.
-# Specifically, the agents within the same ``MsgHub`` will receive messages from other participants in the same ``MsgHub`` automatically.
-#
-
-model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
-)
-formatter = DashScopeMultiAgentFormatter()
-
-alice = ReActAgent(
- name="Alice",
- sys_prompt="You're a student named Alice.",
- model=model,
- formatter=formatter,
- toolkit=Toolkit(),
- memory=InMemoryMemory(),
-)
-
-bob = ReActAgent(
- name="Bob",
- sys_prompt="You're a student named Bob.",
- model=model,
- formatter=formatter,
- toolkit=Toolkit(),
- memory=InMemoryMemory(),
-)
-
-charlie = ReActAgent(
- name="Charlie",
- sys_prompt="You're a student named Charlie.",
- model=model,
- formatter=formatter,
- toolkit=Toolkit(),
- memory=InMemoryMemory(),
-)
-
-
-async def example_msghub() -> None:
- """Example of using MsgHub for multi-agent conversation."""
- async with MsgHub(
- [alice, bob, charlie],
- announcement=Msg(
- "system",
- "Now you meet each other with a brief self-introduction.",
- "system",
- ),
- ):
- await alice()
- await bob()
- await charlie()
-
-
-asyncio.run(example_msghub())
-
-# %%
-# Now we print the memory of Alice to check if her memory is updated correctly.
-#
-
-
-async def example_memory() -> None:
- """Print the memory of Alice."""
- print("Memory of Alice:")
- for msg in await alice.memory.get_memory():
- print(f"{msg.name}: {msg.get_text_content()}")
-
-
-asyncio.run(example_memory())
-
-# %%
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# - :ref:`prompt`
-# - :ref:`pipeline`
-#
diff --git a/docs/tutorial/en/src/workflow_handoffs.py b/docs/tutorial/en/src/workflow_handoffs.py
deleted file mode 100644
index 7af62f05f..000000000
--- a/docs/tutorial/en/src/workflow_handoffs.py
+++ /dev/null
@@ -1,92 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Handoffs
-========================================
-
-.. figure:: ../../_static/images/handoffs.png
- :width: 80%
- :align: center
- :alt: Orchestrator-Workers Workflow
-
- *Handoffs example*
-
-It's very simple to implement the Orchestrator-Workers workflow with tool calls in AgentScope.
-First, we create a function to allow the orchestrator to create workers dynamically.
-
-"""
-
-import asyncio
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import (
- ToolResponse,
- Toolkit,
- execute_python_code,
-)
-
-
-# The tool function to create a worker
-async def create_worker(
- task_description: str,
-) -> ToolResponse:
- """Create a worker to finish the given task. The worker is equipped with python execution tool.
-
- Args:
- task_description (``str``):
- The description of the task to be finished by the worker.
- """
- # Equip the worker agent with some tools
- toolkit = Toolkit()
- toolkit.register_tool_function(execute_python_code)
-
- # Create a worker agent
- worker = ReActAgent(
- name="Worker",
- sys_prompt="You're a worker agent. Your target is to finish the given task.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- )
- # Let the worker finish the task
- res = await worker(Msg("user", task_description, "user"))
- return ToolResponse(
- content=res.get_content_blocks("text"),
- )
-
-
-async def run_handoffs() -> None:
- """Example of handoffs workflow."""
- # Initialize the orchestrator agent
- toolkit = Toolkit()
- toolkit.register_tool_function(create_worker)
-
- orchestrator = ReActAgent(
- name="Orchestrator",
- sys_prompt="You're an orchestrator agent. Your target is to finish the given task by decomposing it into smaller tasks and creating workers to finish them.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- )
-
- # The task description
- task_description = "Execute hello world in Python"
-
- # Create a worker to finish the task
- await orchestrator(Msg("user", task_description, "user"))
-
-
-asyncio.run(run_handoffs())
diff --git a/docs/tutorial/en/src/workflow_multiagent_debate.py b/docs/tutorial/en/src/workflow_multiagent_debate.py
deleted file mode 100644
index 58c053708..000000000
--- a/docs/tutorial/en/src/workflow_multiagent_debate.py
+++ /dev/null
@@ -1,139 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _multiagent-debate:
-
-Multi-Agent Debate
-========================
-
-Debate workflow simulates a multi-turn discussion between different agents, mostly several solvers and an aggregator.
-Typically, the solvers generate and exchange their answers, while the aggregator collects and summarizes the answers.
-
-We implement the examples in `EMNLP 2024`_, where two debater agents will discuss a topic in a fixed order, and express their
-arguments based on the previous debate history.
-At each round a moderator agent will decide whether the correct answer can be obtained in the current iteration.
-"""
-import asyncio
-import os
-
-from pydantic import Field, BaseModel
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import (
- DashScopeMultiAgentFormatter,
- DashScopeChatFormatter,
-)
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.pipeline import MsgHub
-
-# Prepare a topic
-topic = (
- "The two circles are externally tangent and there is no relative sliding. "
- "The radius of circle A is 1/3 the radius of circle B. Circle A rolls "
- "around circle B one trip back to its starting point. How many times will "
- "circle A revolve in total?"
-)
-
-
-# Create two debater agents, Alice and Bob, who will discuss the topic.
-def create_solver_agent(name: str) -> ReActAgent:
- """Get a solver agent."""
- return ReActAgent(
- name=name,
- sys_prompt=f"You're a debater named {name}. Hello and welcome to the "
- "debate competition. It's unnecessary to fully agree with "
- "each other's perspectives, as our objective is to find "
- "the correct answer. The debate topic is stated as "
- f"follows: {topic}.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeMultiAgentFormatter(),
- )
-
-
-alice, bob = [create_solver_agent(name) for name in ["Alice", "Bob"]]
-
-# Create a moderator agent
-moderator = ReActAgent(
- name="Aggregator",
- sys_prompt=f"""You're a moderator. There will be two debaters involved in a debate competition. They will present their answer and discuss their perspectives on the topic:
-``````
-{topic}
-``````
-At the end of each round, you will evaluate both sides' answers and decide which one is correct.""",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- # Use multiagent formatter because the moderator will receive messages from more than a user and an assistant
- formatter=DashScopeMultiAgentFormatter(),
-)
-
-
-# A structured output model for the moderator
-class JudgeModel(BaseModel):
- """The structured output model for the moderator."""
-
- finished: bool = Field(
- description="Whether the debate is finished.",
- )
- correct_answer: str | None = Field(
- description="The correct answer to the debate topic, only if the debate is finished. Otherwise, leave it as None.",
- default=None,
- )
-
-
-async def run_multiagent_debate() -> None:
- """Run the multi-agent debate workflow."""
- while True:
- # The reply messages in MsgHub from the participants will be broadcasted to all participants.
- async with MsgHub(participants=[alice, bob, moderator]):
- await alice(
- Msg(
- "user",
- "You are affirmative side, Please express your viewpoints.",
- "user",
- ),
- )
- await bob(
- Msg(
- "user",
- "You are negative side. You disagree with the affirmative side. Provide your reason and answer.",
- "user",
- ),
- )
-
- # Alice and Bob doesn't need to know the moderator's message, so moderator is called outside the MsgHub.
- msg_judge = await moderator(
- Msg(
- "user",
- "Now you have heard the answers from the others, have the debate finished, and can you get the correct answer?",
- "user",
- ),
- structured_model=JudgeModel,
- )
-
- if msg_judge.metadata.get("finished"):
- print(
- "\nThe debate is finished, and the correct answer is: ",
- msg_judge.metadata.get("correct_answer"),
- )
- break
-
-
-asyncio.run(run_multiagent_debate())
-
-
-# %%
-# Further Reading
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# - :ref:`pipeline`
-#
-# .. _EMNLP 2024:
-# Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate. EMNLP 2024.
-#
diff --git a/docs/tutorial/en/src/workflow_routing.py b/docs/tutorial/en/src/workflow_routing.py
deleted file mode 100644
index 912f9fe7a..000000000
--- a/docs/tutorial/en/src/workflow_routing.py
+++ /dev/null
@@ -1,176 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _routing:
-
-Routing
-==========================
-There are two ways to implement routing in AgentScope, both simple and easy to implement:
-
-- Routing by structured output
-- Routing by tool calls
-
-.. tip:: Considering there is no unified standard/definition for agent routing, we follow the setting in `Building effective agents <https://www.anthropic.com/engineering/building-effective-agents>`_
-
-Routing by Structured Output
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-By this way, we can directly use the structured output of the agent to determine which agent to route the message to.
-
-Initialize a routing agent
-"""
-import asyncio
-import json
-import os
-from typing import Literal
-
-from pydantic import BaseModel, Field
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit, ToolResponse
-
-router = ReActAgent(
- name="Router",
- sys_prompt="You're a routing agent. Your target is to route the user query to the right follow-up task.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
-)
-
-
-# Use structured output to specify the routing task
-class RoutingChoice(BaseModel):
- your_choice: Literal[
- "Content Generation",
- "Programming",
- "Information Retrieval",
- None,
- ] = Field(
- description="Choose the right follow-up task, and choose ``None`` if the task is too simple or no suitable task",
- )
- task_description: str | None = Field(
- description="The task description",
- default=None,
- )
-
-
-async def example_router_explicit() -> None:
- """Example of explicit routing with structured output."""
- msg_user = Msg(
- "user",
- "Help me to write a poem",
- "user",
- )
-
- # Route the query
- msg_res = await router(
- msg_user,
- structured_model=RoutingChoice,
- )
-
- # The structured output is stored in the metadata field
- print("The structured output:")
- print(json.dumps(msg_res.metadata, indent=4, ensure_ascii=False))
-
-
-asyncio.run(example_router_explicit())
-
-# %%
-# Routing by Tool Calls
-# ~~~~~~~~~~~~~~~~~~~~~~~~~
-# Another way is to wrap the downstream agents into a tool function, so that the routing agent decides which tool to call based on the user query.
-#
-# We first define several tool functions:
-#
-
-
-async def generate_python(demand: str) -> ToolResponse:
- """Generate Python code based on the demand.
-
- Args:
- demand (``str``):
- The demand for the Python code.
- """
- # An example demand agent
- python_agent = ReActAgent(
- name="PythonAgent",
- sys_prompt="You're a Python expert, your target is to generate Python code based on the demand.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=Toolkit(),
- )
- msg_res = await python_agent(Msg("user", demand, "user"))
-
- return ToolResponse(
- content=msg_res.get_content_blocks("text"),
- )
-
-
-# Fake some other tool functions for demonstration purposes
-async def generate_poem(demand: str) -> ToolResponse:
- """Generate a poem based on the demand.
-
- Args:
- demand (``str``):
- The demand for the poem.
- """
- pass
-
-
-async def web_search(query: str) -> ToolResponse:
- """Search the web for the query.
-
- Args:
- query (``str``):
- The query to search.
- """
- pass
-
-
-# %%
-# After that, we define a routing agent and equip it with the above tool functions.
-#
-
-toolkit = Toolkit()
-toolkit.register_tool_function(generate_python)
-toolkit.register_tool_function(generate_poem)
-toolkit.register_tool_function(web_search)
-
-# Initialize the routing agent with the toolkit
-router_implicit = ReActAgent(
- name="Router",
- sys_prompt="You're a routing agent. Your target is to route the user query to the right follow-up task.",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- memory=InMemoryMemory(),
-)
-
-
-async def example_router_implicit() -> None:
- """Example of implicit routing with tool calls."""
- msg_user = Msg(
- "user",
- "Help me to generate a quick sort function in Python",
- "user",
- )
-
- # Route the query
- await router_implicit(msg_user)
-
-
-asyncio.run(example_router_implicit())
diff --git a/docs/tutorial/zh_CN/Makefile b/docs/tutorial/zh_CN/Makefile
deleted file mode 100644
index 92dd33a1a..000000000
--- a/docs/tutorial/zh_CN/Makefile
+++ /dev/null
@@ -1,20 +0,0 @@
-# Minimal makefile for Sphinx documentation
-#
-
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS ?=
-SPHINXBUILD ?= sphinx-build
-SOURCEDIR = source
-BUILDDIR = _build
-
-# Put it first so that "make" without argument is like "make help".
-help:
- @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
-
-.PHONY: help Makefile
-
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile
- @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/tutorial/zh_CN/build.sh b/docs/tutorial/zh_CN/build.sh
deleted file mode 100755
index 1a658d153..000000000
--- a/docs/tutorial/zh_CN/build.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/bin/bash
-
-set -e
-
-# Clean old build files
-rm -rf build/ doctrees/
-
-# Build the html
-sphinx-build -M html ./ build
-
-# Remove temporary files (double insurance)
-rm -rf build/html/.doctrees
-rm -f build/html/.buildinfo
-find build/html -name "*.pickle" -delete
-find build/html -name "__pycache__" -delete
-find build/html -name "*.pyc" -delete
-
-echo "✅ Chinese docs built successfully, temporary files cleaned"
\ No newline at end of file
diff --git a/docs/tutorial/zh_CN/conf.py b/docs/tutorial/zh_CN/conf.py
deleted file mode 100644
index a51f662f8..000000000
--- a/docs/tutorial/zh_CN/conf.py
+++ /dev/null
@@ -1,140 +0,0 @@
-# -*- coding: utf-8 -*-
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
-project = "AgentScope"
-copyright = "2025, Alibaba"
-author = "Alibaba Tongyi Lab"
-
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = [
- "myst_parser",
- "sphinx_gallery.gen_gallery",
- "sphinx.ext.autodoc",
- "sphinx.ext.viewcode",
- "sphinx.ext.napoleon",
-]
-
-myst_enable_extensions = [
- "colon_fence",
-]
-
-sphinx_gallery_conf = {
- "download_all_examples": False,
- "examples_dirs": [
- "src",
- ],
- "gallery_dirs": [
- "tutorial",
- ],
- "filename_pattern": "src/.*\.py",
- "example_extensions": [".py"],
-}
-
-templates_path = ["../_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-languages = ["en", "zh_CN"]
-language = "zh_CN"
-
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
-
-html_theme = "furo"
-html_title = (
- "<span style='font-weight: 700; color: #2196f3;'>AgentScope</span>"
-)
-html_logo = "../_static/images/logo.svg"
-html_favicon = "../_static/images/logo.svg"
-html_static_path = ["../_static"]
-html_css_files = [
- "css/gallery.css",
-]
-
-html_js_files = [
- "language_switch.js",
-]
-
-html_theme_options = {
- "footer_icons": [
- {
- "name": "GitHub",
- "url": "https://github.com/agentscope-ai/agentscope",
- "html": """
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
- <path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
- </svg>
- """,
- "class": "",
- },
- {
- "name": "Discord",
- "url": "https://discord.gg/eYMpfnkG8h",
- "html": """
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" t="1753331148815" class="icon" viewBox="0 0 1024 1024" version="1.1" xmlns="http://www.w3.org/2000/svg" p-id="5721" width="200" height="200">
- <path d="M723.903423 359.138018c-69.65045-52.952793-136.256577-51.476757-136.256576-51.476757l-6.088649 7.564685c83.027027 25.738378 121.127207 62.085766 121.127207 62.085766a387.459459 387.459459 0 0 0-145.297297-46.956397 418.179459 418.179459 0 0 0-98.340901 1.752793 73.801802 73.801802 0 0 1-7.564684 1.476036 357.385225 357.385225 0 0 0-110.702703 30.258739 278.786306 278.786306 0 0 0-28.782703 13.653333S353.049369 339.488288 440.873514 313.657658l-4.612613-6.088649s-66.513874-1.476036-136.164324 51.476757A654.252973 654.252973 0 0 0 230.630631 642.167928s40.867748 71.126486 148.341621 73.801802c0 0 16.697658-22.694054 31.827027-40.867748-62.085766-18.45045-84.77982-57.565405-84.77982-57.565405a130.998198 130.998198 0 0 0 13.653334 7.564684s0 1.568288 1.476036 1.568289c1.476036 1.476036 3.044324 1.476036 4.52036 3.044324a238.748829 238.748829 0 0 0 34.779099 16.605405 513.199279 513.199279 0 0 0 71.218739 21.218018 350.558559 350.558559 0 0 0 125.555315 0 329.894054 329.894054 0 0 0 69.650451-21.218018A247.328288 247.328288 0 0 0 702.685405 618.09009s-24.262342 39.391712-87.824144 57.565405c13.653333 18.45045 31.827027 39.299459 31.827027 39.29946 107.473874-2.952072 148.341622-73.801802 146.773334-72.602523a654.990991 654.990991 0 0 0-69.558199-283.214414zM421.131532 596.77982a54.705586 54.705586 0 0 1 0-109.042162 54.705586 54.705586 0 0 1 0 109.042162z m177.124324 0a54.705586 54.705586 0 1 1 49.908468-54.521081 52.491532 52.491532 0 0 1-49.908468 54.521081z" p-id="5722"></path><path d="M512 1024A512 512 0 1 1 1024 512 512.645766 512.645766 0 0 1 512 1024z m0-972.892252a461.261261 461.261261 0 1 0 461.261261 461.261261 461.261261 461.261261 0 0 0-461.261261-461.261261z" p-id="5723"></path>
- </svg>
- """,
- "class": "",
- },
- {
- "name": "DingTalk",
- "url": "https://qr.dingtalk.com/action/joingroup?code=v1,k1,OmDlBXpjW+I2vWjKDsjvI9dhcXjGZi3bQiojOq3dlDw=&_dt_no_comment=1&origin=11",
- "html": """
- <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024">
- <path d="M512 0C229.205333 0 0 229.205333 0 512s229.205333 512 512 512 512-229.205333 512-512S794.794667 0 512 0z m237.312 480.810667c-1.109333 4.48-3.712 11.093333-7.424 18.986666h0.128l-0.426667 0.682667c-21.504 46.037333-77.610667 136.106667-77.610666 136.106667l-0.298667-0.597334-16.384 28.501334h79.018667l-150.912 200.917333 34.304-136.533333h-62.208l21.589333-90.282667c-17.493333 4.224-38.101333 10.026667-62.592 17.92 0 0-33.109333 19.370667-95.317333-37.333333 0 0-41.984-36.992-17.578667-46.165334 10.410667-3.925333 50.304-8.917333 81.706667-13.226666 42.410667-5.674667 68.48-8.789333 68.48-8.789334s-130.773333 2.005333-161.792-2.901333c-30.976-4.906667-70.4-56.704-78.805334-102.186667 0 0-12.970667-25.002667 27.904-13.226666 40.917333 11.818667 210.005333 46.08 210.005334 46.08S321.109333 411.434667 306.517333 394.922667c-14.634667-16.469333-43.093333-89.770667-39.424-134.869334 0 0 1.621333-11.221333 13.098667-8.192 0 0 162.602667 74.282667 273.792 114.986667 111.104 40.704 207.786667 61.397333 195.328 114.005333z" opacity=".65" p-id="6077"></path>
- </svg>
- """,
- "class": "",
- },
- ],
- "light_css_variables": {
- "color-brand-primary": "#2196f3",
- "color-brand-content": "#2196f3",
- "color-admonition-background": "#f8f9fa",
- },
- "dark_css_variables": {
- "color-link": "#2196f3",
- "color-link--hover": "#2196f3",
- "color-brand-primary": "#64b5f6",
- "color-brand-content": "#64b5f6",
- },
-}
-
-source_suffix = [".md", ".rst"]
-
-
-# -- Options for API documentation -------------------------------------------
-
-autodoc_member_order = "bysource"
-autodoc_typehints = "description"
-autodoc_class_signature = "separated"
-autodoc_default_options = {
- "special-members": "__call__",
-}
-
-add_module_names = False
-python_display_short_literal_types = True
-
-
-def skip_member(app, what, name, obj, skip, options):
- if name in [
- "__call__",
- "_format",
- "_format_agent_message",
- "_format_tool_sequence",
- ]:
- return False
-
- return skip
-
-
-def setup(app):
- app.connect("autodoc-skip-member", skip_member)
diff --git a/docs/tutorial/zh_CN/index.rst b/docs/tutorial/zh_CN/index.rst
deleted file mode 100644
index 2e9914fab..000000000
--- a/docs/tutorial/zh_CN/index.rst
+++ /dev/null
@@ -1,77 +0,0 @@
-.. AgentScope Doc documentation master file, created by
- sphinx-quickstart on Thu Aug 8 15:07:21 2024.
- You can adapt this file completely to your liking, but it should at least
- contain the root `toctree` directive.
-
-Welcome to AgentScope's documentation!
-==========================================
-
-.. toctree::
- :maxdepth: 1
- :caption: Tutorial
-
- tutorial/quickstart_installation
- tutorial/quickstart_key_concept
- tutorial/quickstart_message
- tutorial/quickstart_agent
-
-.. toctree::
- :maxdepth: 1
- :caption: Workflow
-
- tutorial/workflow_conversation
- tutorial/workflow_multiagent_debate
- tutorial/workflow_concurrent_agents
- tutorial/workflow_routing
- tutorial/workflow_handoffs
-
-.. toctree::
- :maxdepth: 1
- :caption: FAQ
-
- tutorial/faq
-
-
-.. toctree::
- :maxdepth: 1
- :caption: Model and Context
-
- tutorial/task_model
- tutorial/task_prompt
- tutorial/task_token
- tutorial/task_memory
- tutorial/task_long_term_memory
-
-.. toctree::
- :maxdepth: 1
- :caption: Tool
-
- tutorial/task_tool
- tutorial/task_mcp
- tutorial/task_agent_skill
-
-.. toctree::
- :maxdepth: 1
- :caption: Agent
-
- tutorial/task_agent
- tutorial/task_state
- tutorial/task_hook
- tutorial/task_middleware
- tutorial/task_a2a
- tutorial/task_realtime
-
-.. toctree::
- :maxdepth: 1
- :caption: Features
-
- tutorial/task_pipeline
- tutorial/task_plan
- tutorial/task_rag
- tutorial/task_studio
- tutorial/task_tracing
- tutorial/task_eval
- tutorial/task_eval_openjudge
- tutorial/task_embedding
- tutorial/task_tts
- tutorial/task_tuner
diff --git a/docs/tutorial/zh_CN/make.bat b/docs/tutorial/zh_CN/make.bat
deleted file mode 100644
index dc1312ab0..000000000
--- a/docs/tutorial/zh_CN/make.bat
+++ /dev/null
@@ -1,35 +0,0 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
- set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=source
-set BUILDDIR=build
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
- echo.
- echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
- echo.installed, then set the SPHINXBUILD environment variable to point
- echo.to the full path of the 'sphinx-build' executable. Alternatively you
- echo.may add the Sphinx directory to PATH.
- echo.
- echo.If you don't have Sphinx installed, grab it from
- echo.https://www.sphinx-doc.org/
- exit /b 1
-)
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
diff --git a/docs/tutorial/zh_CN/src/faq.py b/docs/tutorial/zh_CN/src/faq.py
deleted file mode 100644
index 6afce30af..000000000
--- a/docs/tutorial/zh_CN/src/faq.py
+++ /dev/null
@@ -1,53 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _faq:
-
-常见问题
-========================================
-
-关于 AgentScope
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*什么是AgentScope?*
- AgentScope 是一个多智能体框架,旨在提供一种简单高效的方式来构建基于大语言模型的智能体应用程序。
-
-*AgentScope v1.0 与 v0.x 版本有什么区别?*
- AgentScope v1.0是对框架的完全重写,配备了新功能和改进。详细变更请参考相关文档。
-
-
-关于模型
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*如何在 AgentScope 中集成我自己的模型?*
- 通过继承 ``agentscope.model.ChatModelBase`` 并实现 ``__call__`` 方法来创建您自己的模型。
-
-*AgentScope 支持哪些模型?*
- 目前,AgentScope 内置支持 DashScope、Gemini、OpenAI、Anthropic 和 Ollama API,以及与 DeepSeek 和 vLLMs 模型兼容的 ``OpenAIChatModel``。
-
-*如何在 AgentScope 中监控token 使用情况?*
- 在 AgentScope Studio中,我们提供了 token 使用情况的可视化和追踪功能。详情请参考:ref:`studio` 部分。
-
-
-关于智能体
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*如何创建我自己的智能体?*
- 您可以选择直接使用 ``ReActAgent`` 类,或者通过继承 ``AgentBase`` 或 ``ReActAgentBase`` 类来创建您自己的智能体。详情请参考 :ref:`agent` 部分。
-
-
-*如何将智能体的(流式)输出转发到我自己的前端或应用程序?*
- 使用 ``print`` 函数的前置钩子来转发打印消息。请参考 :ref:`hook` 部分。
-
-
-关于工具
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*AgentScope 提供了多少工具?*
- AgentScope 提供了一套内置工具,包括 ``execute_python_code``、``execute_shell_command``、``write_text_file`` 等。您可以在 ``agentscope.tool`` 模块下找到它们。
-
-
-关于错误报告
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-*如何报告 AgentScope中的错误?*
- 如果您在使用 AgentScope 时遇到错误,请通过在我们的 GitHub仓库中开启一个issue来报告。
-
-*如何报告AgentScope 中的安全漏洞?*
- 如果您在AgentScope 中发现安全问题,请通过 `阿里巴巴安全响应中心(ASRC) <https://security.alibaba.com/>`_ 向我们报告。
-
-"""
diff --git a/docs/tutorial/zh_CN/src/quickstart_agent.py b/docs/tutorial/zh_CN/src/quickstart_agent.py
deleted file mode 100644
index db9b4f319..000000000
--- a/docs/tutorial/zh_CN/src/quickstart_agent.py
+++ /dev/null
@@ -1,243 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _react-agent:
-
-创建 ReAct 智能体
-====================
-
-AgentScope 在 ``agentscope.agent`` 模块下提供了开箱即用的 ReAct 智能体 ``ReActAgent`` 供开发者使用。
-
-它同时支持以下功能:
-
-- ✨ 基础功能
- - 支持围绕 ``reply``、``observe``、``print``、``_reasoning`` 和 ``_acting`` 的 **钩子函数(hooks)**
- - 支持结构化输出
-- ✋ 实时介入(Realtime Steering)
- - 支持用户 **中断**
- - 支持自定义 **中断处理**
-- 🛠️ 工具
- - 支持 **同步/异步** 工具函数
- - 支持 **流式** 工具响应
- - 支持 **状态化** 的工具管理
- - 支持 **并行** 工具调用
- - 支持 **MCP** 服务器
-- 💾 记忆
- - 支持智能体 **自主管理** 长期记忆
- - 支持“静态”的长期记忆管理
-
-.. tip:: 有关这些功能的更多详细信息,请参考 :ref:`agent` 部分。本章节中,我们重点介绍如何创建 ReAct 智能体并运行。
-
-"""
-
-from agentscope.agent import ReActAgent, AgentBase
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-import asyncio
-import os
-
-from agentscope.tool import Toolkit, execute_python_code
-
-
-# %%
-# 创建 ReAct 智能体
-# ------------------------------
-# 为了提高灵活性,``ReActAgent`` 类在其构造函数中暴露了以下参数:
-#
-# .. list-table:: ``ReActAgent`` 类的初始化参数
-# :header-rows: 1
-#
-# * - 参数
-# - 进一步阅读
-# - 描述
-# * - ``name`` (必需)
-# -
-# - 智能体的名称
-# * - ``sys_prompt`` (必需)
-# -
-# - 智能体的系统提示
-# * - ``model`` (必需)
-# - :ref:`model`
-# - 智能体用于生成响应的模型
-# * - ``formatter`` (必需)
-# - :ref:`prompt`
-# - 提示构建策略,应与使用的模型保持一致
-# * - ``toolkit``
-# - :ref:`tool`
-# - 用于注册/调用工具函数的工具模块
-# * - ``memory``
-# - :ref:`memory`
-# - 用于存储对话历史的短期记忆
-# * - ``long_term_memory``
-# - :ref:`long-term-memory`
-# - 长期记忆
-# * - ``long_term_memory_mode``
-# - :ref:`long-term-memory`
-# - 长期记忆的管理模式:
-#
-# - ``agent_control``: 允许智能体通过工具函数自己控制长期记忆
-# - ``static_control``: 在每次回复(reply)的开始/结束时,会自动从长期记忆中检索/记录信息
-# - ``both``: 同时激活上述两种模式
-# * - ``enable_meta_tool``
-# - :ref:`tool`
-# - 是否启用元工具(Meta tool),即允许智能体自主管理工具函数
-# * - ``parallel_tool_calls``
-# - :ref:`agent`
-# - 是否允许并行工具调用
-# * - ``max_iters``
-# -
-# - 智能体生成响应的最大迭代次数
-# * - ``plan_notebook``
-# - :ref:`plan`
-# - 计划模块,允许智能体制定和管理计划与子任务
-# * - ``print_hint_msg``
-# -
-# - 是否在终端打印 ``plan_notebook`` 生成的提示消息
-#
-# 以 DashScope API 为例,我们创建一个智能体对象如下:
-
-
-async def creating_react_agent() -> None:
- """创建一个 ReAct 智能体并运行一个简单任务。"""
- # 准备工具
- toolkit = Toolkit()
- toolkit.register_tool_function(execute_python_code)
-
- jarvis = ReActAgent(
- name="Jarvis",
- sys_prompt="你是一个名为 Jarvis 的助手",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=True,
- enable_thinking=False,
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- memory=InMemoryMemory(),
- )
-
- msg = Msg(
- name="user",
- content="你好!Jarvis,用 Python 运行 Hello World。",
- role="user",
- )
-
- await jarvis(msg)
-
-
-asyncio.run(creating_react_agent())
-
-# %%
-# 从零开始创建
-# --------------------------------
-# 为了支持开发者从零开始创建智能体,AgentScope 提供了两个基类:
-#
-# .. list-table::
-# :header-rows: 1
-#
-# * - 类
-# - 抽象方法
-# - 描述
-# * - ``AgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``handle_interrupt``
-# - - 所有智能体的基类,支持 ``reply``、``observe`` 和 ``print`` 函数的前置和后置钩子函数。
-# - 在 ``__call__`` 函数内实现了基础的实时介入(Realtime Steering)逻辑。
-# * - ``ReActAgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``handle_interrupt``
-# | ``_reasoning``
-# | ``_acting``
-# - 在 ``AgentBase`` 的基础上添加了两个抽象函数 ``_reasoning`` 和 ``_acting``,以及它们的钩子函数。
-#
-# 有关智能体类的更多详细信息,请参考 :ref:`agent` 部分。
-#
-# 以 ``AgentBase`` 类为例,我们可以通过继承它并实现 ``reply`` 方法来创建自定义智能体类。
-
-
-class MyAgent(AgentBase):
- """自定义智能体类"""
-
- def __init__(self) -> None:
- """初始化智能体"""
- super().__init__()
-
- self.name = "Friday"
- self.sys_prompt = "你是一个名为 Friday 的助手。"
- self.model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- )
- self.formatter = DashScopeChatFormatter()
- self.memory = InMemoryMemory()
-
- async def reply(self, msg: Msg | list[Msg] | None) -> Msg:
- """直接调用大模型,产生回复消息。"""
- await self.memory.add(msg)
-
- # 准备提示
- prompt = await self.formatter.format(
- [
- Msg("system", self.sys_prompt, "system"),
- *await self.memory.get_memory(),
- ],
- )
-
- # 调用模型
- response = await self.model(prompt)
-
- msg = Msg(
- name=self.name,
- content=response.content,
- role="assistant",
- )
-
- # 在记忆中记录响应
- await self.memory.add(msg)
-
- # 打印消息
- await self.print(msg)
- return msg
-
- async def observe(self, msg: Msg | list[Msg] | None) -> None:
- """观察消息。"""
- # 将消息存储在记忆中
- await self.memory.add(msg)
-
- async def handle_interrupt(self) -> Msg:
- """处理中断。"""
- # 以固定响应为例
- return Msg(
- name=self.name,
- content="我注意到您打断了我的回复,我能为你做些什么?",
- role="assistant",
- )
-
-
-async def run_custom_agent() -> None:
- """运行自定义智能体。"""
- agent = MyAgent()
- msg = Msg(
- name="user",
- content="你是谁?",
- role="user",
- )
- await agent(msg)
-
-
-asyncio.run(run_custom_agent())
-
-# %%
-#
-# 进一步阅读
-# ---------------------
-# - :ref:`agent`
-# - :ref:`model`
-# - :ref:`prompt`
-# - :ref:`tool`
-#
diff --git a/docs/tutorial/zh_CN/src/quickstart_installation.py b/docs/tutorial/zh_CN/src/quickstart_installation.py
deleted file mode 100644
index b3599f6b8..000000000
--- a/docs/tutorial/zh_CN/src/quickstart_installation.py
+++ /dev/null
@@ -1,54 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _installation:
-
-安装
-============================
-
-AgentScope 需要 Python 3.10 或更高版本。您可以从源代码或 PyPI 安装。
-
-从 PyPI 安装
-----------------
-.. code-block:: bash
-
- pip install agentscope
-
-从源代码安装
-----------------
-从源代码安装 AgentScope,需要从 GitHub 克隆仓库,并通过以下命令安装
-
-.. code-block:: bash
-
- git clone -b main https://github.com/agentscope-ai/agentscope
- cd agentscope
- pip install -e .
-
-执行以下代码确保 AgentScope 正常安装:
-"""
-
-import agentscope
-
-print(agentscope.__version__)
-
-# %%
-# 额外依赖
-# ----------------------------
-#
-# 为了满足不同功能的需求,AgentScope 提供了额外依赖项。
-#
-# - full: 包含模型 API 和工具函数的额外依赖项
-# - dev: 开发依赖项,包括测试和文档工具
-#
-# 以 full 模式为例,安装命令根据您的操作系统而有所不同。
-#
-# 对于 Windows 用户:
-#
-# .. code-block:: bash
-#
-# pip install agentscope[full]
-#
-# 对于 Mac 和 Linux 用户:
-#
-# .. code-block:: bash
-#
-# pip install agentscope\[full\]
diff --git a/docs/tutorial/zh_CN/src/quickstart_key_concept.py b/docs/tutorial/zh_CN/src/quickstart_key_concept.py
deleted file mode 100644
index 4df2fe118..000000000
--- a/docs/tutorial/zh_CN/src/quickstart_key_concept.py
+++ /dev/null
@@ -1,102 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. key-concepts:
-
-核心概念
-====================================
-
-本章从工程实践的角度介绍 AgentScope 中的核心概念,从而阐明 AgentScope 的设计理念。
-
-.. note:: 介绍核心概念的目标是为了更好的阐明 AgentScope 在工程实践中解决的问题,以及为开发者提供的帮助,而非给出严谨的定义。
-
-状态
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-状态(State)管理是 AgentScope 框架构建的基础。其中,状态表示对象运行时某一时刻数据的快照。
-
-AgentScope 将对象的“初始化”与“状态管理”分离,对象在初始化后通过 ``load_state_dict`` 和 ``state_dict`` 方法恢复到不同的状态,或导出当前的状态。
-
-在 AgentScope 中,智能体(Agent)、记忆(memory)、长期记忆(Long-term memory)和工具模块(toolkit)都是有状态的对象。
-AgentScope 通过支持嵌套式的状态管理,将这些对象的状态管理联系起来。
-
-消息
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-消息(message)是 AgentScope 最核心的数据结构,用于
-
-- 在智能体之间交换信息,
-- 在用户交互界面显示信息,
-- 在记忆中存储信息,
-- 作为 AgentScope 与不同 LLM API 之间的统一媒介。
-
-工具
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-AgentScope 中的“工具”指的是可调用的 Python 对象,包括
-
-- 函数,
-- 偏函数(Partial function),
-- 实例方法,
-- 类方法,
-- 静态方法,以及
-- 带有 ``__call__`` 方法的可调用实例。
-
-此外,可调用对象可以是
-
-- 异步或同步调用的,
-- 流式或非流式返回结果的。
-
-因此,请放心在 AgentScope 中使用任何调用对象作为智能体的工具。
-
-智能体
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-在 AgentScope 中,智能体(Agent)行为被抽象为 ``AgentBase`` 类中的三个核心函数:
-
-- ``reply``:处理传入的消息并生成响应消息。
-- ``observe``:接收来自环境或其它智能体的消息,但不返回响应。
-- ``print``:将消息显示到目标输出(例如终端、Web 界面)。
-
-为了支持用户实时介入(Realtime Steering),AgentScope 提供了额外
-的 ``handle_interrupt`` 函数来处理智能体回复过程中的用户中断。
-
-此外,ReAct 智能体是 AgentScope 中最重要的智能体,该智能体的回复过程分为两个阶段:
-
-- 推理(Reasoning):通过调用 LLM 进行推理并生成工具调用
-- 行动(Acting):执行工具函数。
-
-因此,我们在 ``ReActAgentBase`` 类中提供了两个额外的核心函数,``_reasoning`` 和 ``_acting``。
-
-提示词格式化
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-提示词格式化器(Prompt Formatter)是 AgentScope 中保证 LLM 兼容性的核心组件,负责将消息对象转换为 LLM API 所需的格式。
-
-此外,诸如提示工程、截断和消息验证等附加功能也可以在格式化器中实现。
-
-在格式化器中,"多智能体"(或"多实体")概念与常见的多智能体编排概念不同。
-它专注于给定消息中包含多个身份实体的场景,因此 LLM API 中常用的 ``role`` 字段(通常取值为 "user"、"assistant" 或 "system")无法区分它们。
-
-因此,AgentScope 提供 MultiAgentFormatter 来处理这种场景,通常用于游戏、多人聊天和社交仿真。
-
-.. note:: 多智能体工作流 **!=** 格式化器中的多智能体。例如,即使以下代码片段可能涉及多个
- 智能体(``tool_agent`` 和 ``tool_function`` 的调用者),但是输入的 ``query`` 参数
- 被包装成了 ``role`` 为 **“user”** 消息,因此 ``role`` 字段仍然可以区分它们。
-
- .. code-block:: python
-
- async def tool_function(query: str) -> str:
- \"\"\"调用另一个智能体的工具函数\"\"\"
- msg = Msg("user", query, role="user")
- tool_agent = Agent(name="Programmer")
- return await tool_agent(msg)
-
- 理解这种区别有助于开发者了解格式化器部分中单智能体和多智能体的区别。
-
-
-长期记忆
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-虽然 AgentScope 为短期记忆和长期记忆提供了不同的基类,但是 AgentScope 中并没有严格区分它们的作用。
-
-在我们看来,一切都应该是 **需求驱动的**。只要开发者的需求得到了很好的满足,完全可以只使用一个强大的记忆系统。
-
-这里为了确保 AgentScope 的灵活性,我们为长期记忆提供了两种运行和管理方式,开发者可以根据自己的需要进行选择。
-其中“agent_control”模式允许智能体自己主动管理长期记忆,而“static_control”则是传统的由开发者管理的长期记忆
-模式。
-"""
diff --git a/docs/tutorial/zh_CN/src/quickstart_message.py b/docs/tutorial/zh_CN/src/quickstart_message.py
deleted file mode 100644
index 8136c381a..000000000
--- a/docs/tutorial/zh_CN/src/quickstart_message.py
+++ /dev/null
@@ -1,267 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _message:
-
-创建消息
-====================
-
-消息是 AgentScope 中的核心概念,用于支持多模态数据、工具 API、信息存储/交换和提示构建。
-
-一个消息由四个字段组成:
-
-- ``name``,
-- ``role``,
-- ``content``,以及
-- ``metadata``
-
-这些字段的类型和含义如下:
-
-.. list-table:: 消息对象中的字段
- :header-rows: 1
-
- * - 字段
- - 类型
- - 描述
- * - name
- - ``str``
- - 消息发送者的名称/身份
- * - role
- - | ``Literal[``
- | ``"system",``
- | ``"assistant",``
- | ``"user"``
- | ``]``
- - 消息发送者的角色,必须是 "system"、"assistant" 或 "user" 之一。
- * - content
- - ``str | list[ContentBlock]``
- - 消息包含的数据,可以是字符串或 block 的列表。
- * - metadata
- - ``dict[str, JSONSerializableObject] | None``
- - 包含额外元数据的字典,通常用于结构化输出。
-
-.. tip:: - 在具有多个身份实体的应用程序中,``name`` 字段用于区分不同的身份。
- - 建议将 ``metadata`` 字段用于结构化输出,在 AgentScope 内置的模块中,``metadata`` 不会参与 LLM 的提示构建。
-
-接下来,我们根据不同的场景分别介绍 ``content`` 字段中支持的不同数据结构(block)。
-"""
-
-from agentscope.message import (
- Msg,
- Base64Source,
- TextBlock,
- ThinkingBlock,
- ImageBlock,
- AudioBlock,
- VideoBlock,
- ToolUseBlock,
- ToolResultBlock,
-)
-import json
-
-# %%
-# 创建文本消息
-# -----------------------------
-# 通过提供 ``name``、``role`` 和 ``content`` 字段来创建消息对象。
-#
-
-msg = Msg(
- name="Jarvis",
- role="assistant",
- content="你好!我能怎么帮助你?",
-)
-
-print(f"发送者的名称: {msg.name}")
-print(f"发送者的角色: {msg.role}")
-print(f"消息的内容: {msg.content}")
-
-# %%
-# 创建多模态消息
-# --------------------------------------
-# Message 类通过提供不同的 block 结构来支持多模态内容:
-#
-# .. list-table:: AgentScope 中的多模态 block
-# :header-rows: 1
-#
-# * - 类
-# - 描述
-# - 示例
-# * - TextBlock
-# - 纯文本数据
-# - .. code-block:: python
-#
-# TextBlock(
-# type="text",
-# text="Hello, world!"
-# )
-# * - ImageBlock
-# - 图像数据
-# - .. code-block:: python
-#
-# ImageBlock(
-# type="image",
-# source=URLSource(
-# type="url",
-# url="https://example.com/image.jpg"
-# )
-# )
-# * - AudioBlock
-# - 音频数据
-# - .. code-block:: python
-#
-# AudioBlock(
-# type="audio",
-# source=URLSource(
-# type="url",
-# url="https://example.com/audio.mp3"
-# )
-# )
-# * - VideoBlock
-# - 视频数据
-# - .. code-block:: python
-#
-# VideoBlock(
-# type="video",
-# source=URLSource(
-# type="url",
-# url="https://example.com/video.mp4"
-# )
-# )
-#
-# 对于 ``ImageBlock``、``AudioBlock`` 和 ``VideoBlock``,还可以使用 base64 编码的字符串作为数据源(Source):
-#
-
-msg = Msg(
- name="Jarvis",
- role="assistant",
- content=[
- TextBlock(
- type="text",
- text="这是一个包含 base64 编码数据的多模态消息。",
- ),
- ImageBlock(
- type="image",
- source=Base64Source(
- type="base64",
- media_type="image/jpeg",
- data="/9j/4AAQSkZ...",
- ),
- ),
- AudioBlock(
- type="audio",
- source=Base64Source(
- type="base64",
- media_type="audio/mpeg",
- data="SUQzBAAAAA...",
- ),
- ),
- VideoBlock(
- type="video",
- source=Base64Source(
- type="base64",
- media_type="video/mp4",
- data="AAAAIGZ0eX...",
- ),
- ),
- ],
-)
-
-# %%
-# 创建推理消息
-# --------------------------------------
-# ``ThinkingBlock`` 用于支持推理模型,包含模型的思考过程。
-#
-
-msg_thinking = Msg(
- name="Jarvis",
- role="assistant",
- content=[
- ThinkingBlock(
- type="thinking",
- thinking="我正在为 AgentScope 构建一个思考块的示例。",
- ),
- TextBlock(
- type="text",
- text="这是一个思考块的示例。",
- ),
- ],
-)
-
-# %%
-# .. _tool-block:
-#
-# 创建工具使用/结果消息
-# --------------------------------------
-# ``ToolUseBlock`` 和 ``ToolResultBlock`` 用于支持工具 API:
-#
-
-msg_tool_call = Msg(
- name="Jarvis",
- role="assistant",
- content=[
- ToolUseBlock(
- type="tool_use",
- id="343",
- name="get_weather",
- input={
- "location": "Beijing",
- },
- ),
- ],
-)
-
-msg_tool_res = Msg(
- name="system",
- role="system",
- content=[
- ToolResultBlock(
- type="tool_result",
- id="343",
- name="get_weather",
- output="北京的天气是晴天,温度为 25°C。",
- ),
- ],
-)
-
-
-# %%
-# .. tip:: AgentScope 中,通常使用 ``role`` 为“system”的消息来记录工具函数的执行结果。有关 AgentScope 中工具的更多信息,请参考 :ref:`tool` 部分。
-#
-# 序列化和反序列化
-# ------------------------------------------------
-# 消息对象可以分别通过 ``to_dict`` 和 ``from_dict`` 方法进行序列化和反序列化。
-
-serialized_msg = msg.to_dict()
-
-print(type(serialized_msg))
-print(json.dumps(serialized_msg, indent=4, ensure_ascii=False))
-
-# %%
-# 从 JSON 格式的数据反序列化消息。
-
-new_msg = Msg.from_dict(serialized_msg)
-
-print(type(new_msg))
-print(f'消息的发送者: "{new_msg.name}"')
-print(f'发送者的角色: "{new_msg.role}"')
-print(f'消息的内容: "{json.dumps(new_msg.content, indent=4, ensure_ascii=False)}"')
-
-# %%
-# 属性函数
-# ------------------------------------------------
-# 为了便于使用 Msg 对象,AgentScope 提供了以下函数:
-#
-# .. list-table:: Msg 对象的函数
-# :header-rows: 1
-#
-# * - 函数
-# - 参数
-# - 描述
-# * - ``get_text_content``
-# -
-# - 将所有 ``TextBlock`` 中的内容收集到单个字符串中(用 "\\n" 分隔)。
-# * - ``get_content_blocks``
-# - ``block_type``
-# - 返回指定类型的内容块列表。如果未提供 ``block_type``,则以块格式返回全部内容。
-# * - ``has_content_blocks``
-# - ``block_type``
-# - 检查消息是否具有指定类型的内容块。``str`` 内容会被视为 ``TextBlock`` 类型。
diff --git a/docs/tutorial/zh_CN/src/task_a2a.py b/docs/tutorial/zh_CN/src/task_a2a.py
deleted file mode 100644
index 954c21230..000000000
--- a/docs/tutorial/zh_CN/src/task_a2a.py
+++ /dev/null
@@ -1,213 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _a2a:
-
-A2A 智能体
-============================
-
-A2A(Agent-to-Agent)是一种开放标准协议,用于实现不同 AI 智能体之间的互操作通信。
-
-AgentScope 从获取 Agent Card 信息和连接远程智能体两个层面提供对 A2A 协议的支持,涉及到的相关 API 如下:
-
-.. list-table:: A2A 相关类
- :header-rows: 1
-
- * - 类
- - 描述
- * - ``A2AAgent``
- - 用于与远程 A2A 智能体通信的智能体类
- * - ``A2AChatFormatter``
- - 用于在 AgentScope 消息和 A2A 消息/任务格式之间进行转换的格式化器
- * - ``AgentCardResolverBase``
- - Agent Card 解析器基类
- * - ``FileAgentCardResolver``
- - 从本地 JSON 文件加载 Agent Card 的解析器
- * - ``WellKnownAgentCardResolver``
- - 从 URL 的 well-known 路径获取 Agent Card 的解析器
- * - ``NacosAgentCardResolver``
- - 从 Nacos Agent 注册中心获取 Agent Card 的解析器
-
-本节将演示如何创建 ``A2aAgent`` 并与远程 A2A 智能体进行通信。
-
-.. note:: 注意 A2A 的支持为**实验性功能**,可能会在未来版本中发生变化。同时由于 A2A 协议自身
- 的局限性,因此功能上 ``A2AAgent`` 无法完全对齐 ``ReActAgent`` 等本地智能体,包括:
-
- - 仅支持 chatbot 场景,即仅支持一个用户与一个智能体之间的对话(不影响 handsoff/router 等使用方式)
- - 不支持在对话过程中实时打断
- - 不支持 agentic 结构化输出
- - 目前实现中,``observe`` 方法收到的消息会被存储在本地,并在调用 ``reply`` 方法时一并发送给远程智能体,因此如果最后若干 ``observe`` 调用后未发生 ``reply`` 调用,则这些消息不会被远程智能体看到
-
-
-"""
-
-# %%
-# 获取 Agent Card
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 首先,我们需要获得一个 Agent Card 来连接对应的智能体。Agent Card 中包含了智能体的名称,描述,能力以及连接方式等信息。
-#
-# 手动创建 Agent Card 对象
-# --------------------------------
-#
-# 在已知 Agent Card 各项信息的情况下,可以直接从 `a2a.types.AgentCard` 手动创建 Agent Card 对象。
-#
-
-from a2a.types import AgentCard, AgentCapabilities
-from v2.nacos import ClientConfig
-
-from agentscope.a2a import WellKnownAgentCardResolver, NacosAgentCardResolver
-from agentscope.agent import A2AAgent, UserAgent
-from agentscope.message import Msg, TextBlock
-from agentscope.tool import ToolResponse
-
-# 创建 Agent Card 对象
-agent_card = AgentCard(
- name="Friday", # 智能体名称
- description="一个有趣的聊天伙伴", # 智能体描述
- url="http://localhost:8000", # 智能体的 RPC 服务地址
- version="1.0.0", # 智能体版本
- capabilities=AgentCapabilities( # 智能体能力配置
- push_notifications=False,
- state_transition_history=True,
- streaming=True,
- ),
- default_input_modes=["text/plain"], # 支持的输入格式
- default_output_modes=["text/plain"], # 支持的输出格式
- skills=[], # 智能体技能列表
-)
-
-# %%
-#
-# 从远程服务获取 Agent Card
-# --------------------------------
-# 同时,AgentScope 也支持通过多种方式动态获取 Agent Card,包括从本地文件加载、从远程服务 (well-known server) 的标准路径获取以及从 Nacos 注册中心获取等。
-# 这里以 ``WellKnownAgentCardResolver`` 为例,从远程服务的标准路径获取 Agent Card:
-#
-
-
-async def agent_card_from_well_known_website() -> AgentCard:
- """从远程服务的 well-known 路径获取 Agent Card 的示例。"""
- # 创建 Agent Card 解析器
- resolver = WellKnownAgentCardResolver(
- base_url="http://localhost:8000",
- )
- # 获取并返回 Agent Card
- return await resolver.get_agent_card()
-
-
-# %%
-# 从本地文件加载 Agent Card
-# --------------------------------
-#
-# ``FileAgentCardResolver`` 类支持从本地 JSON 文件加载 Agent Card,适用于配置文件管理的场景。
-# 一个 JSON 格式的 Agent Card 样例如下所示:
-#
-# .. code-block:: json
-# :caption: 示例 Agent Card JSON 文件内容
-#
-# {
-# "name": "RemoteAgent",
-# "url": "http://localhost:8000",
-# "description": "远程 A2A 智能体",
-# "version": "1.0.0",
-# "capabilities": {},
-# "default_input_modes": ["text/plain"],
-# "default_output_modes": ["text/plain"],
-# "skills": []
-# }
-#
-# 通过 ``FileAgentCardResolver`` 可以方便地加载该文件:
-#
-
-
-async def agent_card_from_file() -> AgentCard:
- """从本地 JSON 文件加载 Agent Card 的示例。"""
- from agentscope.a2a import FileAgentCardResolver
-
- # 从 JSON 文件加载 Agent Card
- resolver = FileAgentCardResolver(
- file_path="./agent_card.json", # JSON 文件路径
- )
- # 获取并返回 Agent Card
- return await resolver.get_agent_card()
-
-
-# %%
-# 从 Nacos 注册中心获取 Agent Card
-# --------------------------------
-#
-# Nacos 是一款开源的动态服务发现、配置管理和服务管理平台,在 3.1.0 版本中引入了 Agent 注册中心功能,支持 A2A 智能体的分布式注册、发现和版本管理。
-#
-# .. important:: 使用 ``NacosAgentCardResolver`` 的前提是用户已经部署了 3.1.0 版本以上的 Nacos 服务端,部署与注册流程请参考`官方文档 <https://nacos.io/docs/latest/quickstart/quick-start>`_。
-#
-
-
-async def agent_card_from_nacos() -> AgentCard:
- """从 Nacos 注册中心获取 Agent Card 的示例。"""
-
- # 创建 Nacos Agent Card 解析器
- resolver = NacosAgentCardResolver(
- remote_agent_name="my-remote-agent", # Nacos 中注册的智能体名称
- nacos_client_config=ClientConfig(
- server_addresses="http://localhost:8848", # Nacos 服务器地址
- # 其他可选配置项
- ),
- )
- # 获取并返回 Agent Card
- return await resolver.get_agent_card()
-
-
-# %%
-# 构建 A2A 智能体
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope 提供的 ``A2AAgent`` 类用于与远程 A2A 智能体进行通信,其使用方式与普通智能体类似。
-
-agent = A2AAgent(agent_card=agent_card)
-
-# %%
-# 利用 ``A2AAgent``,开发者可以构建 chatbot 场景的聊天,或是封装成工具函数,从而构建 handsoff/router 等更复杂的应用场景。
-# 目前 ``A2AAgent`` 支持的格式协议转换由 ``agentscope.formatter.A2AChatFormatter`` 负责,支持
-#
-# - 将 AgentScope 的 ``Msg`` 消息转换为 A2A 协议的 ``Message`` 格式
-# - 将 A2A 协议的响应转换回 AgentScope 的 ``Msg`` 格式
-# - 将 A2A 协议的 ``Task`` 相应转换成 AgentScope 的 ``Msg`` 格式
-# - 支持文本、图像、音频、视频等多种内容类型
-#
-
-
-async def a2a_in_chatbot() -> None:
- """使用 A2AAgent 进行聊天的示例。"""
-
- user = UserAgent("user")
-
- msg = None
- while True:
- msg = await user(msg)
- if msg.get_text_content() == "exit":
- break
- msg = await agent(msg)
-
-
-# %%
-# 或是如下封装成工具函数用于调用:
-
-
-async def create_worker(query: str) -> ToolResponse:
- """通过子智能体完成给定的任务
-
- Args:
- query (`str`):
- 需要子智能体完成的任务描述
- """
- res = await agent(
- Msg("user", query, "user"),
- )
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=res.get_text_content(),
- ),
- ],
- )
diff --git a/docs/tutorial/zh_CN/src/task_agent.py b/docs/tutorial/zh_CN/src/task_agent.py
deleted file mode 100644
index ad6041afa..000000000
--- a/docs/tutorial/zh_CN/src/task_agent.py
+++ /dev/null
@@ -1,400 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _agent:
-
-智能体
-=========================
-
-在章我们首先重点介绍 AgentScope 中的 ReAct 智能体,然后简要介绍如何从零开始自定义智能体。
-
-ReAct 智能体
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-在 AgentScope 中,``ReActAgent`` 类将各种功能集成到最终实现中,具体包括
-
-.. list-table:: ``ReActAgent`` 的功能特性
- :header-rows: 1
-
- * - 功能特性
- - 参考文档
- * - 支持实时介入(Realtime Steering)
- -
- * - 支持记忆压缩
- -
- * - 支持并行工具调用
- -
- * - 支持结构化输出
- -
- * - 支持智能体自主管理工具(Meta tool)
- - :ref:`tool`
- * - 支持函数粒度的 MCP 控制
- - :ref:`mcp`
- * - 支持智能体自主控制长期记忆
- - :ref:`long-term-memory`
- * - 支持自动状态管理
- - :ref:`state`
-
-
-由于篇幅限制,本章我们仅演示 ``ReActAgent`` 类的前三个功能特性,其它功能我们在对应的章节进行介绍。
-
-"""
-
-import asyncio
-import json
-import os
-from datetime import datetime
-import time
-
-from pydantic import BaseModel, Field
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import TextBlock, Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit, ToolResponse
-
-
-# %%
-# 实时控制
-# ---------------------------------------
-#
-# 实时控制指 **允许用户随时中断智能体的回复,介入智能体的执行过程**,AgentScope 基于 asyncio 取消机制实现了该功能。
-#
-# 具体来说,AgentScope 中智能体提供了 ``interrupt`` 方法,当该函数被调用时,它将取消当前正在执行的 `reply` 函数,并执行 ``handle_interrupt`` 方法进行后处理。
-#
-# .. hint:: 结合 :ref:`tool` 中提到的 AgentScope 支持工具函数流式返回结果的功能,工具执行过程中如果执行时间过长或偏离用户期望,用户可以通过在终端中按 Ctrl+C 或在代码中调用智能体的
-# ``interrupt`` 方法来中断工具执行。
-#
-# .. hint:: ``ReActAgent`` 中提供了完善的中断逻辑,智能体的记忆和状态会在中断发生时被正确的保存。
-#
-# 中断逻辑已在 ``AgentBase`` 类中作为基本功能实现,并提供 ``handle_interrupt`` 抽象方法供用户自定义
-# 中断的后处理,如下所示:
-#
-# .. code-block:: python
-#
-# # AgentBase 的代码片段
-# class AgentBase:
-# ...
-# async def __call__(self, *args: Any, **kwargs: Any) -> Msg:
-# ...
-# reply_msg: Msg | None = None
-# try:
-# self._reply_task = asyncio.current_task()
-# reply_msg = await self.reply(*args, **kwargs)
-#
-# except asyncio.CancelledError:
-# # 捕获中断并通过 handle_interrupt 方法处理
-# reply_msg = await self.handle_interrupt(*args, **kwargs)
-#
-# ...
-#
-# @abstractmethod
-# async def handle_interrupt(self, *args: Any, **kwargs: Any) -> Msg:
-# pass
-#
-#
-# 在 ``ReActAgent`` 类的实现中,我们返回一个固定消息"I noticed that you have interrupted me. What can I do for you?",如下所示:
-#
-# .. figure:: ../../_static/images/interruption_zh.gif
-# :width: 100%
-# :align: center
-# :class: bordered-image
-# :alt: 中断示例
-#
-# 中断智能体 ``reply`` 的执行过程
-#
-# 开发者可以通过覆盖 ``handle_interrupt`` 函数实现自定义的中断后处理逻辑,例如,调用 LLM 生成对中断的简单响应。
-#
-#
-# 记忆压缩
-# ----------------------------------------
-# 随着对话的不断增长,记忆中的 token 数量可能会超过模型的上下文限制或导致推理速度变慢。
-# ``ReActAgent`` 提供了自动记忆压缩功能来解决这个问题。
-#
-# **基础用法**
-#
-# 要启用记忆压缩,在初始化 ``ReActAgent`` 时提供一个 ``CompressionConfig`` 实例:
-#
-# .. code-block:: python
-#
-# from agentscope.agent import ReActAgent
-# from agentscope.token import CharTokenCounter
-#
-# agent = ReActAgent(
-# name="助手",
-# sys_prompt="你是一个有用的助手。",
-# model=model,
-# formatter=formatter,
-# compression_config=ReActAgent.CompressionConfig(
-# enable=True,
-# agent_token_counter=CharTokenCounter(), # 智能体的 token 计数器
-# trigger_threshold=10000, # 超过 10000 个 token 时触发压缩
-# keep_recent=3, # 保持最近 3 条消息不被压缩
-# ),
-# )
-#
-# 启用记忆压缩后,智能体会监控其记忆中的 token 数量。
-# 一旦超过 ``trigger_threshold``,智能体会自动:
-#
-# 1. 识别尚未被压缩的消息(通过 ``exclude_mark``)
-# 2. 保持最近 ``keep_recent`` 条消息不被压缩(以保留最近的上下文)
-# 3. 将较早的消息发送给 LLM 生成结构化摘要
-# 4. 使用 ``MemoryMark.COMPRESSED`` 标记已压缩的消息(通过 ``update_messages_mark``)
-# 5. 将摘要存储在记忆中(通过 ``update_compressed_summary``)
-#
-# .. important:: 压缩采用**标记机制**而非替换消息。旧消息被标记为已压缩,并通过 ``exclude_mark=MemoryMark.COMPRESSED`` 在后续检索中被排除,而生成的摘要则单独存储,在需要时检索。这种方式保留了原始消息,允许灵活的记忆管理。关于标记功能的更多详情,请参考 :ref:`memory`。
-#
-# 默认情况下,压缩摘要被结构化为五个关键字段:
-#
-# - **task_overview**:用户的核心请求和成功标准
-# - **current_state**:到目前为止已完成的工作,包括文件和输出
-# - **important_discoveries**:技术约束、决策、错误和失败的尝试
-# - **next_steps**:完成任务所需的具体操作
-# - **context_to_preserve**:用户偏好、领域细节和做出的承诺
-#
-# **自定义压缩**
-#
-# 可以通过指定 ``summary_schema``、``summary_template`` 和 ``compression_prompt`` 参数来自定义压缩的工作方式。
-#
-# - **summary_schema**:使用 Pydantic 模型定义压缩摘要的结构
-# - **compression_prompt**:指导 LLM 如何生成摘要
-# - **summary_template**:格式化压缩摘要如何呈现给智能体
-#
-# 下面是一个自定义压缩的示例:
-#
-# .. code-block:: python
-#
-# from pydantic import BaseModel, Field
-#
-# # 定义自定义摘要结构
-# class CustomSummary(BaseModel):
-# main_topic: str = Field(
-# max_length=200,
-# description="对话的主题"
-# )
-# key_points: str = Field(
-# max_length=400,
-# description="讨论的重要观点"
-# )
-# pending_tasks: str = Field(
-# max_length=200,
-# description="待完成的任务"
-# )
-#
-# # 使用自定义压缩配置创建智能体
-# agent = ReActAgent(
-# name="助手",
-# sys_prompt="你是一个有用的助手。",
-# model=model,
-# formatter=formatter,
-# compression_config=ReActAgent.CompressionConfig(
-# enable=True,
-# agent_token_counter=CharTokenCounter(),
-# trigger_threshold=10000,
-# keep_recent=3,
-# # 结构化摘要的自定义 schema
-# summary_schema=CustomSummary,
-# # 指导压缩的自定义提示
-# compression_prompt=(
-# "<system-hint>请总结上述对话,"
-# "重点关注主题、关键讨论点和待完成任务。</system-hint>"
-# ),
-# # 格式化摘要的自定义模板
-# summary_template=(
-# "<system-info>对话摘要:\n"
-# "主题:{main_topic}\n\n"
-# "关键观点:\n{key_points}\n\n"
-# "待完成任务:\n{pending_tasks}"
-# "</system-info>"
-# ),
-# ),
-# )
-#
-# ``summary_template`` 使用 ``summary_schema`` 中定义的字段作为占位符
-# (例如 ``{main_topic}``、``{key_points}``)。在 LLM 生成结构化摘要后,
-# 这些占位符将被实际值替换。
-#
-# .. note:: 智能体确保工具使用和工具结果对在压缩过程中保持在一起,以维护对话流程的完整性。
-#
-# .. tip:: 可以通过指定不同的 ``compression_model`` 和 ``compression_formatter`` 来使用更小、更快的模型进行压缩,以降低成本和延迟。
-#
-#
-#
-# 并行工具调用
-# ----------------------------------------
-# ``ReActAgent`` 通过在其构造函数中提供 ``parallel_tool_calls`` 参数来支持并行工具调用。
-# 当 LLM 生成多个工具调用且 ``parallel_tool_calls`` 设置为 ``True`` 时,
-# 它们将通过 ``asyncio.gather`` 函数并行执行。
-#
-# .. note:: ``ReActAgent`` 中的工具并行调用是基于异步 ``asyncio.gather`` 实现的,因此,只有当工具函数是异步函数,同时工具函数内也为异步逻辑时,才能最大程度发挥工具并行执行的效果
-#
-# .. note:: 运行时请确保模型层面支持工具并行调用,并且相应参数设置正确(可以通过 ``generate_kwargs`` 传入),例如对于DashScope API,需要设置 ``parallel_tool_calls`` 为 ``True``,否则将无法进行并行工具调用。
-
-
-# 准备一个工具函数
-async def example_tool_function(tag: str) -> ToolResponse:
- """一个示例工具函数"""
- start_time = datetime.now().strftime("%H:%M:%S.%f")
-
- # 休眠 3 秒以模拟长时间运行的任务
- await asyncio.sleep(3)
-
- end_time = datetime.now().strftime("%H:%M:%S.%f")
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"标签 {tag} 开始于 {start_time},结束于 {end_time}。",
- ),
- ],
- )
-
-
-toolkit = Toolkit()
-toolkit.register_tool_function(example_tool_function)
-
-# 创建一个 ReAct 智能体
-agent = ReActAgent(
- name="Jarvis",
- sys_prompt="你是一个名为 Jarvis 的有用助手。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- # 启用并行工具调用
- generate_kwargs={
- "parallel_tool_calls": True,
- },
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- parallel_tool_calls=True,
-)
-
-
-async def example_parallel_tool_calls() -> None:
- """并行工具调用示例"""
- # 提示智能体同时生成两个工具调用
- await agent(
- Msg(
- "user",
- "同时生成两个 'example_tool_function' 函数的工具调用,标签分别为 'tag1' 和 'tag2',以便它们可以并行执行。",
- "user",
- ),
- )
-
-
-asyncio.run(example_parallel_tool_calls())
-
-# %%
-# 结构化输出
-# ----------------------------------------
-# AgentScope 中的结构化输出是与工具调用紧密结合的。具体来说,``ReActAgent`` 类在其 ``__call__`` 函数中接收 ``pydantic.BaseModel`` 的子类作为 ``structured_model`` 参数。
-# 从而提供复杂的结构化输出限制。
-# 然后我们可以从 返回消息的 ``metadata`` 字段获取结构化输出。
-#
-# 以介绍爱因斯坦为例:
-#
-
-# 创建一个 ReAct 智能体
-agent = ReActAgent(
- name="Jarvis",
- sys_prompt="你是一个名为 Jarvis 的有用助手。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
-)
-
-
-# 结构化模型
-class Model(BaseModel):
- name: str = Field(description="人物的姓名")
- description: str = Field(description="人物的一句话描述")
- age: int = Field(description="年龄")
- honor: list[str] = Field(description="人物荣誉列表")
-
-
-async def example_structured_output() -> None:
- """结构化输出示例"""
- res = await agent(
- Msg(
- "user",
- "介绍爱因斯坦",
- "user",
- ),
- structured_model=Model,
- )
- print("\n结构化输出:")
- print(json.dumps(res.metadata, indent=4, ensure_ascii=False))
-
-
-asyncio.run(example_structured_output())
-
-# %%
-# 自定义智能体
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 提供了两个基类:``AgentBase`` 和 ``ReActAgentBase``,它们在抽象方法和支持的钩子函数方面有所不同。
-# 具体来说,``ReActAgentBase`` 扩展了 ``AgentBase``,增加了额外的 ``_reasoning`` 和 ``_acting`` 抽象方法,以及它们的前置和后置钩子函数。
-#
-# 开发者可以根据需要选择继承这两个基类中的任一个。
-# 我们总结了 ``agentscope.agent`` 模块下的智能体如下:
-#
-# .. list-table:: AgentScope 中的智能体类
-# :header-rows: 1
-#
-# * - 类
-# - 抽象方法
-# - 支持的钩子函数
-# - 描述
-# * - ``AgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``print``
-# | ``handle_interrupt``
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# - 所有智能体的基类,提供基本接口和钩子。
-# * - ``ReActAgentBase``
-# - | ``reply``
-# | ``observe``
-# | ``print``
-# | ``handle_interrupt``
-# | ``_reasoning``
-# | ``_acting``
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# | pre\_/post_reasoning
-# | pre\_/post_acting
-# - ReAct 类智能体的抽象类,扩展了 ``AgentBase``,增加了 ``_reasoning`` 和 ``_acting`` 抽象方法及其钩子。
-# * - ``ReActAgent``
-# - \-
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# | pre\_/post_reasoning
-# | pre\_/post_acting
-# - ``ReActAgentBase`` 的实现
-# * - ``UserAgent``
-# -
-# -
-# - 代表用户的特殊智能体,用于与智能体交互
-# * - ``A2aAgent``
-# - \-
-# - | pre\_/post_reply
-# | pre\_/post_observe
-# | pre\_/post_print
-# - 用于与远程 A2A 代理通信的智能体,详见 :ref:`a2a`
-#
-#
-#
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`tool`
-# - :ref:`hook`
-# - :ref:`a2a`
-#
diff --git a/docs/tutorial/zh_CN/src/task_agent_skill.py b/docs/tutorial/zh_CN/src/task_agent_skill.py
deleted file mode 100644
index c2710f3aa..000000000
--- a/docs/tutorial/zh_CN/src/task_agent_skill.py
+++ /dev/null
@@ -1,124 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _agent_skill:
-
-智能体技能
-============================
-
-`智能体技能(Agent skill) <https://claude.com/blog/skills>`_ 是 Anthropic 提出的一种提升智能体在特定任务上能力的方法。
-
-AgentScope 通过 ``Toolkit`` 类提供了对智能体技能的内置支持,让开发者可以注册和管理智能体技能。
-
-相关 API 如下:
-
-.. list-table:: ``Toolkit`` 类中的智能体技能 API
- :header-rows: 1
-
- * - API
- - 描述
- * - ``register_agent_skill``
- - 从指定目录注册智能体技能
- * - ``remove_agent_skill``
- - 根据名称移除已注册的智能体技能
- * - ``get_agent_skill_prompt``
- - 获取所有已注册智能体技能的提示词,可以附加到智能体的系统提示词中
-
-本节将演示如何注册智能体技能并在 ReActAgent 类中使用它们。
-"""
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit
-
-# %%
-# 注册智能体技能
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 首先,我们需要准备一个智能体技能目录,该目录需要遵循 `Anthropic blog <https://claude.com/blog/skills>`_ 中指定的要求。
-#
-# .. note:: 技能目录必须包含一个 ``SKILL.md`` 文件,其中包含 YAML 前置元数据和指令说明。
-#
-# 这里我们创建一个示例技能目录 ``sample_skill``,包含以下文件:
-#
-# .. code-block:: markdown
-#
-# ---
-# name: sample_skill
-# description: 用于演示的示例智能体技能
-# ---
-#
-# # 示例技能
-# ...
-#
-
-os.makedirs("sample_skill", exist_ok=True)
-with open("sample_skill/SKILL.md", "w", encoding="utf-8") as f:
- f.write(
- """---
-name: sample_skill
-description: 用于演示的示例智能体技能
----
-
-# 示例技能
-...
-""",
- )
-
-# %%
-# 然后,我们可以使用 ``Toolkit`` 类的 ``register_agent_skill`` API 注册技能。
-#
-
-toolkit = Toolkit()
-
-toolkit.register_agent_skill("sample_skill")
-
-# %%
-# 之后,我们可以使用 ``get_agent_skill_prompt`` API 获取所有已注册智能体技能的提示词
-
-agent_skill_prompt = toolkit.get_agent_skill_prompt()
-print("智能体技能提示词:")
-print(agent_skill_prompt)
-
-# %%
-# 当然,我们也可以在创建 ``Toolkit`` 实例时自定义提示词模板。
-
-custom_toolkit = Toolkit(
- # 向智能体/大语言模型介绍如何使用技能的指令
- agent_skill_instruction="<system-info>为你提供了一组技能,每个技能都在一个目录中,并由 SKILL.md 文件进行描述。</system-info>",
- # 用于格式化每个技能提示词的模板,必须包含 {name}、{description} 和 {dir} 字段
- agent_skill_template="- {name}(in directory '{dir}'): {description}",
-)
-
-custom_toolkit.register_agent_skill("sample_skill")
-agent_skill_prompt = custom_toolkit.get_agent_skill_prompt()
-print("自定义智能体技能提示词:")
-print(agent_skill_prompt)
-
-# %%
-# 在 ReActAgent 中集成智能体技能
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope 中的 `ReActAgent` 类会自动将智能体技能提示词附加到系统提示词中。
-#
-# 我们可以按如下方式创建一个带有已注册智能体技能的 ReAct 智能体:
-#
-# .. important:: 使用智能体技能时,智能体必须配备文本文件读取或 shell 命令工具,以便访问 `SKILL.md` 文件中的技能指令。
-#
-
-agent = ReActAgent(
- name="Friday",
- sys_prompt="你是一个名为 Friday 的智能助手。",
- model=DashScopeChatModel(
- model_name="qwen3-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
-)
-
-print("带有智能体技能的系统提示词:")
-print(agent.sys_prompt)
diff --git a/docs/tutorial/zh_CN/src/task_embedding.py b/docs/tutorial/zh_CN/src/task_embedding.py
deleted file mode 100644
index a6a791f13..000000000
--- a/docs/tutorial/zh_CN/src/task_embedding.py
+++ /dev/null
@@ -1,132 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _embedding:
-
-嵌入(Embedding)
-=========================
-
-AgentScope 中,嵌入模块提供了用于向量生成的统一接口,具有以下特性:
-
-- 支持 **缓存 embedding** 以避免冗余的 API 调用
-- 支持 **不同 embedding API 提供商** 并提供一致的接口
-
-AgentScope 内置支持以下 API:
-
-.. list-table::
- :header-rows: 1
-
- * - API 提供商
- - 类
- * - OpenAI
- - ``OpenAITextEmbedding``
- * - Gemini
- - ``GeminiTextEmbedding``
- * - DashScope
- - ``DashScopeTextEmbedding``, ``DashScopeMultiModalEmbedding``
- * - Ollama
- - ``OllamaTextEmbedding``
-
-所有类都继承自 ``EmbeddingModelBase``,实现了 ``__call__`` 方法并生成包含嵌入和使用信息的 ``EmbeddingResponse`` 对象。
-其中 ``DashScopeMultiModalEmbedding`` 支持文本,图像和视频的多模态嵌入。
-
-以 DashScope 嵌入类为例,可以按如下方式使用:
-"""
-
-import asyncio
-import os
-import tempfile
-
-from agentscope.embedding import DashScopeTextEmbedding, FileEmbeddingCache
-
-
-async def example_dashscope_embedding() -> None:
- """DashScope 文本嵌入的使用示例。"""
- texts = [
- "法国的首都是什么?",
- "巴黎是法国的首都城市。",
- ]
-
- # 初始化 DashScope 文本嵌入实例
- embedding_model = DashScopeTextEmbedding(
- model_name="text-embedding-v2",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- )
-
- # 从模型获取嵌入
- response = await embedding_model(texts)
-
- print("嵌入 ID: ", response.id)
- print("嵌入创建时间: ", response.created_at)
- print("嵌入使用情况: ", response.usage)
- print("嵌入向量:")
- print(response.embeddings)
-
-
-asyncio.run(example_dashscope_embedding())
-
-# %%
-# 可以通过继承 ``EmbeddingModelBase`` 并实现 ``__call__`` 方法来自定义 embedding 模型。
-#
-# Embedding 缓存
-# ---------------------
-# AgentScope 提供了用于缓存 embedding 的基类 ``EmbeddingCacheBase``,以及基于文件的实现 ``FileEmbeddingCache``。
-# 它在 embedding 模块中的工作方式如下:
-#
-# .. image:: ../../_static/images/embedding_cache.png
-# :align: center
-# :width: 90%
-#
-# 要使用缓存,只需将 ``FileEmbeddingCache`` 实例(或自定义缓存)传给模型的构造函数,如下所示:
-#
-
-
-async def example_embedding_cache() -> None:
- """演示带有缓存功能的 embedding。"""
- # 示例文本
- texts = [
- "法国的首都是什么?",
- "巴黎是法国的首都城市。",
- ]
-
- # 为缓存演示创建临时目录
- # 在实际应用中,建议使用持久目录以最大发挥缓存效果
- cache_dir = tempfile.mkdtemp(prefix="embedding_cache_")
- print(f"使用缓存目录: {cache_dir}")
-
- # 使用缓存初始化嵌入模型
- # 为演示目的,我们将缓存限制为 100 个文件和 10MB
- embedder = DashScopeTextEmbedding(
- model_name="text-embedding-v3",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- embedding_cache=FileEmbeddingCache(
- cache_dir=cache_dir,
- max_file_number=100,
- max_cache_size=10, # 最大缓存大小(MB)
- ),
- )
-
- # 第一次调用 - 将从 API 获取并存储在缓存中
- print("\n=== 第一次 API 调用(无缓存命中)===")
- start_time = asyncio.get_event_loop().time()
- response1 = await embedder(texts)
- elapsed_time1 = asyncio.get_event_loop().time() - start_time
- print(f"来源: {response1.source}") # 应该是 'api'
- print(f"耗时: {elapsed_time1:.4f} 秒")
- print(f"使用的 token: {response1.usage.tokens}")
-
- # 使用相同文本的第二次调用 - 应该使用缓存
- print("\n=== 第二次 API 调用(预期缓存命中)===")
- start_time = asyncio.get_event_loop().time()
- response2 = await embedder(texts)
- elapsed_time2 = asyncio.get_event_loop().time() - start_time
- print(f"来源: {response2.source}") # 应该是 'cache'
- print(f"耗时: {elapsed_time2:.4f} 秒")
- print(
- f"使用的 token: {response2.usage.tokens}",
- ) # 缓存结果应该为 0
- print(
- f"速度提升: 使用缓存快 {elapsed_time1 / elapsed_time2:.1f} 倍",
- )
-
-
-asyncio.run(example_embedding_cache())
diff --git a/docs/tutorial/zh_CN/src/task_eval.py b/docs/tutorial/zh_CN/src/task_eval.py
deleted file mode 100644
index f58ecc4e4..000000000
--- a/docs/tutorial/zh_CN/src/task_eval.py
+++ /dev/null
@@ -1,255 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _eval:
-
-智能体评测
-=========================
-
-AgentScope 提供了一个内置的评测框架,用于评测智能体在不同任务和基准测试中的性能,主要特性包括:
-
-- 基于 `Ray <https://github.com/ray-project/ray>`_ 的并行和分布式评估
-- 支持中断后继续评估
-- [开发中] 评估结果可视化
-
-.. note:: 我们正在持续集成新的基准测试到 AgentScope 中:
-
- - ✅ `ACEBench <https://github.com/ACEBench/ACEBench>`_
- - 🚧 `GAIA <https://huggingface.co/datasets/gaia-benchmark/GAIA/tree/main>`_ 基准测试
-
-
-概述
----------------------------
-
-AgentScope 评估框架由几个关键组件组成:
-
-- **基准测试 (Benchmark)**: 用于系统性评估的任务集合
- - **任务 (Task)**: 包含输入、标准答案和指标的独立评估单元
- - **指标 (Metric)**: 评估解决方案质量的测量函数
-- **评估器 (Evaluator)**: 运行评估的引擎,聚合结果并分析性能
- - **评估器存储 (Evaluator Storage)**: 用于记录和检索评估结果的持久化存储
-- **解决方案 (Solution)**: 用户定义的解决方案
-
-.. figure:: ../../_static/images/evaluation.png
- :width: 90%
- :alt: AgentScope 评估框架
-
- *AgentScope 评估框架*
-
-AgentScope 当前的实现包括:
-
-- 评估器:
- - ``RayEvaluator``: 基于 ray 的评估器,支持并行和分布式评估。
- - ``GeneralEvaluator``: 通用评估器,按顺序运行任务,便于调试。
-- 基准测试:
- - ``ACEBench``: 用于评估智能体能力的基准测试。
-
-我们在 `GitHub 仓库 <https://github.com/agentscope-ai/agentscope/tree/main/examples/evaluation/ace_bench>`_ 中提供了一个使用 ``RayEvaluator`` 和 ACEBench 中智能体多步骤任务的玩具示例。
-
-核心组件
----------------
-我们将构建一个简单的玩学问题基准测试来演示如何使用 AgentScope 评估模块。
-"""
-
-TOY_BENCHMARK = [
- {
- "id": "math_problem_1",
- "question": "What is 2 + 2?",
- "ground_truth": 4.0,
- "tags": {
- "difficulty": "easy",
- "category": "math",
- },
- },
- {
- "id": "math_problem_2",
- "question": "What is 12345 + 54321 + 6789 + 9876?",
- "ground_truth": 83331,
- "tags": {
- "difficulty": "medium",
- "category": "math",
- },
- },
-]
-
-# %%
-# 从任务、解决方案和指标到基准测试
-# ~~~~~~~~~~~~~~~~~~~
-#
-# - 一个 ``SolutionOutput`` (Agent解决方案输出) 包含智能体生成的所有信息,包括轨迹和最终输出。
-# - 一个 ``Metric`` (评测指标) 代表一个单一的评估可调用实例,它将生成的解决方案(例如,轨迹或最终输出)与标准答案进行比较。
-# 在这个示例中,我们定义了一个指标,简单地检查解决方案中的 ``output`` 字段是否与标准答案匹配。
-
-from agentscope.evaluate import (
- SolutionOutput,
- MetricBase,
- MetricResult,
- MetricType,
-)
-
-
-class CheckEqual(MetricBase):
- def __init__(
- self,
- ground_truth: float,
- ):
- super().__init__(
- name="math check number equal",
- metric_type=MetricType.NUMERICAL,
- description="Toy metric checking if two numbers are equal",
- categories=[],
- )
- self.ground_truth = ground_truth
-
- async def __call__(
- self,
- solution: SolutionOutput,
- ) -> MetricResult:
- if solution.output == self.ground_truth:
- return MetricResult(
- name=self.name,
- result=1.0,
- message="Correct",
- )
- else:
- return MetricResult(
- name=self.name,
- result=0.0,
- message="Incorrect",
- )
-
-
-# %%
-# - 一个 ``Task`` (任务) 是基准测试中的一个单元,包含智能体执行和评估所需的所有信息(例如,输入/查询及其标准答案)。
-# - 一个 ``Benchmark`` (基准测试) 组织多个任务进行系统性评估。
-
-from typing import Generator
-from agentscope.evaluate import (
- Task,
- BenchmarkBase,
-)
-
-
-class ToyBenchmark(BenchmarkBase):
- def __init__(self):
- super().__init__(
- name="Toy bench",
- description="A toy benchmark for demonstrating the evaluation module.",
- )
- self.dataset = self._load_data()
-
- @staticmethod
- def _load_data() -> list[Task]:
- dataset = []
- for item in TOY_BENCHMARK:
- dataset.append(
- Task(
- id=item["id"],
- input=item["question"],
- ground_truth=item["ground_truth"],
- tags=item.get("tags", {}),
- metrics=[
- CheckEqual(item["ground_truth"]),
- ],
- metadata={},
- ),
- )
- return dataset
-
- def __iter__(self) -> Generator[Task, None, None]:
- """遍历基准测试。"""
- for task in self.dataset:
- yield task
-
- def __getitem__(self, index: int) -> Task:
- """根据索引获取任务。"""
- return self.dataset[index]
-
- def __len__(self) -> int:
- """获取基准测试的长度。"""
- return len(self.dataset)
-
-
-# %%
-# 评估器
-# ~~~~~~~~~~
-#
-# 评估器 (Evaluators) 管理评估过程。它们可以自动遍历
-# 基准测试中的任务,并将每个任务输入到解决方案生成函数中,
-# 开发者需要在其中定义运行智能体和检索
-# 执行结果和轨迹的逻辑。下面是一个
-# 使用我们的玩具基准测试运行 ``GeneralEvaluator`` (通用评估器) 的示例。如果有一个大型
-# 基准测试,开发者希望通过并行化更高效地进行评估,
-# ``RayEvaluator`` (Ray评估器) 也可作为内置解决方案使用。
-
-
-import os
-import asyncio
-from typing import Callable
-from pydantic import BaseModel
-
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.agent import ReActAgent
-
-from agentscope.evaluate import (
- GeneralEvaluator,
- FileEvaluatorStorage,
-)
-
-
-class ToyBenchAnswerFormat(BaseModel):
- answer_as_number: float
-
-
-async def toy_solution_generation(
- task: Task,
- pre_hook: Callable,
-) -> SolutionOutput:
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You are a helpful assistant named Friday. "
- "Your target is to solve the given task with your tools. "
- "Try to solve the task as best as you can.",
- model=DashScopeChatModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- model_name="qwen-max",
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
- )
- agent.register_instance_hook(
- "pre_print",
- "save_logging",
- pre_hook,
- )
- msg_input = Msg("user", task.input, role="user")
- res = await agent(
- msg_input,
- structured_model=ToyBenchAnswerFormat,
- )
- return SolutionOutput(
- success=True,
- output=res.metadata.get("answer_as_number", None),
- trajectory=[],
- )
-
-
-async def main() -> None:
- evaluator = GeneralEvaluator(
- name="Toy benchmark evaluation",
- benchmark=ToyBenchmark(),
- # 重复多少次
- n_repeat=1,
- storage=FileEvaluatorStorage(
- save_dir="./results",
- ),
- # 使用多少个工作进程
- n_workers=1,
- )
-
- # 运行评估
- await evaluator.run(toy_solution_generation)
-
-
-asyncio.run(main())
diff --git a/docs/tutorial/zh_CN/src/task_eval_openjudge.py b/docs/tutorial/zh_CN/src/task_eval_openjudge.py
deleted file mode 100644
index ead1e3b85..000000000
--- a/docs/tutorial/zh_CN/src/task_eval_openjudge.py
+++ /dev/null
@@ -1,346 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-OpenJudge 评估器
-=======================
-
-[OpenJudge](https://github.com/agentscope-ai/OpenJudge) 是一个专为评估LLM/Agent应用质量而设计的评估框架。通过将 OpenJudge 集成到 AgentScope 中,您可以将 AgentScope 的原生评估能力从基础的执行检查扩展到深度的语义质量分析。
-
-本指南中我们将介绍如何使用 OpenJudge 的评估器(Grader)作为 AgentScope 的评估指标(Metric)来评估您的智能体应用。
-
-.. note::
- 在运行本教程之前,请安装必要的依赖:
-
- .. code-block:: bash
-
- pip install agentscope py-openjudge
-
-为什么选择 OpenJudge?
-----------------------
-
-虽然 AgentScope 提供了强大的评估框架用于定义评估逻辑,但实现复杂的语义级指标(如“幻觉检测”或“回复相关性”)通常需要大量的 Prompt 工程和流程构建工作。
-
-集成 OpenJudge 可以为 AgentScope 带来了三个维度的能力提升:
-
-1. **提升评估深度**:从简单的成功/失败检查升级为多维度的质量评估(如准确性、安全性、语气等)。
-2. **开箱即用的 Grader**:直接使用 50+ 个预置的、专家级验证过的 Grader,无需手动编写评估 Prompt,详情请参阅 [OpenJudge官方文档](https://agentscope-ai.github.io/OpenJudge/built_in_graders/overview/)。
-3. **闭环迭代**:将 OpenJudge 无缝嵌入 AgentScope 的 ``Benchmark`` 中,同时获取量化的分数和定性的理由分析。
-
-如何使用 OpenJudge 进行评估
----------------------------
-
-我们将构建一个简单的问答(QA)基准测试,演示如何通过集成 OpenJudge 的 Grader 来使用 AgentScope 的评估模块。
-"""
-
-# %%
-QA_BENCHMARK_DATASET = [
- {
- "id": "qa_task_1",
- "question": "What are the health benefits of regular exercise?",
- "reference_output": "Regular exercise improves cardiovascular health, strengthens muscles and bones, "
- "helps maintain a healthy weight, and can improve mental health by reducing anxiety and depression.",
- "ground_truth": "Answers should cover physical and mental health benefits",
- "difficulty": "medium",
- "category": "health",
- },
- {
- "id": "qa_task_2",
- "question": "Describe the main causes of climate change.",
- "reference_output": "Climate change is primarily caused by increased concentrations of greenhouse gases "
- "in the atmosphere due to human activities like burning fossil fuels, deforestation, and industrial processes.",
- "ground_truth": "Answers should mention greenhouse gases and human activities",
- "difficulty": "hard",
- "category": "environment",
- },
- {
- "id": "qa_task_3",
- "question": "What is the significance of the Turing Test in AI?",
- "reference_output": "The Turing Test, proposed by Alan Turing, is a measure of a machine's ability to exhibit"
- " intelligent behavior equivalent to, or indistinguishable from, that of a human.",
- "ground_truth": "Should mention Alan Turing, purpose of the test, and its implications for AI",
- "difficulty": "hard",
- "category": "technology",
- },
-]
-
-
-# %% [markdown]
-# AgentScope Metric vs. OpenJudge Grader
-# ~~~~~~~~~~
-# 为了使 AgentScope 兼容 OpenJudge,我们需要一个适配器(Adapter)来完成两个框架间的转换。
-# 这个适配器继承自 AgentScope 的 ``MetricBase``,并充当通往 OpenJudge ``BaseGrader`` 的桥梁。
-#
-# * **AgentScope Metric**: 一个通用的评估单元,接收 ``SolutionOutput`` 并返回 ``MetricResult``。
-# * **OpenJudge Grader**: 一个特定的评估单元(例如 ``RelevanceGrader``),需要特定的语义输入(如 ``query``, ``response``, ``context``),返回``GraderResult``。
-#
-# 这个“适配器”允许您将 *任何* OpenJudge Grader 无缝插入到您的 AgentScope 基准测试中。
-
-# %%
-from openjudge.graders.base_grader import BaseGrader
-from openjudge.graders.schema import GraderScore, GraderError
-from openjudge.utils.mapping import parse_data_with_mapper
-from agentscope.evaluate import (
- MetricBase,
- MetricType,
- MetricResult,
- SolutionOutput,
-)
-
-
-class OpenJudgeMetric(MetricBase):
- def __init__(
- self,
- grader_cls: type[BaseGrader],
- data: dict,
- mapper: dict,
- name: str | None = None,
- description: str | None = None,
- **grader_kwargs,
- ):
- """Initializes the OpenJudgeMetric.
-
- Args:
- grader_cls (`type[BaseGrader]`):
- The OpenJudge grader class to be wrapped.
- data (`dict`):
- The static data for the task.
- mapper (`dict`):
- The mapper to extract grader inputs from combined data.
- name (`str | None`, optional):
- The name of the metric. Defaults to the grader's name.
- description (`str | None`, optional):
- The description of the metric. Defaults to the grader's
- description.
- **grader_kwargs:
- Additional keyword arguments for the grader initialization.
- """
- self.grader = grader_cls(**grader_kwargs)
-
- super().__init__(
- name=name or self.grader.name,
- metric_type=MetricType.NUMERICAL,
- description=description or self.grader.description,
- )
-
- self.data = data
- self.mapper = mapper
-
- async def __call__(self, solution: SolutionOutput) -> MetricResult:
- """针对 Agent 的输出执行封装好的 OpenJudge Grader。"""
- if not solution.success:
- return MetricResult(
- name=self.name,
- result=0.0,
- message="Solution failed",
- )
-
- try:
- # 1. 构建上下文
- # 将静态的任务上下文 (data) 和动态的 Agent 输出 (solution) 组合
- combined_data = {
- "data": self.data,
- "solution": {
- "output": solution.output,
- "meta": solution.meta,
- "trajectory": getattr(solution, "trajectory", []),
- },
- }
-
- # 2. 数据映射
- # 使用 mapper 从组合数据中提取Grader需要的 'query', 'response', 'context' 等参数
- grader_inputs = parse_data_with_mapper(
- combined_data,
- self.mapper,
- )
-
- ## 3. 执行评估
- result = await self.grader.aevaluate(**grader_inputs)
-
- # 4. 格式化结果
- if isinstance(result, GraderScore):
- return MetricResult(
- name=self.name,
- result=result.score,
- # 保留 OpenJudge 提供的详细理由
- message=result.reason or "",
- )
- elif isinstance(result, GraderError):
- return MetricResult(
- name=self.name,
- result=0.0,
- message=f"Error: {result.error}",
- )
- else:
- return MetricResult(
- name=self.name,
- result=0.0,
- message="Unknown result type",
- )
-
- except Exception as e:
- return MetricResult(
- name=self.name,
- result=0.0,
- message=f"Exception: {str(e)}",
- )
-
-
-# %% [markdown]
-# 从 OpenJudge 到 AgentScope
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# OpenJudge 提供了丰富的内置 Grader 集合。在当前实例中,我们选择两个适合问答任务的常用 Grader:
-#
-# * **RelevanceGrader (相关性)**:评估 Agent 的回答是否直接回应了用户的查询(忽略事实准确性)。
-# * **CorrectnessGrader (正确性)**:根据提供的参考答案(Ground Truth)验证回答的事实准确性。
-#
-# .. tip::
-# OpenJudge 提供了 50+ 种内置 Grader,涵盖 **幻觉检测**、**安全性**、**代码质量** 和 **JSON 格式化** 等多个维度。
-# 请查阅 `OpenJudge 官方文档 <https://agentscope-ai.github.io/OpenJudge/built_in_graders/overview/>`_ 获取完整列表。
-#
-# .. note::
-# 在运行以下示例之前,请确保您已设置 ``DASHSCOPE_API_KEY`` 环境变量。
-
-# %%
-import os
-from typing import Generator
-from openjudge.graders.common.relevance import RelevanceGrader
-from openjudge.graders.common.correctness import CorrectnessGrader
-from agentscope.evaluate import (
- Task,
- BenchmarkBase,
-)
-
-
-class QABenchmark(BenchmarkBase):
- def __init__(self):
- super().__init__(
- name="QA Quality Benchmark",
- description="Benchmark to evaluate QA systems using OpenJudge grader classes",
- )
- self.dataset = self._load_data()
-
- def _load_data(self):
- tasks = []
- # 配置 LLM Grader 的模型参数
- # 注意:如果不使用环境变量,请在此处设置 "api_key"
- model_config = {
- "model": "qwen3-32b",
- "api_key": os.environ.get("DASHSCOPE_API_KEY"),
- "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
- }
-
- for data in QA_BENCHMARK_DATASET:
- # 定义映射关系:左侧是 OpenJudge 的键,右侧是 AgentScope 的数据路径
- mapper = {
- "query": "data.input",
- "response": "solution.output",
- "context": "data.ground_truth",
- "reference_response": "data.reference_output",
- }
-
- # 通过 Adapter 实例化 Metrics
- metrics = [
- OpenJudgeMetric(
- grader_cls=RelevanceGrader,
- data=data,
- mapper=mapper,
- name="Relevance",
- model=model_config,
- ),
- OpenJudgeMetric(
- grader_cls=CorrectnessGrader,
- data=data,
- mapper=mapper,
- name="Correctness",
- model=model_config,
- ),
- ]
-
- # 创建 Task
- task = Task(
- id=data["id"],
- input=data["question"],
- ground_truth=data["ground_truth"],
- metrics=metrics,
- )
-
- tasks.append(task)
-
- return tasks
-
- def __iter__(self) -> Generator[Task, None, None]:
- yield from self.dataset
-
- def __getitem__(self, index: int) -> Task:
- return self.dataset[index]
-
- def __len__(self) -> int:
- return len(self.dataset)
-
-
-# %% [markdown]
-# 运行评估
-# ~~~~~~~~~~
-# 最后,使用 AgentScope 的 ``GeneralEvaluator`` 对一个简单的QA Agent进行评估测试。
-# 我们将收集到来自 OpenJudge Grader 的 **量化分数 (Score)** 和 **定性理由 (Reasoning)**。
-
-# %%
-
-import asyncio
-from typing import Callable
-
-from agentscope.agent import ReActAgent
-from agentscope.evaluate import GeneralEvaluator
-from agentscope.evaluate import FileEvaluatorStorage
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.message import Msg
-from agentscope.model import OpenAIChatModel
-
-
-async def qa_agent(task: Task, pre_hook: Callable) -> SolutionOutput:
- model = OpenAIChatModel(
- model_name="qwen3-32b",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- )
- agent = ReActAgent(
- name="QAAgent",
- sys_prompt="You are an expert at answering questions. Provide clear, accurate, and comprehensive answers.",
- model=model,
- formatter=DashScopeChatFormatter(),
- )
-
- # Generate response
- msg_input = Msg(name="User", content=task.input, role="user")
- response = await agent(msg_input)
- response_text = response.content
-
- return SolutionOutput(
- success=True,
- output=response_text,
- trajectory=[
- task.input,
- response_text,
- ], # Store the interaction trajectory
- )
-
-
-async def main() -> None:
- evaluator = GeneralEvaluator(
- name="OpenJudge Integration Demo",
- benchmark=QABenchmark(),
- # Repeat how many times
- n_repeat=1,
- storage=FileEvaluatorStorage(
- save_dir="./results",
- ),
- # How many workers to use
- n_workers=1,
- )
-
- await evaluator.run(qa_agent)
-
-
-# %% [markdown]
-#
-# ~~~~~~~~~~
-# 最后,使用 AgentScope 的 ``GeneralEvaluator`` 对一个简单的QA Agent进行评估测试。
-# 我们将收集到来自 OpenJudge Grader 的 **量化分数 (Score)** 和 **定性理由 (Reasoning)**。
diff --git a/docs/tutorial/zh_CN/src/task_hook.py b/docs/tutorial/zh_CN/src/task_hook.py
deleted file mode 100644
index 80b880b22..000000000
--- a/docs/tutorial/zh_CN/src/task_hook.py
+++ /dev/null
@@ -1,286 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _hook:
-
-智能体钩子函数
-===========================
-
-钩子(Hook)是 AgentScope 中的扩展点,允许开发者在特定位置自定义智能体行为,提供了一种灵活的方式来修改或扩展智能体的功能,而无需更改其核心实现。
-
-在 AgentScope 中,钩子围绕智能体的核心函数实现:
-
-
-.. list-table:: AgentScope 中支持的钩子类型
- :header-rows: 1
-
- * - 智能体类
- - 核心函数
- - 钩子类型
- - 描述
- * - | ``AgentBase`` 及其子类
- - ``reply``
- - | ``pre_reply``
- | ``post_reply``
- - 智能体回复消息前/后的钩子
- * -
- - ``print``
- - | ``pre_print``
- | ``post_print``
- - 向目标输出(如终端、Web 界面)打印消息前/后的钩子
- * -
- - ``observe``
- - | ``pre_observe``
- | ``post_observe``
- - 从环境或其它智能体观察消息前/后的钩子
- * - | ``ReActAgentBase`` 及其子类
- - | ``reply``
- | ``print``
- | ``observe``
- - | ``pre_reply``
- | ``post_reply``
- | ``pre_print``
- | ``post_print``
- | ``pre_observe``
- | ``post_observe``
- -
- * -
- - ``_reasoning``
- - | ``pre_reasoning``
- | ``post_reasoning``
- - 智能体推理过程前/后的钩子
- * -
- - ``_acting``
- - | ``pre_acting``
- | ``post_acting``
- - 智能体行动过程前/后的钩子
-
-.. tip:: 由于 AgentScope 中的钩子函数是通过 meta class 实现的,因此支持继承。
-
-为了简化使用,AgentScope 为所有钩子提供了统一的签名。
-
-"""
-import asyncio
-from typing import Any, Type
-
-from agentscope.agent import ReActAgentBase, AgentBase
-from agentscope.message import Msg
-
-
-# %%
-# 钩子签名
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope 为所有前置(pre_)和后置(post_)钩子提供统一的钩子签名,如下所示:
-#
-# **前置钩子签名**
-#
-# .. list-table:: 所有前置钩子的签名
-# :header-rows: 1
-#
-# * -
-# - 名称
-# - 描述
-# * - 参数
-# - ``self: AgentBase | ReActAgentBase``
-# - 智能体实例
-# * -
-# - ``kwargs: dict[str, Any]``
-# - | 目标函数的输入参数,或来自最近
-# | 一个非 None 返回值的钩子修
-# | 改后的参数
-# * - 返回值
-# - ``dict[str, Any] | None``
-# - 修改后的参数或 None
-#
-# .. note:: 核心函数的所有位置参数(*args)和关键字参数(**kwargs)被统一成单个 ``kwargs`` 字典传递给钩子函数
-#
-# 前置钩子模板定义如下:
-#
-
-
-def pre_hook_template(
- self: AgentBase | ReActAgentBase,
- kwargs: dict[str, Any],
-) -> dict[str, Any] | None: # 修改后的输入
- """前置钩子模板。"""
- pass
-
-
-# %%
-# **后置钩子签名**
-#
-# 对于后置钩子,在签名中增加了一个额外的 ``output`` 参数,表示目标函数的输出。
-# 如果核心函数没有输出,``output`` 参数将为 ``None``。
-#
-# .. list-table:: 所有后置钩子的签名
-# :header-rows: 1
-#
-# * -
-# - 名称
-# - 描述
-# * - 参数
-# - ``self: AgentBase | ReActAgentBase``
-# - 智能体实例
-# * -
-# - ``kwargs: dict[str, Any]``
-# - | 包含目标函数所有参数的字典
-# * -
-# - ``output: Any``
-# - | 目标函数的输出或来自前序钩子
-# | 最近一个非 None 返回值
-# * - 返回值
-# - ``dict[str, Any] | None``
-# - 修改后的输出或 None
-#
-
-
-def post_hook_template(
- self: AgentBase | ReActAgentBase,
- kwargs: dict[str, Any],
- output: Any, # 目标函数的输出
-) -> Any: # 修改后的输出
- """后置钩子模板。"""
- pass
-
-
-# %%
-# 钩子管理
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope 提供实例级(instance)和类级(class)钩子,其区别在于钩子函数的作用范围。
-# 它们按以下顺序执行:
-#
-# .. image:: ../../_static/images/sequential_hook.png
-# :width: 90%
-# :align: center
-# :alt: AgentScope 中的钩子
-# :class: bordered-image
-#
-# AgentScope 提供内置方法来管理实例级和类级的钩子,如下所示:
-#
-# .. list-table:: AgentScope 中的钩子管理方法
-# :header-rows: 1
-#
-# * - 级别
-# - 方法
-# - 描述
-# * - 实例级
-# - ``register_instance_hook``
-# - | 为当前对象注册具有给定钩子类型
-# | 和名称的钩子。
-# * -
-# - ``remove_instance_hook``
-# - | 移除当前对象具有给定钩子类型
-# | 和名称的钩子。
-# * -
-# - ``clear_instance_hooks``
-# - | 清除当前对象具有给定钩子类型
-# | 的所有钩子。
-# * - 类级
-# - ``register_class_hook``
-# - | 为该类的所有对象注册具有给定
-# | 钩子类型和名称的钩子。
-# * -
-# - ``remove_class_hook``
-# - | 移除该类所有对象具有给定
-# | 钩子类型和名称的钩子。
-# * -
-# - ``clear_class_hooks``
-# - | 清除该类所有对象具有给定
-# | 钩子类型的所有钩子。
-#
-# 使用钩子时,开发者需要注意以下规则:
-#
-# .. important:: **执行顺序**
-#
-# - 钩子按注册顺序执行
-# - 多个钩子可以链式连接
-# **返回值处理**
-#
-# - 对于前置钩子:非 None 返回值会传递给下一个钩子或核心函数
-# - 当钩子返回 None 时,下一个钩子将使用前序钩子中最近的非 None 返回值
-# - 如果所有前序钩子都返回 None,那该钩子接收原始参数的副本作为输入
-# - 最后一个非 None 返回值(或如果所有钩子都返回 None 则使用原始参数)传递给核心函数
-# - 对于后置钩子:工作方式与前置钩子相似。
-# **重要提示**:不要在钩子内调用核心函数(reply/speak/observe/_reasoning/_acting)以避免循环调用!
-#
-# 以下面的智能体为例,我们可以看到如何注册、移除和清除钩子:
-#
-
-
-# 创建一个简单的测试智能体类
-class TestAgent(AgentBase):
- """用于演示钩子的测试智能体。"""
-
- async def reply(self, msg: Msg) -> Msg:
- """回复消息。"""
- return msg
-
-
-# %%
-# 我们创建一个实例级钩子和一个类级钩子来在回复前修改消息内容。
-#
-
-
-# 创建两个前置回复钩子
-def instance_pre_reply_hook(
- self: AgentBase,
- kwargs: dict[str, Any],
-) -> dict[str, Any]:
- """修改消息内容的前置回复钩子。"""
- msg = kwargs["msg"]
- msg.content += "[instance-pre-reply]"
- # 返回修改后的 kwargs
- return {
- **kwargs,
- "msg": msg,
- }
-
-
-def cls_pre_reply_hook(
- self: AgentBase,
- kwargs: dict[str, Any],
-) -> dict[str, Any]:
- """修改消息内容的前置回复钩子。"""
- msg = kwargs["msg"]
- msg.content += "[cls-pre-reply]"
- # 返回修改后的 kwargs
- return {
- **kwargs,
- "msg": msg,
- }
-
-
-# 注册类钩子
-TestAgent.register_class_hook(
- hook_type="pre_reply",
- hook_name="test_pre_reply",
- hook=cls_pre_reply_hook,
-)
-
-# 注册实例钩子
-agent = TestAgent()
-agent.register_instance_hook(
- hook_type="pre_reply",
- hook_name="test_pre_reply",
- hook=instance_pre_reply_hook,
-)
-
-
-async def example_test_hook() -> None:
- """测试钩子的示例函数。"""
- msg = Msg(
- name="user",
- content="Hello, world!",
- role="user",
- )
- res = await agent(msg)
- print("响应内容:", res.content)
- TestAgent.clear_class_hooks()
-
-
-asyncio.run(example_test_hook())
-
-# %%
-# 我们可以看到 "[instance-pre-reply]" 和 "[cls-pre-reply]" 被添加到了消息内容中。
-#
diff --git a/docs/tutorial/zh_CN/src/task_long_term_memory.py b/docs/tutorial/zh_CN/src/task_long_term_memory.py
deleted file mode 100644
index b901693a7..000000000
--- a/docs/tutorial/zh_CN/src/task_long_term_memory.py
+++ /dev/null
@@ -1,408 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _long-term-memory:
-
-长期记忆
-========================
-
-AgentScope 为长期记忆提供了一个基类 ``LongTermMemoryBase`` 和一个基于 `mem0 <https://github.com/mem0ai/mem0>`_ 的具体实现 ``Mem0LongTermMemory``。
-结合 :ref:`agent` 章节中 ``ReActAgent`` 类的设计,我们提供了两种长期记忆模式:
-
-- ``agent_control``:智能体通过工具调用自主管理长期记忆。
-- ``static_control``:开发者通过编程显式控制长期记忆操作。
-
-当然,开发者也可以使用 ``both`` 参数,将同时激活上述两种记忆管理模式。
-
-.. hint:: 不同的记忆模式适用于不同的使用场景,开发者可以根据需要选择合适的模式。
-
-使用 mem0 长期记忆
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. note:: 在 GitHub 仓库的 ``examples/long_term_memory/mem0`` 目录下我们提供了 mem0 长期记忆的使用示例。
-
-"""
-
-import os
-import asyncio
-
-from agentscope.message import Msg
-from agentscope.memory import InMemoryMemory, Mem0LongTermMemory
-from agentscope.agent import ReActAgent
-from agentscope.embedding import DashScopeTextEmbedding
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit
-
-
-# 创建 mem0 长期记忆实例
-long_term_memory = Mem0LongTermMemory(
- agent_name="Friday",
- user_name="user_123",
- model=DashScopeChatModel(
- model_name="qwen-max-latest",
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- stream=False,
- ),
- embedding_model=DashScopeTextEmbedding(
- model_name="text-embedding-v2",
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- ),
- on_disk=False,
-)
-
-# %%
-# ``Mem0LongTermMemory`` 类提供了两个操作长期记忆的方法,``record`` 和 ``retrieve``。
-# 它们接收消息对象的列表作为输入,分别记录和检索长期记忆中的信息。
-#
-# 例如下面的例子中,我们先存入用户的一条偏好,然后在长期记忆中检索相关信息。
-#
-
-
-# 基本使用示例
-async def basic_usage():
- """基本使用示例"""
- # 记录记忆
- await long_term_memory.record([Msg("user", "我喜欢住民宿", "user")])
-
- # 检索记忆
- results = await long_term_memory.retrieve(
- [Msg("user", "我的住宿偏好", "user")],
- )
- print(f"检索结果: {results}")
-
-
-asyncio.run(basic_usage())
-
-
-# %%
-# 与 ReAct 智能体集成
-# ----------------------------------------
-# AgentScope 中的 ``ReActAgent`` 在构造函数中包含 ``long_term_memory`` 和 ``long_term_memory_mode`` 两个参数,
-# 其中 ``long_term_memory`` 用于指定长期记忆实例,``long_term_memory_mode`` 的取值为 ``"agent_control"``, ``"static_control"`` 或 ``"both"``。
-#
-# 当 ``long_term_memory_mode`` 设置为 ``"agent_control"`` 或 ``both`` 时,在 ``ReActAgent`` 的构造函数中将
-# 注册两个工具函数:``record_to_memory`` 和 ``retrieve_from_memory``。
-# 从而使智能体能够自主的管理长期记忆。
-#
-# .. note:: 为了达到最好的效果,``"agent_control"`` 模式可能还需要在系统提示(system prompt)中添加相应的说明。
-#
-
-# 创建带有长期记忆的 ReAct 智能体
-agent = ReActAgent(
- name="Friday",
- sys_prompt="你是一个具有长期记忆功能的助手。",
- model=DashScopeChatModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY"),
- model_name="qwen-max-latest",
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=Toolkit(),
- memory=InMemoryMemory(),
- long_term_memory=long_term_memory,
- long_term_memory_mode="static_control", # 使用 static_control 模式
-)
-
-
-async def record_preferences():
- """ReAct agent integration example"""
- # 对话示例
- msg = Msg("user", "我去杭州旅行时,喜欢住民宿", "user")
- await agent(msg)
-
-
-asyncio.run(record_preferences())
-
-# %%
-# 然后我们清空智能体的短期记忆,以避免造成干扰,并测试智能体是否会记住之前的对话。
-#
-
-
-async def retrieve_preferences():
- """Retrieve user preferences from long-term memory"""
- # 我们清空智能体的短期记忆,以避免造成干扰
- await agent.memory.clear()
-
- # 测试智能体是否会记住之前的对话
- msg2 = Msg("user", "我有什么偏好?简要的回答我", "user")
- await agent(msg2)
-
-
-asyncio.run(retrieve_preferences())
-
-# %%
-# 使用 ReMe 个人长期记忆
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# .. note:: 在 GitHub 仓库的 ``examples/long_term_memory/reme`` 目录下我们提供了 ReMe 长期记忆的使用示例。
-#
-# .. code-block:: python
-# :caption: 安装 ReMe 依赖
-#
-# from agentscope.memory import ReMePersonalLongTermMemory
-#
-# # 创建 ReMe 个人长期记忆实例
-# reme_long_term_memory = ReMePersonalLongTermMemory(
-# agent_name="Friday",
-# user_name="user_123",
-# model=DashScopeChatModel(
-# model_name="qwen3-max",
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# stream=False,
-# ),
-# embedding_model=DashScopeTextEmbedding(
-# model_name="text-embedding-v4",
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# dimensions=1024,
-# ),
-# )
-#
-#
-# ``ReMePersonalLongTermMemory`` 类提供了四个操作长期记忆的方法。
-# 它们分别是用于工具调用的 ``record_to_memory`` 和 ``retrieve_from_memory``,
-# 以及用于直接调用的 ``record`` 和 ``retrieve``。
-#
-# 例如下面的例子中,我们使用 ``record_to_memory`` 记录用户偏好。
-#
-# .. code-block:: python
-# :caption: 创建 ReMe 个人长期记忆实例
-#
-# async def test_record_to_memory():
-# """测试 record_to_memory 工具函数接口"""
-# async with reme_long_term_memory:
-# result = await reme_long_term_memory.record_to_memory(
-# thinking="用户正在分享他们的旅行偏好和习惯",
-# content=[
-# "我去杭州旅行时喜欢住民宿",
-# "我喜欢早上去西湖游玩",
-# "我喜欢喝龙井茶",
-# ],
-# )
-# # 提取结果文本
-# result_text = " ".join(
-# block.get("text", "")
-# for block in result.content
-# if block.get("type") == "text"
-# )
-# print(f"记录结果: {result_text}")
-#
-#
-# 然后我们使用 ``retrieve_from_memory`` 检索相关记忆。
-#
-# .. code-block:: python
-# :caption: 使用 retrieve_from_memory 检索记忆
-#
-# async def test_retrieve_from_memory():
-# """测试 retrieve_from_memory 工具函数接口"""
-# async with reme_long_term_memory:
-# # 先记录一些内容
-# await reme_long_term_memory.record_to_memory(
-# thinking="用户正在分享旅行偏好",
-# content=["我去杭州旅行时喜欢住民宿"],
-# )
-#
-# # 然后检索
-# result = await reme_long_term_memory.retrieve_from_memory(
-# keywords=["杭州旅行", "茶偏好"],
-# )
-# retrieved_text = " ".join(
-# block.get("text", "")
-# for block in result.content
-# if block.get("type") == "text"
-# )
-# print(f"检索到的记忆: {retrieved_text}")
-#
-#
-# 除了工具函数接口,我们也可以使用 ``record`` 方法直接记录消息对话。
-#
-# .. code-block:: python
-# :caption: 使用 record 直接记录消息
-#
-# async def test_record_direct():
-# """测试 record 直接记录方法"""
-# async with reme_long_term_memory:
-# await reme_long_term_memory.record(
-# msgs=[
-# Msg(
-# role="user",
-# content="我是一名软件工程师,喜欢远程工作",
-# name="user",
-# ),
-# Msg(
-# role="assistant",
-# content="明白了!您是一名重视远程工作灵活性的软件工程师。",
-# name="assistant",
-# ),
-# Msg(
-# role="user",
-# content="我通常早上9点开始工作,会先喝一杯咖啡",
-# name="user",
-# ),
-# ],
-# )
-# print("成功记录了对话消息")
-#
-#
-# 类似地,我们使用 ``retrieve`` 方法检索相关记忆。
-#
-# .. code-block:: python
-# :caption: 使用 retrieve 直接检索消息
-#
-# async def test_retrieve_direct():
-# """测试 retrieve 直接检索方法"""
-# async with reme_long_term_memory:
-# # 先记录一些内容
-# await reme_long_term_memory.record(
-# msgs=[
-# Msg(
-# role="user",
-# content="我是一名软件工程师,喜欢远程工作",
-# name="user",
-# ),
-# ],
-# )
-#
-# # 然后检索
-# memories = await reme_long_term_memory.retrieve(
-# msg=Msg(
-# role="user",
-# content="你知道我的工作偏好吗?",
-# name="user",
-# ),
-# )
-# print(f"检索到的记忆: {memories if memories else '未找到相关记忆'}")
-#
-#
-# 与 ReAct 智能体集成
-# ----------------------------------------
-# AgentScope 中的 ``ReActAgent`` 在构造函数中包含 ``long_term_memory`` 和 ``long_term_memory_mode`` 两个参数。
-#
-# 当 ``long_term_memory_mode`` 设置为 ``"agent_control"`` 或 ``both`` 时,在 ``ReActAgent`` 的构造函数中将
-# 注册 ``record_to_memory`` 和 ``retrieve_from_memory`` 工具函数,使智能体能够自主的管理长期记忆。
-#
-# .. note:: 为了达到最好的效果,``"agent_control"`` 模式可能还需要在系统提示(system prompt)中添加相应的说明。
-#
-# .. code-block:: python
-# :caption: 创建带有长期记忆的 ReAct 智能体
-#
-# # 创建带有长期记忆的 ReAct 智能体(agent_control 模式)
-# async def test_react_agent_with_reme():
-# """测试 ReActAgent 与 ReMe 个人记忆的集成"""
-# async with reme_long_term_memory:
-# agent_with_reme = ReActAgent(
-# name="Friday",
-# sys_prompt=(
-# "你是一个名为 Friday 的助手,具有长期记忆能力。"
-# "\n\n## 记忆管理指南:\n"
-# "1. **记录记忆**:当用户分享个人信息、偏好、习惯或关于自己的事实时,"
-# "始终使用 `record_to_memory` 记录这些信息以供将来参考。\n"
-# "\n2. **检索记忆**:在回答关于用户偏好、过去信息或个人详细信息的问题之前,"
-# "你必须首先调用 `retrieve_from_memory` 来检查是否有任何相关的存储信息。"
-# "不要仅依赖当前对话上下文。\n"
-# "\n3. **何时检索**:在以下情况下调用 `retrieve_from_memory`:\n"
-# " - 用户问类似'我喜欢什么?'、'我的偏好是什么?'、"
-# "'你对我了解多少?'的问题\n"
-# " - 用户询问他们过去的行为、习惯或偏好\n"
-# " - 用户提到他们之前提到的信息\n"
-# " - 你需要关于用户的上下文来提供个性化的响应\n"
-# "\n在声称不了解用户的某些信息之前,始终先检查你的记忆。"
-# ),
-# model=DashScopeChatModel(
-# model_name="qwen3-max",
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# stream=False,
-# ),
-# formatter=DashScopeChatFormatter(),
-# toolkit=Toolkit(),
-# memory=InMemoryMemory(),
-# long_term_memory=reme_long_term_memory,
-# long_term_memory_mode="agent_control", # 使用 agent_control 模式
-# )
-#
-# # 用户分享偏好
-# msg = Msg(
-# role="user",
-# content="我去杭州旅行时,喜欢住民宿",
-# name="user",
-# )
-# response = await agent_with_reme(msg)
-# print(f"智能体响应: {response.get_text_content()}")
-#
-# # 清空短期记忆以测试长期记忆
-# await agent_with_reme.memory.clear()
-#
-# # 查询偏好
-# msg2 = Msg(role="user", content="我有什么偏好?", name="user")
-# response2 = await agent_with_reme(msg2)
-# print(f"智能体响应: {response2.get_text_content()}")
-#
-#
-# 然后我们清空智能体的短期记忆,以避免造成干扰,并测试智能体是否会记住之前的对话。
-#
-# .. code-block:: python
-# :caption: 测试 ReAct 智能体是否记住偏好
-#
-# async def retrieve_reme_preferences():
-# """从长期记忆中检索用户偏好"""
-# async with reme_long_term_memory:
-# # 创建智能体(这里可以复用之前创建的智能体,为了示例完整性重新创建)
-# agent_with_reme = ReActAgent(
-# name="Friday",
-# sys_prompt="你是一个具有长期记忆功能的助手。",
-# model=DashScopeChatModel(
-# api_key=os.environ.get("DASHSCOPE_API_KEY"),
-# model_name="qwen3-max",
-# stream=False,
-# ),
-# formatter=DashScopeChatFormatter(),
-# toolkit=Toolkit(),
-# memory=InMemoryMemory(),
-# long_term_memory=reme_long_term_memory,
-# long_term_memory_mode="agent_control",
-# )
-#
-# # 我们清空智能体的短期记忆,以避免造成干扰
-# await agent_with_reme.memory.clear()
-#
-# # 测试智能体是否会记住之前的对话
-# msg2 = Msg("user", "我有什么偏好?简要的回答我", "user")
-# await agent_with_reme(msg2)
-#
-#
-# 自定义长期记忆
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 提供了 ``LongTermMemoryBase`` 基类,它定义了长期记忆的基本接口。
-#
-# 开发者可以继承 ``LongTermMemoryBase`` 并实现以下的抽象方法来定义自己的长期记忆类:
-#
-# .. list-table:: AgentScope 中的长期记忆类
-# :header-rows: 1
-#
-# * - 类
-# - 抽象方法
-# - 描述
-# * - ``LongTermMemoryBase``
-# - | ``record``
-# | ``retrieve``
-# | ``record_to_memory``
-# | ``retrieve_from_memory``
-# - - 如果想支持 "static_control" 模式,必须实现 ``record`` 和 ``retrieve`` 方法。
-# - 想要支持 "agent_control" 模式,必须实现 ``record_to_memory`` 和 ``retrieve_from_memory`` 方法。
-# * - ``Mem0LongTermMemory``
-# - | ``record``
-# | ``retrieve``
-# | ``record_to_memory``
-# | ``retrieve_from_memory``
-# - 基于 mem0 库的长期记忆实现,支持向量存储和检索。
-# * - ``ReMePersonalLongTermMemory``
-# - | ``record``
-# | ``retrieve``
-# | ``record_to_memory``
-# | ``retrieve_from_memory``
-# - 基于 ReMe 框架的个人记忆实现,提供强大的记忆管理和检索功能。
-#
-#
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`memory` - 基础记忆系统
-# - :ref:`agent` - ReAct 智能体
-# - :ref:`tool` - 工具系统
diff --git a/docs/tutorial/zh_CN/src/task_mcp.py b/docs/tutorial/zh_CN/src/task_mcp.py
deleted file mode 100644
index 33122f47d..000000000
--- a/docs/tutorial/zh_CN/src/task_mcp.py
+++ /dev/null
@@ -1,203 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _mcp:
-
-MCP
-=========================
-
-本章将介绍 AgentScope 对 MCP(Model Context Protocol)的以下支持:
-
-- 支持 **HTTP** (StreamableHTTP 和 SSE)和 **StdIO** 类型的 MCP 服务器
-- 提供 **有状态** 和 **无状态** 两种 MCP 客户端
-- 提供 **MCP 级别** 和 **函数级别** 的 MCP 工具管理
-
-这里的有状态/无状态是指客户端是否会维持与 MCP 服务器的会话(session)。
-无状态客户端只会在调用工具发生时建立会话,并在工具调用结束后立即销毁会话,是一种轻量化的使用方式。
-
-下表总结了支持的 MCP 客户端类型和协议:
-
-.. list-table:: 支持的 MCP 客户端类型和协议
- :header-rows: 1
-
- * - 客户端类型
- - HTTP(StreamableHTTP 和 SSE)
- - StdIO
- * - 有状态客户端
- - ``HttpStatefulClient``
- - ``StdIOStatefulClient``
- * - 无状态客户端
- - ``HttpStatelessClient``
- -
-
-"""
-import asyncio
-import json
-import os
-
-from agentscope.mcp import HttpStatefulClient, HttpStatelessClient
-from agentscope.tool import Toolkit
-
-# %%
-# MCP 客户端
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 在 AgentScope 中,MCP 客户端负责
-#
-# - 连接到 MCP 服务器,
-# - 从服务器获取工具函数,以及
-# - 调用 MCP 服务器中的工具函数。
-#
-# AgentScope 中有两种类型的 MCP 客户端:**有状态** 和 **无状态**。
-# 它们仅在 **如何管理与 MCP 服务器的会话** 方面有所不同。
-#
-# - 有状态客户端:有状态 MCP 客户端在其生命周期内 **维持与 MCP 服务器的持久会话**。开发者应显式调用 ``connect()`` 和 ``close()`` 方法来管理会话的生命周期。
-# - 无状态客户端:无状态 MCP 客户端在调用工具函数时创建新会话,在工具函数调用完成后立即销毁会话,更加轻量化。
-#
-# .. note:: - StdIO MCP 服务器只有有状态客户端,当调用 ``connect()`` 时,它将在本地启动 MCP 服务器然后连接到它。
-# - 对于有状态客户端,开发者必须确保在调用工具函数时客户端已连接。
-# - 当有多个 `HttpStatefulClient` 或 `StdIOStatefulClient` 建立连接时,应按照后进先出 (LIFO) 的顺序关闭它们以避免引发错误。
-#
-# 以高德地图 MCP 服务器为例,有状态和无状态客户端的创建非常相似:
-#
-
-stateful_client = HttpStatefulClient(
- # 用于标识 MCP 的名称
- name="mcp_services_stateful",
- transport="streamable_http",
- url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
-)
-
-stateless_client = HttpStatelessClient(
- # 用于标识 MCP 的名称
- name="mcp_services_stateless",
- transport="streamable_http",
- url=f"https://mcp.amap.com/mcp?key={os.environ['GAODE_API_KEY']}",
-)
-
-# %%
-# 有状态和无状态客户端都提供以下方法:
-#
-# .. list-table:: MCP 客户端方法
-# :header-rows: 1
-#
-# * - 方法
-# - 描述
-# * - ``list_tools``
-# - 列出 MCP 服务器中所有可用的工具。
-# * - ``get_callable_function``
-# - 通过名称从 MCP 服务器获取可调用的函数对象。
-#
-# MCP 作为工具
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 提供了对 MCP 工具的细粒度管理,包括 MCP 级别和函数级别的管理。
-#
-# MCP 级别管理
-# --------------------------------
-# 您可以将 MCP 服务器的所有工具一次性注册到 ``Toolkit`` 中,如下所示。
-#
-# .. tip:: 可选地,开发者可以通过指定组名来管理工具。有关分组工具管理,请参考 :ref:`tool` 部分。
-#
-
-toolkit = Toolkit()
-
-
-async def example_register_stateless_mcp() -> None:
- """注册无状态客户端 MCP 工具的示例。"""
- # 从 MCP 服务器注册所有工具
- await toolkit.register_mcp(
- stateless_client,
- # group_name="map_services", # 可选的组名
- )
-
- print("注册的 MCP 工具总数:", len(toolkit.get_json_schemas()))
-
- maps_geo = next(
- tool
- for tool in toolkit.get_json_schemas()
- if tool["function"]["name"] == "maps_geo"
- )
- print("\n示例 ``maps_geo`` 函数:")
- print(
- json.dumps(
- maps_geo,
- indent=4,
- ensure_ascii=False,
- ),
- )
-
-
-asyncio.run(example_register_stateless_mcp())
-
-# %%
-# 要移除已注册的工具,可以使用 ``remove_tool_function`` 函数,或使用 ``remove_mcp_clients`` 移除特定 MCP 的所有工具。
-#
-
-
-async def example_remove_mcp_tools() -> None:
- """移除 MCP 工具的示例。"""
- print("移除前的工具总数:", len(toolkit.get_json_schemas()))
-
- # 通过名称移除特定的工具函数
- toolkit.remove_tool_function("maps_geo")
- print("工具数量:", len(toolkit.get_json_schemas()))
-
- # 通过名称移除 MCP 客户端的所有工具
- await toolkit.remove_mcp_clients(client_names=["mcp_services_stateless"])
- print("工具数量:", len(toolkit.get_json_schemas()))
-
-
-asyncio.run(example_remove_mcp_tools())
-
-# %%
-# 函数级别管理
-# --------------------------------
-# 注意到开发者有对 MCP 工具进行更细粒度控制的需求,例如对工具结果进行后处理,或使用它们创建更复杂的工具函数。
-#
-# 因此,AgentScope 支持通过工具名从 MCP 客户端获取可调用的函数对象,这样开发者可以
-#
-# - 直接调用它,
-# - 将其包装到自己的函数中,或以任何其它方式进行使用。
-#
-# 此外,开发者可以指定是否将工具函数执行结果包装成 ``ToolResponse`` 对象,以便与 ``Toolkit`` 无缝使用。
-# 如果设置 ``wrap_tool_result=False``,将返回原始结果类型 ``mcp.types.CallToolResult``。
-#
-# 以 ``maps_geo`` 函数为例,可以将其获取为可调用的函数对象,如下所示:
-#
-
-
-async def example_function_level_usage() -> None:
- """使用函数级别 MCP 工具的示例。"""
- func_obj = await stateless_client.get_callable_function(
- func_name="maps_geo",
- # 是否将工具结果包装到 AgentScope 的 ToolResponse 中
- wrap_tool_result=True,
- )
-
- # 您可以获取其名称、描述和 JSON schema
- print("函数名称:", func_obj.name)
- print("函数描述:", func_obj.description)
- print(
- "函数 JSON schema:",
- json.dumps(func_obj.json_schema, indent=4, ensure_ascii=False),
- )
-
- # 直接调用函数对象
- res = await func_obj(
- address="天安门广场",
- city="北京",
- )
- print("\n函数调用结果:")
- print(res)
-
-
-asyncio.run(example_function_level_usage())
-
-# %%
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 有关更多详细信息,请参见:
-#
-# - :ref:`tool`
-# - :ref:`agent`
-#
diff --git a/docs/tutorial/zh_CN/src/task_memory.py b/docs/tutorial/zh_CN/src/task_memory.py
deleted file mode 100644
index e905f2cac..000000000
--- a/docs/tutorial/zh_CN/src/task_memory.py
+++ /dev/null
@@ -1,433 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _memory:
-
-记忆
-========================
-
-AgentScope 中的记忆模块负责:
-
-- 存储消息对象(``Msg``)
-- 利用标记(mark)管理消息
-
-**标记** 是与记忆中每条消息关联的字符串标签,可用于根据消息的上下文或目的对消息进行分类、过滤和检索。
-可用于实现进阶的记忆管理功能,例如在 `ReActAgent` 类中,使用``"hint"``标签标记一次性的提示消息,
-以便在使用完成后将其从记忆中删除。
-
-.. note:: AgentScope 中的记忆模块仅提供消息存储和管理的原子功能,记忆压缩等算法逻辑在 `智能体 <agent>`_ 中实现。
-
-目前,AgentScope 提供以下记忆存储实现:
-
-.. list-table:: AgentScope 中的内置记忆类
- :header-rows: 1
-
- * - 类
- - 描述
- * - ``InMemoryMemory``
- - 简单的内存记忆存储实现。
- * - ``AsyncSQLAlchemyMemory``
- - 基于异步 SQLAlchemy 的记忆存储实现,支持如 SQLite、PostgreSQL、MySQL 等多种关系数据库。
- * - ``RedisMemory``
- - 基于 Redis 的记忆存储实现。
-
-.. tip:: 如果您有兴趣贡献新的记忆存储实现,请参考 `贡献指南 <https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md#types-of-contributions>`_。
-
-以上所有记忆类均继承自基类 ``MemoryBase``,并提供以下方法来管理记忆中的消息:
-
-.. list-table:: 记忆类提供的方法
- :header-rows: 1
-
- * - 方法
- - 描述
- * - ``add(
- memories: Msg | list[Msg] | None,
- marks: str | list[str] | None = None,
- ) -> None``
- - 将 ``Msg`` 对象添加到记忆存储中,并使用给定的标记(如果提供)。
- * - ``delete(msg_ids: list[str]) -> int``
- - 通过ID从记忆存储中删除消息。
- * - ``delete_by_mark(mark: str | list[str]) -> int``
- - 通过标记从记忆中删除消息。
- * - ``size() -> int``
- - 获取记忆存储的大小。
- * - ``clear() -> None``
- - 清空记忆存储。
- * - ``get_memory(
- mark: str | None = None,
- exclude_mark: str | None = None,
- ) -> list[Msg]``
- - 通过标记从记忆中获取消息(如果提供)。否则,获取所有消息。如果使用 ``update_compressed_summary`` 方法存储压缩摘要,它将附加到返回消息的头部。
- * - ``update_messages_mark(
- new_mark: str | None,
- old_mark: str | None = None,
- msg_ids: list[str] | None = None,
- ) -> int``
- - 统一的方法,用于更新存储中消息的标记(添加、删除或更改标记)。
- * - ``update_compressed_summary(
- summary: str,
- ) -> None``
- - 更新存储在记忆中的摘要属性。
-"""
-import asyncio
-import json
-
-import fakeredis
-from sqlalchemy.ext.asyncio import create_async_engine
-
-from agentscope.memory import (
- InMemoryMemory,
- AsyncSQLAlchemyMemory,
- RedisMemory,
-)
-from agentscope.message import Msg
-
-
-# %%
-# 内存记忆
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 内存记忆提供了一种在内存中存储消息的简单方式。
-# 结合 :ref:`state` 模块,它可以在不同用户和会话之间持久化记忆内容。
-#
-
-
-async def in_memory_example():
- """使用InMemoryMemory在内存中存储消息的示例。"""
- memory = InMemoryMemory()
- await memory.add(
- Msg("Alice", "生成一份关于AgentScope的报告", "user"),
- )
-
- # 添加一条带有标记"hint"的提示消息
- await memory.add(
- [
- Msg(
- "system",
- "<system-hint>首先创建一个计划来收集信息,然后逐步生成报告。</system-hint>",
- "system",
- ),
- ],
- marks="hint",
- )
-
- msgs = await memory.get_memory(mark="hint")
- print("带有标记'hint'的消息:")
- for msg in msgs:
- print(f"- {msg}")
-
- # 所有存储的消息都可以通过 ``state_dict`` 和 ``load_state_dict`` 方法导出和加载。
- state = memory.state_dict()
- print("记忆的状态字典:")
- print(json.dumps(state, indent=2, ensure_ascii=False))
-
- # 通过标记删除消息
- deleted_count = await memory.delete_by_mark("hint")
- print(f"删除了 {deleted_count} 条带有标记'hint'的消息。")
-
- print("删除后的记忆状态字典:")
- state = memory.state_dict()
- print(json.dumps(state, indent=2, ensure_ascii=False))
-
-
-asyncio.run(in_memory_example())
-
-# %%
-# 关系数据库记忆(Relational Database Memory)
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 通过 SQLAlchemy 提供统一的接口来使用关系数据库,支持:
-#
-# - 多种数据库,如 SQLite、PostgreSQL、MySQL 等
-# - 用户和会话管理
-# - 生产环境中的连接池
-#
-# 具体来说,这里我们以SQLite支持的记忆为例。
-
-
-async def sqlalchemy_example() -> None:
- """使用 AsyncSQLAlchemyMemory 在 SQLite 数据库中存储消息的示例。"""
-
- # 首先创建一个异步 SQLAlchemy 引擎
- engine = create_async_engine("sqlite+aiosqlite:///./test_memory.db")
-
- # 然后使用该引擎创建记忆
- memory = AsyncSQLAlchemyMemory(
- engine_or_session=engine,
- # 可选传入指定user_id和session_id
- user_id="user_1",
- session_id="session_1",
- )
-
- await memory.add(
- Msg("Alice", "生成一份关于AgentScope的报告", "user"),
- )
-
- await memory.add(
- [
- Msg(
- "system",
- "<system-hint>首先创建一个计划来收集信息,然后逐步生成报告。</system-hint>",
- "system",
- ),
- ],
- marks="hint",
- )
-
- msgs = await memory.get_memory(mark="hint")
- print("带有标记'hint'的消息:")
- for msg in msgs:
- print(f"- {msg}")
-
- # 完成后关闭引擎
- await memory.close()
-
-
-asyncio.run(sqlalchemy_example())
-
-# %%
-# 可选地,您也可以将 ``AsyncSQLAlchemyMemory`` 用作异步上下文管理器,退出上下文时会话将自动关闭。
-
-
-async def sqlalchemy_context_example() -> None:
- """使用 AsyncSQLAlchemyMemory 作为异步上下文管理器的示例。"""
- engine = create_async_engine("sqlite+aiosqlite:///./test_memory.db")
- async with AsyncSQLAlchemyMemory(
- engine_or_session=engine,
- user_id="user_1",
- session_id="session_1",
- ) as memory:
- await memory.add(
- Msg("Alice", "生成一份关于 AgentScope 的报告", "user"),
- )
-
- msgs = await memory.get_memory()
- print("记忆中的所有消息:")
- for msg in msgs:
- print(f"- {msg}")
-
-
-asyncio.run(sqlalchemy_context_example())
-
-# %%
-# 在生产环境中,例如使用FastAPI时,可以按如下方式启用连接池:
-#
-# .. code-block:: python
-# :caption: FastAPI中使用连接池的SQLAlchemy记忆
-#
-# from typing import AsyncGenerator
-#
-# from fastapi import FastAPI, Depends
-# from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
-#
-# from agentscope.agent import ReActAgent
-# from agentscope.pipeline import stream_printing_messages
-#
-#
-# app = FastAPI()
-#
-# # 创建带连接池的异步SQLAlchemy引擎
-# engine = create_async_engine(
-# "sqlite+aiosqlite:///./test_memory.db",
-# pool_size=10,
-# max_overflow=20,
-# pool_timeout=30,
-# # ... 其他连接池设置
-# )
-#
-# # 创建会话制造器
-# async_session_marker = async_sessionmaker(
-# engine,
-# expire_on_commit=False,
-# autocommit=False,
-# autoflush=False,
-# )
-#
-# async def get_db() -> AsyncGenerator[AsyncSession, None]:
-# async with async_session_marker() as session:
-# try:
-# yield session
-# await session.commit()
-# except Exception:
-# await session.rollback()
-# raise
-# finally:
-# await session.close()
-#
-# @app.post("/chat")
-# async def chat_endpoint(
-# user_id: str,
-# session_id: str,
-# input: str,
-# db_session: AsyncSession = Depends(get_db),
-# ):
-# # 智能体的一些设置
-# ...
-#
-# # 使用SQLAlchemy记忆创建智能体
-# agent = ReActAgent(
-# # ...
-# memory=AsyncSQLAlchemyMemory(
-# engine_or_session=db_session,
-# user_id=user_id,
-# session_id=session_id,
-# ),
-# )
-#
-# # 处理与智能体的对话
-# async for msg, _ in stream_printing_messages(
-# agents=[agent],
-# coroutine_task=agent(Msg("user", input, "user")),
-# ):
-# # 将消息返回给客户端
-# ...
-#
-#
-# NoSQL数据库记忆(NoSQL Database Memory)
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope还提供基于NoSQL数据库(如Redis)的记忆实现。
-# 它也支持用户和会话管理,以及生产环境中的连接池。
-#
-# 首先,我们可以按如下方式初始化Redis记忆:
-
-
-async def redis_memory_example() -> None:
- """使用 RedisMemory 在 Redis 中存储消息的示例。"""
- # 使用fakeredis进行内存测试,无需真实的 Redis 服务器
- fake_redis = fakeredis.aioredis.FakeRedis(decode_responses=True)
- # 创建 Redis 记忆
- memory = RedisMemory(
- # 使用fake redis进行演示
- connection_pool=fake_redis.connection_pool,
- # 也可以通过指定主机和端口连接到真实的Redis服务器
- # host="localhost",
- # port=6379,
- # 可选地指定 user_id 和 session_id
- user_id="user_1",
- session_id="session_1",
- )
-
- # 向记忆中添加消息
- await memory.add(
- Msg(
- "Alice",
- "生成一份关于AgentScope的报告",
- "user",
- ),
- )
-
- # 添加一条带有标记"hint"的提示消息
- await memory.add(
- Msg(
- "system",
- "<system-hint>首先创建一个计划来收集信息,然后逐步生成报告。</system-hint>",
- "system",
- ),
- marks="hint",
- )
-
- # 检索带有标记"hint"的消息
- msgs = await memory.get_memory(mark="hint")
- print("带有标记'hint'的消息:")
- for msg in msgs:
- print(f"- {msg}")
-
-
-asyncio.run(redis_memory_example())
-
-# %%
-# 同样,`RedisMemory` 也可以在生产环境中使用连接池,例如与FastAPI一起使用。
-#
-# .. code-block:: python
-# :caption: FastAPI中使用连接池的Redis记忆
-#
-# from fastapi import FastAPI, HTTPException
-# from redis.asyncio import ConnectionPool
-# from contextlib import asynccontextmanager
-#
-# # 全局Redis连接池
-# redis_pool: ConnectionPool | None = None
-#
-#
-# # 使用lifespan事件管理Redis连接池
-# @asynccontextmanager
-# async def lifespan(app: FastAPI):
-# global redis_pool
-# redis_pool = ConnectionPool(
-# host="localhost",
-# port=6379,
-# db=0,
-# password=None,
-# decode_responses=True,
-# max_connections=10,
-# encoding="utf-8",
-# )
-# print("✅ Redis连接已建立")
-#
-# yield
-#
-# await redis_pool.disconnect()
-# print("✅ Redis连接已关闭")
-#
-#
-# app = FastAPI(lifespan=lifespan)
-#
-#
-# @app.post("/chat_endpoint")
-# async def chat_endpoint(
-# user_id: str, session_id: str, input: str
-# ):
-# """聊天端点"""
-# global redis_pool
-# if redis_pool is None:
-# raise HTTPException(
-# status_code=500,
-# detail="Redis连接池未初始化。",
-# )
-#
-# # 创建Redis记忆
-# memory = RedisMemory(
-# connection_pool=redis_pool,
-# user_id=user_id,
-# session_id=session_id,
-# )
-#
-# ...
-#
-# # 完成后关闭Redis客户端连接
-# client = memory.get_client()
-# await client.aclose()
-#
-#
-#
-# 自定义记忆(Customizing Memory)
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 要自定义您自己的记忆实现,只需从 ``MemoryBase`` 继承并实现以下方法:
-#
-# .. list-table::
-# :header-rows: 1
-#
-# * - 方法
-# - 描述
-# * - ``add``
-# - 向记忆中添加 ``Msg`` 对象
-# * - ``delete``
-# - 从记忆中删除 ``Msg`` 对象
-# * - ``delete_by_mark``
-# - 通过标记从记忆中删除 ``Msg`` 对象
-# * - ``size``
-# - 记忆的大小
-# * - ``clear``
-# - 清空记忆内容
-# * - ``get_memory``
-# - 以 ``Msg`` 对象列表的形式获取记忆内容
-# * - ``update_messages_mark``
-# - 更新记忆中消息的标记
-# * - ``state_dict``
-# - 获取记忆的状态字典
-# * - ``load_state_dict``
-# - 加载记忆的状态字典
-#
-# 延伸阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`agent`
-# - :ref:`long-term-memory`
diff --git a/docs/tutorial/zh_CN/src/task_middleware.py b/docs/tutorial/zh_CN/src/task_middleware.py
deleted file mode 100644
index 2f02a0384..000000000
--- a/docs/tutorial/zh_CN/src/task_middleware.py
+++ /dev/null
@@ -1,403 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _middleware:
-
-中间件
-===========================
-
-AgentScope 提供了灵活的中间件系统,允许开发者拦截和修改各种操作的执行。
-目前,中间件支持已在 ``Toolkit`` 类中实现,用于**工具执行**。
-
-中间件系统遵循**洋葱模型**,每个中间件包裹在前一个中间件之外,形成层次结构。
-这使得开发者可以:
-
-- 在操作前进行**预处理**
-- 在执行过程中**拦截和修改**响应
-- 在操作完成后进行**后处理**
-- 根据条件**跳过**操作执行
-
-.. tip:: 未来版本的 AgentScope 将扩展中间件支持到其他组件,如智能体和模型。
-
-"""
-import asyncio
-from typing import AsyncGenerator, Callable
-
-from agentscope.message import TextBlock, ToolUseBlock
-from agentscope.tool import ToolResponse, Toolkit
-
-
-# %%
-# 工具执行中间件
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# ``Toolkit`` 类通过 ``register_middleware`` 方法支持工具执行的中间件。
-# 每个中间件可以拦截工具调用并修改输入或输出。
-#
-# 中间件签名
-# ------------------------------
-#
-# 中间件函数应具有以下签名:
-#
-# .. code-block:: python
-#
-# async def middleware(
-# kwargs: dict,
-# next_handler: Callable,
-# ) -> AsyncGenerator[ToolResponse, None]:
-# # 从 kwargs 访问参数
-# tool_call = kwargs["tool_call"]
-#
-# # 预处理
-# # ...
-#
-# # 调用下一个中间件或工具函数
-# async for response in await next_handler(**kwargs):
-# # 后处理
-# yield response
-#
-# .. list-table:: 中间件参数
-# :header-rows: 1
-#
-# * - 参数
-# - 类型
-# - 描述
-# * - ``kwargs``
-# - ``dict``
-# - 上下文参数。当前包含 ``tool_call`` (ToolUseBlock)。未来版本可能包含更多参数。
-# * - ``next_handler``
-# - ``Callable``
-# - 一个可调用对象,接受 kwargs dict 并返回产生 AsyncGenerator[ToolResponse] 的协程
-# * - **返回值**
-# - ``AsyncGenerator[ToolResponse, None]``
-# - 产生 ToolResponse 对象的异步生成器
-#
-# 基本示例
-# ------------------------------
-#
-# 以下是一个记录工具调用的简单中间件:
-#
-
-
-async def logging_middleware(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """记录工具执行的中间件。"""
- # 从 kwargs 访问工具调用
- tool_call = kwargs["tool_call"]
-
- # 预处理:在工具执行前记录日志
- print(f"[中间件] 调用工具:{tool_call['name']}")
- print(f"[中间件] 输入:{tool_call['input']}")
-
- # 调用下一个处理器(另一个中间件或实际工具)
- async for response in await next_handler(**kwargs):
- # 后处理:记录响应
- print(f"[中间件] 响应:{response.content[0]['text']}")
- yield response
-
- # 在所有响应产生后执行
- print(f"[中间件] 工具 {tool_call['name']} 完成")
-
-
-# %%
-# 让我们将这个中间件注册到工具包并测试它:
-#
-
-
-async def search_tool(query: str) -> ToolResponse:
- """一个简单的搜索工具。
-
- Args:
- query (`str`):
- 搜索查询。
-
- Returns:
- `ToolResponse`:
- 搜索结果。
- """
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"'{query}' 的搜索结果",
- ),
- ],
- )
-
-
-async def example_logging_middleware() -> None:
- """使用日志中间件的示例。"""
- # 创建工具包并注册工具
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
-
- # 注册中间件
- toolkit.register_middleware(logging_middleware)
-
- # 调用工具
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="1",
- name="search_tool",
- input={"query": "AgentScope"},
- ),
- )
-
- async for response in result:
- print(f"\n[最终] {response.content[0]['text']}\n")
-
-
-print("=" * 60)
-print("示例 1:日志中间件")
-print("=" * 60)
-asyncio.run(example_logging_middleware())
-
-# %%
-# 修改输入和输出
-# ------------------------------
-#
-# 中间件还可以修改工具调用的输入和响应内容:
-#
-
-
-async def transform_middleware(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """转换输入和输出的中间件。"""
- # 从 kwargs 访问工具调用
- tool_call = kwargs["tool_call"]
-
- # 预处理:修改输入
- original_query = tool_call["input"]["query"]
- tool_call["input"]["query"] = f"[已转换] {original_query}"
-
- async for response in await next_handler(**kwargs):
- # 后处理:修改响应
- original_text = response.content[0]["text"]
- response.content[0]["text"] = f"{original_text} [已修改]"
- yield response
-
-
-async def example_transform_middleware() -> None:
- """转换中间件的示例。"""
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
- toolkit.register_middleware(transform_middleware)
-
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="2",
- name="search_tool",
- input={"query": "中间件"},
- ),
- )
-
- async for response in result:
- print(f"结果:{response.content[0]['text']}")
-
-
-print("\n" + "=" * 60)
-print("示例 2:转换中间件")
-print("=" * 60)
-asyncio.run(example_transform_middleware())
-
-# %%
-# 授权中间件
-# ------------------------------
-#
-# 可以使用中间件实现授权检查,如果未授权则跳过工具执行:
-#
-
-
-async def authorization_middleware(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """检查授权的中间件。"""
- # 从 kwargs 访问工具调用
- tool_call = kwargs["tool_call"]
-
- # 检查工具是否已授权(简单示例)
- authorized_tools = {"search_tool"}
-
- if tool_call["name"] not in authorized_tools:
- # 跳过执行并直接返回错误
- print(f"[授权] 工具 {tool_call['name']} 未授权")
- yield ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"错误:工具 '{tool_call['name']}' 未授权",
- ),
- ],
- )
- return
-
- # 工具已授权,继续执行
- print(f"[授权] 工具 {tool_call['name']} 已授权")
- async for response in await next_handler(**kwargs):
- yield response
-
-
-async def unauthorized_tool(data: str) -> ToolResponse:
- """一个未授权的工具。
-
- Args:
- data (`str`):
- 一些数据。
-
- Returns:
- `ToolResponse`:
- 结果。
- """
- return ToolResponse(
- content=[TextBlock(type="text", text=f"处理 {data}")],
- )
-
-
-async def example_authorization_middleware() -> None:
- """授权中间件的示例。"""
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
- toolkit.register_tool_function(unauthorized_tool)
- toolkit.register_middleware(authorization_middleware)
-
- # 尝试授权的工具
- print("\n调用已授权的工具:")
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="3",
- name="search_tool",
- input={"query": "测试"},
- ),
- )
- async for response in result:
- print(f"结果:{response.content[0]['text']}")
-
- # 尝试未授权的工具
- print("\n调用未授权的工具:")
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="4",
- name="unauthorized_tool",
- input={"data": "测试"},
- ),
- )
- async for response in result:
- print(f"结果:{response.content[0]['text']}")
-
-
-print("\n" + "=" * 60)
-print("示例 3:授权中间件")
-print("=" * 60)
-asyncio.run(example_authorization_middleware())
-
-# %%
-# 多个中间件(洋葱模型)
-# ------------------------------
-#
-# 当注册多个中间件时,它们形成类似洋葱的结构。
-# 执行顺序遵循洋葱模型:
-#
-# - **预处理**:按照中间件注册的顺序执行
-# - **后处理**:按相反顺序执行(从内到外)
-#
-# 这是因为实际的工具响应对象会通过中间件链传递,
-# 每个中间件都会原地修改它。
-#
-
-
-async def middleware_1(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """第一个中间件。"""
- # 从 kwargs 访问工具调用
- tool_call = kwargs["tool_call"]
-
- # 预处理
- print("[M1] 预处理")
- tool_call["input"]["query"] += " [M1]"
-
- async for response in await next_handler(**kwargs):
- # 后处理
- response.content[0]["text"] += " [M1]"
- print("[M1] 后处理")
- yield response
-
-
-async def middleware_2(
- kwargs: dict,
- next_handler: Callable,
-) -> AsyncGenerator[ToolResponse, None]:
- """第二个中间件。"""
- # 从 kwargs 访问工具调用
- tool_call = kwargs["tool_call"]
-
- # 预处理
- print("[M2] 预处理")
- tool_call["input"]["query"] += " [M2]"
-
- async for response in await next_handler(**kwargs):
- # 后处理
- response.content[0]["text"] += " [M2]"
- print("[M2] 后处理")
- yield response
-
-
-async def example_multiple_middleware() -> None:
- """多个中间件的示例。"""
- toolkit = Toolkit()
- toolkit.register_tool_function(search_tool)
-
- # 按顺序注册中间件
- toolkit.register_middleware(middleware_1)
- toolkit.register_middleware(middleware_2)
-
- result = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="5",
- name="search_tool",
- input={"query": "测试"},
- ),
- )
-
- async for response in result:
- print(f"\n最终结果:{response.content[0]['text']}")
-
-
-print("\n" + "=" * 60)
-print("示例 4:多个中间件(洋葱模型)")
-print("=" * 60)
-print("\n执行流程:")
-print("M1 预处理 → M2 预处理 → 工具 → M2 后处理 → M1 后处理")
-print()
-asyncio.run(example_multiple_middleware())
-
-# %%
-# 使用场景
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 中间件系统适用于各种场景:
-#
-# - **日志和监控**:跟踪工具使用情况和性能
-# - **授权**:控制对特定工具的访问
-# - **速率限制**:限制工具调用的频率
-# - **缓存**:缓存重复调用的工具响应
-# - **错误处理**:添加重试逻辑或优雅降级
-# - **输入验证**:验证和清理工具输入
-# - **输出转换**:格式化或过滤工具输出
-# - **指标收集**:收集有关工具使用情况的统计信息
-#
-# .. note::
-# - 中间件按注册顺序应用
-# - 同一个 ``ToolResponse`` 对象通过中间件链传递并原地修改
-# - 中间件可以通过不调用 ``next_handler`` 来完全跳过工具执行
-# - 所有中间件必须是产生 ``ToolResponse`` 对象的异步生成器函数
diff --git a/docs/tutorial/zh_CN/src/task_model.py b/docs/tutorial/zh_CN/src/task_model.py
deleted file mode 100644
index a4d3d4136..000000000
--- a/docs/tutorial/zh_CN/src/task_model.py
+++ /dev/null
@@ -1,235 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _model:
-
-模型
-====================
-
-在本教程中,我们介绍 AgentScope 中集成的模型 API、如何使用它们,以及如何集成新的模型 API。
-AgentScope 目前支持的模型 API 和模型提供商包括:
-
-.. list-table::
- :header-rows: 1
-
- * - API
- - 类
- - 兼容
- - 流式
- - 工具
- - 视觉
- - 推理
- * - OpenAI
- - ``OpenAIChatModel``
- - vLLM, DeepSeek
- - ✅
- - ✅
- - ✅
- - ✅
- * - DashScope
- - ``DashScopeChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
- * - Anthropic
- - ``AnthropicChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
- * - Gemini
- - ``GeminiChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
- * - Ollama
- - ``OllamaChatModel``
- -
- - ✅
- - ✅
- - ✅
- - ✅
-
-.. note:: 当使用 vLLM 时,需要在部署时为不同模型配置相应的工具调用参数,例如 ``--enable-auto-tool-choice``、``--tool-call-parser`` 等参数。更多详情请参考 `vLLM 官方文档 <https://docs.vllm.ai/en/latest/features/tool_calling.html>`_。
-
-.. note:: 兼容 OpenAI API 的模型(例如 vLLM 部署的模型),推荐使用 ``OpenAIChatModel``,并通过 ``client_kwargs={"base_url": "http://your-api-endpoint"}`` 参数指定 API 端点。例如:
-
- .. code-block:: python
-
- OpenAIChatModel(client_kwargs={"base_url": "http://localhost:8000/v1"})
-
-.. note:: 模型的行为参数(如温度、最大长度等)可以通过 ``generate_kwargs`` 参数在构造函数中提前设定。例如:
-
- .. code-block:: python
-
- OpenAIChatModel(generate_kwargs={"temperature": 0.3, "max_tokens": 1000})
-
-为了提供统一的模型接口,上述所有类均被统一为:
-
-- ``__call__`` 函数的前三个参数是 ``messages``,``tools`` 和 ``tool_choice``,分别是输入消息,工具函数的 JSON schema,以及工具选择的模式。
-- 非流式返回时,返回类型是 ``ChatResponse`` 实例;流式返回时,返回的是 ``ChatResponse`` 的异步生成器。
-
-.. note:: 不同的模型 API 在输入消息格式上有所不同,AgentScope 通过 formatter 模块处理消息的转换,请参考 :ref:`format`。
-
-``ChatResponse`` 包含大模型生成的推理/文本/工具使用内容、身份、创建时间和使用信息。
-"""
-import asyncio
-import json
-import os
-
-from agentscope.message import TextBlock, ToolUseBlock, ThinkingBlock, Msg
-from agentscope.model import ChatResponse, DashScopeChatModel
-
-response = ChatResponse(
- content=[
- ThinkingBlock(
- type="thinking",
- thinking="我应该在 Google 上搜索 AgentScope。",
- ),
- TextBlock(type="text", text="我将在 Google 上搜索 AgentScope。"),
- ToolUseBlock(
- type="tool_use",
- id="642n298gjna",
- name="google_search",
- input={"query": "AgentScope"},
- ),
- ],
-)
-
-print(response)
-
-# %%
-# 以 ``DashScopeChatModel`` 为例,调用和返回结果如下:
-
-
-async def example_model_call() -> None:
- """使用 DashScopeChatModel 的示例。"""
- model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- )
-
- res = await model(
- messages=[
- {"role": "user", "content": "你好!"},
- ],
- )
-
- # 您可以直接使用响应内容创建 ``Msg`` 对象
- msg_res = Msg("Friday", res.content, "assistant")
-
- print("LLM 返回结果:", res)
- print("作为 Msg 的响应:", msg_res)
-
-
-asyncio.run(example_model_call())
-
-# %%
-# 流式返回
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 要启用流式返回,请在模型的构造函数中将 ``stream`` 参数设置为 ``True``。
-# 流式返回中,``__call__`` 方法将返回一个 **异步生成器**,该生成器迭代返回 ``ChatResponse`` 实例。
-#
-# .. note:: AgentScope 中的流式返回结果为 **累加式**,这意味着每个 chunk 中的内容包含所有之前的内容加上新生成的内容。
-#
-
-
-async def example_streaming() -> None:
- """使用流式模型的示例。"""
- model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=True,
- )
-
- generator = await model(
- messages=[
- {
- "role": "user",
- "content": "从 1 数到 20,只报告数字,不要任何其他信息。",
- },
- ],
- )
- print("响应的类型:", type(generator))
-
- i = 0
- async for chunk in generator:
- print(f"块 {i}")
- print(f"\t类型: {type(chunk.content)}")
- print(f"\t{chunk}\n")
- i += 1
-
-
-asyncio.run(example_streaming())
-
-# %%
-# 推理模型
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 通过提供 ``ThinkingBlock`` 来支持推理模型。
-#
-
-
-async def example_reasoning() -> None:
- """使用推理模型的示例。"""
- model = DashScopeChatModel(
- model_name="qwen-turbo",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- enable_thinking=True,
- )
-
- res = await model(
- messages=[
- {"role": "user", "content": "我是谁?"},
- ],
- )
-
- last_chunk = None
- async for chunk in res:
- last_chunk = chunk
- print("最终响应:")
- print(last_chunk)
-
-
-asyncio.run(example_reasoning())
-
-# %%
-# 工具 API
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 不同的模型提供商在工具 API 方面有所不同,例如工具 JSON schema、工具调用/响应格式。
-# 为了提供统一的接口,AgentScope 通过以下方式解决了这个问题:
-#
-# - 提供了统一的工具调用结构 block :ref:`ToolUseBlock <tool-block>` 和工具响应结构 :ref:`ToolResultBlock <tool-block>`。
-# - 在模型类的 ``__call__`` 方法中提供统一的工具接口 ``tools``,接受工具 JSON schema 列表,如下所示:
-#
-
-json_schemas = [
- {
- "type": "function",
- "function": {
- "name": "google_search",
- "description": "在 Google 上搜索查询。",
- "parameters": {
- "type": "object",
- "properties": {
- "query": {
- "type": "string",
- "description": "搜索查询。",
- },
- },
- "required": ["query"],
- },
- },
- },
-]
-
-# %%
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`message`
-# - :ref:`prompt`
-#
diff --git a/docs/tutorial/zh_CN/src/task_pipeline.py b/docs/tutorial/zh_CN/src/task_pipeline.py
deleted file mode 100644
index 10c752a7d..000000000
--- a/docs/tutorial/zh_CN/src/task_pipeline.py
+++ /dev/null
@@ -1,283 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _pipeline:
-
-管道 (Pipeline)
-========================
-
-对于多智能体编排,AgentScope 提供了 ``agentscope.pipeline`` 模块
-作为将智能体链接在一起的语法糖,具体包括
-
-- **MsgHub**: 用于多个智能体之间消息的广播
-- **sequential_pipeline** 和 **SequentialPipeline**: 以顺序方式执行多个智能体的函数式和类式实现
-- **fanout_pipeline** 和 **FanoutPipeline**: 将相同输入分发给多个智能体的函数式和类式实现
-- **stream_printing_messages**: 将智能体在回复过程中,调用 ``self.print`` 打印的消息转换为一个异步生成器
-
-"""
-
-import os, asyncio
-
-from agentscope.formatter import DashScopeMultiAgentFormatter
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.agent import ReActAgent
-from agentscope.pipeline import MsgHub, stream_printing_messages
-
-
-# %%
-# 使用 MsgHub 进行广播
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# ``MsgHub`` 类是一个 **异步上下文管理器**,它接收一个智能体列表作为其参与者。
-# 当一个参与者生成回复消息时,将通过调用所有其他参与者的 ``observe`` 方法广播该消息。
-# 这意味着在 ``MsgHub`` 上下文中,开发者无需手动将回复消息从一个智能体发送到另一个智能体。
-#
-# 这里我们创建四个智能体:Alice、Bob、Charlie 和 David。
-# 然后我们让 Alice、Bob 和 Charlie 通过自我介绍开始一个会议。需要注意的是 David 没有包含在这个会议中。
-#
-
-
-def create_agent(name: str, age: int, career: str) -> ReActAgent:
- """根据给定信息创建智能体对象。"""
- return ReActAgent(
- name=name,
- sys_prompt=f"你是{name},一个{age}岁的{career}",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeMultiAgentFormatter(),
- )
-
-
-alice = create_agent("Alice", 50, "老师")
-bob = create_agent("Bob", 35, "工程师")
-charlie = create_agent("Charlie", 28, "设计师")
-david = create_agent("David", 30, "开发者")
-
-# %%
-# 然后我们创建一个 ``MsgHub`` 上下文,并让他们自我介绍:
-#
-# .. hint:: ``announcement`` 中的消息将在进入 ``MsgHub`` 上下文时广播给所有参与者。
-#
-
-
-async def example_broadcast_message():
- """使用 MsgHub 广播消息的示例。"""
-
- # 创建消息中心
- async with MsgHub(
- participants=[alice, bob, charlie],
- announcement=Msg(
- "user",
- "现在请简要介绍一下自己,包括你的姓名、年龄和职业。",
- "user",
- ),
- ) as hub:
- # 无需手动消息传递的群聊
- await alice()
- await bob()
- await charlie()
-
-
-asyncio.run(example_broadcast_message())
-
-# %%
-# 现在让我们检查 Bob、Charlie 和 David 是否收到了 Alice 的消息。
-#
-
-
-async def check_broadcast_message():
- """检查消息是否正确广播。"""
- user_msg = Msg(
- "user",
- "你知道 Alice 是谁吗,她是做什么的?",
- "user",
- )
-
- await bob(user_msg)
- await charlie(user_msg)
- await david(user_msg)
-
-
-asyncio.run(check_broadcast_message())
-
-# %%
-# 现在我们观察到 Bob 和 Charlie 知道 Alice 和她的职业,而 David 对
-# Alice 一无所知,因为他没有包含在 ``MsgHub`` 上下文中。
-#
-#
-# 动态管理
-# ---------------------------
-# 此外,``MsgHub`` 支持通过以下方法动态管理参与者:
-#
-# - ``add``: 添加一个或多个智能体作为新参与者
-# - ``delete``: 从参与者中移除一个或多个智能体,他们将不再接收广播消息
-# - ``broadcast``: 向所有当前参与者广播消息
-#
-# .. note:: 新添加的参与者不会接收到之前的消息。
-#
-# .. code-block:: python
-#
-# async with MsgHub(participants=[alice]) as hub:
-# # 添加新参与者
-# hub.add(david)
-#
-# # 移除参与者
-# hub.delete(alice)
-#
-# # 向所有当前参与者广播
-# await hub.broadcast(
-# Msg("system", "现在我们开始...", "system"),
-# )
-#
-#
-# 管道
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 管道是 AgentScope 中多智能体编排的一种语法糖。
-#
-# 目前,AgentScope 提供三种管道,用于减轻开发者的负担:
-#
-# 1. **顺序管道 (Sequential Pipeline)**: 按预定义顺序逐个执行智能体
-# 2. **扇出管道 (Fanout Pipeline)**: 将相同输入分发给多个智能体并收集它们的响应
-# 3. **流式获取打印消息 (stream printing messages)**: 将智能体在回复过程中,调用 ``self.print`` 打印的消息转换为一个异步生成器
-#
-# 顺序管道
-# ------------------------
-# 顺序管道逐个执行智能体,前一个智能体的输出成为下一个智能体的输入。
-#
-# 例如,以下两个代码片段是等价的:
-#
-# .. code-block:: python
-# :caption: 代码片段 1: 手动消息传递
-#
-# msg = None
-# msg = await alice(msg)
-# msg = await bob(msg)
-# msg = await charlie(msg)
-# msg = await david(msg)
-#
-#
-# .. code-block:: python
-# :caption: 代码片段 2: 使用顺序管道
-#
-# from agentscope.pipeline import sequential_pipeline
-#
-# msg = await sequential_pipeline(
-# # 按顺序执行的智能体列表
-# agents=[alice, bob, charlie, david],
-# # 第一个输入消息,可以是 None
-# msg=None
-# )
-#
-
-# %%
-# 扇出管道
-# ------------------------
-# 扇出管道将相同的输入消息同时分发给多个智能体并收集所有响应。当你想要收集对同一话题的不同观点或专业意见时,这非常有用。
-#
-# 例如,以下两个代码片段是等价的:
-#
-# .. code-block:: python
-# :caption: 代码片段 3: 手动逐个调用智能体
-#
-# from copy import deepcopy
-#
-# msgs = []
-# msg = None
-# for agent in [alice, bob, charlie, david]:
-# msgs.append(await agent(deepcopy(msg)))
-#
-#
-# .. code-block:: python
-# :caption: 代码片段 4: 使用扇出管道
-#
-# from agentscope.pipeline import fanout_pipeline
-#
-# msgs = await fanout_pipeline(
-# # 要执行的智能体列表
-# agents=[alice, bob, charlie, david],
-# # 输入消息,可以是 None
-# msg=None,
-# enable_gather=False,
-# )
-#
-# .. note::
-# ``enable_gather`` 参数控制扇出管道的执行模式:
-#
-# - ``enable_gather=True`` (默认): 使用 ``asyncio.gather()`` **并发** 执行所有智能体。这为 I/O 密集型操作(如 API 调用)提供更好的性能,因为智能体并行运行。
-# - ``enable_gather=False``: 逐个 **顺序** 执行智能体。当你需要确定性的执行顺序或想要避免并发请求压垮外部服务时,这很有用。
-#
-# 选择并发执行以获得更好的性能,或选择顺序执行以获得可预测的顺序和资源控制。
-#
-# .. tip::
-# 通过结合 ``MsgHub`` 和 ``sequential_pipeline`` 或 ``fanout_pipeline``,你可以非常容易地创建更复杂的工作流。
-
-# %%
-# 流式获取打印消息
-# ------------------------
-# ``stream_printing_messages`` 函数将智能体在回复过程中调用 ``self.print`` 打印的消息转换为一个异步生成器。
-# 可以帮助开发者快速以流式方式获取智能体的中间消息。
-#
-# 该函数接受一个或多个智能体和一个协程任务作为输入,并返回一个异步生成器。
-# 该异步生成器返回一个二元组,包含执行协程任务过程中通过 ``await self.print(...)`` 打印的消息,以及一个布尔值,表示该消息是否为一组流式消息中的最后一个。
-#
-# 需要注意的是,生成器返回的元组中,布尔值表示该消息是否为一组流式消息中的最后一个,而非此次智能体调用的最后一条消息。
-
-
-async def run_example_pipeline() -> None:
- """运行流式打印消息的示例。"""
- agent = create_agent("Alice", 20, "student")
-
- # 我们关闭agent的终端打印以避免输出混乱
- agent.set_console_output_enabled(False)
-
- async for msg, last in stream_printing_messages(
- agents=[agent],
- coroutine_task=agent(
- Msg("user", "你好,你是谁?", "user"),
- ),
- ):
- print(msg, last)
- if last:
- print()
-
-
-asyncio.run(run_example_pipeline())
-
-
-# %%
-# 高级管道特性
-# ~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 此外,为了可重用性,我们还提供了基于类的实现:
-#
-# .. code-block:: python
-# :caption: 使用 SequentialPipeline 类
-#
-# from agentscope.pipeline import SequentialPipeline
-#
-# # 创建管道对象
-# pipeline = SequentialPipeline(agents=[alice, bob, charlie, david])
-#
-# # 调用管道
-# msg = await pipeline(msg=None)
-#
-# # 使用不同输入复用管道
-# msg = await pipeline(msg=Msg("user", "你好!", "user"))
-#
-#
-# .. code-block:: python
-# :caption: 使用 FanoutPipeline 类
-#
-# from agentscope.pipeline import FanoutPipeline
-#
-# # 创建管道对象
-# pipeline = FanoutPipeline(agents=[alice, bob, charlie, david])
-#
-# # 调用管道
-# msgs = await pipeline(msg=None)
-#
-# # 使用不同输入复用管道
-# msgs = await pipeline(msg=Msg("user", "你好!", "user"))
-#
diff --git a/docs/tutorial/zh_CN/src/task_plan.py b/docs/tutorial/zh_CN/src/task_plan.py
deleted file mode 100644
index 09644263c..000000000
--- a/docs/tutorial/zh_CN/src/task_plan.py
+++ /dev/null
@@ -1,273 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _plan:
-
-计划
-=========================
-
-AgentScope 中的计划(Plan)模块使智能体能够正式地将复杂任务分解为可管理的子任务并系统地执行它们。主要功能包括:
-
-- 支持 **手动计划规范**
-- 全面的计划管理功能:
- - **创建、修改、放弃和恢复** 计划
- - 在多个计划之间 **切换**
- - 通过临时暂停计划来处理用户查询或紧急任务,**优雅地处理中断**
-- 计划执行的 **实时可视化和监控**
-
-.. note:: 当前计划模块仅支持子任务按照顺序执行。
-
-
-具体来说,计划模块的工作原理是
-
-- 提供计划管理的工具函数
-- 插入提示消息来指导ReAct智能体完成计划
-
-下图说明了计划模块如何与ReAct智能体协作:
-
-.. figure:: ../../_static/images/plan.png
- :width: 90%
- :alt: 计划模块
- :class: bordered-image
- :align: center
-
- 计划模块如何与ReAct智能体协作
-
-"""
-import asyncio
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.model import DashScopeChatModel
-from agentscope.plan import PlanNotebook, Plan, SubTask
-
-# %%
-# PlanNotebook
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# ``PlanNotebook`` 类是计划模块的核心,负责提供
-#
-# - 管理计划,子任务的工具函数
-# - 提供用于“引导智能体正确完成任务”的提示消息(Hint message)
-#
-# ``PlanNotebook`` 类使用以下参数实例化:
-#
-# .. list-table:: ``PlanNotebook`` 构造函数的参数
-# :header-rows: 1
-#
-# * - 名称
-# - 类型
-# - 描述
-# * - ``max_subtasks``
-# - ``int | None``
-# - 计划中允许的子任务最大数量,如果为 ``None`` 则无限制
-# * - ``plan_to_hint``
-# - ``Callable[[Plan | None], str | None] | None``
-# - 基于当前计划的完成情况,生成对应提示消息的函数。如果未提供,将使用默认的 ``DefaultPlanToHint`` 对象。
-# * - ``storage``
-# - ``PlanStorageBase | None``
-# - 计划的存储模块,用于恢复,保存历史计划。如果未提供,将使用默认的内存(In-memory)存储。
-#
-# ``plan_to_hint`` 参数是 ``PlanNotebook`` 类的核心参数,也是开发者进行提示工程的接口。
-# 作为可调用对象,接受当前计划作为输入,并返回一个字符串类型的提示消息。
-# AgentScope 构建了一个默认的 ``DefaultPlanToHint`` 类,可以直接使用,同时我们鼓励开发者提供自己的 ``plan_to_hint`` 函数以获得更好的性能。
-#
-# ``storage`` 用于存储历史计划,允许智能体检索和恢复历史计划。
-# 我们同样鼓励开发者通过继承 ``PlanStorageBase`` 类来实现自己的计划存储。如果未提供,将使用默认的内存存储。
-#
-# .. tip:: ``PlanStorageBase`` 类继承自 ``StateModule`` 类,因此 storage也会通过会话管理进行保存和加载。
-#
-# ``PlanNotebook`` 类的核心属性和方法总结如下:
-#
-# .. list-table:: ``PlanNotebook`` 类的核心属性和方法
-# :header-rows: 1
-#
-# * - 类型
-# - 名称
-# - 描述
-# * - 属性
-# - ``current_plan``
-# - 智能体正在执行的当前计划
-# * -
-# - ``storage``
-# - 历史计划的存储,用于检索和恢复历史计划
-# * -
-# - ``plan_to_hint``
-# - 一个可调用对象,以当前计划为输入并生成提示消息来指导智能体完成计划
-# * - 函数
-# - ``list_tools``
-# - 列出 ``PlanNotebook`` 类提供的所有工具函数
-# * -
-# - ``get_current_hint``
-# - 获取当前计划的提示消息,将调用 ``plan_to_hint`` 函数
-# * -
-# - | ``create_plan``,
-# | ``view_subtasks``,
-# | ``revise_current_plan``,
-# | ``update_subtask_state``,
-# | ``finish_subtask``,
-# | ``finish_plan``,
-# | ``view_historical_plans``,
-# | ``recover_historical_plan``
-# - 允许智能体管理计划和子任务的工具函数
-# * -
-# - ``register_plan_change_hook``
-# - 注册一个钩子函数,当计划发生变化时将被调用,用于计划可视化和监控
-# * -
-# - ``remove_plan_change_hook``
-# - 移除已注册的钩子函数
-#
-# ``list_tools`` 方法是获取所有工具函数的快速方法,这样您就可以将它们注册到智能体的工具包中。
-
-plan_notebook = PlanNotebook()
-
-
-async def list_tools() -> None:
- """列出PlanNotebook提供的工具函数。"""
- print("PlanNotebook提供的工具:")
- for tool in plan_notebook.list_tools():
- print(tool.__name__)
-
-
-asyncio.run(list_tools())
-
-
-# %%
-# 与ReActAgent协作
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope中的 ``ReActAgent`` 已通过构造函数中的 ``plan_notebook`` 参数集成了计划模块。
-# 一旦提供,智能体将
-#
-# - 配备计划管理工具函数,并且
-# - 在每个推理步骤开始时插入提示消息
-#
-# 有两种方式在 ``ReActAgent`` 中使用计划模块:
-#
-# - 开发者指定计划:开发者可以通过调用 ``create_plan`` 工具函数手动创建计划,并使用该计划来初始化 ``ReActAgent`` 。
-# - 智能体管理的计划执行:智能体将通过调用计划管理工具函数自己创建和管理计划。
-#
-# 手动计划规范
-# ---------------------------------
-# 通过调用 ``create_plan`` 工具函数手动创建计划非常简单。
-# 以下是手动创建计划以对LLM赋能的智能体进行全面研究的示例。
-#
-async def manual_plan_specification() -> None:
- """手动计划规范示例。"""
- await plan_notebook.create_plan(
- name="智能体研究",
- description="对基于LLM的智能体进行全面研究",
- expected_outcome="一份Markdown格式的报告,回答三个问题:1. 什么是智能体?2. 智能体的当前技术水平是什么?3. 智能体的未来趋势是什么?",
- subtasks=[
- SubTask(
- name="搜索智能体相关调研论文",
- description=(
- "在多个来源搜索调研论文,包括"
- "Google Scholar、arXiv和Semantic Scholar。必须"
- "在2021年后发表且引用数超过50。"
- ),
- expected_outcome="Markdown格式的论文列表",
- ),
- SubTask(
- name="阅读和总结论文",
- description="阅读前一步找到的论文,并总结关键点,包括定义、分类、挑战和关键方向。",
- expected_outcome="Markdown格式的关键点总结",
- ),
- SubTask(
- name="研究大公司的最新进展",
- description=(
- "研究大公司的最新进展,包括但不限于Google、Microsoft、OpenAI、"
- "Anthropic、阿里巴巴和Meta。查找官方博客或新闻文章。"
- ),
- expected_outcome="大公司的最新进展",
- ),
- SubTask(
- name="撰写报告",
- description="基于前面的步骤撰写报告,并回答预期结果中的三个问题。",
- expected_outcome=(
- "一份Markdown格式的报告,回答三个问题:1. "
- "什么是智能体?2. 智能体的当前技术水平"
- "是什么?3. 智能体的未来趋势是什么?"
- ),
- ),
- ],
- )
-
- print("当前提示消息:\n")
- msg = await plan_notebook.get_current_hint()
- print(f"{msg.name}: {msg.content}")
-
-
-asyncio.run(manual_plan_specification())
-
-# %%
-# 创建计划后,可以按如下方式使用计划笔记本初始化 ``ReActAgent`` :
-
-agent = ReActAgent(
- name="Friday",
- sys_prompt="你是一个有用的助手。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
- plan_notebook=plan_notebook,
-)
-
-# %%
-# 智能体自主管理
-# ---------------------------------
-# 智能体也可以通过调用计划管理工具函数自己创建和管理计划。
-# 我们只需要按如下方式使用计划笔记本初始化 ``ReActAgent`` :
-#
-
-agent = ReActAgent(
- name="Friday",
- sys_prompt="你是一个有用的助手。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
- plan_notebook=PlanNotebook(),
-)
-
-
-# %%
-# 之后,我们可以构建一个循环来与智能体交互,如下所示。
-# 一旦用户的任务复杂比较复杂,智能体将自己创建计划并逐步执行计划。
-#
-# .. code-block:: python
-# :caption: 与计划智能体建立对话
-#
-# async def interact_with_agent() -> None:
-# """与计划智能体交互。"""
-# user = UserAgent(name="user")
-#
-# msg = None
-# while True:
-# msg = await user(msg)
-# if msg.get_text_content() == "exit":
-# break
-# msg = await agent(msg)
-#
-# asyncio.run(interact_with_agent())
-#
-# 可视化和监控
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 通过钩子函数支持计划执行的实时可视化和监控。
-#
-# 当前计划被工具函数改变时,钩子函数将被触发,开发者可以在这些钩子函数中将当前的计划转发到对应的前端进行可视化或其他处理。
-# 计划变化钩子函数的模板如下:
-#
-
-
-def plan_change_hook_template(self: PlanNotebook, plan: Plan) -> None:
- """计划变化钩子函数的模板。
-
- Args:
- self (`PlanNotebook`):
- PlanNotebook实例。
- plan (`Plan`):
- 当前计划实例(变化后)。
- """
- # 将计划转发到前端进行可视化或其他处理
diff --git a/docs/tutorial/zh_CN/src/task_prompt.py b/docs/tutorial/zh_CN/src/task_prompt.py
deleted file mode 100644
index 4a020dddd..000000000
--- a/docs/tutorial/zh_CN/src/task_prompt.py
+++ /dev/null
@@ -1,329 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _prompt:
-
-提示词格式化
-=========================
-
-AgentScope 中的格式化器(formatter)模块负责
-
-- 将 Msg 对象转换为不同 LLM API 要求的格式,
-- (可选)截断消息以适应 max_token 的限制,
-- (可选)执行提示工程,例如对长对话进行总结。
-
-后两个功能是可选的,开发者也可以选择在记忆(memory)或智能体(agent)层面进行处理和实现。
-
-在 AgentScope 中,有两种类型的格式化器:"ChatFormatter" 和 "MultiAgentFormatter",它们根据输入消息中的“身份实体”进行区分。
-
-- **ChatFormatter**:专为标准的用户-助手场景(聊天机器人)设计,使用 ``role`` 字段来识别用户和助手。
-- **MultiAgentFormatter**:专为多智能体场景设计,使用 ``name`` 字段来识别不同的实体,在格式化的过程中会将多智能体的对话历史合并为单个消息。
-
-AgentScope 内置的格式化器如下所列
-
-.. list-table:: AgentScope 中的内置格式化器
- :header-rows: 1
-
- * - API 提供商
- - 用户-助手场景
- - 多智能体场景
- * - OpenAI
- - ``OpenAIChatFormatter``
- - ``OpenAIMultiAgentFormatter``
- * - Anthropic
- - ``AnthropicChatFormatter``
- - ``AnthropicMultiAgentFormatter``
- * - DashScope
- - ``DashScopeChatFormatter``
- - ``DashScopeMultiAgentFormatter``
- * - Gemini
- - ``GeminiChatFormatter``
- - ``GeminiChatFormatter``
- * - Ollama
- - ``OllamaChatFormatter``
- - ``OllamaMultiAgentFormatter``
- * - DeepSeek
- - ``DeepSeekChatFormatter``
- - ``DeepSeekMultiAgentFormatter``
- * - vLLM
- - ``OpenAIFormatter``
- - ``OpenAIFormatter``
-
-.. tip:: OpenAI API 支持 `name` 字段,因此 `OpenAIFormatter` 也可以用于多智能体场景。也可以使用 `OpenAIMultiAgentFormatter` 代替,它会将对话历史合并为单个用户消息。
-
-此外,内置格式化器对于不同的消息块(message blocks)的支持情况如下表所示:
-
-.. list-table:: 内置格式化器中支持的消息块
- :header-rows: 1
-
- * - 格式化器
- - tool_use/result
- - image
- - audio
- - video
- - thinking
- * - ``OpenAIChatFormatter``
- - ✅
- - ✅
- - ✅
- - ❌
- -
- * - ``DashScopeChatFormatter``
- - ✅
- - ✅
- - ✅
- - ❌
- -
- * - ``DashScopeMultiAgentFormatter``
- - ✅
- - ✅
- - ✅
- - ❌
- -
- * - ``AnthropicChatFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- - ✅
- * - ``AnthropicMultiAgentFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- - ✅
- * - ``GeminiChatFormatter``
- - ✅
- - ✅
- - ✅
- - ✅
- -
- * - ``GeminiMultiAgentFormatter``
- - ✅
- - ✅
- - ✅
- - ✅
- -
- * - ``OllamaChatFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- -
- * - ``OllamaMultiAgentFormatter``
- - ✅
- - ✅
- - ❌
- - ❌
- -
- * - ``DeepSeekChatFormatter``
- - ✅
- - ❌
- - ❌
- - ❌
- -
- * - ``DeepSeekMultiAgentFormatter``
- - ✅
- - ❌
- - ❌
- - ❌
- -
-
-.. note:: 如 `官方文档 <https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#preserving-thinking-blocks>`_ 所述,只有 Anthropic 建议在输入的提示词中保留推理的部分(thinking blocks)。对于其它格式化器,我们忽略输入消息中包含的 ``ThinkingBlock``。
-
-面向 ReAct 的格式化
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-内置的 formatter 均面向 ReAct 智能体进行设计,其中输入消息由交替的 **对话历史** 和 **工具调用序列** 组成。
-
-在用户-助手场景中,对话历史是用户和助手的消息,我们直接将它们转换为所期望的格式。
-然而,在多智能体场景中,对话历史是来自不同智能体的消息列表,如下所示:
-
-.. figure:: ../../_static/images/multiagent_msgs.png
- :alt: 多智能体消息示例
- :width: 85%
- :align: center
-
- *多智能体消息示例*
-
-
-因此,我们必须将对话历史合并为带有标签 "<history>" 和 "</history>" 的单个用户消息。
-以 DashScope 为例,格式化后的消息将如下所示:
-"""
-
-from agentscope.token import HuggingFaceTokenCounter
-from agentscope.formatter import DashScopeMultiAgentFormatter
-from agentscope.message import Msg, ToolResultBlock, ToolUseBlock, TextBlock
-import asyncio, json
-
-
-input_msgs = [
- # 系统提示
- Msg("system", "你是一个名为 Friday 的有用助手", "system"),
- # 对话历史
- Msg("Bob", "你好,Alice,你知道最近的图书馆在哪里吗?", "assistant"),
- Msg(
- "Alice",
- "抱歉,我不知道。Charlie,你有什么想法吗?",
- "assistant",
- ),
- Msg(
- "Charlie",
- "没有,我们问问 Friday 吧。Friday,帮我找到最近的图书馆。",
- "assistant",
- ),
- # 工具序列
- Msg(
- "Friday",
- [
- ToolUseBlock(
- type="tool_use",
- name="get_current_location",
- id="1",
- input={},
- ),
- ],
- "assistant",
- ),
- Msg(
- "system",
- [
- ToolResultBlock(
- type="tool_result",
- name="get_current_location",
- id="1",
- output=[TextBlock(type="text", text="104.48, 36.30")],
- ),
- ],
- "system",
- ),
- Msg(
- "Friday",
- [
- ToolUseBlock(
- type="tool_use",
- name="search_around",
- id="2",
- input={"location": [104.48, 36.30], "keyword": "library"},
- ),
- ],
- "assistant",
- ),
- Msg(
- "system",
- [
- ToolResultBlock(
- type="tool_result",
- name="search_around",
- id="2",
- output=[TextBlock(type="text", text="[...]")],
- ),
- ],
- "system",
- ),
- # 对话历史继续
- Msg("Friday", "最近的图书馆是...", "assistant"),
- Msg("Bob", "谢谢,Friday!", "assistant"),
- Msg("Alice", "我们一起去吧。", "assistant"),
-]
-
-
-async def run_formatter_example() -> list[dict]:
- """多智能体消息格式化示例。"""
- formatter = DashScopeMultiAgentFormatter()
- formatted_message = await formatter.format(input_msgs)
- print("格式化后的消息:")
- print(json.dumps(formatted_message, indent=4, ensure_ascii=False))
- return formatted_message
-
-
-formatted_message = asyncio.run(run_formatter_example())
-
-# %%
-# 具体来说,对话历史被格式化为:
-#
-print("第一段对话历史:")
-print(formatted_message[1]["content"])
-
-print("\n第二段对话历史:")
-print(formatted_message[-1]["content"])
-
-# %%
-# 基于截断的格式化
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 通过 AgentScope 中的 token 模块,内置格式化器支持通过 **删除最旧的消息**(除了系统提示消息)在 token 超过限制时截断输入消息。
-#
-# 以 OpenAIFormatter 为例,我们首先计算输入消息的总 token 数。
-#
-
-
-async def run_token_counter() -> int:
- """计算输入消息的 token 数量。"""
- # 我们使用 huggingface token 计数器用于 dashscope 模型。
- token_counter = HuggingFaceTokenCounter(
- "Qwen/Qwen2.5-VL-3B-Instruct",
- use_mirror=False,
- )
-
- return await token_counter.count(formatted_message)
-
-
-# %%
-# 然后我们将最大 token 限制设置为比总 token 数少 20 个,并运行格式化器。
-#
-
-
-async def run_truncated_formatter() -> None:
- """带截断的消息格式化示例。"""
- token_counter = HuggingFaceTokenCounter(
- pretrained_model_name_or_path="Qwen/Qwen2.5-VL-3B-Instruct",
- use_mirror=False,
- )
- formatter = DashScopeMultiAgentFormatter(
- token_counter=token_counter,
- max_tokens=n_tokens - 20,
- )
- truncated_formatted_message = await formatter.format(input_msgs)
- n_truncated_tokens = await token_counter.count(truncated_formatted_message)
- print("截断后的 token 数量:", n_truncated_tokens)
-
- print("\n截断后的对话历史:")
- print(truncated_formatted_message[1]["content"])
-
-
-# %%
-# 我们可以看到来自 Bob 和 Alice 的前两条消息被删除以适应 ``max_tokens`` 的限制。
-#
-#
-# 自定义格式化器
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 提供了两个基类 ``FormatterBase`` 和其子类 ``TruncatedFormatterBase``。
-# 其中 ``TruncatedFormatterBase`` 类提供了 FIFO(First In First Out)截断策略,所有内置格式化器都继承自它。
-#
-# .. list-table:: AgentScope 中格式化器的基类
-# :header-rows: 1
-#
-# * - 类
-# - 抽象方法
-# - 描述
-# * - ``FormatterBase``
-# - ``format``
-# - 将输入的 ``Msg`` 对象格式化为目标 API 所期望的格式
-# * - ``TruncatedFormatterBase``
-# - ``_format_agent_message``
-# - 格式化智能体消息,在多智能体场景中可能包含多个身份
-# * -
-# - ``_format_tool_sequence``
-# - 将工具使用和结果序列格式化为所期望的格式
-# * -
-# - ``_format`` (可选)
-# - 将输入的 ``Msg`` 对象格式化为目标 API 所期望的格式
-#
-# .. tip:: ``TruncatedFormatterBase`` 中的 ``_format`` 将输入消息分组为智能体消息和工具序列,然后分别通过调用 ``_format_agent_message`` 和 ``_format_tool_sequence`` 来格式化它们。开发者可以重写两个函数来实现自己的格式化策略。
-#
-# .. tip:: 可选地,开发者可以重写 ``TruncatedFormatterBase`` 中的 ``_truncate`` 方法来实现自己的截断策略。
-#
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# - :ref:`token`
-# - :ref:`model`
-#
diff --git a/docs/tutorial/zh_CN/src/task_rag.py b/docs/tutorial/zh_CN/src/task_rag.py
deleted file mode 100644
index 8df617d67..000000000
--- a/docs/tutorial/zh_CN/src/task_rag.py
+++ /dev/null
@@ -1,404 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _rag:
-
-RAG
-==========================
-
-AgentScope 提供了内置的 RAG(Retrieval-Augmented Generation) 实现。本节将详细介绍
-
-- 如何使用 AgentScope 中的 RAG 模块,
-- 如何实现 **多模态** RAG,
-- 如何在 ``ReActAgent`` 中以两种不同的方式集成 RAG 模块:
- - 智能体自主控制(Agentic manner)
- - 通用方式(Generic manner)
-
-我们在下列表格中总结了两种模式的优缺点:
-
-.. list-table:: RAG 集成方式比较
- :header-rows: 1
-
- * - 集成方式
- - 描述
- - 优点
- - 缺点
- * - 智能体自主控制
- - 以工具调用方式让智能体自主决定何时进行查询,查询什么关键字
- - - 与 ReAct 算法契合,灵活性高
- - 智能体能够根据当前的上下文改写查询关键词
- - 避免在不必要时发生查询
- - 对 LLM 模型能力要求较高
- * - 通用方式
- - 每次在 ``reply`` 函数开始时固定进行查询,并将检索结果整合到提示(prompt)中
- - - 实现简单
- - 对 LLM 模型能力要求低
- - - 每次都会运行查询,因此会引入过多不必要的查询检索
- - 查询数据库较大时,回复延迟较高
-
-.. note:: 作为开源框架,AgentScope 的目标是让开发过程更简单也更有趣。因此,AgentScope 的设计中并不强制要求使用内置的 RAG 实现,同时支持、鼓励开发者集成现有的 RAG 实现或第三方 RAG 框架。
-
-"""
-import asyncio
-import json
-import os
-
-from matplotlib import pyplot as plt
-
-import agentscope
-from agentscope.agent import ReActAgent
-from agentscope.embedding import (
- DashScopeTextEmbedding,
- DashScopeMultiModalEmbedding,
-)
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.rag import (
- TextReader,
- SimpleKnowledge,
- QdrantStore,
- Document,
- ImageReader,
-)
-from agentscope.tool import Toolkit
-
-# %%
-# 使用 RAG 模块
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 中的 RAG 模块由以下三个核心组件构成:
-#
-# - **Reader**:负责从数据源读取数据,并进行分块(chunking)
-# - **Knowledge**:负责知识库查询检索和数据存储逻辑的算法实现
-# - **Store**:负责与向量数据库交互的逻辑实现
-#
-# .. note:: 我们将持续在 AgentScope 中集成新的向量数据库和数据读取模块。详情请查看我们的 `开发路线图 <https://github.com/orgs/agentscope-ai/projects/2>`_,同时也欢迎贡献代码!
-#
-# 当前 AgentScope 中内置支持的 reader 包括:
-#
-
-for _ in agentscope.rag.__all__:
- if _.endswith("Reader"):
- print(f"- {_}")
-
-# %%
-# 这些 reader 的作用是读取数据,将数据分块并包装成 ``agentscope.rag.Document`` 对象。 ``Document`` 对象包含以下字段:
-#
-# - ``metadata``:数据块的元信息,包含数据内容(``content``)、数据 ID(``doc_id``)、块 ID(``chunk_id``)和总块数(``total_chunks``)
-# - ``embedding``: 数据块的向量表示,默认为 ``None``,在将数据块添加到知识库时会被填充
-# - ``score``: 数据块的相关性分数,默认为 ``None``,在从知识库检索数据块时会被填充
-#
-# 以 ``TextReader`` 为例,通过如下代码读取文本字符串,并将文本分块为 ``Document`` 对象:
-#
-
-
-async def example_text_reader(print_docs: bool) -> list[Document]:
- """使用 TextReader 读取文本字符串,并将文本分块为 Document 对象。"""
- # 创建 TextReader 对象
- reader = TextReader(chunk_size=512, split_by="paragraph")
-
- # 读取文本字符串
- documents = await reader(
- text=(
- # 我们准备一些文本数据用于演示 RAG 功能。
- "我的名字是李明,今年28岁。\n"
- "我居住在中国杭州,是一名算法工程师。我喜欢打篮球和玩游戏。\n"
- "我父亲的名字是李强,是一名医生,我的母亲是陈芳芳,是一名教师,她总是指导我学习。\n"
- "我现在在北京大学攻读博士学位,研究方向是人工智能。\n"
- "我最好的朋友是王伟,我们从小一起长大,现在他是一名律师。"
- ),
- )
-
- if print_docs:
- print(f"文本被分块为 {len(documents)} 个 Document 对象:")
- for idx, doc in enumerate(documents):
- print(f"Document {idx}:")
- print("\tScore: ", doc.score)
- print(
- "\tMetadata: ",
- json.dumps(doc.metadata, indent=2, ensure_ascii=False),
- "\n",
- )
-
- return documents
-
-
-docs = asyncio.run(example_text_reader(print_docs=True))
-
-# %%
-# 由于并不存在一个 “one-for-all” 的数据读取和分块方法,特别像是 PDF 和 Word 这类复杂格式的文档。
-# 因此,AgentScope 鼓励开发者根据自己的数据格式实现自定义的 reader。
-# 只需要继承 ``BaseReader`` 类,并实现 ``__call__`` 方法即可。
-#
-# 在数据分块后,接下来需要将数据块添加到知识库中。
-# 在 AgentScope 中,知识库的初始化需要提供 **嵌入模型** 和 **向量存储** (即向量数据库) 的对象。
-# AgentScope 目前内置支持基于 `Qdrant <https://qdrant.tech/>`_ 实现的向量存储,以及一个知识库的基础实现 ``SimpleKnowledge``。
-# 具体使用方式如下:
-#
-# .. note::
-#
-# - 我们正在 AgentScope 中集成新的向量数据库,详情请查看我们的 `开发路线图 <https://github.com/orgs/agentscope-ai/projects/2>`_。欢迎贡献代码!
-# - Qdrant 的实现通过 ``location`` 参数支持多种不同的部署方式,包括内存模式,本地模式和云端模式。详情请参考 `Qdrant 文档 <https://qdrant.tech/>`_。
-#
-
-
-async def build_knowledge_base() -> SimpleKnowledge:
- """构建知识库。"""
- # 读取 documents 数据
- documents = await example_text_reader(print_docs=False)
-
- # 创建一个内存中的 Qdrant 向量存储,以及使用 DashScopeTextEmbedding 作为嵌入模型,初始化知识库
- knowledge = SimpleKnowledge(
- # 提供一个 embedding 模型用于将文本转换为向量
- embedding_model=DashScopeTextEmbedding(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="text-embedding-v4",
- dimensions=1024,
- ),
- # 选择 Qdrant 作为向量存储
- embedding_store=QdrantStore(
- location=":memory:", # 使用内存模式
- collection_name="test_collection",
- dimensions=1024, # 嵌入向量的维度必须与嵌入模型输出的维度一致
- ),
- )
-
- # 将 documents 添加到知识库中
- await knowledge.add_documents(documents)
-
- # 从知识库中检索数据
- docs = await knowledge.retrieve(
- query="李明的父亲是谁?",
- limit=3,
- score_threshold=0.5,
- )
-
- print("检索到的 Document 对象:")
- for doc in docs:
- print(doc, "\n")
-
- return knowledge
-
-
-knowledge = asyncio.run(build_knowledge_base())
-
-# %%
-# AgentScope 中的知识库类提供两个核心方法:``add_documents`` 和 ``retrieve``,分别用于添加数据块和搜索检索数据块。
-#
-# 此外,AgentScope 提供了 ``retrieve_knowledge`` 方法,它将 ``retrieve`` 方法封装成一个智能体能够直接调用的工具函数。开发者可以直接使用该工具函数装备智能体。
-#
-# 自定义 RAG 组件
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 支持并鼓励开发者自定义 RAG 组件,包括 reader、知识库和向量数据库。
-# 具体来说,我们提供了以下基类用于自定义:
-#
-# .. list-table:: RAG 基类
-# :header-rows: 1
-#
-# * - 基类
-# - 描述
-# - 抽象方法
-# * - ``ReaderBase``
-# - 所有 reader 的基类
-# - ``__call__``
-# * - ``VDBStoreBase``
-# - 向量数据库的基类
-# - | ``add``
-# | ``search``
-# | ``get_client`` (可选)
-# | ``delete`` (可选)
-# * - ``KnowledgeBase``
-# - 知识库的基类
-# - | ``retrieve``
-# | ``add_documents``
-#
-# ``VDBStoreBase`` 中的 ``get_client`` 方法允许开发者访问底层向量数据库的完整功能。
-# 这样,他们就可以基于向量数据库实现更高级的功能,例如建立索引、高级搜索等。
-#
-# 与 ReActAgent 集成
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 接下来,我们将演示如何以智能体自主控制(agentic)和通用(generic)两种方式将 RAG 模块与 AgentScope 中的 ``ReActAgent`` 集成。
-#
-# 智能体自主控制
-# --------------------------------
-# 在智能体自主控制的方式中,ReAct 智能体可以自主决定何时检索知识以及检索的查询内容。
-# 将 RAG 模块与 AgentScope 中的 ``ReActAgent`` 集成非常简单,只需将知识库的 ``retrieve_knowledge`` 方法注册为工具,并为该工具提供适当的描述即可。
-
-
-async def example_agentic_manner() -> None:
- """以智能体自主控制方式将 RAG 模块与 ReActAgent 集成的示例。"""
- # 创建一个 ReAct 智能体
- toolkit = Toolkit()
-
- # 使用 DashScope 作为模型创建 ReAct 智能体
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You're a helpful assistant named Friday.",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen-max",
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- )
-
- print("第一次回复: ")
- # 第一次我们进行一些交流,提供“李明”这个名字作为上下文内容
- await agent(
- Msg(
- "user",
- "李明是我最好的朋友。",
- "user",
- ),
- )
-
- # 将 retrieve_knowledge 方法注册为工具箱中的工具函数
- toolkit.register_tool_function(
- knowledge.retrieve_knowledge,
- func_description=( # 为工具提供清晰的描述
- "用于检索与给定查询相关的文档的工具。" "当你需要查找有关李明的信息时使用此工具。"
- ),
- )
-
- print("\n\n第二次回复: ")
- # 第二次回复中,我们希望智能体能够将查询中“他父亲”改写得更具体,例如
- # “李明的父亲是谁?”或“李明的父亲”
- await agent(
- Msg(
- "user",
- "你知道他父亲是谁吗?",
- "user",
- ),
- )
-
-
-asyncio.run(example_agentic_manner())
-
-# %%
-# 在上面的例子中,我们模拟了正常与智能体交流过程。第一次的交流我们提供了“李明”的名字作为上下文内容。
-# 第二次提问时,我们的问题是“你知道他父亲是谁吗?”,
-# 我们希望智能体能够利用上下文历史信息改写查询,使其更具体,更好的进行检索,例如改写为“李明的父亲是谁?”或“李明的父亲”。
-#
-# 更进一步,结合 :ref:`plan` 模块,我们可以让智能体实现更加复杂的查询改写和多轮检索。
-#
-# 通用方式
-# --------------------------------
-# ``ReActAgent`` 还以一种更加通用的方式集成了 RAG 模块,
-# 它在每次 ``reply`` 函数开始执行时检索知识,并将检索到的知识附加到用户消息的提示中。
-#
-# 只需设置 ``ReActAgent`` 的 ``knowledge`` 参数,智能体就会在每次回复开始时自动检索知识。
-#
-
-
-async def example_generic_manner() -> None:
- """以通用方式将 RAG 模块与 ReActAgent 集成的示例。"""
- # 创建一个 ReAct 智能体
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You're a helpful assistant named Friday.",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen-max",
- ),
- formatter=DashScopeChatFormatter(),
- # 将知识库传递给智能体
- knowledge=knowledge,
- )
-
- await agent(
- Msg(
- "user",
- "你知道李明的父亲是谁吗?",
- "user",
- ),
- )
-
- print("\n查看智能体记忆中检索信息如何插入:")
- content = (await agent.memory.get_memory())[1].content
- print(json.dumps(content, indent=2, ensure_ascii=False))
-
-
-asyncio.run(example_generic_manner())
-
-
-# %%
-# 多模态 RAG
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 中的 RAG 模块原生支持多模态,因为
-#
-# - AgentScope 支持多模态嵌入 API,例如 ``DashScopeMultimodalEmbedding``。
-# - ``Document`` 类的 ``metadata`` 中,``content`` 字段的类型是 ``TextBlock | ImageBlock | VideoBlock``,因此可以存储文本、图片和视频等多模态数据。
-#
-# 因此,我们可以直接使用多模态 reader 和嵌入模型来构建多模态知识库,如下所示。
-#
-# 首先,我们准备一张本地的图片,这张图片上包含了文本“My name is Ming Li”。
-
-# 准备一张包含文本“My name is Ming Li”的图片。
-path_image = "./example.png"
-plt.figure(figsize=(8, 3))
-plt.text(0.5, 0.5, "My name is Ming Li", ha="center", va="center", fontsize=30)
-plt.axis("off")
-plt.savefig(path_image, bbox_inches="tight", pad_inches=0.1)
-plt.close()
-
-# %%
-# 然后我们可以构建一个多模态知识库,构建过程与纯文本知识库类似。只是将 reader 和嵌入模型替换为多模态版本即可。
-# 在下面的例子中,我们使用了 ``ImageReader`` 和 ``DashScopeMultiModalEmbedding``。
-# 同时,这里我们使用多模态模型 ``qwen3-vl-plus`` 作为智能体的语言模型。
-#
-
-
-async def example_multimodal_rag() -> None:
- """使用多模态 RAG 的示例。"""
- # 使用 ImageReader 读取图片
- reader = ImageReader()
- docs = await reader(image_url=path_image)
-
- # 创建一个知识库
- knowledge = SimpleKnowledge(
- embedding_model=DashScopeMultiModalEmbedding(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="multimodal-embedding-v1",
- dimensions=1024,
- ),
- embedding_store=QdrantStore(
- location=":memory:",
- collection_name="test_collection",
- dimensions=1024,
- ),
- )
-
- await knowledge.add_documents(docs)
-
- agent = ReActAgent(
- name="Friday",
- sys_prompt="You're a helpful assistant named Friday.",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen3-vl-plus",
- ),
- formatter=DashScopeChatFormatter(),
- knowledge=knowledge,
- )
-
- await agent(
- Msg(
- "user",
- "你知道我的名字吗?",
- "user",
- ),
- )
-
- # 让我们看看检索到的图片数据是否已经加入了智能体的记忆中
- print("\n查看智能体记忆中检索信息如何插入:")
- content = (await agent.memory.get_memory())[1].content
- print(json.dumps(content, indent=2, ensure_ascii=False))
-
-
-asyncio.run(example_multimodal_rag())
-
-# %%
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`embedding`
-# - :ref:`plan`
-#
diff --git a/docs/tutorial/zh_CN/src/task_realtime.py b/docs/tutorial/zh_CN/src/task_realtime.py
deleted file mode 100644
index 7d113bb03..000000000
--- a/docs/tutorial/zh_CN/src/task_realtime.py
+++ /dev/null
@@ -1,486 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _realtime:
-
-实时智能体
-====================
-
-**实时智能体(Realtime Agent)** 用于处理实时交互场景,例如语音对话或实时聊天会话。
-AgentScope 中的实时智能体具有以下特性:
-
-- 集成 OpenAI、DashScope、Gemini 等实时模型 API
-- 统一的事件接口,简化与不同实时模型的交互
-- 支持工具调用能力
-- 支持多智能体交互
-
-.. note:: 实时智能体目前处于活跃开发阶段,欢迎社区贡献、讨论和反馈!如果开发者对实时智能体感兴趣,欢迎加入讨论和开发。
-
-"""
-
-import asyncio
-import os
-from agentscope.agent import RealtimeAgent
-from agentscope.realtime import (
- DashScopeRealtimeModel,
- OpenAIRealtimeModel,
- GeminiRealtimeModel,
-)
-
-# %%
-# 创建实时模型
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope 目前支持以下实时模型 API:
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 15 25 25 15 20
-#
-# * - 提供商
-# - 类名
-# - 支持的模型
-# - 输入模态
-# - 工具支持
-# * - DashScope
-# - ``DashScopeRealtimeModel``
-# - ``qwen3-omni-flash-realtime``
-# - 文本、音频、图像
-# - 否
-# * - OpenAI
-# - ``OpenAIRealtimeModel``
-# - ``gpt-4o-realtime-preview``
-# - 文本、音频
-# - 是
-# * - Gemini
-# - ``GeminiRealtimeModel``
-# - ``gemini-2.5-flash-native-audio-preview-09-2025``
-# - 文本、音频、图像
-# - 是
-#
-#
-# 以下是初始化不同实时模型的示例:
-#
-# .. code-block:: python
-# :caption: 初始化不同实时模型的示例
-#
-# # DashScope 实时模型
-# dashscope_model = DashScopeRealtimeModel(
-# model_name="qwen3-omni-flash-realtime",
-# api_key=os.getenv("DASHSCOPE_API_KEY"),
-# voice="Cherry", # 可选项: "Cherry", "Serena", "Ethan", "Chelsie"
-# enable_input_audio_transcription=True,
-# )
-#
-# # OpenAI 实时模型
-# openai_model = OpenAIRealtimeModel(
-# model_name="gpt-4o-realtime-preview",
-# api_key=os.getenv("OPENAI_API_KEY"),
-# voice="alloy", # 可选项: "alloy", "echo", "marin", "cedar"
-# enable_input_audio_transcription=True,
-# )
-#
-# # Gemini 实时模型
-# gemini_model = GeminiRealtimeModel(
-# model_name="gemini-2.5-flash-native-audio-preview-09-2025",
-# api_key=os.getenv("GEMINI_API_KEY"),
-# voice="Puck", # 可选项: "Puck", "Charon", "Kore", "Fenrir"
-# enable_input_audio_transcription=True,
-# )
-#
-#
-#
-# 实时模型提供以下核心方法:
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 30 70
-#
-# * - 方法
-# - 描述
-# * - ``connect(outgoing_queue, instructions, tools)``
-# - 建立与实时模型 API 的 WebSocket 连接
-# * - ``disconnect()``
-# - 关闭 WebSocket 连接
-# * - ``send(data)``
-# - 向实时模型发送音频/文本/图像数据进行处理
-#
-# ``connect()`` 方法中的 ``outgoing_queue`` 参数是一个 asyncio 队列,
-# 用于将实时模型的事件转发到外部(例如智能体或前端)。
-#
-#
-# 模型事件接口
-# -----------------------
-#
-# AgentScope 提供统一的 ``agentscope.realtime.ModelEvents`` 接口,
-# 简化与不同实时模型的交互。支持以下事件:
-#
-# .. note:: ModelEvents 中的 "session" 指的是实时模型与模型 API 之间的
-# WebSocket 连接会话,而非前端与后端之间的会话。
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 40 60
-#
-# * - 事件
-# - 描述
-# * - ``ModelEvents.ModelSessionCreatedEvent``
-# - 会话创建成功
-# * - ``ModelEvents.ModelSessionEndedEvent``
-# - 会话已结束
-# * - ``ModelEvents.ModelResponseCreatedEvent``
-# - 模型开始生成响应
-# * - ``ModelEvents.ModelResponseDoneEvent``
-# - 模型完成响应生成
-# * - ``ModelEvents.ModelResponseAudioDeltaEvent``
-# - 流式音频数据块
-# * - ``ModelEvents.ModelResponseAudioDoneEvent``
-# - 音频响应完成
-# * - ``ModelEvents.ModelResponseAudioTranscriptDeltaEvent``
-# - 流式音频转录文本块
-# * - ``ModelEvents.ModelResponseAudioTranscriptDoneEvent``
-# - 音频转录完成
-# * - ``ModelEvents.ModelResponseToolUseDeltaEvent``
-# - 流式工具调用参数
-# * - ``ModelEvents.ModelResponseToolUseDoneEvent``
-# - 工具调用参数完成
-# * - ``ModelEvents.ModelInputTranscriptionDeltaEvent``
-# - 流式用户输入转录文本块
-# * - ``ModelEvents.ModelInputTranscriptionDoneEvent``
-# - 用户输入转录完成
-# * - ``ModelEvents.ModelInputStartedEvent``
-# - 检测到用户音频输入开始(VAD)
-# * - ``ModelEvents.ModelInputDoneEvent``
-# - 检测到用户音频输入结束(VAD)
-# * - ``ModelEvents.ModelErrorEvent``
-# - 发生错误
-#
-#
-#
-# 创建实时智能体
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# ``RealtimeAgent`` 作为桥接层,负责:
-#
-# - 将实时模型的 ``ModelEvents`` 转换为 ``ServerEvents``,发送给前端和其他智能体
-# - 接收来自前端或其他智能体的 ``ClientEvents``,并转发给实时模型 API
-# - 管理智能体的生命周期和事件队列
-#
-# 服务端和客户端事件
-# -------------------------
-#
-# AgentScope 提供统一的 ``ServerEvents`` 和 ``ClientEvents``,
-# 用于后端与前端之间的通信:
-#
-# **ServerEvents**(后端 → 前端):
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 40 60
-#
-# * - 事件
-# - 描述
-# * - ``ServerEvents.ServerSessionCreatedEvent``
-# - 后端创建会话
-# * - ``ServerEvents.ServerSessionUpdatedEvent``
-# - 后端更新会话
-# * - ``ServerEvents.ServerSessionEndedEvent``
-# - 后端结束会话
-# * - ``ServerEvents.AgentReadyEvent``
-# - 智能体准备接收输入
-# * - ``ServerEvents.AgentEndedEvent``
-# - 智能体已结束
-# * - ``ServerEvents.AgentResponseCreatedEvent``
-# - 智能体开始生成响应
-# * - ``ServerEvents.AgentResponseDoneEvent``
-# - 智能体完成响应生成
-# * - ``ServerEvents.AgentResponseAudioDeltaEvent``
-# - 智能体流式音频块
-# * - ``ServerEvents.AgentResponseAudioDoneEvent``
-# - 音频响应完成
-# * - ``ServerEvents.AgentResponseAudioTranscriptDeltaEvent``
-# - 智能体响应的流式转录
-# * - ``ServerEvents.AgentResponseAudioTranscriptDoneEvent``
-# - 转录完成
-# * - ``ServerEvents.AgentResponseToolUseDeltaEvent``
-# - 流式工具调用数据
-# * - ``ServerEvents.AgentResponseToolUseDoneEvent``
-# - 工具调用完成
-# * - ``ServerEvents.AgentResponseToolResultEvent``
-# - 工具执行结果
-# * - ``ServerEvents.AgentInputTranscriptionDeltaEvent``
-# - 用户输入的流式转录
-# * - ``ServerEvents.AgentInputTranscriptionDoneEvent``
-# - 输入转录完成
-# * - ``ServerEvents.AgentInputStartedEvent``
-# - 用户音频输入开始
-# * - ``ServerEvents.AgentInputDoneEvent``
-# - 用户音频输入结束
-# * - ``ServerEvents.AgentErrorEvent``
-# - 发生错误
-#
-# **ClientEvents**(前端 → 后端):
-#
-# .. list-table::
-# :header-rows: 1
-# :widths: 40 60
-#
-# * - 事件
-# - 描述
-# * - ``ClientEvents.ClientSessionCreateEvent``
-# - 创建指定配置的新会话
-# * - ``ClientEvents.ClientSessionEndEvent``
-# - 结束当前会话
-# * - ``ClientEvents.ClientResponseCreateEvent``
-# - 请求智能体立即生成响应
-# * - ``ClientEvents.ClientResponseCancelEvent``
-# - 中断智能体的当前响应
-# * - ``ClientEvents.ClientTextAppendEvent``
-# - 追加文本输入
-# * - ``ClientEvents.ClientAudioAppendEvent``
-# - 追加音频输入
-# * - ``ClientEvents.ClientAudioCommitEvent``
-# - 提交音频输入(标志输入结束)
-# * - ``ClientEvents.ClientImageAppendEvent``
-# - 追加图像输入
-# * - ``ClientEvents.ClientToolResultEvent``
-# - 发送工具执行结果
-#
-# 初始化实时智能体
-# ------------------------------
-#
-# 以下是创建和使用实时智能体的示例:
-
-
-async def example_realtime_agent() -> None:
- """创建和使用实时智能体的示例。"""
- agent = RealtimeAgent(
- name="Friday",
- sys_prompt="你是一个名为 Friday 的助手。",
- model=DashScopeRealtimeModel(
- model_name="qwen3-omni-flash-realtime",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- ),
- )
-
- # 创建队列接收来自智能体的消息
- outgoing_queue = asyncio.Queue()
-
- # 智能体现在已准备好处理输入
- # 在独立任务中处理输出消息
- async def handle_agent_messages():
- while True:
- event = await outgoing_queue.get()
- # 处理事件(例如通过 WebSocket 发送到前端)
- print(f"智能体事件: {event.type}")
-
- # 启动消息处理任务
- asyncio.create_task(handle_agent_messages())
-
- # 启动智能体(建立连接)
- await agent.start(outgoing_queue)
-
- # 完成后停止智能体
- await agent.stop()
-
-
-# %%
-# 启动实时对话
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 下面演示如何在用户和实时智能体之间建立实时对话。
-#
-# 这里以 FastAPI 为例,展示如何搭建实时对话的后端框架。
-#
-# **后端设置(服务端):**
-#
-# 后端需要:
-#
-# 1. 创建 WebSocket 端点接受前端连接
-# 2. 在会话开始时创建 ``RealtimeAgent``
-# 3. 将前端的 ``ClientEvents`` 转发给智能体
-# 4. 将智能体的 ``ServerEvents`` 转发给前端
-#
-# .. code-block:: python
-#
-# from fastapi import FastAPI, WebSocket
-# from agentscope.agent import RealtimeAgent
-# from agentscope.realtime import (
-# DashScopeRealtimeModel,
-# ClientEvents,
-# ServerEvents,
-# )
-#
-# app = FastAPI()
-#
-# @app.websocket("/ws/{user_id}/{session_id}")
-# async def websocket_endpoint(
-# websocket: WebSocket,
-# user_id: str,
-# session_id: str,
-# ):
-# await websocket.accept()
-#
-# # 创建智能体消息队列
-# frontend_queue = asyncio.Queue()
-#
-# # 创建智能体
-# agent = RealtimeAgent(
-# name="Assistant",
-# sys_prompt="你是一个有用的助手。",
-# model=DashScopeRealtimeModel(
-# model_name="qwen3-omni-flash-realtime",
-# api_key=os.getenv("DASHSCOPE_API_KEY"),
-# ),
-# )
-#
-# # 启动智能体
-# await agent.start(frontend_queue)
-#
-# # 将智能体消息转发到前端
-# async def send_to_frontend():
-# while True:
-# msg = await frontend_queue.get()
-# await websocket.send_json(msg.model_dump())
-#
-# asyncio.create_task(send_to_frontend())
-#
-# # 接收前端消息并转发给智能体
-# while True:
-# data = await websocket.receive_json()
-# client_event = ClientEvents.from_json(data)
-# await agent.handle_input(client_event)
-#
-# **前端设置(客户端):**
-#
-# 前端需要:
-#
-# 1. 建立与后端的 WebSocket 连接
-# 2. 发送 ``CLIENT_SESSION_CREATE`` 事件初始化会话
-# 3. 捕获麦克风音频,通过 ``CLIENT_AUDIO_APPEND`` 事件发送
-# 4. 接收并处理 ``ServerEvents``(例如播放音频、显示转录文本)
-#
-# .. code-block:: javascript
-#
-# // 连接 WebSocket
-# const ws = new WebSocket('ws://localhost:8000/ws/user1/session1');
-#
-# ws.onopen = () => {
-# // 创建会话
-# ws.send(JSON.stringify({
-# type: 'client_session_create',
-# config: {
-# instructions: '你是一个有用的助手。',
-# user_name: 'User1'
-# }
-# }));
-# };
-#
-# // 处理来自后端的消息
-# ws.onmessage = (event) => {
-# const data = JSON.parse(event.data);
-# if (data.type === 'response_audio_delta') {
-# // 播放音频块
-# playAudio(data.delta);
-# }
-# };
-#
-# // 发送音频数据
-# function sendAudioChunk(audioData) {
-# ws.send(JSON.stringify({
-# type: 'client_audio_append',
-# session_id: 'session1',
-# audio: audioData, // base64 编码
-# format: { encoding: 'pcm16', sample_rate: 16000 }
-# }));
-# }
-#
-# 完整的工作示例请参见 AgentScope 仓库中的
-# ``examples/agent/realtime_voice_agent/``。
-
-# %%
-# 多智能体实时对话
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# AgentScope 通过 ``ChatRoom`` 类支持多智能体实时交互。
-#
-# 请注意目前大多数实时模型 API 仅支持单用户交互,但 AgentScope 的架构设计支持多智能体和多用户,
-# 当 API 能力扩展时即可应用到多智能体场景。
-#
-# 实时聊天室
-# ----------------------------
-#
-# AgentScope 引入 ``ChatRoom`` 类来管理共享对话空间中的多个实时智能体。
-# ChatRoom 提供:
-#
-# - 集中管理多个 ``RealtimeAgent`` 实例
-# - 智能体之间的自动消息广播
-# - 统一的前端通信消息队列
-# - 房间内所有智能体的生命周期管理
-#
-# 使用 ChatRoom
-# --------------
-#
-# ``ChatRoom`` 的用法与 ``RealtimeAgent`` 类似:
-#
-
-
-async def example_chat_room() -> None:
- """使用 ChatRoom 和多个实时智能体的示例。"""
- from agentscope.pipeline import ChatRoom
- from agentscope.agent import RealtimeAgent
- from agentscope.realtime import DashScopeRealtimeModel
-
- # 创建多个智能体
- agent1 = RealtimeAgent(
- name="Agent1",
- sys_prompt="你是 Agent1,一个有用的助手。",
- model=DashScopeRealtimeModel(
- model_name="qwen3-omni-flash-realtime",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- ),
- )
-
- agent2 = RealtimeAgent(
- name="Agent2",
- sys_prompt="你是 Agent2,一个有用的助手。",
- model=DashScopeRealtimeModel(
- model_name="qwen3-omni-flash-realtime",
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- ),
- )
-
- # 创建包含多个智能体的聊天室
- chat_room = ChatRoom(agents=[agent1, agent2])
-
- # 创建队列接收来自所有智能体的消息
- outgoing_queue = asyncio.Queue()
-
- # 启动聊天室
- await chat_room.start(outgoing_queue)
-
- # 处理来自前端的输入
- # 聊天室会广播给所有智能体
- from agentscope.realtime import ClientEvents
-
- client_event = ClientEvents.ClientTextAppendEvent(
- session_id="session1",
- text="大家好!",
- )
- await chat_room.handle_input(client_event)
-
- # 完成后停止聊天室
- await chat_room.stop()
-
-
-# %%
-# 发展规划
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 实时智能体功能目前为实验性质,正在积极开发中。未来计划包括:
-#
-# - 支持更多实时模型 API
-# - 增强对话历史的记忆管理
-# - 多用户语音交互支持
-# - 改进 VAD(语音活动检测)配置
-# - 更好的错误处理和恢复机制
-#
-#
diff --git a/docs/tutorial/zh_CN/src/task_state.py b/docs/tutorial/zh_CN/src/task_state.py
deleted file mode 100644
index 89a0d64b3..000000000
--- a/docs/tutorial/zh_CN/src/task_state.py
+++ /dev/null
@@ -1,215 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _state:
-
-状态/会话管理
-=================================
-
-在 AgentScope 中,**"状态"** 是指智能体在运行中某一时刻的数据快照,包括其当前的系统提示、记忆、上下文、装备的工具以及其他 **随时间变化** 的信息。
-
-为了管理应用程序的状态,AgentScope 设计实现了 **自动状态注册** 和 **会话级状态管理**,具有以下特性:
-
-- 支持所有继承自 ``StateModule`` 的变量的 **自动状态注册**
-- 支持使用自定义序列化/反序列化方法的 **手动状态注册**
-- 支持 **会话/应用程序级别管理**
-"""
-import asyncio
-import json
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.module import StateModule
-from agentscope.session import JSONSession
-from agentscope.tool import Toolkit
-
-# %%
-# 状态模块
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# ``StateModule`` 类是 AgentScope 中状态管理的基础,提供三个基本函数:
-#
-# .. list-table:: ``StateModule`` 的方法
-# :header-rows: 1
-#
-# * - 方法
-# - 参数
-# - 描述
-# * - ``register_state``
-# - | ``attr_name``,
-# | ``custom_to_json`` (可选),
-# | ``custom_from_json`` (可选)
-# - 将属性注册为其状态,带有可选的序列化/反序列化函数。
-# * - ``state_dict``
-# -
-# - 获取当前对象的状态字典
-# * - ``load_state_dict``
-# - | ``state_dict``,
-# | ``strict`` (可选)
-# - 将状态字典加载到当前对象
-#
-# 在 ``StateModule`` 的对象中,以下所有属性都将被视为其状态的一部分:
-#
-# - 继承自 ``StateModule`` 的 **属性**
-# - 通过 ``register_state`` 方法注册的 **属性**
-#
-# 注意 ``StateModule`` 支持 **嵌套** 序列化和反序列化,例如下面的示例中,``ClassB`` 中包含一个 ``ClassA`` 的实例:
-#
-
-
-class ClassA(StateModule):
- def __init__(self) -> None:
- super().__init__()
- self.cnt = 123
- # 将 cnt 属性注册为状态
- self.register_state("cnt")
-
-
-class ClassB(StateModule):
- def __init__(self) -> None:
- super().__init__()
-
- # 属性 "a" 继承自 StateModule,将自动视为状态的一部分
- self.a = ClassA()
-
- # 手动将属性 "c" 注册为状态
- self.c = "Hello, world!"
- self.register_state("c")
-
-
-obj_b = ClassB()
-
-print("obj_b.a 的状态:")
-print(obj_b.a.state_dict())
-
-print("\nobj_b 的状态:")
-print(json.dumps(obj_b.state_dict(), indent=4))
-
-# %%
-# 我们可以观察到 ``obj_b`` 的状态自动包含了其属性 ``a`` 的状态。
-#
-# 在 AgentScope 中,``AgentBase``、``MemoryBase``、``LongTermMemoryBase`` 和 ``Toolkit`` 类都继承自 ``StateModule``,因此支持自动和嵌套状态管理。
-#
-
-# 创建一个智能体
-agent = ReActAgent(
- name="Friday",
- sys_prompt="你是一个名为 Friday 的助手。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(),
- memory=InMemoryMemory(),
- toolkit=Toolkit(),
-)
-
-initial_state = agent.state_dict()
-
-print("智能体的初始状态:")
-print(json.dumps(initial_state, indent=4, ensure_ascii=False))
-
-# %%
-# 然后我们通过生成回复消息来改变其状态:
-#
-
-
-async def example_agent_state() -> None:
- """智能体状态管理示例。"""
- await agent(Msg("user", "你好,智能体!", "user"))
-
- print("生成回复后智能体的状态:")
- print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
-
-
-asyncio.run(example_agent_state())
-
-# %%
-# 现在我们将智能体的状态恢复到初始状态:
-#
-
-agent.load_state_dict(initial_state)
-
-print("加载初始状态后:")
-print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
-
-# %%
-# 会话管理
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# 会话(Session)是应用程序中状态的集合,例如多个智能体。
-#
-# AgentScope 提供了 ``SessionBase`` 类,包含两个用于会话管理的抽象方法:``save_session_state`` 和 ``load_session_state``。
-# 开发者可以继承该类来实现自己的状态保存方案,例如对接到自己的数据库或文件系统。
-#
-# 在 AgentScope 中,我们提供了基于 JSON 和文件系统的的会话类 ``JSONSession``,
-# 它会将状态保存到会化 ID 命名的 JSON 文件中,也可以从中加载状态。
-#
-# 保存会话状态
-# -----------------------------------------
-#
-
-# 通过生成回复消息改变智能体状态
-asyncio.run(example_agent_state())
-
-print("\n智能体的状态:")
-print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
-
-# %%
-# 然后我们将其保存到会话文件中:
-
-session = JSONSession(
- save_dir="./", # 保存所有session文件的目录
-)
-
-
-async def example_session() -> None:
- """会话管理示例。"""
-
- # 可以保存多个状态,只需要输入的对象为 `StateModule` 的子类。
- await session.save_session_state(
- session_id="user_bob",
- agent=agent,
- )
-
- print("保存的状态:")
- with open("./user_bob.json", "r", encoding="utf-8") as f:
- print(json.dumps(json.load(f), indent=4, ensure_ascii=False))
-
-
-asyncio.run(example_session())
-
-# %%
-# 加载会话状态
-# -----------------------------------------
-# 然后我们可以从会话文件中加载状态:
-#
-
-
-async def example_load_session() -> None:
- """加载会话状态示例。"""
-
- # 清空智能体状态
- await agent.memory.clear()
-
- print("当前智能体状态:")
- print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
-
- # 从会话文件中加载状态
- await session.load_session_state(
- session_id="user_bob",
- # 这里使用的关键词参数必须与 `save_session_state` 中的参数一致
- agent=agent,
- )
- print("加载会话状态后智能体的状态:")
- print(json.dumps(agent.state_dict(), indent=4, ensure_ascii=False))
-
-
-asyncio.run(example_load_session())
-
-# %%
-# 此时我们可以观察到智能体的状态已经恢复到之前保存的状态。
-#
diff --git a/docs/tutorial/zh_CN/src/task_studio.py b/docs/tutorial/zh_CN/src/task_studio.py
deleted file mode 100644
index 5ab6096e6..000000000
--- a/docs/tutorial/zh_CN/src/task_studio.py
+++ /dev/null
@@ -1,118 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _studio:
-
-AgentScope Studio
-=========================
-
-AgentScope Studio 是一个本地部署的 Web 应用程序,它
-
-- 为智能体应用程序的开发提供 **项目管理**
-- 为运行中的应用程序提供 **可视化** 追踪
-- 内置一个为 "Friday" 的 **智能体**,支持用户二次开发
-
-.. note:: Studio 正在快速开发中,更多功能即将推出!
-
-.. figure:: ../../_static/images/studio_home.webp
- :width: 100%
- :alt: AgentScope Studio 主页
- :class: bordered-image
- :align: center
-
- AgentScope Studio 主页
-
-快速开始
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-AgentScope Studio 通过 ``npm`` 安装:
-
-.. code-block:: bash
-
- npm install -g @agentscope/studio
-
-
-使用以下命令启动 Studio:
-
-.. code-block:: bash
-
- as_studio
-
-要将应用程序连接到 Studio,请在 ``agentscope.init`` 函数中使用 ``studio_url`` 参数:
-
-.. code-block:: python
-
- import agentscope
-
- agentscope.init(studio_url="http://localhost:3000")
-
- # 应用程序代码
- ...
-
-然后可以在 Studio 中看到该应用程序,如下所示:
-
-.. figure:: ../../_static/images/studio_project.webp
- :width: 100%
- :alt: 项目管理
- :class: bordered-image
- :align: center
-
- AgentScope Studio 中的项目管理
-
-关于应用程序的详细信息,例如 token 使用情况、模型调用和追踪信息,都可以在 Studio 中查看。
-
-.. figure:: ../../_static/images/studio_run.webp
- :width: 100%
- :alt: AgentScope Studio 运行页面
- :class: bordered-image
- :align: center
-
- AgentScope Studio 中的应用程序可视化
-
-
-Friday 智能体
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Friday 是由 AgentScope 构建的实验性本地部署智能体,旨在
-
-- 回答关于 AgentScope 开发的问题,
-- 为开发者提供便捷的二次开发环境,
-- 集成 AgentScope 中所有可用功能以构建更强大的智能体,以及
-- 持续测试和集成 AgentScope 中的高级功能。
-
-.. note:: 我们非常欢迎开源社区贡献并改进 Friday!欢迎在我们的 `GitHub 仓库 <https://github.com/agentscope-ai/agentscope>`_ 上提出问题或拉取请求。
-
-我们正在持续改进 Friday,目前它集成了 AgentScope 中的以下功能:
-
-.. list-table::
- :header-rows: 1
-
- * - 功能
- - 状态
- - 进一步阅读
- - 描述
- * - 元工具
- - ✅
- - :ref:`tool`
- - 分组工具管理,允许智能体自己更改装备的工具。
- * - 智能体钩子
- - ✅
- - :ref:`hook`
- - 使用钩子将打印消息转发到前端。
- * - 智能体中断
- - ✅
- - :ref:`agent`
- - 允许用户通过后处理中断智能体的回复过程。
- * - 截断提示
- - ✅
- - :ref:`prompt`
- - 支持使用预设的最大 token 限制截断提示。
- * - 状态和会话管理
- - ✅
- - :ref:`state`
- - 智能体的自动状态管理和会话管理,在不同运行之间维护状态。
- * - 长期记忆
- - 🚧
- - :ref:`memory`
- - 支持长期记忆管理。
-
-
-"""
diff --git a/docs/tutorial/zh_CN/src/task_token.py b/docs/tutorial/zh_CN/src/task_token.py
deleted file mode 100644
index 63c6e893e..000000000
--- a/docs/tutorial/zh_CN/src/task_token.py
+++ /dev/null
@@ -1,77 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _token:
-
-Token 计数
-=========================
-
-AgentScope 在 ``agentscope.token`` 模块下提供了 token 计数功能,用于计算给定消息中
-的 token 数量,允许开发者在调用 LLM API 前预估 token 数量。
-
-具体而言,可用的 token 计数器如下:
-
-.. list-table::
- :header-rows: 1
-
- * - LLM API
- - 类
- - 实现方式
- - 支持图像数据
- - 支持工具
- * - Anthropic
- - ``AnthropicTokenCounter``
- - 官方 API
- - ✅
- - ✅
- * - OpenAI
- - ``OpenAITokenCounter``
- - 本地计算
- - ✅
- - ✅
- * - Gemini
- - ``GeminiTokenCounter``
- - 官方 API
- - ✅
- - ✅
- * - HuggingFace
- - ``HuggingFaceTokenCounter``
- - 基于Tokenizer计算
- - 取决于模型
- - 取决于模型
-
-.. tip:: 格式化器模块已集成了 token 计数器以支持提示截断。更多详细信息请参考 :ref:`prompt` 部分。
-
-.. note::
- - 对于 DashScope 模型,目前 dashscope 库不提供 token 计数 API。因此我们建议使用 HuggingFace token 计数器代替。
- - 对于 OpenAI 模型,由于官方未提供 token 计数 API,因此可能存在与官方计算结果不一致的情况。
-
-下面展示使用 OpenAI token 计数器计算 token 数量的示例:
-"""
-
-import asyncio
-from agentscope.token import OpenAITokenCounter
-
-
-async def example_token_counting():
- # 示例消息
- messages = [
- {"role": "user", "content": "Hello!"},
- {"role": "assistant", "content": "Hi, how can I help you?"},
- ]
-
- # OpenAI token 计数
- openai_counter = OpenAITokenCounter(model_name="gpt-4.1")
- n_tokens = await openai_counter.count(messages)
-
- print(f"Token 数量: {n_tokens}")
-
-
-asyncio.run(example_token_counting())
-
-
-# %%
-# 进一步阅读
-# ------------------------------
-#
-# - :ref:`prompt`
-#
diff --git a/docs/tutorial/zh_CN/src/task_tool.py b/docs/tutorial/zh_CN/src/task_tool.py
deleted file mode 100644
index ae8b80d75..000000000
--- a/docs/tutorial/zh_CN/src/task_tool.py
+++ /dev/null
@@ -1,457 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tool:
-
-工具
-=========================
-
-为了确保准确可靠的工具解析,AgentScope 全面支持工具 API 的使用,具有以下特性:
-
-- 支持从文档字符串 **自动** 解析工具函数
-- 支持 **同步和异步** 工具函数
-- 支持 **流式** 工具响应(同步或异步生成器)
-- 支持对工具 JSON Schema 的 **动态扩展**
-- 支持用户实时 **中断** 工具的执行
-- 支持智能体的 **自主工具管理**
-
-所有上述功能都由 AgentScope 中的 ``Toolkit`` 类实现,该类负责管理工具函数及其执行。
-
-.. tip:: MCP(模型上下文协议)的支持请参考 :ref:`mcp` 部分。
-"""
-import asyncio
-import inspect
-import json
-from typing import Any, AsyncGenerator
-
-from pydantic import BaseModel, Field
-
-import agentscope
-from agentscope.message import TextBlock, ToolUseBlock
-from agentscope.tool import ToolResponse, Toolkit, execute_python_code
-
-
-# %%
-# 工具函数
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 在 AgentScope 中,工具函数是一个 Python 的可调用对象,它
-#
-# - 返回一个 ``ToolResponse`` 对象或产生 ``ToolResponse`` 对象的生成器(可以是异步或同步)
-# - 具有描述工具功能和参数的文档字符串
-#
-# 工具函数的模板如下:
-
-
-def tool_function(a: int, b: str) -> ToolResponse:
- """{函数描述}
-
- Args:
- a (int):
- {第一个参数的描述}
- b (str):
- {第二个参数的描述}
- """
-
-
-# %%
-# .. tip:: 实例方法和类方法也可以用作工具函数,``Toolkit`` 中将自动忽略 ``self`` 和 ``cls`` 参数。
-#
-# AgentScope 在 ``agentscope.tool`` 模块下提供了几个内置工具函数,如 ``execute_python_code``、``execute_shell_command`` 和文本文件读写函数。
-#
-
-print("内置工具函数:")
-for _ in agentscope.tool.__all__:
- if _ not in ["Toolkit", "ToolResponse"]:
- print(_)
-
-# %%
-# 工具模块(Toolkit)
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# ``Toolkit`` 类设计用于管理工具函数,从文档字符串中提取它们的 JSON Schema,并为工具执行提供统一接口。
-#
-# 基本用法
-# ------------------------------
-# ``Toolkit`` 类的基本功能是注册工具函数并执行它们。
-#
-
-
-# 准备一个自定义工具函数
-async def my_search(query: str, api_key: str) -> ToolResponse:
- """一个简单的示例工具函数。
-
- Args:
- query (str):
- 搜索查询。
- api_key (str):
- 用于身份验证的 API 密钥。
- """
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"正在使用 API 密钥 '{api_key}' 搜索 '{query}'",
- ),
- ],
- )
-
-
-# 在工具模块中注册工具函数
-toolkit = Toolkit()
-toolkit.register_tool_function(my_search)
-
-# %%
-# 注册工具函数后,可以通过调用 ``get_json_schemas`` 方法获取其 JSON Schema。
-#
-
-print("工具 JSON Schemas:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# ``Toolkit`` 还允许开发者为工具函数预设参数,这对于 API 密钥或其他敏感信息特别有用。
-#
-
-# 先清空工具模块
-toolkit.clear()
-
-# 使用预设关键字参数注册工具函数
-toolkit.register_tool_function(my_search, preset_kwargs={"api_key": "xxx"})
-
-print("带预设参数的工具 JSON Schemas:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# 预设参数后,该参数将从 JSON schema 中被移除,并在工具调用时自动传递给该工具函数。
-#
-# 在 ``Toolkit`` 中,``call_tool_function`` 方法以 ``ToolUseBlock`` 作为输入执行指定的工具函数,统一返回一个 **异步生成器**,该生成器产生 ``ToolResponse`` 对象。
-#
-# .. note:: AgentScope 中,流式返回的工具函数应该是 **“累积的”**,即当前块的内容应包含之前所有块的内容。
-#
-
-
-async def example_tool_execution() -> None:
- """工具调用执行示例。"""
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="123",
- name="my_search",
- input={"query": "AgentScope"},
- ),
- )
-
- # 非流式返回的工具函数只有一个 ToolResponse 返回
- print("工具响应:")
- async for tool_response in res:
- print(tool_response)
-
-
-asyncio.run(example_tool_execution())
-
-# %%
-# 动态扩展 JSON Schema
-# --------------------------------------
-#
-# Toolkit 允许通过调用 ``set_extended_model`` 方法动态扩展工具函数的 JSON schemas。
-# 这种功能允许开发者在不修改工具函数原始定义的情况下,向工具函数添加更多参数。
-#
-# .. tip:: 相关场景包括动态 :ref:`structured-output` 和 CoT(思维链)推理
-#
-# .. note:: 要扩展的工具函数应该接受可变关键字参数(``**kwargs``),以便附加字段可以传递给它。
-#
-# 以 CoT 推理为例,我们可以用 ``thinking`` 字段扩展所有工具函数,允许智能体总结当前状态然后决定下一步做什么。
-#
-
-
-# 示例工具函数
-def tool_function(**kwargs: Any) -> ToolResponse:
- """一个工具函数"""
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text=f"接收到的参数:{kwargs}",
- ),
- ],
- )
-
-
-# 添加一个思考字段,以便智能体在给出其他参数之前可以思考。
-class ThinkingModel(BaseModel):
- """用于附加字段的 Pydantic 模型。"""
-
- thinking: str = Field(
- description="总结当前状态并决定下一步做什么。",
- )
-
-
-# 注册
-toolkit.set_extended_model("my_search", ThinkingModel)
-
-print("扩展后的 JSON Schema:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# 中断工具执行
-# ------------------------------
-# ``Toolkit`` 类支持 **异步工具函数** 的 **执行中断**,并提供 **面向智能体的后处理机制**。
-# 这种中断基于 asyncio 取消机制实现,其后处理过程根据工具函数的返回类型而有所不同。
-#
-# .. note:: 对于同步(工具)函数,它们的执行无法通过 asyncio 取消来中断。因此其中断在智能体内而不是工具模块内处理。
-# 有关更多信息,请参考 :ref:`agent` 部分。
-#
-# 具体来说,如果工具函数返回 ``ToolResponse`` 对象,将产生一个带有中断消息的 ``ToolResponse`` 对象。
-# 这样智能体可以观察到这一中断并相应地处理它。
-# 此外,该 ``ToolResponse`` 对象中的 ``is_interrupted`` 将设置为 ``True``,外部调用者可以决定是否将 ``CancelledError`` 异常抛出到外层。
-#
-# 可以被中断的异步工具函数示例如下:
-#
-
-
-async def non_streaming_function() -> ToolResponse:
- """一个可以被中断的非流式工具函数。"""
- await asyncio.sleep(1) # 模拟长时间运行的任务
-
- # 为演示目的模拟中断
- raise asyncio.CancelledError()
-
- # 由于取消,以下代码不会被执行
- return ToolResponse(
- content=[
- TextBlock(
- type="text",
- text="运行成功!",
- ),
- ],
- )
-
-
-async def example_tool_interruption() -> None:
- """工具中断示例。"""
- toolkit = Toolkit()
- toolkit.register_tool_function(non_streaming_function)
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="123",
- name="non_streaming_function",
- input={},
- ),
- )
-
- async for tool_response in res:
- print("工具响应:")
- print(tool_response)
- print("中断标志:")
- print(tool_response.is_interrupted)
-
-
-asyncio.run(example_tool_interruption())
-
-# %%
-# 对于流式工具函数,``Toolkit`` 将把中断消息附加到中断发生时的 ``ToolResponse`` 上。
-# 通过这种方式,智能体可以观察到工具在中断前返回的内容。
-#
-# 中断流式工具函数的示例如下:
-#
-
-
-async def streaming_function() -> AsyncGenerator[ToolResponse, None]:
- """一个可以被中断的流式工具函数。"""
- # 模拟一块响应
- yield ToolResponse(
- content=[
- TextBlock(
- type="text",
- text="1234",
- ),
- ],
- stream=True,
- )
-
- # 模拟中断
- raise asyncio.CancelledError()
-
- # 由于取消,以下代码不会被执行
- yield ToolResponse(
- content=[
- TextBlock(
- type="text",
- text="123456789",
- ),
- ],
- )
-
-
-async def example_streaming_tool_interruption() -> None:
- """流式工具中断示例。"""
- toolkit = Toolkit()
- toolkit.register_tool_function(streaming_function)
-
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="xxx",
- name="streaming_function",
- input={},
- ),
- )
-
- i = 0
- async for tool_response in res:
- print(f"块 {i}:")
- print(tool_response)
- print("中断标志:", tool_response.is_interrupted, "\n")
- i += 1
-
-
-asyncio.run(example_streaming_tool_interruption())
-
-# %%
-# 自动工具管理
-# -------------------------------------
-# .. image:: https://img.alicdn.com/imgextra/i3/O1CN013cvRpO27MfesMsTeh_!!6000000007783-2-tps-840-521.png
-# :width: 100%
-# :align: center
-# :alt: 自动工具管理
-#
-#
-# ``Toolkit`` 类通过引入 **工具组** (Group) 的概念,以及名为 ``reset_equipped_tools`` 的 **元工具函数** (Meta Tool) 来支持 **自动工具管理** 。
-#
-# 工具组是一组相关工具函数的集合,例如浏览器使用工具、地图服务工具等,它们将被一起管理。工具组有激活和非激活两种状态,
-# 只有工具组被激活,其中的工具函数才对智能体可见,即可以通过 ``toolkit.get_json_schemas()`` 方法访问。
-#
-# 注意有一个名为 ``basic`` 的特殊组,它始终处于激活状态,注册工具时如果未指定组名,则工具函数将默认添加到此组。
-#
-# .. tip:: ``basic`` 组确保开发者不需要“组管理”的功能时,工具的基本使用不会受到影响。
-#
-# 现在我们尝试创建一个名为 ``browser_use`` 的工具组,其中包含一些网页浏览工具。
-#
-
-
-# 我们创建一些浏览器操作相关的工具
-def navigate(url: str) -> ToolResponse:
- """导航到网页。
-
- Args:
- url (str):
- 要导航到的网页的 URL。
- """
- pass
-
-
-def click_element(element_id: str) -> ToolResponse:
- """点击网页上的元素。
-
- Args:
- element_id (str):
- 要点击的元素的 ID。
- """
- pass
-
-
-toolkit = Toolkit()
-
-# 创建一个名为 browser_use 的工具组
-toolkit.create_tool_group(
- group_name="browser_use",
- description="用于网页浏览的工具函数。",
- active=False,
- # 使用这些工具时的注意事项
- notes="""1. 使用 ``navigate`` 打开网页。
-2. 当需要用户身份验证时,请向用户询问凭据
-3. ...""",
-)
-
-toolkit.register_tool_function(navigate, group_name="browser_use")
-toolkit.register_tool_function(click_element, group_name="browser_use")
-
-# 我们也可以注册一些基本工具
-toolkit.register_tool_function(execute_python_code)
-
-# %%
-# 此时 ``browser_use`` 未被激活,如果我们检查工具 JSON schema,只能看到 ``execute_python_code`` 工具:
-
-print("此时对智能体可见的工具函数 JSON Schemas:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# 使用 ``update_tool_groups`` 方法激活或停用工具组:
-
-toolkit.update_tool_groups(group_names=["browser_use"], active=True)
-
-print("激活后对智能体可见的工具函数 JSON Schemas:")
-print(json.dumps(toolkit.get_json_schemas(), indent=4, ensure_ascii=False))
-
-# %%
-# 此外,``Toolkit`` 提供了一个名为 ``reset_equipped_tools`` 的元工具函数,它会将所有组名(除了 "basic")作为一个 bool 型的参数,
-# 让智能体调用该工具来决定要激活哪些工具组:
-#
-# .. note:: 在 ``ReActAgent`` 类的实现中,只需要在构造函数中将 ``enable_meta_tool`` 设置为 ``True`` 即可启用元工具函数。
-#
-
-# 注册元工具函数
-toolkit.register_tool_function(toolkit.reset_equipped_tools)
-
-reset_equipped = next(
- tool
- for tool in toolkit.get_json_schemas()
- if tool["function"]["name"] == "reset_equipped_tools"
-)
-print("``reset_equipped_tools`` 函数的 JSON schema:")
-print(
- json.dumps(
- reset_equipped,
- indent=4,
- ensure_ascii=False,
- ),
-)
-
-# %%
-# 当智能体调用 ``reset_equipped_tools`` 时,对应工具组将被激活,同时返回的结果中将包含工具的使用注意事项。
-#
-
-
-async def mock_agent_reset_tools() -> None:
- """模拟智能体调用 reset_equipped_tools 函数。"""
- res = await toolkit.call_tool(
- ToolUseBlock(
- type="tool_use",
- id="456",
- name="reset_equipped_tools",
- input={
- "browser_use": True, # 激活浏览器使用工具组
- },
- ),
- )
-
- async for tool_response in res:
- print("工具响应中的文字返回:")
- print(tool_response.content[0]["text"])
-
-
-asyncio.run(mock_agent_reset_tools())
-
-# %%
-# 此外,``Toolkit`` 还通过 ``get_activated_notes`` 函数提供已经被激活了的工具组的 notes,开发者也可以将其组装到智能体的系统提示中,从而达到动态管理工具的作用。
-#
-# .. tip:: 自动工具管理功能已在 ``ReActAgent`` 类中实现,有关更多详细信息,请参考 :ref:`agent` 部分。
-#
-
-# 再创建一个工具组
-toolkit.create_tool_group(
- group_name="map_service",
- description="谷歌地图服务工具。",
- active=True,
- notes="""1. 使用 ``get_location`` 获取地点的位置。
-2. ...""",
-)
-
-print("激活工具组的汇总注意事项:")
-print(toolkit.get_activated_notes())
-
-# %%
-# 进一步阅读
-# ---------------------
-# - :ref:`agent`
-# - :ref:`state`
-# - :ref:`mcp`
-#
diff --git a/docs/tutorial/zh_CN/src/task_tracing.py b/docs/tutorial/zh_CN/src/task_tracing.py
deleted file mode 100644
index 587d136c1..000000000
--- a/docs/tutorial/zh_CN/src/task_tracing.py
+++ /dev/null
@@ -1,213 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tracing:
-
-追踪
-==============================
-
-AgentScope 实现了基于 OpenTelemetry 的追踪来监控和调试
-智能体应用程序的执行,具有以下特性
-
-- 为 LLM、工具、智能体、格式化器等提供内置追踪
-- 支持错误和异常追踪
-- 在 AgentScope Studio 中提供原生追踪 **可视化**
-- 支持连接到 **第三方平台**,如阿里云云监控、`Arize-Phoenix <https://github.com/Arize-ai/phoenix>`_、`Langfuse <https://langfuse.com/>`_ 等
-
-设置
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. note:: 连接到 :ref:`studio` 或第三方平台应该在应用程序开始时通过调用 ``agentscope.init`` 函数完成。
-
-AgentScope Studio
----------------------------------------
-
-.. figure:: ../../_static/images/studio_tracing.webp
- :width: 100%
- :alt: AgentScope Studio 追踪页面
- :class: bordered-image
- :align: center
-
- *AgentScope Studio 中的追踪页面*
-
-
-当连接到 AgentScope Studio 时,只需在 ``agentscope.init`` 函数中提供 ``studio_url`` 参数。
-
-.. code-block:: python
-
- import agentscope
-
- agentscope.init(studio_url="http://xxx:port")
-
-
-第三方平台
----------------------------------------
-
-要连接到第三方追踪平台,请在 ``agentscope.init`` 函数中设置 ``tracing_url`` 参数。
-``tracing_url`` 是您的 OpenTelemetry 收集器或任何支持 OTLP(OpenTelemetry 协议)的服务器 URL。
-
-.. code-block:: python
-
- import agentscope
-
- # 连接到 OpenTelemetry 兼容的后端
- agentscope.init(tracing_url="https://your-tracing-backend:port/traces")
-
-以阿里云云监控、Arize-Phoenix 和 Langfuse 为例:
-
-**阿里云云监控(Alibaba Cloud CloudMonitor)**:全托管可观测平台。
-
-.. code-block:: python
- :caption: 连接到阿里云云监控
-
- agentscope.init(tracing_url="https://tracing-cn-hangzhou.arms.aliyuncs.com/adapt_xxx/api/otlp/traces")
-
-.. tip::
- **获取 Endpoint:** 在 `ARMS 控制台 <https://arms.console.aliyun.com/>`_ 的 **接入中心** > **OpenTelemetry** 中,
- 根据实际部署地域选择对应的 **公网接入点**。可通过环境变量 ``OTEL_SERVICE_NAME`` 自定义应用名称。
- 阿里云云监控可通过 `LoongSuite <https://github.com/alibaba/loongsuite-python-agent>`_ 探针提供零侵入的自动化接入。
- 更多信息请参考 `云监控文档 <https://help.aliyun.com/zh/cms/cloudmonitor-2-0/user-guide/model-application>`_。
-
-**Arize-Phoenix**:需要在环境变量中设置 ``PHOENIX_API_KEY``。
-
-.. code-block:: python
- :caption: 连接到 Arize Phoenix
-
- # Arize Phoenix 集成
- import os
-
- PHOENIX_API_KEY = os.environ.get("PHOENIX_API_KEY")
- os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"api_key={PHOENIX_API_KEY}"
-
- agentscope.init(tracing_url="https://app.phoenix.arize.com/v1/traces")
-
-**LangFuse**:需要在环境变量中设置 ``LANGFUSE_PUBLIC_KEY`` 和 ``LANGFUSE_SECRET_KEY``。
-授权头是使用这些密钥构建的。
-
-.. code-block:: python
- :caption: 连接到 LangFuse
-
- import os, base64
-
- LANGFUSE_PUBLIC_KEY = os.environ["LANGFUSE_PUBLIC_KEY"]
- LANGFUSE_SECRET_KEY = os.environ["LANGFUSE_SECRET_KEY"]
- LANGFUSE_AUTH_STRING = f"{LANGFUSE_PUBLIC_KEY}:{LANGFUSE_SECRET_KEY}"
-
- LANGFUSE_AUTH = base64.b64encode(LANGFUSE_AUTH_STRING.encode("utf-8")).decode("ascii")
- os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
-
- # 欧盟数据区域
- agentscope.init(tracing_url="https://cloud.langfuse.com/api/public/otel/v1/traces")
- # 美国数据区域
- # agentscope.init(tracing_url="https://us.cloud.langfuse.com/api/public/otel/v1/traces")
-
-
-自定义追踪
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-如前所述,AgentScope 中的追踪功能是基于 OpenTelemetry 实现的。
-这意味着 AgentScope 中的追踪与开发者基于 OpenTelemetry SDK 自己实现的的追踪代码**完全兼容**。
-
-此外,AgentScope 内置了以下装饰器来追踪相应的模块,它们对不同类的特殊属性,以及返回值做了相应的特殊处理:
-
-- ``@trace_llm``:追踪 ``ChatModelBase`` 子类的 ``__call__`` 函数
-- ``@trace_reply``:追踪 ``AgentBase`` 子类的 ``reply`` 函数
-- ``@trace_format``:追踪 ``FormatterBase`` 子类的 ``format`` 函数
-- ``@trace``:追踪一般函数
-
-
-追踪大语言模型
-----------------------------------------
-
-``@trace_llm`` 装饰器用于追踪 ``ChatModelBase`` 类的 ``__call__`` 函数。
-
-.. code-block:: python
- :caption: 追踪新的 ChatModel 类
-
- class ExampleChatModel(ChatModelBase):
- \"\"\"示例模型\"\"\"
-
- ...
-
- @trace_llm
- async def __call__(
- self,
- *args: Any,
- **kwargs: Any,
- ) -> AsyncGenerator[ChatResponse, None] | ChatResponse:
- \"\"\"LLM 调用\"\"\"
- ...
-
-
-追踪智能体
-----------------------------------------
-
-``@trace_reply`` 装饰器用于追踪智能体的 `reply` 函数。
-
-.. code-block:: python
- :caption: 追踪新的 Agent 类
-
- class ExampleAgent(AgentBase):
- \"\"\"示例智能体类\"\"\"
-
- @trace_reply
- async def reply(self, *args: Any, **kwargs: Any) -> Msg:
- \"\"\"回复消息。\"\"\"
- ...
-
-
-追踪格式化器
-----------------------------------------
-``@trace_format`` 装饰器用于格式化器实现并追踪 `format` 函数。
-
-.. code-block:: python
- :caption: 追踪新的 Formatter 类
-
- class ExampleFormatter(FormatterBase):
- \"\"\"简单的示例格式化器类\"\"\"
-
- @trace_format
- async def format(self, *args: Any, **kwargs: Any) -> list[dict]:
- \"\"\"示例格式化\"\"\"
-
-
-一般函数追踪
-----------------------------------------
-
-``@trace`` 装饰器与上述装饰器不同,它是一个通用的追踪装饰器,可以应用于任何函数。
-它需要一个 `name` 参数来标识被追踪的函数,并且可以追踪各种类型的函数,包括:
-
-- 同步函数
-- 同步生成器函数
-- 异步函数
-- 异步生成器函数
-
-.. code-block:: python
- :caption: 一般追踪示例
-
- # 1. 同步函数
- @trace(name='simple_function')
- def simple_function(name: str, age: int) -> str:
- \"\"\"带有自动追踪的简单函数。\"\"\"
- return f"你好, {name}! 你的年龄是 {age} 岁。"
-
- # 2. 同步生成器函数
- @trace(name='number_generator')
- def number_generator(n: int) -> Generator[int, None, None]:
- \"\"\"生成从 0 到 n-1 的数字。\"\"\"
- for i in range(n):
- yield i
-
- # 3. 异步函数
- @trace(name='async_function')
- async def async_function(data: dict) -> dict:
- \"\"\"异步处理数据。\"\"\"
- return {"processed": data}
-
- # 4. 异步生成器函数
- @trace(name='async_stream')
- async def async_stream(n: int) -> AsyncGenerator[str, None]:
- \"\"\"异步生成数据流。\"\"\"
- for i in range(n):
- yield f"data_{i}"
-
-"""
diff --git a/docs/tutorial/zh_CN/src/task_tts.py b/docs/tutorial/zh_CN/src/task_tts.py
deleted file mode 100644
index 313a60ced..000000000
--- a/docs/tutorial/zh_CN/src/task_tts.py
+++ /dev/null
@@ -1,242 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tts:
-
-TTS
-====================
-
-AgentScope 为多个 API 提供商的文本转语音(TTS)模型提供了统一接口。
-本章节演示如何在 AgentScope 中使用 TTS 模型。
-
-AgentScope 支持以下 TTS API:
-
-.. list-table:: 内置 TTS 模型
- :header-rows: 1
-
- * - API
- - 类
- - 流式输入
- - 非流式输入
- - 流式输出
- - 非流式输出
- * - DashScope 实时 API
- - ``DashScopeRealtimeTTSModel``
- - ✅
- - ✅
- - ✅
- - ✅
- * - DashScope CosyVoice 实时 API
- - ``DashScopeCosyVoiceRealtimeTTSModel``
- - ✅
- - ✅
- - ✅
- - ✅
- * - DashScope API
- - ``DashScopeTTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
- * - DashScope CosyVoice API
- - ``DashScopeCosyVoiceTTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
- * - OpenAI API
- - ``OpenAITTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
- * - Gemini API
- - ``GeminiTTSModel``
- - ❌
- - ✅
- - ✅
- - ✅
-
-.. note:: AgentScope TTS 模型中的流式输入和输出都是累积式的。
-
-**选择合适的模型:**
-
-- **使用非实时 TTS**:当已有完整文本时(例如预先编写的响应、完整的 LLM 输出)
-- **使用实时 TTS**:当文本是逐步生成时(例如 LLM 的流式返回),以获得更低的延迟
-
-"""
-
-import asyncio
-import os
-
-from agentscope.agent import ReActAgent, UserAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tts import (
- DashScopeRealtimeTTSModel,
- DashScopeTTSModel,
-)
-
-# %%
-# 非实时 TTS
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 非实时 TTS 模型处理完整的文本输入,使用起来最简单,可以直接调用它们的 ``synthesize()`` 方法。
-#
-# 以 DashScope TTS 模型为例:
-
-
-async def example_non_realtime_tts() -> None:
- """使用非实时 TTS 模型的基本示例。"""
- # DashScope TTS 示例
- tts_model = DashScopeTTSModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
- model_name="qwen3-tts-flash",
- voice="Cherry",
- stream=False, # 非流式输出
- )
-
- msg = Msg(
- name="assistant",
- content="你好,这是 DashScope TTS。",
- role="assistant",
- )
-
- tts_response = await tts_model.synthesize(msg)
-
- # tts_response.content 包含一个带有 base64 编码音频数据的音频块
- print("音频数据长度:", len(tts_response.content["source"]["data"]))
-
-
-asyncio.run(example_non_realtime_tts())
-
-# %%
-# **流式输出以降低延迟:**
-#
-# 当 ``stream=True`` 时,模型会逐步返回音频块,允许
-# 您在合成完成前开始播放。这减少了感知延迟。
-#
-
-
-async def example_non_realtime_tts_streaming() -> None:
- """使用带流式输出的非实时 TTS 模型的示例。"""
- # 使用流式输出的 DashScope TTS 示例
- tts_model = DashScopeTTSModel(
- api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
- model_name="qwen3-tts-flash",
- voice="Cherry",
- stream=True, # 启用流式输出
- )
-
- msg = Msg(
- name="assistant",
- content="你好,这是带流式输出的 DashScope TTS。",
- role="assistant",
- )
-
- # 合成并接收用于流式输出的异步生成器
- async for tts_response in await tts_model.synthesize(msg):
- # 处理到达的每个音频块
- print("接收到的音频块长度:", len(tts_response.content["source"]["data"]))
-
-
-asyncio.run(example_non_realtime_tts_streaming())
-
-
-# %%
-# 实时 TTS
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 实时 TTS 模型专为文本增量生成的场景设计,
-# 例如流式 LLM 响应。这通过在完整文本准备好之前
-# 开始音频合成,实现尽可能低的延迟。
-#
-# **核心概念:**
-#
-# - **有状态处理**:实时 TTS 为单个流式会话维护状态,
-# 由 ``msg.id`` 标识。一次只能有一个流式会话处于活动状态。
-# - **两种方法**:
-#
-# - ``push(msg)``:非阻塞方法,提交文本块并立即返回。
-# 如果有可用的部分音频,可能会返回。
-# - ``synthesize(msg)``:阻塞方法,完成会话并返回
-# 所有剩余的音频。当 ``stream=True`` 时,返回异步生成器。
-#
-# .. code-block:: python
-#
-# async def example_realtime_tts_streaming():
-# tts_model = DashScopeRealtimeTTSModel(
-# api_key=os.environ.get("DASHSCOPE_API_KEY", ""),
-# model_name="qwen3-tts-flash-realtime",
-# voice="Cherry",
-# stream=False,
-# )
-#
-# # 实时 tts 模型接收累积的文本块
-# res = await tts_model.push(msg_chunk_1) # 非阻塞
-# res = await tts_model.push(msg_chunk_2) # 非阻塞
-# ...
-# res = await tts_model.synthesize(final_msg) # 阻塞,获取所有剩余音频
-#
-# 在初始化时设置 ``stream=True`` 时,``synthesize()`` 方法返回 ``TTSResponse`` 对象的异步生成器,允许您在音频块到达时处理它们。
-#
-#
-# 与 ReActAgent 集成
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# AgentScope 智能体在提供 TTS 模型时,可以自动将其响应合成为语音。
-# 这与实时和非实时 TTS 模型都能无缝协作。
-#
-# **工作原理:**
-#
-# 1. 智能体生成文本响应(可能从 LLM 流式传输)
-# 2. TTS 模型自动将文本合成为音频
-# 3. 合成的音频附加到 ``Msg`` 对象的 ``speech`` 字段
-# 4. 音频在智能体的 ``self.print()`` 方法期间播放
-#
-
-
-async def example_agent_with_tts() -> None:
- """使用带 TTS 的 ReActAgent 的示例。"""
- # 创建启用了 TTS 的智能体
- agent = ReActAgent(
- name="Assistant",
- sys_prompt="你是一个有用的助手。",
- model=DashScopeChatModel(
- api_key=os.environ["DASHSCOPE_API_KEY"],
- model_name="qwen-max",
- stream=True,
- ),
- formatter=DashScopeChatFormatter(),
- # 启用 TTS
- tts_model=DashScopeRealtimeTTSModel(
- api_key=os.getenv("DASHSCOPE_API_KEY"),
- model_name="qwen3-tts-flash-realtime",
- voice="Cherry",
- ),
- )
- user = UserAgent("User")
-
- # 像正常情况一样构建对话
- msg = None
- while True:
- msg = await agent(msg)
- msg = await user(msg)
- if msg.get_text_content() == "exit":
- break
-
-
-# %%
-# 自定义 TTS 模型
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 可以通过继承 ``TTSModelBase`` 来创建自定义 TTS 实现。
-# 基类为实时和非实时 TTS 模型提供了灵活的接口。
-# 我们使用属性 ``supports_streaming_input`` 来指示 TTS 模型是否为实时模型。
-#
-# 对于实时 TTS 模型,需要实现 ``connect``、``close``、``push`` 和 ``synthesize`` 方法来处理 API 的生命周期和流式输入。
-#
-# 而对于非实时 TTS 模型,只需实现 ``synthesize`` 方法。
-#
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# - :ref:`agent` - 了解更多关于 AgentScope 中的智能体
-# - :ref:`message` - 理解 AgentScope 中的消息格式
-# - API 参考::class:`agentscope.tts.TTSModelBase`
-#
diff --git a/docs/tutorial/zh_CN/src/task_tuner.py b/docs/tutorial/zh_CN/src/task_tuner.py
deleted file mode 100644
index 48a50eafc..000000000
--- a/docs/tutorial/zh_CN/src/task_tuner.py
+++ /dev/null
@@ -1,249 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _tuner:
-
-Tuner
-=================
-
-AgentScope 提供了 ``tuner`` 模块,用于通过强化学习(RL)训练智能体应用。
-本教程将带你系统了解如何利用 ``tuner`` 提升智能体在特定任务上的表现,包括:
-
-- 介绍 ``tuner`` 的核心组件
-- 演示调优流程所需的关键代码实现
-- 展示调优流程的配置与运行方法
-
-主要组件
-~~~~~~~~~~~~~~~~~~~
-``tuner`` 模块为智能体训练工作流引入了三大核心组件:
-
-- **任务数据集**:用于训练和评估智能体的任务集合。
-- **工作流函数**:封装被调优智能体应用的决策逻辑。
-- **评判函数**:评估智能体在特定任务上的表现,并为调优过程提供奖励信号。
-
-此外,``tuner`` 还提供了若干用于自定义调优流程的配置类,包括:
-
-- **TunerModelConfig**:用于指定被调优模型的相关配置。
-- **AlgorithmConfig**:用于指定强化学习算法(如 GRPO、PPO 等)及其参数。
-
-实现流程
-~~~~~~~~~~~~~~~~~~~
-本节以一个简单的数学智能体为例,演示如何用 ``tuner`` 进行训练。
-
-任务数据集
---------------------
-任务数据集包含用于训练和评估的任务集合。
-
-``tuner`` 的任务数据集采用 Huggingface `datasets <https://huggingface.co/docs/datasets/quickstart>`_ 格式,并通过 ``datasets.load_dataset`` 加载。例如:
-
-.. code-block:: text
-
- my_dataset/
- ├── train.jsonl # 训练样本
- └── test.jsonl # 测试样本
-
-假设 `train.jsonl` 内容如下:
-
-.. code-block:: json
-
- {"question": "2 + 2 等于多少?", "answer": "4"}
- {"question": "4 + 4 等于多少?", "answer": "8"}
-
-在开始调优前,你可以用如下方法来确定你的数据集能够被正确加载:
-
-.. code-block:: python
-
- from agentscope.tuner import DatasetConfig
-
- dataset = DatasetConfig(path="my_dataset", split="train")
- dataset.preview(n=2)
- # 输出前两个样本以验证数据集加载正确
- # [
- # {
- # "question": "2 + 2 等于多少?",
- # "answer": "4"
- # },
- # {
- # "question": "4 + 4 等于多少?",
- # "answer": "8"
- # }
- # ]
-
-工作流函数
---------------------
-工作流函数定义了智能体与环境的交互方式和决策过程。所有工作流函数需遵循 ``agentscope.tuner.WorkflowType`` 的输入/输出签名。
-
-以下是一个用 ReAct 智能体回答数学问题的简单工作流函数示例:
-"""
-
-from typing import Dict, Optional
-from agentscope.agent import ReActAgent
-from agentscope.formatter import OpenAIChatFormatter
-from agentscope.message import Msg
-from agentscope.model import ChatModelBase
-from agentscope.tuner import WorkflowOutput
-
-
-async def example_workflow_function(
- task: Dict,
- model: ChatModelBase,
- auxiliary_models: Optional[Dict[str, ChatModelBase]] = None,
-) -> WorkflowOutput:
- """一个用于调优的工作流函数示例。
-
- Args:
- task (`Dict`): 任务信息。
- model (`ChatModelBase`): 智能体使用的对话模型。
- auxiliary_models (`Optional[Dict[str, ChatModelBase]]`):
- 用于辅助的额外对话模型,一般用于多智能体场景下模拟其他非训练智能体的行为。
-
- Returns:
- `WorkflowOutput`: 工作流生成的输出。
- """
- agent = ReActAgent(
- name="react_agent",
- sys_prompt="你是一个善于解决数学问题的智能体。",
- model=model,
- formatter=OpenAIChatFormatter(),
- )
-
- response = await agent.reply(
- msg=Msg(
- "user",
- task["question"],
- role="user",
- ), # 从任务中提取问题
- )
-
- return WorkflowOutput( # 返回响应结果
- response=response,
- )
-
-
-# %%
-# 你可以直接用任务字典和日常调试使用的 ``DashScopeChatModel`` / ``OpenAIChatModel`` 运行此工作流函数,从而在正式训练前测试其流程的正确性。例如:
-
-import asyncio
-import os
-from agentscope.model import DashScopeChatModel
-
-task = {"question": "123 加 456 等于多少?", "answer": "579"}
-model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
-)
-workflow_output = asyncio.run(example_workflow_function(task, model))
-assert isinstance(
- workflow_output.response,
- Msg,
-), "在此示例中,响应应为 Msg 实例。"
-print("\n工作流响应:", workflow_output.response.get_text_content())
-
-# %%
-#
-# 评判函数
-# --------------------
-# 评判函数用于评估智能体在特定任务上的表现,并为调优过程提供奖励信号。
-# 所有评判函数需遵循 ``agentscope.tuner.JudgeType`` 的输入/输出签名。
-# 下面是一个简单的评判函数示例,通过比较智能体响应与标准答案给出奖励:
-
-from typing import Any
-from agentscope.tuner import JudgeOutput
-
-
-async def example_judge_function(
- task: Dict,
- response: Any,
- auxiliary_models: Optional[Dict[str, ChatModelBase]] = None,
-) -> JudgeOutput:
- """仅用于演示的简单评判函数。
-
- Args:
- task (`Dict`): 任务信息。
- response (`Any`): WorkflowOutput 的响应字段。
- auxiliary_models (`Optional[Dict[str, ChatModelBase]]`):
- 用于 LLM-as-a-Judge 的辅助模型。
- Returns:
- `JudgeOutput`: 评判函数分配的奖励。
- """
- ground_truth = task["answer"]
- reward = 1.0 if ground_truth in response.get_text_content() else 0.0
- return JudgeOutput(reward=reward)
-
-
-# 本地测试函数的正确性:
-judge_output = asyncio.run(
- example_judge_function(
- task,
- workflow_output.response,
- ),
-)
-print(f"评判奖励: {judge_output.reward}")
-
-# %%
-# 评判函数同样可以按照上述案例中展示的方式在正式训练前进行本地测试,以确保其逻辑正确。
-#
-# .. tip::
-# 你可以在评判函数中利用已有的 `MetricBase <https://github.com/agentscope-ai/agentscope/blob/main/src/agentscope/evaluate/_metric_base.py>`_ 实现,计算更复杂的指标,并将其组合为复合奖励。
-#
-# 配置并运行
-# ~~~~~~~~~~~~~~~
-# 最后,你可以用 ``tuner`` 模块配置并运行调优流程。
-# 在开始调优前,请确保环境已安装 `Trinity-RFT <https://github.com/agentscope-ai/Trinity-RFT>`_,这是 ``tuner`` 的依赖。
-#
-# 下面是调优流程的配置与启动示例:
-#
-# .. note::
-# 此示例仅供演示。完整可运行示例请参考 `Tune ReActAgent <https://github.com/agentscope-ai/agentscope/tree/main/examples/tuner/model_tuning>`_
-#
-# .. code-block:: python
-#
-# from agentscope.tuner import tune, AlgorithmConfig, DatasetConfig, TunerModelConfig
-# # 你的工作流 / 评判函数 ...
-#
-# if __name__ == "__main__":
-# dataset = DatasetConfig(path="my_dataset", split="train")
-# model = TunerModelConfig(model_path="Qwen/Qwen3-0.6B", max_model_len=16384)
-# algorithm = AlgorithmConfig(
-# algorithm_type="multi_step_grpo",
-# group_size=8,
-# batch_size=32,
-# learning_rate=1e-6,
-# )
-# tune(
-# workflow_func=example_workflow_function,
-# judge_func=example_judge_function,
-# model=model,
-# train_dataset=dataset,
-# algorithm=algorithm,
-# )
-#
-# 这里用 ``DatasetConfig`` 配置训练数据集,用 ``TunerModelConfig`` 配置可训练模型相关参数,用 ``AlgorithmConfig`` 指定强化学习算法及其超参数。
-#
-# .. tip::
-# ``tune`` 函数基于 `Trinity-RFT <https://github.com/agentscope-ai/Trinity-RFT>`_ 实现,内部会将输入参数转换为 YAML 配置。
-# 高级用户可忽略 ``model``、``train_dataset``、``algorithm`` 参数,直接通过 ``config_path`` 指定 YAML 配置文件。
-# 推荐使用配置文件方式以便更细粒度地控制训练过程,充分利用 Trinity-RFT 的高级功能。
-# 你可参考 Trinity-RFT 的 `配置指南 <https://agentscope-ai.github.io/Trinity-RFT/en/main/tutorial/trinity_configs.html>`_ 了解更多配置选项。
-#
-# 你可以将上述代码保存为 ``main.py``,并用如下命令运行:
-#
-# .. code-block:: bash
-#
-# ray start --head
-# python main.py
-#
-# 检查点和日志会自动保存到当前工作目录下的 ``checkpoints/AgentScope`` 目录,每次运行会以时间戳为后缀保存到子目录。
-# tensorboard 日志可在检查点目录下的 ``monitor/tensorboard`` 中找到。
-#
-# .. code-block:: text
-#
-# your_workspace/
-# └── checkpoints/
-# └──AgentScope/
-# └── Experiment-20260104185355/ # 每次运行以时间戳保存
-# ├── monitor/
-# │ └── tensorboard/ # tensorboard 日志
-# └── global_step_x/ # 第 x 步保存的模型检查点
-#
-# .. tip::
-# 更多调优样例请参考 AgentScope-Samples 库中的 `tuner 目录 <https://github.com/agentscope-ai/agentscope-samples/tree/main/tuner>`_
diff --git a/docs/tutorial/zh_CN/src/workflow_concurrent_agents.py b/docs/tutorial/zh_CN/src/workflow_concurrent_agents.py
deleted file mode 100644
index c6d69e7dd..000000000
--- a/docs/tutorial/zh_CN/src/workflow_concurrent_agents.py
+++ /dev/null
@@ -1,42 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-
-Concurrent Agents
-===================================
-在异步编程的帮助下,多智能体并发可以通过 Python 中的 ``asyncio.gather`` 执行。
-
-下面展示了一个简单的示例,其中创建了两个智能体并并发执行。
-"""
-import asyncio
-from datetime import datetime
-from typing import Any
-
-from agentscope.agent import AgentBase
-
-
-class ExampleAgent(AgentBase):
- """用于并发执行的示例智能体。"""
-
- def __init__(self, name: str) -> None:
- """使用智能体名称初始化智能体。"""
- super().__init__()
- self.name = name
-
- async def reply(self, *args: Any, **kwargs: Any) -> None:
- """回复消息。"""
- start_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
- print(f"{self.name} 开始于 {start_time}")
- await asyncio.sleep(3) # 模拟长时间运行的任务
- end_time = datetime.now().strftime("%H:%M:%S.%f")[:-3]
- print(f"{self.name} 结束于 {end_time}")
-
-
-async def run_concurrent_agents() -> None:
- """运行并发智能体。"""
- agent1 = ExampleAgent("智能体 1")
- agent2 = ExampleAgent("智能体 2")
-
- await asyncio.gather(agent1(), agent2())
-
-
-asyncio.run(run_concurrent_agents())
diff --git a/docs/tutorial/zh_CN/src/workflow_conversation.py b/docs/tutorial/zh_CN/src/workflow_conversation.py
deleted file mode 100644
index a96e2f54a..000000000
--- a/docs/tutorial/zh_CN/src/workflow_conversation.py
+++ /dev/null
@@ -1,202 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _conversation:
-
-Conversation
-======================
-
-Conversation 是一种智能体间交换和共享信息的设计模式,常见于游戏、聊天机器人和多智能体讨论场景。
-
-在 AgentScope 中,conversation 的构建在 **显式的消息传递** 基础上。在本章中,我们将演示如何构建:
-
-- User-assistant 之间的对话(聊天机器人)
-- 多实体对话(游戏、讨论等)
-
-它们的主要区别在于
-
-- **提示的构建方式**,以及
-- 信息在智能体之间的 **传播/共享** 方式。
-"""
-import asyncio
-import json
-import os
-
-from agentscope.agent import ReActAgent, UserAgent
-from agentscope.memory import InMemoryMemory
-from agentscope.formatter import (
- DashScopeChatFormatter,
- DashScopeMultiAgentFormatter,
-)
-from agentscope.model import DashScopeChatModel
-from agentscope.message import Msg
-from agentscope.pipeline import MsgHub
-from agentscope.tool import Toolkit
-
-# %%
-# User-Assistant 对话
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# User-assistant 对话,也称为聊天机器人(chatbot),是最常见的智能体应用,也是当前大多数 LLM API 的设计模式。
-# 在这种对话只有两个参与者:用户(user)和智能体(assistant)。
-#
-# 在 AgentScope 中,名称中带有 **"Chat"** 的格式化器专为 user-assistant 对话设计,
-# 如 ``DashScopeChatFormatter``、``AnthropicChatFormatter`` 等。
-# 它们使用消息中的 ``role`` 字段来区分用户和智能体,并相应地格式化消息。
-#
-# 这里我们构建智能体 ``Friday`` 和用户之间的简单对话。
-#
-# .. tip:: AgentScope 提供了内置的 ``UserAgent`` 类,用于人机交互(HITL)。更多详细信息请参考 :ref:`user-agent`。
-#
-
-friday = ReActAgent(
- name="Friday",
- sys_prompt="你是一个名为 Friday 的有用助手",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- ),
- formatter=DashScopeChatFormatter(), # 用于 user-assistant 对话的格式化器
- memory=InMemoryMemory(),
- toolkit=Toolkit(),
-)
-
-# 创建用户智能体
-user = UserAgent(name="User")
-
-# %%
-# 现在,我们可以通过在这两个智能体之间交换消息来开始对话,直到用户输入"exit"结束对话。
-#
-# .. code-block:: python
-#
-# async def run_conversation() -> None:
-# """运行 Friday 和用户之间的简单对话。"""
-# msg = None
-# while True:
-# msg = await friday(msg)
-# msg = await user(msg)
-# if msg.get_text_content() == "exit":
-# break
-#
-# asyncio.run(run_conversation())
-#
-
-# %%
-# 多实体对话
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-# 如开头所述,我们演示如何在 **提示构建** 和 **信息共享** 方面构建多智能体对话。
-#
-# 构建提示
-# -------------------------------
-# 在 AgentScope 中,我们为多智能体对话提供了内置格式化器,其名称中带有 **"MultiAgent"**,
-# 如 ``DashScopeMultiAgentFormatter``、``AnthropicMultiAgentFormatter`` 等。
-#
-# 具体而言,它们使用消息中的 ``name`` 字段来区分不同的实体,并将对话历史格式化为单个用户消息。
-# 以 ``DashScopeMultiAgentFormatter`` 为例:
-#
-# .. tip:: 有关格式化器的更多详细信息可以在 :ref:`prompt` 中找到。
-#
-
-
-async def example_multi_agent_prompt() -> None:
- msgs = [
- Msg("system", "你是一个名为 Bob 的有用助手。", "system"),
- Msg("Alice", "嗨!", "user"),
- Msg("Bob", "嗨!很高兴见到大家。", "assistant"),
- Msg("Charlie", "我也是!顺便说一下,我是 Charlie。", "assistant"),
- ]
-
- formatter = DashScopeMultiAgentFormatter()
- prompt = await formatter.format(msgs)
-
- print("格式化的提示:")
- print(json.dumps(prompt, indent=4, ensure_ascii=False))
-
- # 我们在这里打印组合用户消息的内容以便更好地理解:
- print("-------------")
- print("组合消息")
- print(prompt[1]["content"])
-
-
-asyncio.run(example_multi_agent_prompt())
-
-
-# %%
-# 消息共享
-# -------------------------------
-# 在多智能体对话中,显式交换消息可能不够高效和便利,
-# 特别是在多个智能体之间广播消息时。
-#
-# 因此,AgentScope 提供了一个名为 ``MsgHub`` 的异步上下文管理器来简化消息广播。
-# 具体而言,同一个 ``MsgHub`` 中的智能体将自动接收其它参与者通过 ``reply`` 函数返回的消息。
-#
-# 下面我们构建一个多人聊天的场景,多个智能体扮演不同的角色:
-#
-
-model = DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
-)
-formatter = DashScopeMultiAgentFormatter()
-
-alice = ReActAgent(
- name="Alice",
- sys_prompt="你是一个名为 Alice 的学生。",
- model=model,
- formatter=formatter,
-)
-
-bob = ReActAgent(
- name="Bob",
- sys_prompt="你是一个名为 Bob 的学生。",
- model=model,
- formatter=formatter,
-)
-
-charlie = ReActAgent(
- name="Charlie",
- sys_prompt="你是一个名为 Charlie 的学生。",
- model=model,
- formatter=formatter,
-)
-
-
-async def example_msghub() -> None:
- """使用 MsgHub 进行多智能体对话的示例。"""
- async with MsgHub(
- [alice, bob, charlie],
- # 进入 MsgHub 时的公告消息
- announcement=Msg(
- "system",
- "现在大家互相认识一下,简单自我介绍。",
- "system",
- ),
- ):
- await alice()
- await bob()
- await charlie()
-
-
-asyncio.run(example_msghub())
-
-# %%
-# 现在我们打印 Alice 的记忆,检查她的记忆是否正确更新。
-#
-
-
-async def example_memory() -> None:
- """打印 Alice 的记忆。"""
- print("Alice 的记忆:")
- for msg in await alice.memory.get_memory():
- print(
- f"{msg.name}: {json.dumps(msg.content, indent=4, ensure_ascii=False)}",
- )
-
-
-asyncio.run(example_memory())
-
-# %%
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# - :ref:`prompt`
-# - :ref:`pipeline`
-#
diff --git a/docs/tutorial/zh_CN/src/workflow_handoffs.py b/docs/tutorial/zh_CN/src/workflow_handoffs.py
deleted file mode 100644
index 799e94f18..000000000
--- a/docs/tutorial/zh_CN/src/workflow_handoffs.py
+++ /dev/null
@@ -1,94 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _handoffs:
-
-Handoffs
-========================================
-
-Handoffs 是由 OpenAI 提出的工作流模式,通过调用子智能体的方式来完成目标任务。
-在 AgentScope 中通过工具调用的方式实现 handoffs 非常简单。首先,我们创建一个函数来允许协调者动态创建子智能体。
-
-.. figure:: ../../_static/images/handoffs.png
- :width: 80%
- :align: center
- :alt: 协调者-子智能体工作流
-
- *Handoffs 示例*
-
-"""
-
-import asyncio
-import os
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import (
- ToolResponse,
- Toolkit,
- execute_python_code,
-)
-
-
-# 创建子智能体的工具函数
-async def create_worker(
- task_description: str,
-) -> ToolResponse:
- """创建一个子智能体来完成给定的任务。子智能体配备了 Python 执行工具。
-
- Args:
- task_description (``str``):
- 子智能体要完成的任务描述。
- """
- # 为子智能体智能体配备一些工具
- toolkit = Toolkit()
- toolkit.register_tool_function(execute_python_code)
-
- # 创建子智能体智能体
- worker = ReActAgent(
- name="Worker",
- sys_prompt="你是一个智能体。你的目标是完成给定的任务。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- )
- # 让子智能体完成任务
- res = await worker(Msg("user", task_description, "user"))
- return ToolResponse(
- content=res.get_content_blocks("text"),
- )
-
-
-async def run_handoffs() -> None:
- """交接工作流示例。"""
- # 初始化协调者智能体
- toolkit = Toolkit()
- toolkit.register_tool_function(create_worker)
-
- orchestrator = ReActAgent(
- name="Orchestrator",
- sys_prompt="你是一个协调者智能体。你的目标是通过将任务分解为更小的任务并创建子智能体来完成它们,从而完成给定的任务。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- )
-
- # 任务描述
- task_description = "在 Python 中执行 hello world"
-
- # 创建子智能体来完成任务
- await orchestrator(Msg("user", task_description, "user"))
-
-
-asyncio.run(run_handoffs())
diff --git a/docs/tutorial/zh_CN/src/workflow_multiagent_debate.py b/docs/tutorial/zh_CN/src/workflow_multiagent_debate.py
deleted file mode 100644
index 20358d651..000000000
--- a/docs/tutorial/zh_CN/src/workflow_multiagent_debate.py
+++ /dev/null
@@ -1,128 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _multiagent-debate:
-
-Multi-Agent Debate
-========================
-
-Multi-Agent debate 模拟不同智能体之间的多轮讨论场景,通常包括几个 solver 和一个 aggregator。
-典型情况下,solver 生成并交换他们的答案,而 aggregator 收集并总结答案。
-
-我们实现了 `EMNLP 2024`_ 中的示例,其中两个 solver 智能体将按固定顺序讨论一个话题,根据先前的辩论历史表达他们的论点。
-在每一轮中,主持人智能体将决定是否可以在当前轮获得最终的正确答案。
-"""
-import asyncio
-import os
-
-from pydantic import Field, BaseModel
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import (
- DashScopeMultiAgentFormatter,
-)
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.pipeline import MsgHub
-
-# 准备一个话题
-topic = "两个圆外切且没有相对滑动。圆A的半径是圆B半径的1/3。圆A绕圆B滚动一圈回到起点。圆A总共会旋转多少次?"
-
-
-# 创建两个辩论者智能体,Alice 和 Bob,他们将讨论这个话题。
-def create_solver_agent(name: str) -> ReActAgent:
- """获取一个解决者智能体。"""
- return ReActAgent(
- name=name,
- sys_prompt=f"你是一个名为 {name} 的辩论者。你好,欢迎来到"
- "辩论比赛。我们的目标是找到正确答案,因此你没有必要完全同意对方"
- f"的观点。辩论话题如下所述:{topic}",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeMultiAgentFormatter(),
- )
-
-
-alice, bob = [create_solver_agent(name) for name in ["Alice", "Bob"]]
-
-# 创建主持人智能体
-moderator = ReActAgent(
- name="Aggregator",
- sys_prompt=f"""你是一个主持人。将有两个辩论者参与辩论比赛。他们将就以下话题提出观点并进行讨论:
-``````
-{topic}
-``````
-在每轮讨论结束时,你将评估辩论是否结束,以及话题正确的答案。""",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- # 使用多智能体格式化器,因为主持人将接收来自多于用户和助手的消息
- formatter=DashScopeMultiAgentFormatter(),
-)
-
-
-# 主持人的结构化输出模型
-class JudgeModel(BaseModel):
- """主持人的结构化输出模型。"""
-
- finished: bool = Field(description="辩论是否结束。")
- correct_answer: str | None = Field(
- description="辩论话题的正确答案,仅当辩论结束时提供该字段。否则保留为 None。",
- default=None,
- )
-
-
-async def run_multiagent_debate() -> None:
- """运行多智能体辩论工作流。"""
- while True:
- # MsgHub 中参与者的回复消息将广播给所有参与者。
- async with MsgHub(participants=[alice, bob, moderator]):
- await alice(
- Msg(
- "user",
- "你是正方,请表达你的观点。",
- "user",
- ),
- )
- await bob(
- Msg(
- "user",
- "你是反方。你不同意正方的观点。请表达你的观点和理由。",
- "user",
- ),
- )
-
- # Alice 和 Bob 不需要知道主持人的消息,所以主持人在 MsgHub 外部调用。
- msg_judge = await moderator(
- Msg(
- "user",
- "现在你已经听到了他们的辩论,现在判断辩论是否结束,以及你能得到正确答案吗?",
- "user",
- ),
- structured_model=JudgeModel,
- )
-
- if msg_judge.metadata.get("finished"):
- print(
- "\n辩论结束,正确答案是:",
- msg_judge.metadata.get("correct_answer"),
- )
- break
-
-
-asyncio.run(run_multiagent_debate())
-
-
-# %%
-# 进一步阅读
-# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-#
-# - :ref:`pipeline`
-#
-# .. _EMNLP 2024:
-# Encouraging Divergent Thinking in Large Language Models through Multi-Agent Debate. EMNLP 2024.
-#
diff --git a/docs/tutorial/zh_CN/src/workflow_routing.py b/docs/tutorial/zh_CN/src/workflow_routing.py
deleted file mode 100644
index 7f6a99da6..000000000
--- a/docs/tutorial/zh_CN/src/workflow_routing.py
+++ /dev/null
@@ -1,176 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-.. _routing:
-
-Routing
-==========================
-在 AgentScope 中有两种实现 Routing 的方法,都简单易实现:
-
-- 使用结构化输出的显式 routing
-- 使用工具调用的隐式 routing
-
-.. tip:: 考虑到智能体 routing 没有统一的标准/定义,我们遵循 `Building effective agents <https://www.anthropic.com/engineering/building-effective-agents>`_ 中的设置
-
-显式 Routing
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-在显式 routing 中,我们可以直接使用智能体的结构化输出来确定将消息路由到哪个智能体。
-
-初始化 routing 智能体
-"""
-import asyncio
-import json
-import os
-from typing import Literal
-
-from pydantic import BaseModel, Field
-
-from agentscope.agent import ReActAgent
-from agentscope.formatter import DashScopeChatFormatter
-from agentscope.memory import InMemoryMemory
-from agentscope.message import Msg
-from agentscope.model import DashScopeChatModel
-from agentscope.tool import Toolkit, ToolResponse
-
-router = ReActAgent(
- name="Router",
- sys_prompt="你是一个路由智能体。你的目标是将用户查询路由到正确的后续任务,注意你不需要回答用户的问题。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
-)
-
-
-# 使用结构化输出指定路由任务
-class RoutingChoice(BaseModel):
- your_choice: Literal[
- "Content Generation",
- "Programming",
- "Information Retrieval",
- None,
- ] = Field(
- description="选择正确的后续任务,如果任务太简单或没有合适的任务,则选择 ``None``",
- )
- task_description: str | None = Field(
- description="任务描述",
- default=None,
- )
-
-
-async def example_router_explicit() -> None:
- """使用结构化输出进行显式路由的示例。"""
- msg_user = Msg(
- "user",
- "帮我写一首诗",
- "user",
- )
-
- # 路由查询
- msg_res = await router(
- msg_user,
- structured_model=RoutingChoice,
- )
-
- # 结构化输出存储在 metadata 字段中
- print("结构化输出:")
- print(json.dumps(msg_res.metadata, indent=4, ensure_ascii=False))
-
-
-asyncio.run(example_router_explicit())
-
-# %%
-# 隐式 Routing
-# ~~~~~~~~~~~~~~~~~~~~~~~~~
-# 另一种方法是将下游智能体包装成工具函数,这样路由智能体就可以根据用户查询决定调用哪个工具。
-#
-# 我们首先定义几个工具函数:
-#
-
-
-async def generate_python(demand: str) -> ToolResponse:
- """根据需求生成 Python 代码。
-
- Args:
- demand (``str``):
- 对 Python 代码的需求。
- """
- # 示例需求智能体
- python_agent = ReActAgent(
- name="PythonAgent",
- sys_prompt="你是一个 Python 专家,你的目标是根据需求生成 Python 代码。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- memory=InMemoryMemory(),
- formatter=DashScopeChatFormatter(),
- toolkit=Toolkit(),
- )
- msg_res = await python_agent(Msg("user", demand, "user"))
-
- return ToolResponse(
- content=msg_res.get_content_blocks("text"),
- )
-
-
-# 为演示目的模拟一些其他工具函数
-async def generate_poem(demand: str) -> ToolResponse:
- """根据需求生成诗歌。
-
- Args:
- demand (``str``):
- 对诗歌的需求。
- """
- pass
-
-
-async def web_search(query: str) -> ToolResponse:
- """在网络上搜索查询。
-
- Args:
- query (``str``):
- 要搜索的查询。
- """
- pass
-
-
-# %%
-# 之后,我们定义一个路由智能体并为其配备上述工具函数。
-#
-
-toolkit = Toolkit()
-toolkit.register_tool_function(generate_python)
-toolkit.register_tool_function(generate_poem)
-toolkit.register_tool_function(web_search)
-
-# 使用工具模块初始化路由智能体
-router_implicit = ReActAgent(
- name="Router",
- sys_prompt="你是一个路由智能体。你的目标是将用户查询路由到正确的后续任务。",
- model=DashScopeChatModel(
- model_name="qwen-max",
- api_key=os.environ["DASHSCOPE_API_KEY"],
- stream=False,
- ),
- formatter=DashScopeChatFormatter(),
- toolkit=toolkit,
- memory=InMemoryMemory(),
-)
-
-
-async def example_router_implicit() -> None:
- """使用工具调用进行隐式路由的示例。"""
- msg_user = Msg(
- "user",
- "帮我在 Python 中生成一个快速排序函数",
- "user",
- )
-
- # 路由查询
- await router_implicit(msg_user)
-
-
-asyncio.run(example_router_implicit())
diff --git a/docs/tutorial/en/src/README.md b/examples/agent_service/README.md
similarity index 100%
rename from docs/tutorial/en/src/README.md
rename to examples/agent_service/README.md
diff --git a/examples/agent_service/main.py b/examples/agent_service/main.py
new file mode 100644
index 000000000..ded377dde
--- /dev/null
+++ b/examples/agent_service/main.py
@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""The example script to start the agent service."""
+import os
+
+import uvicorn
+from fastapi.middleware import Middleware
+from fastapi.middleware.cors import CORSMiddleware
+
+from agentscope.app import (
+ create_app,
+ RedisStorage,
+ LocalWorkspaceManager,
+)
+from agentscope.mcp import MCPClient, StdioMCPConfig, HttpMCPConfig
+
+app = create_app(
+ RedisStorage(
+ # connection_pool=fakeredis.aioredis.FakeRedis().connection_pool,
+ ),
+ workspace_manager=LocalWorkspaceManager(
+ basedir="/Users/david/Documents/Python/agents/agentscope_2/workdir",
+ default_mcps=[
+ MCPClient(
+ name="browser-use",
+ mcp_config=StdioMCPConfig(
+ command="npx",
+ args=["install @playwright/browser-use"],
+ ),
+ is_stateful=True,
+ ),
+ MCPClient(
+ name="amap",
+ mcp_config=HttpMCPConfig(
+ url=f"https://mcp.amap.com/mcp?key="
+ f"{os.environ['GAODE_API_KEY']}",
+ ),
+ is_stateful=False,
+ ),
+ ],
+ ),
+ extra_middlewares=[
+ Middleware(
+ CORSMiddleware,
+ allow_origins=["*"],
+ allow_methods=["*"],
+ allow_headers=["*"],
+ ),
+ ],
+)
+
+if __name__ == "__main__":
+ uvicorn.run(
+ "main:app",
+ host="0.0.0.0",
+ port=8000,
+ reload=True,
+ )
diff --git a/pyproject.toml b/pyproject.toml
index f7a1a63bc..6c8698366 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -57,10 +57,22 @@ models = [
"agentscope[gemini]",
"agentscope[xai]",
]
-
+# ------------ Service ------------
+service = [
+ "fastapi",
+ "uvicorn",
+ "apscheduler",
+ "ag-ui-protocol>=0.1.10",
+]
+# ------------ Storage ------------
+storage = [
+ "redis",
+]
# ------------ Full ------------
full = [
"agentscope[models]",
+ "agentscope[service]",
+ "agentscope[storage]",
]
# ------------ Development ------------
@@ -75,6 +87,7 @@ dev = [
"furo",
"myst_parser",
"matplotlib",
+ "fakeredis",
]
[project.urls]
diff --git a/src/agentscope/agent/__init__.py b/src/agentscope/agent/__init__.py
index f87dd3a99..a1628c8bd 100644
--- a/src/agentscope/agent/__init__.py
+++ b/src/agentscope/agent/__init__.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
"""Initialize the agent module."""
from ._agent import Agent
-from ._config import ContextConfig
+from ._config import ContextConfig, ReActConfig
-__all__ = ["Agent", "ContextConfig"]
+__all__ = ["Agent", "ContextConfig", "ReActConfig"]
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index 7681c6ad2..c03f2cff4 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -12,6 +12,7 @@ from typing import (
Sequence,
Literal,
List,
+ TYPE_CHECKING,
)
import jsonschema
@@ -50,7 +51,6 @@ from ..event import (
ExceedMaxItersEvent,
)
from ..exception import AgentOrientedException
-from ..middleware import MiddlewareBase
from ..model import (
ChatResponse,
ChatUsage,
@@ -83,6 +83,11 @@ from ..permission import (
PermissionDecision,
)
+if TYPE_CHECKING:
+ from ..middleware import MiddlewareBase
+else:
+ MiddlewareBase = Any
+
class Agent:
"""The agent class."""
@@ -138,12 +143,13 @@ class Agent:
async def reply_stream(
self,
- msgs: Msg | list[Msg] | None = None,
- event: UserConfirmResultEvent
+ inputs: Msg
+ | list[Msg]
+ | UserConfirmResultEvent
| ExternalExecutionResultEvent
| None = None,
) -> AsyncGenerator[AgentEvent, None]:
- """Reply to the given message and stream agent events.
+ """Reply to the given inputs and stream agent events.
**NOTE**:
@@ -154,7 +160,7 @@ class Agent:
calls.
"""
try:
- async for chunk in self._reply(msgs=msgs, event=event):
+ async for chunk in self._reply(inputs=inputs):
if not isinstance(chunk, Msg):
yield chunk
finally:
@@ -162,24 +168,26 @@ class Agent:
async def reply(
self,
- msgs: Msg | list[Msg] | None = None,
- event: UserConfirmResultEvent
+ inputs: Msg
+ | list[Msg]
+ | UserConfirmResultEvent
| ExternalExecutionResultEvent
| None = None,
) -> Msg:
- """Reply to the given message, consuming all streamed events.
+ """Reply to the given inputs, consuming all streamed events.
Args:
- msgs (`Msg | list[Msg] | None`, optional):
- The message(s) to reply to. Can be a single `Msg` object,
- a list of `Msg` objects, or `None` if there are no new
- messages.
- event (`UserConfirmResultEvent | ExternalExecutionResultEvent | \
- None`, optional):
- The event to continue from, which should be the result of the
- required outside interaction triggered by the previous reply.
- If the previous reply does not trigger any outside
- interaction, this should be `None`.
+ inputs (`Msg | list[Msg] | UserConfirmResultEvent | \
+ 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,
+ - `None` if there is nothing new to feed in (e.g. just
+ continue from the current state).
Returns:
`Msg`:
@@ -187,7 +195,7 @@ class Agent:
"""
try:
final_msg: Msg | None = None
- async for evt_or_msg in self._reply(msgs=msgs, event=event):
+ async for evt_or_msg in self._reply(inputs=inputs):
if isinstance(evt_or_msg, Msg):
final_msg = evt_or_msg
if final_msg is None:
@@ -386,30 +394,32 @@ class Agent:
async def _reply(
self,
- msgs: Msg | list[Msg] | None = None,
- event: UserConfirmResultEvent
+ inputs: Msg
+ | list[Msg]
+ | UserConfirmResultEvent
| ExternalExecutionResultEvent
| None = None,
) -> AsyncGenerator[AgentEvent | Msg, None]:
- """Reply entry point (may be wrapped by middleware)."""
+ """Reply entry point (maybe wrapped by middleware)."""
if not self._reply_middlewares:
- async for item in self._reply_impl(msgs=msgs, event=event):
+ async for item in self._reply_impl(inputs=inputs):
yield item
else:
async def execute_chain(
index: int = 0,
- msgs: Msg | list[Msg] | None = msgs,
- event: UserConfirmResultEvent
+ inputs: Msg
+ | list[Msg]
+ | UserConfirmResultEvent
| ExternalExecutionResultEvent
- | None = event,
+ | None = inputs,
) -> AsyncGenerator[AgentEvent | Msg, None]:
if index >= len(self._reply_middlewares):
- async for item in self._reply_impl(msgs=msgs, event=event):
+ async for item in self._reply_impl(inputs=inputs):
yield item
else:
mw = self._reply_middlewares[index]
- input_kwargs = {"msgs": msgs, "event": event}
+ input_kwargs = {"inputs": inputs}
async def next_handler(
**kwargs: Any,
@@ -429,12 +439,26 @@ class Agent:
async def _reply_impl(
self,
- msgs: Msg | list[Msg] | None = None,
- event: UserConfirmResultEvent
+ inputs: Msg
+ | list[Msg]
+ | UserConfirmResultEvent
| ExternalExecutionResultEvent
| None = None,
) -> AsyncGenerator[AgentEvent | Msg, None]:
"""Core reply logic."""
+ # Dispatch the unified inputs by type into the legacy local variables
+ event: (UserConfirmResultEvent | ExternalExecutionResultEvent | None)
+ msgs: Msg | list[Msg] | None
+ if isinstance(
+ inputs,
+ (UserConfirmResultEvent, ExternalExecutionResultEvent),
+ ):
+ event = inputs
+ msgs = None
+ else:
+ event = None
+ msgs = inputs
+
# ===================================================================
# Step 1: Checking agent input:
# - if incoming event and agent is waiting for an event
@@ -1145,50 +1169,14 @@ class Agent:
| ToolResultEndEvent,
None,
]:
- """Execute tool call entry point (maybe wrapped by middleware)."""
- if not self._acting_middlewares:
- async for item in self._execute_tool_call_impl(tool_call):
- yield item
- else:
+ """Execute a single tool call with permission checking and context
+ management.
- async def execute_chain(
- index: int = 0,
- tool_call: ToolCallBlock = tool_call,
- ) -> AsyncGenerator:
- if index >= len(self._acting_middlewares):
- async for item in self._execute_tool_call_impl(tool_call):
- yield item
- else:
- mw = self._acting_middlewares[index]
- input_kwargs = {"tool_call": tool_call}
-
- async def next_handler(**kwargs: Any) -> AsyncGenerator:
- async for item in execute_chain(index + 1, **kwargs):
- yield item
-
- async for item in mw.on_acting(
- agent=self,
- input_kwargs=input_kwargs,
- next_handler=next_handler,
- ):
- yield item
-
- async for item in execute_chain():
- yield item
-
- async def _execute_tool_call_impl(
- self,
- tool_call: ToolCallBlock,
- ) -> AsyncGenerator[
- RequireUserConfirmEvent
- | RequireExternalExecutionEvent
- | ToolResultStartEvent
- | ToolResultTextDeltaEvent
- | ToolResultDataDeltaEvent
- | ToolResultEndEvent,
- None,
- ]:
- """Execute a single tool call with permission checking.
+ This method handles the full tool call lifecycle: input validation,
+ permission checking, event emission, and context writes. The raw
+ tool execution (``toolkit.call_tool``) is delegated to
+ :meth:`_acting`, which is the hook point for ``on_acting``
+ middleware.
Args:
tool_call (`ToolCallBlock`):
@@ -1198,8 +1186,7 @@ class Agent:
`RequireUserConfirmEvent \
| RequireExternalExecutionEvent \
| ToolResultStartEvent \
- | ToolResult \
- | TextDeltaEvent \
+ | ToolResultTextDeltaEvent \
| ToolResultDataDeltaEvent \
| ToolResultEndEvent`:
The events generated during the tool call execution.
@@ -1277,6 +1264,7 @@ class Agent:
ToolCallState.ASKING,
)
+ tool_call.suggested_rules = decision.suggested_rules or []
yield RequireUserConfirmEvent(
reply_id=self.state.reply_id,
tool_calls=[tool_call],
@@ -1323,10 +1311,10 @@ class Agent:
)
return
- # Execute the tool call and yield the events.
-
- res = self.toolkit.call_tool(tool_call, self.state)
- async for chunk in res:
+ # ================================================================
+ # Step 4: Delegate raw execution to _acting (middleware hook point)
+ # ================================================================
+ async for chunk in self._acting(tool_call):
# The ToolResponse is the last and completed tool result here
if isinstance(chunk, ToolResponse):
tool_result_block = ToolResultBlock(
@@ -1339,7 +1327,7 @@ class Agent:
)
# ========================================================
- # Step 4: Truncate the tool result if exceed
+ # Step 5: Truncate the tool result if exceed
# ========================================================
(
reserved_tool_result_block,
@@ -1390,6 +1378,7 @@ class Agent:
)
else:
+ # Intermediate ToolChunk — convert to streaming events
async for evt in self._convert_tool_chunk_to_event(
tool_call.id,
chunk.content,
@@ -1402,6 +1391,87 @@ class Agent:
f"Invalid permission decision behavior: {decision.behavior}",
)
+ async def _acting(
+ self,
+ tool_call: ToolCallBlock,
+ ) -> AsyncGenerator["ToolChunk | ToolResponse", None]:
+ """Raw tool execution entry point (maybe wrapped by middleware).
+
+ This method is the hook point for ``on_acting`` middleware. It
+ delegates to :meth:`_acting_impl` which wraps
+ ``toolkit.call_tool`` directly. Permission checking and context
+ writes are **not** part of this method — they are handled by
+ :meth:`_execute_tool_call` before and after this call.
+
+ Args:
+ tool_call (`ToolCallBlock`):
+ The tool call block to execute.
+
+ Yields:
+ `ToolChunk | ToolResponse`:
+ Intermediate :class:`~agentscope.tool.ToolChunk` objects
+ followed by a final :class:`~agentscope.tool.ToolResponse`.
+ """
+ if not self._acting_middlewares:
+ async for item in self._acting_impl(tool_call):
+ yield item
+ else:
+
+ async def execute_chain(
+ index: int = 0,
+ tool_call: ToolCallBlock = tool_call,
+ ) -> AsyncGenerator:
+ if index >= len(self._acting_middlewares):
+ async for item in self._acting_impl(tool_call):
+ yield item
+ else:
+ mw = self._acting_middlewares[index]
+ input_kwargs = {"tool_call": tool_call}
+
+ async def next_handler(**kwargs: Any) -> AsyncGenerator:
+ async for item in execute_chain(index + 1, **kwargs):
+ yield item
+
+ async for item in mw.on_acting(
+ agent=self,
+ input_kwargs=input_kwargs,
+ next_handler=next_handler,
+ ):
+ yield item
+
+ async for item in execute_chain():
+ yield item
+
+ async def _acting_impl(
+ self,
+ tool_call: ToolCallBlock,
+ ) -> AsyncGenerator["ToolChunk | ToolResponse", None]:
+ """Core tool execution logic.
+
+ Wraps :meth:`~agentscope.tool.Toolkit.call_tool` and yields its
+ output unchanged. Does **not** perform permission checking or
+ write to the agent context — those responsibilities belong to
+ :meth:`_execute_tool_call`.
+
+ .. note::
+ Tools with ``is_state_injected=True`` receive the live
+ ``agent.state`` object. Offloading such tools to a background
+ task (via ``on_acting`` middleware) may cause concurrent state
+ mutations. TODO: block background offloading for
+ state-injected tools.
+
+ Args:
+ tool_call (`ToolCallBlock`):
+ The tool call block to execute.
+
+ Yields:
+ `ToolChunk | ToolResponse`:
+ Intermediate :class:`~agentscope.tool.ToolChunk` objects
+ followed by a final :class:`~agentscope.tool.ToolResponse`.
+ """
+ async for chunk in self.toolkit.call_tool(tool_call, self.state):
+ yield chunk
+
async def _handle_error_tool_call(
self,
tool_call: ToolCallBlock,
@@ -1916,10 +1986,19 @@ class Agent:
],
_usage: ChatUsage | None = None,
) -> None:
- """Save content blocks into the context."""
+ """Save content blocks into the context.
+
+ Newly created :class:`AssistantMsg` uses ``self.state.reply_id`` as
+ its id so that one reply corresponds to one message and the message
+ id matches the ``reply_id`` carried by streaming events.
+ """
if len(self.state.context) == 0:
self.state.context.append(
- AssistantMsg(name=self.name, content=list(blocks)),
+ AssistantMsg(
+ id=self.state.reply_id,
+ name=self.name,
+ content=list(blocks),
+ ),
)
else:
last_msg = self.state.context[-1]
@@ -1931,6 +2010,7 @@ class Agent:
else:
self.state.context.append(
AssistantMsg(
+ id=self.state.reply_id,
name=self.name,
content=list(blocks),
),
diff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.py
index 8b5b8b84a..d50046594 100644
--- a/src/agentscope/agent/_config.py
+++ b/src/agentscope/agent/_config.py
@@ -49,6 +49,8 @@ class SummarySchema(BaseModel):
"Any promises made to the user"
),
)
+ """Whether to execute multiple tool calls in parallel within one
+ reasoning step."""
class ContextConfig(BaseModel):
diff --git a/src/agentscope/app/__init__.py b/src/agentscope/app/__init__.py
new file mode 100644
index 000000000..833fbb31e
--- /dev/null
+++ b/src/agentscope/app/__init__.py
@@ -0,0 +1,45 @@
+# -*- 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 ._middleware import (
+ ProtocolMiddlewareBase,
+ AGUIProtocolMiddleware,
+ ToolOffloadMiddleware,
+)
+from .storage import (
+ RedisStorage,
+ AgentRecord,
+ CredentialRecord,
+ SessionConfig,
+ SessionRecord,
+ UserRecord,
+)
+from ._manager import (
+ WorkspaceManagerBase,
+ LocalWorkspaceManager,
+ BackgroundTaskManager,
+ SchedulerManager,
+ SessionManager,
+)
+
+__all__ = [
+ "create_app",
+ "ProtocolMiddlewareBase",
+ "AGUIProtocolMiddleware",
+ "ToolOffloadMiddleware",
+ "RedisStorage",
+ "AgentRecord",
+ "CredentialRecord",
+ "SessionConfig",
+ "SessionRecord",
+ "UserRecord",
+ "WorkspaceManagerBase",
+ "BackgroundTaskManager",
+ "LocalWorkspaceManager",
+ "BackgroundTaskManager",
+ "SchedulerManager",
+ "SessionManager",
+]
diff --git a/src/agentscope/app/_app.py b/src/agentscope/app/_app.py
new file mode 100644
index 000000000..b8b6eaf6c
--- /dev/null
+++ b/src/agentscope/app/_app.py
@@ -0,0 +1,107 @@
+# -*- coding: utf-8 -*-
+"""AgentScope app factory."""
+from typing import Type, TYPE_CHECKING, Any
+
+from ._lifespan import lifespan
+from ._manager import WorkspaceManagerBase
+from ._router import (
+ agent_router,
+ background_task_router,
+ chat_router,
+ credential_router,
+ model_router,
+ schedule_router,
+ session_router,
+ workspace_router,
+)
+from .storage import StorageBase
+from ..credential import CredentialFactory, CredentialBase
+
+if TYPE_CHECKING:
+ from fastapi import FastAPI
+ from fastapi.middleware import Middleware
+else:
+ FastAPI = Any
+ Middleware = Any
+
+
+def create_app(
+ storage: StorageBase,
+ *,
+ workspace_manager: WorkspaceManagerBase | None = None,
+ extra_credentials: list[Type[CredentialBase]] | None = None,
+ extra_middlewares: list[Middleware] | None = None,
+ title: str = "AgentScope",
+ version: str = "2.0.0",
+) -> 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())
+ uvicorn.run(app, host="0.0.0.0", port=8000)
+
+ Usage — mount onto an existing app::
+
+ root = FastAPI()
+ agentscope_app = create_app(storage=RedisStorage())
+ root.mount("/agentscope", agentscope_app)
+
+ Args:
+ storage (`StorageBase`):
+ The storage backend. Its lifecycle (``__aenter__`` /
+ ``__aexit__``) is managed by the app lifespan.
+ workspace_manager (`WorkspaceManagerBase | None`, optional):
+ The workspace manager. When provided, its ``close_all`` is called
+ on shutdown. Pass a :class:`~agentscope.app._manager.
+ LocalWorkspaceManager`
+ for local-directory workspaces.
+ 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.
+ title (`str`, defaults to ``"AgentScope"``):
+ OpenAPI title shown in the docs UI.
+ version (`str`, defaults to ``"2.0.0"``):
+ API version shown in the docs UI.
+
+ Returns:
+ `FastAPI`: A fully configured application ready to serve requests.
+ """
+ from fastapi import FastAPI
+
+ # Register any user-supplied credential types before the app starts
+ for cls in extra_credentials or []:
+ CredentialFactory.register_credential(cls)
+
+ app = FastAPI(title=title, version=version, lifespan=lifespan)
+
+ # Attach shared state that lifespan and dependencies read from app.state
+ app.state.storage = storage
+ app.state.workspace_manager = workspace_manager
+
+ # Built-in routers
+ for router in (
+ agent_router,
+ background_task_router,
+ chat_router,
+ credential_router,
+ schedule_router,
+ session_router,
+ workspace_router,
+ model_router,
+ ):
+ app.include_router(router)
+
+ # Optional extra middlewares
+ for middleware in extra_middlewares or []:
+ app.add_middleware(middleware.cls, **middleware.kwargs)
+
+ return app
diff --git a/src/agentscope/app/_deps.py b/src/agentscope/app/_deps.py
new file mode 100644
index 000000000..921bbc4be
--- /dev/null
+++ b/src/agentscope/app/_deps.py
@@ -0,0 +1,111 @@
+# -*- coding: utf-8 -*-
+"""Shared FastAPI dependencies for the agentscope app."""
+from fastapi import Header, HTTPException, Request, status
+
+from ._manager import (
+ BackgroundTaskManager,
+ SessionManager,
+ WorkspaceManagerBase,
+ SchedulerManager,
+)
+from .storage import StorageBase
+
+
+async def get_current_user_id(
+ x_user_id: str = Header(
+ description="Caller's user ID. "
+ "Temporary header-based identity; will be replaced by JWT auth.",
+ ),
+) -> str:
+ """Return the caller's user ID from the ``X-User-ID`` request header.
+
+ This is a placeholder dependency. Once an auth middleware is in place,
+ replace the header extraction with a JWT / session-token lookup and remove
+ the ``X-User-ID`` header entirely.
+
+ Args:
+ x_user_id (`str`): Value of the ``X-User-ID`` header.
+
+ Returns:
+ `str`: The authenticated user ID.
+
+ Raises:
+ `HTTPException`: 401 if the header is missing or empty.
+ """
+ if not x_user_id:
+ raise HTTPException(
+ status_code=status.HTTP_401_UNAUTHORIZED,
+ detail="X-User-ID header is required.",
+ )
+ return x_user_id
+
+
+async def get_storage(request: Request) -> StorageBase:
+ """Return the application-wide storage backend.
+
+ Args:
+ request (`Request`): The incoming FastAPI request.
+
+ Returns:
+ `StorageBase`: The storage instance stored in ``app.state``.
+ """
+ return request.app.state.storage
+
+
+async def get_session_manager(request: Request) -> SessionManager:
+ """Return the application-wide session manager.
+
+ Args:
+ request (`Request`): The incoming FastAPI request.
+
+ Returns:
+ `SessionManager`: The session manager stored in ``app.state``.
+ """
+ return request.app.state.session_manager
+
+
+async def get_scheduler_manager(request: Request) -> SchedulerManager:
+ """Return the application-wide scheduler manager.
+
+ Args:
+ request (`Request`): The incoming FastAPI request.
+
+ Returns:
+ `SchedulerManager`: The scheduler manager stored in ``app.state``.
+ """
+ return request.app.state.scheduler_manager
+
+
+async def get_workspace_manager(request: Request) -> WorkspaceManagerBase:
+ """Return the application-wide workspace manager.
+
+ Args:
+ request (`Request`): The incoming FastAPI request.
+
+ Returns:
+ `WorkspaceManagerBase`: The workspace manager stored in ``app.state``.
+
+ Raises:
+ `HTTPException`: 503 if no workspace manager is configured.
+ """
+ manager = request.app.state.workspace_manager
+ if manager is None:
+ raise HTTPException(
+ status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+ detail="Workspace manager is not configured.",
+ )
+ return manager
+
+
+async def get_background_task_manager(
+ request: Request,
+) -> BackgroundTaskManager:
+ """Return the application-wide background task manager.
+
+ Args:
+ request (`Request`): The incoming FastAPI request.
+
+ Returns:
+ `BackgroundTaskManager`: The manager stored in ``app.state``.
+ """
+ return request.app.state.background_task_manager
diff --git a/src/agentscope/app/_lifespan.py b/src/agentscope/app/_lifespan.py
new file mode 100644
index 000000000..da42de6ff
--- /dev/null
+++ b/src/agentscope/app/_lifespan.py
@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""The lifespan of the agent service."""
+from contextlib import asynccontextmanager
+from typing import TYPE_CHECKING, Any, AsyncIterator
+
+from ._manager import BackgroundTaskManager, SchedulerManager, SessionManager
+
+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.
+
+ On startup:
+ - Opens the storage connection pool.
+ - Starts the session manager, background task manager, and scheduler.
+ - Restores persisted schedules from storage into the in-memory scheduler.
+
+ On shutdown:
+ - Cancels in-flight sessions and background tasks.
+ - Shuts down the scheduler (waits for running jobs to finish).
+ """
+ async with app.state.storage:
+ session_manager = SessionManager()
+ app.state.session_manager = session_manager
+ app.state.background_task_manager = BackgroundTaskManager()
+
+ scheduler = SchedulerManager(
+ storage=app.state.storage,
+ session_manager=session_manager,
+ background_task_manager=app.state.background_task_manager,
+ workspace_manager=app.state.workspace_manager,
+ )
+ app.state.scheduler_manager = scheduler
+ await scheduler.start()
+
+ # Restore persisted schedules so they survive server restarts
+ all_schedules = await app.state.storage.list_all_schedules()
+ if all_schedules:
+ await scheduler.restore(all_schedules)
+
+ yield
+
+ app.state.session_manager.cancel()
+ app.state.background_task_manager.cancel()
+ await scheduler.shutdown()
diff --git a/src/agentscope/app/_manager/__init__.py b/src/agentscope/app/_manager/__init__.py
new file mode 100644
index 000000000..1f1733389
--- /dev/null
+++ b/src/agentscope/app/_manager/__init__.py
@@ -0,0 +1,17 @@
+# -*- coding: utf-8 -*-
+"""The agent service managers, used in FastAPI lifespan to manage
+application-wide resources."""
+
+from ._background_task_manager import BackgroundTaskManager
+from ._scheduler import SchedulerManager
+from ._session_manager import SessionManager
+from ._workspace_manager import WorkspaceManagerBase, LocalWorkspaceManager
+
+
+__all__ = [
+ "BackgroundTaskManager",
+ "LocalWorkspaceManager",
+ "SchedulerManager",
+ "SessionManager",
+ "WorkspaceManagerBase",
+]
diff --git a/src/agentscope/app/_manager/_background_task_manager.py b/src/agentscope/app/_manager/_background_task_manager.py
new file mode 100644
index 000000000..72a4826be
--- /dev/null
+++ b/src/agentscope/app/_manager/_background_task_manager.py
@@ -0,0 +1,334 @@
+# -*- coding: utf-8 -*-
+"""The background task manager."""
+import asyncio
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any, Callable, Coroutine
+
+import shortuuid
+from pydantic import BaseModel, Field
+
+from ...message import TextBlock, ToolResultState
+from ...permission import (
+ PermissionContext,
+ PermissionDecision,
+ PermissionBehavior,
+)
+from ...tool import ToolBase, ToolChunk
+from ..._logging import logger
+
+
+@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.
+ id (`str`):
+ Auto-generated unique task identifier.
+ """
+
+ 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."""
+
+ id: str = field(default_factory=shortuuid.uuid)
+ """The background task id."""
+
+
+class _TaskStopParams(BaseModel):
+ """The params of the stop task."""
+
+ task_id: str = Field(
+ description="The task id of the stop task.",
+ )
+
+
+class TaskStop(ToolBase):
+ """A tool to stop a running background task."""
+
+ name: str = "TaskStop"
+ """The tool name."""
+
+ description: str = "Stop a background task by its task id."
+ """The tool description."""
+
+ input_schema: dict = _TaskStopParams.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]) -> None:
+ """Initialize the TaskStop tool.
+
+ Args:
+ background_tasks (`dict[str, BackgroundTask]`):
+ A reference to the background tasks managed by the
+ :class:`BackgroundTaskManager`.
+ """
+ self.background_tasks = background_tasks
+
+ 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.
+ """
+ if task_id not in self.background_tasks:
+ return ToolChunk(
+ content=[
+ TextBlock(
+ text=f"TaskNotFoundError: The task {task_id} "
+ f"does not exist.",
+ ),
+ ],
+ state=ToolResultState.ERROR,
+ )
+
+ # Cancel and pop the task
+ task = self.background_tasks.pop(task_id)
+ task.asyncio_task.cancel()
+ logger.info(
+ "Background task stopped via TaskStop tool: task_id=%s, "
+ "session_id=%s, agent_id=%s",
+ task_id,
+ task.session_id,
+ task.agent_id,
+ )
+ return ToolChunk(
+ content=[TextBlock(text=f"Task {task_id} stopped successfully.")],
+ state=ToolResultState.SUCCESS,
+ )
+
+
+class BackgroundTaskManager:
+ """Manages background asyncio task lifecycle within the agent services.
+
+ Responsibilities:
+
+ - **Task registry**: track running tasks so they can be cancelled via
+ :class:`TaskStop`.
+ - **Task scheduling**: convenience method for creating a task from a
+ plain coroutine with an optional completion callback.
+ - **Result storage**: completed task results are stored here so that
+ middleware can pull them on the next reasoning step.
+ """
+
+ def __init__(self) -> None:
+ """Initialise the background task manager."""
+ self.tasks: OrderedDict[str, BackgroundTask] = OrderedDict()
+ self._completed_results: dict[str, list[Any]] = {}
+
+ # ------------------------------------------------------------------
+ # Result storage API
+ # ------------------------------------------------------------------
+
+ def push_result(self, session_id: str, result: Any) -> None:
+ """Store a completed task result for *session_id*.
+
+ Args:
+ session_id (`str`):
+ The target session.
+ result (`Any`):
+ The result object (type determined by the producer).
+ """
+ self._completed_results.setdefault(session_id, []).append(result)
+
+ def pop_results(self, session_id: str) -> list[Any]:
+ """Return and clear all completed results for *session_id*.
+
+ Args:
+ session_id (`str`):
+ The session to query.
+
+ Returns:
+ `list[Any]`:
+ Accumulated results, or ``[]`` if none.
+ """
+ return self._completed_results.pop(session_id, [])
+
+ def has_results(self, session_id: str) -> bool:
+ """Check whether *session_id* has pending completed results.
+
+ Args:
+ session_id (`str`):
+ The session to check.
+
+ Returns:
+ `bool`:
+ ``True`` if there are unconsumed results.
+ """
+ return bool(self._completed_results.get(session_id))
+
+ # ------------------------------------------------------------------
+ # Task registration
+ # ------------------------------------------------------------------
+
+ async def register_task(
+ self,
+ asyncio_task: asyncio.Task,
+ session_id: str,
+ agent_id: str,
+ user_id: str,
+ on_complete: Callable[[], Coroutine] | None = None,
+ ) -> str:
+ """Register an already-running asyncio task and return its id.
+
+ A watcher coroutine is spawned that awaits *asyncio_task*; when it
+ finishes *on_complete* (if provided) is awaited and the task entry
+ is removed from the registry.
+
+ Args:
+ asyncio_task (`asyncio.Task`):
+ The already-running task to register.
+ session_id (`str`):
+ The originating session id.
+ agent_id (`str`):
+ The name of the agent that owns the task.
+ user_id (`str`):
+ The user id of the originating request.
+ on_complete (`Callable[[], Coroutine] | None`, optional):
+ An async callable invoked when the task finishes normally.
+ Not called when the task is cancelled.
+
+ 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,
+ )
+ task_id = bg_task.id
+ self.tasks[task_id] = bg_task
+ logger.info(
+ "Background task registered: task_id=%s, session_id=%s, "
+ "agent_id=%s",
+ task_id,
+ session_id,
+ agent_id,
+ )
+
+ async def _watch() -> None:
+ logger.info(
+ "Background task started: task_id=%s, session_id=%s, "
+ "agent_id=%s",
+ task_id,
+ session_id,
+ agent_id,
+ )
+ try:
+ await asyncio_task
+ except asyncio.CancelledError:
+ logger.info(
+ "Background task cancelled: task_id=%s, session_id=%s, "
+ "agent_id=%s",
+ task_id,
+ session_id,
+ agent_id,
+ )
+ return
+ except Exception: # pylint: disable=broad-except
+ logger.warning(
+ "Background task failed with exception: task_id=%s, "
+ "session_id=%s, agent_id=%s",
+ task_id,
+ session_id,
+ agent_id,
+ exc_info=True,
+ )
+ finally:
+ self.tasks.pop(task_id, None)
+
+ logger.info(
+ "Background task completed: task_id=%s, session_id=%s, "
+ "agent_id=%s",
+ task_id,
+ session_id,
+ agent_id,
+ )
+ if on_complete is not None:
+ await on_complete()
+
+ asyncio.create_task(_watch())
+ return task_id
+
+ async def list_tools(self) -> list[ToolBase]:
+ """List the background tasks related tools.
+
+ Returns:
+ `list[ToolBase]`:
+ A list containing the :class:`TaskStop` tool.
+ """
+ return [TaskStop(self.tasks)]
+
+ def cancel(self) -> None:
+ """Cancel all running background tasks on application shutdown.
+
+ Each task's asyncio task is cancelled. The ``on_complete``
+ callback will **not** be invoked for cancelled tasks.
+ """
+ count = len(self.tasks)
+ logger.info(
+ "Shutting down BackgroundTaskManager: cancelling %d task(s).",
+ count,
+ )
+ for bg_task in list(self.tasks.values()):
+ logger.info(
+ "Cancelling background task on shutdown: task_id=%s, "
+ "session_id=%s, agent_id=%s",
+ bg_task.id,
+ bg_task.session_id,
+ bg_task.agent_id,
+ )
+ bg_task.asyncio_task.cancel()
+ self.tasks.clear()
diff --git a/src/agentscope/app/_manager/_scheduler/__init__.py b/src/agentscope/app/_manager/_scheduler/__init__.py
new file mode 100644
index 000000000..365ce585c
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/__init__.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The scheduler related components."""
+
+from ._scheduler_manager import SchedulerManager
+
+__all__ = [
+ "SchedulerManager",
+]
diff --git a/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py b/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py
new file mode 100644
index 000000000..33ada35c3
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py
@@ -0,0 +1,400 @@
+# -*- coding: utf-8 -*-
+"""The cron scheduler manager class."""
+from collections.abc import Callable, Coroutine
+
+from apscheduler.schedulers.asyncio import AsyncIOScheduler
+from apscheduler.triggers.cron import CronTrigger
+
+from ....message import UserMsg
+from ....tool import ToolBase
+from ...._logging import logger
+from ._tools import ScheduleCreate, ScheduleList, ScheduleStop, ScheduleView
+from ...storage import (
+ StorageBase,
+ ScheduleRecord,
+ ChatModelConfig,
+)
+from .._background_task_manager import BackgroundTaskManager
+from .._session_manager import SessionManager
+from .._workspace_manager import WorkspaceManagerBase
+
+
+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 runs agents on schedule. Inject it with ``storage`` and
+ ``session_manager`` so it can build self-contained trigger coroutines
+ without external callbacks.
+ """
+
+ def __init__(
+ self,
+ storage: StorageBase,
+ session_manager: SessionManager,
+ background_task_manager: BackgroundTaskManager,
+ workspace_manager: WorkspaceManagerBase,
+ ) -> None:
+ """Initialize the scheduler manager.
+
+ Args:
+ storage (`StorageBase`):
+ The storage backend used for persistence and session creation.
+ session_manager (`SessionManager`):
+ The session manager used when running agent chat sessions.
+ background_task_manager (`BackgroundTaskManager`):
+ The background task manager passed through to
+ :class:`ChatService` so triggered agents can offload
+ long-running tools.
+ workspace_manager (`WorkspaceManagerBase`):
+ The workspace manager passed through to :class:`ChatService`
+ so triggered agents get the configured toolkit and MCPs.
+ """
+ self._storage = storage
+ self._session_manager = session_manager
+ self._background_task_manager = background_task_manager
+ self._workspace_manager = workspace_manager
+ self._scheduler = AsyncIOScheduler()
+
+ # ------------------------------------------------------------------
+ # Lifecycle
+ # ------------------------------------------------------------------
+
+ async def start(self) -> None:
+ """Start the underlying APScheduler."""
+ logger.info("SchedulerManager starting APScheduler")
+ self._scheduler.start()
+ logger.info("SchedulerManager APScheduler started")
+
+ async def shutdown(self) -> None:
+ """Shut down the underlying APScheduler."""
+ logger.info("SchedulerManager shutting down APScheduler")
+ 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.
+ """
+ # Collect closure-friendly references to avoid re-looking them up
+ # on every fire. ChatService is imported lazily inside the closure to
+ # break the circular dependency:
+ # _manager._scheduler → _service._chat → _manager
+ storage = self._storage
+ session_manager = self._session_manager
+ background_task_manager = self._background_task_manager
+ 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
+
+ # Lazy import to break circular dependency
+ from ..._service._chat import ChatService # noqa: PLC0415
+ from ....permission._context import (
+ PermissionContext,
+ ) # noqa: PLC0415
+ from ....state import AgentState # noqa: PLC0415
+ from ...storage._model._session import ( # noqa: PLC0415
+ SessionConfig,
+ SessionSource,
+ )
+
+ 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="",
+ 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,
+ source=SessionSource.SCHEDULE,
+ source_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="",
+ chat_model_config=record.data.chat_model_config,
+ ),
+ state=state,
+ source=SessionSource.SCHEDULE,
+ source_schedule_id=record.id,
+ )
+
+ logger.info(
+ "[Schedule:%s(%s)] Session ready: %s, "
+ "starting chat execution",
+ record.id,
+ record.data.name,
+ session.id,
+ )
+
+ input_msg = UserMsg(
+ name=record.user_id,
+ content=record.data.description,
+ )
+
+ chat_service = ChatService(
+ storage=storage,
+ session_manager=session_manager,
+ background_task_manager=background_task_manager,
+ workspace_manager=workspace_manager,
+ )
+ async for _ in chat_service.stream_chat(
+ user_id=record.user_id,
+ session_id=session.id,
+ agent_id=record.agent_id,
+ input_msg=input_msg,
+ ):
+ pass
+
+ logger.info(
+ "[Schedule:%s(%s)] Chat execution completed "
+ "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
+ # ------------------------------------------------------------------
+
+ async def register_schedule(self, record: ScheduleRecord) -> str:
+ """Persist-and-register a schedule record with APScheduler.
+
+ Builds the trigger coroutine via :meth:`_build_trigger` and adds the
+ job to APScheduler. This is the single entry point used by both the
+ HTTP API and the :class:`ScheduleCreate` agent tool.
+
+ Args:
+ record (`ScheduleRecord`):
+ The fully-populated record (already persisted to storage).
+
+ Returns:
+ `str`:
+ The APScheduler job ID (equal to ``record.id``).
+ """
+ logger.info(
+ "Registering schedule %s(%s) cron=%s tz=%s",
+ record.id,
+ record.data.name,
+ record.data.cron_expression,
+ record.data.timezone,
+ )
+ trigger = self._build_trigger(record)
+ job = self._scheduler.add_job(
+ trigger,
+ trigger=CronTrigger.from_crontab(
+ record.data.cron_expression,
+ timezone=record.data.timezone,
+ ),
+ id=record.id,
+ name=record.data.name,
+ misfire_grace_time=300,
+ )
+ logger.info(
+ "Schedule %s(%s) registered, next_run=%s",
+ record.id,
+ record.data.name,
+ job.next_run_time,
+ )
+ return job.id
+
+ async def remove_schedule(self, job_id: str) -> None:
+ """Remove a job from APScheduler.
+
+ Args:
+ job_id (`str`):
+ The APScheduler job ID to remove.
+ """
+ from apscheduler.jobstores.base import JobLookupError
+
+ logger.info("Removing schedule job %s", job_id)
+ try:
+ self._scheduler.remove_job(job_id)
+ logger.info("Schedule job %s removed", job_id)
+ except JobLookupError:
+ logger.warning("Schedule job %s not found in APScheduler", job_id)
+
+ async def restore(self, records: list[ScheduleRecord]) -> None:
+ """Re-register persisted schedules on service startup.
+
+ Only enabled schedules are restored.
+
+ Args:
+ records (`list[ScheduleRecord]`):
+ All schedule records loaded from storage on startup.
+ """
+ enabled = [r for r in records if r.data.enabled]
+ logger.info(
+ "Restoring schedules: %d total, %d enabled",
+ len(records),
+ len(enabled),
+ )
+ for record in enabled:
+ await self.register_schedule(record)
+ logger.info("Schedule restore complete")
+
+ async def list_tasks(self) -> list[dict]:
+ """Return a summary of all currently registered APScheduler jobs.
+
+ Returns:
+ `list[dict]`:
+ Each entry contains ``id``, ``name``, and ``next_run``.
+ """
+ return [
+ {
+ "id": job.id,
+ "name": job.name,
+ "next_run": job.next_run_time,
+ }
+ for job in self._scheduler.get_jobs()
+ ]
+
+ # ------------------------------------------------------------------
+ # Agent tools
+ # ------------------------------------------------------------------
+
+ async def list_tools(
+ self,
+ user_id: str,
+ agent_id: str,
+ chat_model_config: ChatModelConfig,
+ ) -> list[ToolBase]:
+ """Return the agent-facing tools provided by the scheduler manager.
+
+ Args:
+ user_id (`str`):
+ The authenticated user who owns the schedules.
+ agent_id (`str`):
+ The agent that will be run by newly created schedules.
+ chat_model_config (`ChatModelConfig`):
+ Model configuration inherited from the current session and
+ stored on new :class:`~...ScheduleRecord` objects.
+
+ Returns:
+ `list[ToolBase]`:
+ The four schedule tools: :class:`ScheduleCreate`,
+ :class:`ScheduleView`, :class:`ScheduleStop`, and
+ :class:`ScheduleList`.
+ """
+ return [
+ ScheduleCreate(
+ user_id=user_id,
+ agent_id=agent_id,
+ chat_model_config=chat_model_config,
+ storage=self._storage,
+ scheduler_manager=self,
+ ),
+ ScheduleView(
+ user_id=user_id,
+ scheduler=self._scheduler,
+ storage=self._storage,
+ ),
+ ScheduleStop(
+ user_id=user_id,
+ scheduler=self._scheduler,
+ storage=self._storage,
+ ),
+ ScheduleList(
+ user_id=user_id,
+ scheduler=self._scheduler,
+ storage=self._storage,
+ ),
+ ]
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/__init__.py b/src/agentscope/app/_manager/_scheduler/_tools/__init__.py
new file mode 100644
index 000000000..49015fa04
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/__init__.py
@@ -0,0 +1,14 @@
+# -*- coding: utf-8 -*-
+"""The schedule related tools."""
+
+from ._schedule_create import ScheduleCreate
+from ._schedule_list import ScheduleList
+from ._schedule_stop import ScheduleStop
+from ._schedule_view import ScheduleView
+
+__all__ = [
+ "ScheduleCreate",
+ "ScheduleList",
+ "ScheduleStop",
+ "ScheduleView",
+]
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py
new file mode 100644
index 000000000..9aa20aea0
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_create.py
@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""The schedule create tool."""
+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'.",
+ )
+
+ 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 the current agent. "
+ "The agent will be executed automatically according to the given "
+ "cron expression. Returns the new schedule ID on success."
+ )
+
+ 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 register the APScheduler job.
+ Must expose a ``register_schedule(record)`` 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",
+ 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'``.
+ 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,
+ cron_expression=cron_expression,
+ timezone=timezone,
+ stateful=stateful,
+ permission_mode=perm_mode,
+ source=ScheduleSource.AGENT,
+ source_session_id=source_session_id,
+ chat_model_config=self._chat_model_config,
+ ),
+ )
+
+ await self._storage.upsert_schedule(self._user_id, record)
+ await self._scheduler_manager.register_schedule(record)
+
+ 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"Stateful: {stateful}"
+ ),
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ )
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py
new file mode 100644
index 000000000..29bce5dce
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_list.py
@@ -0,0 +1,115 @@
+# -*- 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,
+ )
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_stop.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_stop.py
new file mode 100644
index 000000000..aac8c19cf
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_stop.py
@@ -0,0 +1,132 @@
+# -*- coding: utf-8 -*-
+"""Schedule stop 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 ....storage._base import StorageBase
+
+
+class _ScheduleStopParams(BaseModel):
+ """The params for the schedule stop tool."""
+
+ schedule_id: str = Field(
+ description="The schedule ID to stop (remove).",
+ )
+
+
+class ScheduleStop(ToolBase):
+ """The schedule stop tool.
+
+ Permanently removes the given scheduled job from both the in-memory
+ APScheduler and the persistent storage. The job cannot be recovered
+ after removal.
+ """
+
+ name: str = "ScheduleStop"
+
+ description: str = (
+ "Stop (permanently remove) 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 = _ScheduleStopParams.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,
+ ) -> None:
+ """Initialize the schedule stop 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.
+ """
+ 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]
+ """Stop (remove) the scheduled task with the given ID.
+
+ Args:
+ schedule_id (`str`):
+ The unique identifier of the schedule to stop.
+
+ Returns:
+ `ToolChunk`:
+ A chunk describing the result of the stop 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
+
+ # Delete from persistent storage
+ deleted = await self._storage.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,
+ )
+
+ return ToolChunk(
+ content=[
+ TextBlock(
+ text=(
+ f"Schedule {schedule_id!r} has been stopped "
+ f"and permanently removed."
+ ),
+ ),
+ ],
+ state=ToolResultState.SUCCESS,
+ )
diff --git a/src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py
new file mode 100644
index 000000000..4116a2996
--- /dev/null
+++ b/src/agentscope/app/_manager/_scheduler/_tools/_schedule_view.py
@@ -0,0 +1,138 @@
+# -*- 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,
+ )
diff --git a/src/agentscope/app/_manager/_session_manager.py b/src/agentscope/app/_manager/_session_manager.py
new file mode 100644
index 000000000..9ac8804d0
--- /dev/null
+++ b/src/agentscope/app/_manager/_session_manager.py
@@ -0,0 +1,197 @@
+# -*- coding: utf-8 -*-
+"""The session manager for
+
+- session replay: replaying persisted logs and in-flight buffered outputs
+ to a client that joins a session mid-execution
+- session monitor: tracking which sessions are currently running and
+ serialising concurrent requests for the same session
+"""
+import asyncio
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+
+from ...event import AgentEvent
+
+_SENTINEL = object()
+# Sentinel pushed to subscriber queues to signal end-of-stream.
+
+
+@dataclass
+class _SessionRun:
+ """State for a single in-flight agent run."""
+
+ buffer: list[AgentEvent] = field(default_factory=list)
+ """All events produced so far; used to replay to late-joining clients."""
+
+ subscribers: list[asyncio.Queue] = field(default_factory=list)
+ """One queue per active SSE subscriber; each receives every new event."""
+
+ async def publish(self, event: AgentEvent) -> None:
+ """Append *event* to the replay buffer and fan it out to all
+ subscribers.
+
+ Args:
+ event (`AgentEvent`):
+ The event to publish.
+ """
+ self.buffer.append(event)
+ for q in self.subscribers:
+ await q.put(event)
+
+ async def close_subscribers(self) -> None:
+ """Push the sentinel to every subscriber queue to signal
+ end-of-stream."""
+ for q in self.subscribers:
+ await q.put(_SENTINEL)
+
+
+class SessionManager:
+ """Manages in-flight agent runs per session.
+
+ Responsibilities:
+
+ - **Serialisation**: at most one active run per ``session_id`` at a time;
+ additional callers queue on an ``asyncio.Lock`` and run in order.
+ - **Fan-out buffer**: every event produced during a run is appended to a
+ replay buffer *and* pushed to all active SSE subscriber queues so that
+ clients joining mid-run receive the full event history.
+ - **Lifecycle**: the buffer and subscriber list are created when a run
+ starts and discarded when it ends, keeping memory bounded.
+ """
+
+ def __init__(self) -> None:
+ """Initialise the session manager."""
+ self._locks: dict[str, asyncio.Lock] = {}
+ self._runs: dict[str, _SessionRun] = {}
+
+ # ------------------------------------------------------------------
+ # Internal helpers
+ # ------------------------------------------------------------------
+
+ def _get_lock(self, session_id: str) -> asyncio.Lock:
+ """Return (creating if necessary) the per-session serialisation
+ lock."""
+ if session_id not in self._locks:
+ self._locks[session_id] = asyncio.Lock()
+ return self._locks[session_id]
+
+ # ------------------------------------------------------------------
+ # Producer API (used by the chat endpoint)
+ # ------------------------------------------------------------------
+
+ @asynccontextmanager
+ async def run(self, session_id: str) -> AsyncGenerator[_SessionRun, None]:
+ """Async context manager that serialises runs for *session_id*.
+
+ Acquires the per-session lock (queuing if another run is active),
+ creates a fresh :class:`_SessionRun`, and tears it down on exit.
+
+ Usage::
+
+ async with session_manager.run(session_id) as run:
+ async for event in agent.reply(msg):
+ await run.publish(event)
+ yield f"data: {event.model_dump_json()}\\n\\n"
+
+ Args:
+ session_id (`str`): The session to run against.
+
+ Yields:
+ `_SessionRun`: The active run object;
+ call :meth:`_SessionRun.publish` to broadcast each event.
+ """
+ lock = self._get_lock(session_id)
+ async with lock:
+ session_run = _SessionRun()
+ self._runs[session_id] = session_run
+ try:
+ yield session_run
+ finally:
+ await session_run.close_subscribers()
+ self._runs.pop(session_id, None)
+
+ # ------------------------------------------------------------------
+ # Consumer API (used by the stream endpoint)
+ # ------------------------------------------------------------------
+
+ def is_running(self, session_id: str) -> bool:
+ """Return ``True`` if *session_id* has an active run.
+
+ Args:
+ session_id (`str`): The session to check.
+
+ Returns:
+ `bool`: Whether a run is currently active.
+ """
+ return session_id in self._runs
+
+ def get_buffered_events(self, session_id: str) -> list[AgentEvent]:
+ """Return a snapshot of all events buffered for the active run.
+
+ Used by the stream endpoint to replay events to clients that join
+ mid-execution.
+
+ Args:
+ session_id (`str`): The session to query.
+
+ Returns:
+ `list[AgentEvent]`: Copy of buffered events, or empty list if
+ no active run.
+ """
+ run = self._runs.get(session_id)
+ return list(run.buffer) if run else []
+
+ async def subscribe(
+ self,
+ session_id: str,
+ ) -> AsyncGenerator[AgentEvent, None]:
+ """Async generator that yields all events for an active run.
+
+ Replays events already in the buffer, then streams new events as they
+ arrive. Yields nothing if *session_id* has no active run.
+
+ The replay/subscribe handoff is race-free: the subscriber queue is
+ registered *before* the buffer snapshot is taken, so no event can be
+ missed between the two steps (asyncio is single-threaded; no ``await``
+ separates the two operations).
+
+ Args:
+ session_id (`str`): The session to subscribe to.
+
+ Yields:
+ `AgentEvent`: Events in arrival order.
+ """
+ run = self._runs.get(session_id)
+ if run is None:
+ return
+
+ queue: asyncio.Queue = asyncio.Queue()
+ # Register BEFORE snapshotting the buffer length so that events
+ # added after this point go to the queue, not the buffer only.
+ run.subscribers.append(queue)
+ replay_until = len(run.buffer)
+
+ # Replay events that existed before we subscribed.
+ for event in run.buffer[:replay_until]:
+ yield event
+
+ # Stream events produced after we subscribed.
+ while True:
+ item = await queue.get()
+ if item is _SENTINEL:
+ break
+ yield item
+
+ # ------------------------------------------------------------------
+ # Lifecycle
+ # ------------------------------------------------------------------
+
+ def cancel(self) -> None:
+ """Cancel all active runs on application shutdown.
+
+ Clears internal state; in-flight SSE generators will receive
+ ``StopAsyncIteration`` when their queues are garbage-collected.
+ """
+ self._runs.clear()
+ self._locks.clear()
diff --git a/src/agentscope/app/_manager/_workspace_manager.py b/src/agentscope/app/_manager/_workspace_manager.py
new file mode 100644
index 000000000..d16ba1247
--- /dev/null
+++ b/src/agentscope/app/_manager/_workspace_manager.py
@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""Workspace manager implementations."""
+import asyncio
+import os
+import time
+from abc import ABC, abstractmethod
+
+from ...workspace import WorkspaceBase, LocalWorkspace
+
+
+class WorkspaceManagerBase(ABC):
+ """Abstract base for workspace managers."""
+
+ @abstractmethod
+ async def get_workspace(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ workspace_id: str,
+ ) -> WorkspaceBase:
+ """Return an initialized workspace.
+
+ Args:
+ user_id: The user id.
+ agent_id: The agent id.
+ session_id: The session id.
+ workspace_id: The workspace id (reconnection credential).
+ """
+
+ @abstractmethod
+ async def create_workspace(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> WorkspaceBase:
+ """Create a new workspace and return it."""
+
+ @abstractmethod
+ async def close(self, workspace_id: str) -> None:
+ """Close and evict a single workspace from the cache."""
+
+ @abstractmethod
+ async def close_all(self) -> None:
+ """Close all cached workspaces (called on app shutdown)."""
+
+
+class LocalWorkspaceManager(WorkspaceManagerBase):
+ """Manages LocalWorkspace instances with TTL-based lazy lifecycle.
+
+ Workspaces are keyed by ``workspace_id`` in the cache. On cache miss
+ the manager reconstructs the workspace from ``basedir/agent_id`` — the
+ workdir is deterministic for local workspaces so no storage lookup is
+ needed.
+
+ Args:
+ basedir: Root directory under which per-agent workdirs are created.
+ default_mcps: MCP clients seeded into brand-new workspaces.
+ skill_paths: Skill directories seeded into brand-new workspaces.
+ ttl: Seconds before an idle cached workspace is evicted.
+ """
+
+ def __init__(
+ self,
+ basedir: str,
+ default_mcps: list | None = None,
+ skill_paths: list[str] | None = None,
+ ttl: float = 3600.0,
+ ) -> None:
+ self._basedir = os.path.abspath(basedir)
+ self._default_mcps = default_mcps or []
+ self._skill_paths = skill_paths or []
+ self._ttl = ttl
+ # workspace_id → (workspace, last_access_monotonic)
+ self._cache: dict[str, tuple[LocalWorkspace, float]] = {}
+ self._lock = asyncio.Lock()
+
+ def _evict_expired(self, now: float) -> list[LocalWorkspace]:
+ expired_ids = [
+ wid for wid, (_, ts) in self._cache.items() if now - ts > self._ttl
+ ]
+ evicted = []
+ for wid in expired_ids:
+ ws, _ = self._cache.pop(wid)
+ evicted.append(ws)
+ return evicted
+
+ async def get_workspace(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ workspace_id: str,
+ ) -> LocalWorkspace:
+ """Return an initialized workspace, reconstructing from
+ disk on cache miss."""
+ async with self._lock:
+ now = time.monotonic()
+ for ws in self._evict_expired(now):
+ await ws.close()
+
+ if workspace_id in self._cache:
+ ws, _ = self._cache[workspace_id]
+ self._cache[workspace_id] = (ws, now)
+ return ws
+
+ # Workdir is deterministic for local workspaces — no storage needed
+ workdir = os.path.join(self._basedir, agent_id)
+ ws = LocalWorkspace(workdir=workdir, skill_paths=self._skill_paths)
+ await ws.initialize()
+ self._cache[workspace_id] = (ws, now)
+ return ws
+
+ async def create_workspace(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> LocalWorkspace:
+ """Create a new workspace for the given agent and return it."""
+ async with self._lock:
+ workdir = os.path.join(self._basedir, agent_id)
+ os.makedirs(workdir, exist_ok=True)
+ ws = LocalWorkspace(
+ workdir=workdir,
+ default_mcps=self._default_mcps,
+ skill_paths=self._skill_paths,
+ )
+ await ws.initialize()
+ self._cache[ws.id] = (ws, time.monotonic())
+ return ws
+
+ async def close(self, workspace_id: str) -> None:
+ """Close and evict a single workspace from the cache."""
+ async with self._lock:
+ if workspace_id in self._cache:
+ ws, _ = self._cache.pop(workspace_id)
+ await ws.close()
+
+ async def close_all(self) -> None:
+ """Close all cached workspaces."""
+ async with self._lock:
+ for ws, _ in self._cache.values():
+ await ws.close()
+ self._cache.clear()
diff --git a/src/agentscope/app/_middleware/__init__.py b/src/agentscope/app/_middleware/__init__.py
new file mode 100644
index 000000000..c34b4aa20
--- /dev/null
+++ b/src/agentscope/app/_middleware/__init__.py
@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+"""The middlewares module."""
+
+from ._protocol import ProtocolMiddlewareBase, AGUIProtocolMiddleware
+from ._tool_offload_middleware import ToolOffloadMiddleware
+
+
+__all__ = [
+ "ProtocolMiddlewareBase",
+ "AGUIProtocolMiddleware",
+ "ToolOffloadMiddleware",
+]
diff --git a/src/agentscope/app/_middleware/_protocol/__init__.py b/src/agentscope/app/_middleware/_protocol/__init__.py
new file mode 100644
index 000000000..0a2fda589
--- /dev/null
+++ b/src/agentscope/app/_middleware/_protocol/__init__.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8 -*-
+"""The middleware used for agent protocol."""
+
+from ._base import ProtocolMiddlewareBase
+from ._agui import AGUIProtocolMiddleware
+
+__all__ = [
+ "ProtocolMiddlewareBase",
+ "AGUIProtocolMiddleware",
+]
diff --git a/src/agentscope/app/_middleware/_protocol/_agui.py b/src/agentscope/app/_middleware/_protocol/_agui.py
new file mode 100644
index 000000000..48730ca5f
--- /dev/null
+++ b/src/agentscope/app/_middleware/_protocol/_agui.py
@@ -0,0 +1,257 @@
+# -*- coding: utf-8 -*-
+"""The AGUI middleware class."""
+from typing import TYPE_CHECKING, Any
+
+from starlette.types import ASGIApp
+
+from ._base import ProtocolMiddlewareBase
+from ....event import (
+ AgentEvent,
+ DataBlockDeltaEvent,
+ DataBlockEndEvent,
+ DataBlockStartEvent,
+ ExceedMaxItersEvent,
+ ExternalExecutionResultEvent,
+ ModelCallEndEvent,
+ ModelCallStartEvent,
+ ReplyEndEvent,
+ ReplyStartEvent,
+ RequireExternalExecutionEvent,
+ RequireUserConfirmEvent,
+ TextBlockDeltaEvent,
+ TextBlockEndEvent,
+ TextBlockStartEvent,
+ ThinkingBlockDeltaEvent,
+ ThinkingBlockEndEvent,
+ ThinkingBlockStartEvent,
+ ToolCallDeltaEvent,
+ ToolCallEndEvent,
+ ToolCallStartEvent,
+ ToolResultDataDeltaEvent,
+ ToolResultEndEvent,
+ ToolResultStartEvent,
+ ToolResultTextDeltaEvent,
+ UserConfirmResultEvent,
+)
+
+if TYPE_CHECKING:
+ from ag_ui.core.events import BaseEvent as AGUIBaseEvent
+else:
+ AGUIBaseEvent = Any
+
+
+class AGUIProtocolMiddleware(ProtocolMiddlewareBase):
+ """The middleware that converts the AgentScope events into AGUI
+ protocol."""
+
+ def __init__(self, app: ASGIApp) -> None:
+ """Initialize the AGUI protocol middleware.
+
+ Args:
+ app: The ASGI application to wrap.
+ """
+ super().__init__(app)
+ # Per-instance state; safe under typical single-stream usage
+ # but not across concurrent requests. Use contextvars if
+ # concurrency is needed.
+ self._last_model_name: str = "model_call"
+ self._tool_result_buffers: dict[str, list[str]] = {}
+
+ def _convert_to_protocol(self, event: AgentEvent) -> dict:
+ """Convert the AgentScope events into AGUI protocol."""
+ agui_event = self._to_agui_event(event)
+ return agui_event.model_dump(
+ mode="json",
+ exclude_none=True,
+ by_alias=True,
+ )
+
+ # pylint: disable=too-many-return-statements
+ def _to_agui_event( # noqa: C901
+ self,
+ event: AgentEvent,
+ ) -> "AGUIBaseEvent":
+ """Convert an AgentScope event to an AGUI event."""
+
+ from ag_ui.core.events import (
+ CustomEvent as AGUICustomEvent,
+ ReasoningMessageContentEvent as AGUIReasoningMessageContentEvent,
+ ReasoningMessageEndEvent as AGUIReasoningMessageEndEvent,
+ ReasoningMessageStartEvent as AGUIReasoningMessageStartEvent,
+ RunErrorEvent as AGUIRunErrorEvent,
+ RunFinishedEvent as AGUIRunFinishedEvent,
+ RunStartedEvent as AGUIRunStartedEvent,
+ StepFinishedEvent as AGUIStepFinishedEvent,
+ StepStartedEvent as AGUIStepStartedEvent,
+ TextMessageContentEvent as AGUITextMessageContentEvent,
+ TextMessageEndEvent as AGUITextMessageEndEvent,
+ TextMessageStartEvent as AGUITextMessageStartEvent,
+ ToolCallArgsEvent as AGUIToolCallArgsEvent,
+ ToolCallEndEvent as AGUIToolCallEndEvent,
+ ToolCallResultEvent as AGUIToolCallResultEvent,
+ ToolCallStartEvent as AGUIToolCallStartEvent,
+ )
+
+ if isinstance(event, ReplyStartEvent):
+ return AGUIRunStartedEvent(
+ thread_id=event.session_id,
+ run_id=event.reply_id,
+ )
+
+ if isinstance(event, ReplyEndEvent):
+ return AGUIRunFinishedEvent(
+ thread_id=event.session_id,
+ run_id=event.reply_id,
+ )
+
+ if isinstance(event, ExceedMaxItersEvent):
+ return AGUIRunErrorEvent(
+ message=(f"Agent '{event.name}' exceeded max iterations"),
+ code="exceed_max_iters",
+ )
+
+ if isinstance(event, ModelCallStartEvent):
+ self._last_model_name = event.model_name
+ return AGUIStepStartedEvent(
+ step_name=event.model_name,
+ )
+
+ if isinstance(event, ModelCallEndEvent):
+ return AGUIStepFinishedEvent(
+ step_name=self._last_model_name,
+ )
+
+ if isinstance(event, TextBlockStartEvent):
+ return AGUITextMessageStartEvent(
+ message_id=event.block_id,
+ )
+
+ if isinstance(event, TextBlockDeltaEvent):
+ return AGUITextMessageContentEvent(
+ message_id=event.block_id,
+ delta=event.delta,
+ )
+
+ if isinstance(event, TextBlockEndEvent):
+ return AGUITextMessageEndEvent(
+ message_id=event.block_id,
+ )
+
+ # AGUI has a two-level reasoning structure (ReasoningStart/End wrapping
+ # ReasoningMessage*), but _convert_to_protocol returns a single dict
+ # per input event, so only the inner ReasoningMessage* events are
+ # emitted. Most AGUI consumers render correctly with message-level
+ # events alone.
+ if isinstance(event, ThinkingBlockStartEvent):
+ return AGUIReasoningMessageStartEvent(
+ message_id=event.block_id,
+ role="reasoning",
+ )
+
+ if isinstance(event, ThinkingBlockDeltaEvent):
+ return AGUIReasoningMessageContentEvent(
+ message_id=event.block_id,
+ delta=event.delta,
+ )
+
+ if isinstance(event, ThinkingBlockEndEvent):
+ return AGUIReasoningMessageEndEvent(
+ message_id=event.block_id,
+ )
+
+ if isinstance(event, ToolCallStartEvent):
+ return AGUIToolCallStartEvent(
+ tool_call_id=event.tool_call_id,
+ tool_call_name=event.tool_call_name,
+ parent_message_id=event.reply_id,
+ )
+
+ if isinstance(event, ToolCallDeltaEvent):
+ return AGUIToolCallArgsEvent(
+ tool_call_id=event.tool_call_id,
+ delta=event.delta,
+ )
+
+ if isinstance(event, ToolCallEndEvent):
+ return AGUIToolCallEndEvent(
+ tool_call_id=event.tool_call_id,
+ )
+
+ if isinstance(event, ToolResultStartEvent):
+ return AGUICustomEvent(
+ name="tool_result_start",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, ToolResultTextDeltaEvent):
+ self._tool_result_buffers.setdefault(
+ event.tool_call_id,
+ [],
+ ).append(event.delta)
+ return AGUICustomEvent(
+ name="tool_result_text_delta",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, ToolResultDataDeltaEvent):
+ return AGUICustomEvent(
+ name="tool_result_data_delta",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, ToolResultEndEvent):
+ content = "".join(
+ self._tool_result_buffers.pop(event.tool_call_id, []),
+ )
+ return AGUIToolCallResultEvent(
+ tool_call_id=event.tool_call_id,
+ message_id=event.reply_id,
+ content=content or str(event.state),
+ )
+
+ if isinstance(event, DataBlockStartEvent):
+ return AGUICustomEvent(
+ name="data_block_start",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, DataBlockDeltaEvent):
+ return AGUICustomEvent(
+ name="data_block_delta",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, DataBlockEndEvent):
+ return AGUICustomEvent(
+ name="data_block_end",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, RequireUserConfirmEvent):
+ return AGUICustomEvent(
+ name="require_user_confirm",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, RequireExternalExecutionEvent):
+ return AGUICustomEvent(
+ name="require_external_execution",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, UserConfirmResultEvent):
+ return AGUICustomEvent(
+ name="user_confirm_result",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ if isinstance(event, ExternalExecutionResultEvent):
+ return AGUICustomEvent(
+ name="external_execution_result",
+ value=event.model_dump(exclude_none=True),
+ )
+
+ return AGUICustomEvent(
+ name="unknown",
+ value=event.model_dump(exclude_none=True),
+ )
diff --git a/src/agentscope/app/_middleware/_protocol/_base.py b/src/agentscope/app/_middleware/_protocol/_base.py
new file mode 100644
index 000000000..be093bd8b
--- /dev/null
+++ b/src/agentscope/app/_middleware/_protocol/_base.py
@@ -0,0 +1,169 @@
+# -*- coding: utf-8 -*-
+"""Protocol middleware base class for converting AgentEvent stream to
+various protocols."""
+import json
+from abc import ABC, abstractmethod
+from typing import AsyncGenerator, Callable
+
+from fastapi import Request, Response
+from fastapi.responses import StreamingResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+from agentscope.event import AgentEvent
+
+
+class ProtocolMiddlewareBase(BaseHTTPMiddleware, ABC):
+ """Base middleware for converting AgentEvent stream to protocol format.
+
+ This middleware intercepts streaming responses that yield AgentEvent
+ objects, deserializes them, and converts them to a specific protocol
+ format.
+
+ Subclasses should implement the `_convert_to_protocol` method to define
+ the conversion logic for their specific protocol (e.g., AGUI, A2A).
+
+ Example:
+ ```python
+ class AGUIMiddleware(ProtocolMiddlewareBase):
+ def _convert_to_protocol(self, event: AgentEvent) -> dict:
+ # Implement AGUI-specific conversion logic
+ return {...}
+
+ app = FastAPI()
+ app.add_middleware(AGUIMiddleware)
+ ```
+ """
+
+ def __init__(self, app: ASGIApp) -> None:
+ """Initialize the protocol middleware.
+
+ Args:
+ app: The ASGI application to wrap.
+ """
+ super().__init__(app)
+
+ async def dispatch(
+ self,
+ request: Request,
+ call_next: Callable,
+ ) -> Response:
+ """Process the request and convert AgentEvent stream to protocol
+ format.
+
+ Args:
+ request: The incoming HTTP request.
+ call_next: The next middleware or endpoint handler.
+
+ Returns:
+ The response, potentially with converted stream content.
+ """
+ # Call the next middleware or endpoint
+ response = await call_next(request)
+
+ # Check if the response is a streaming response
+ if isinstance(response, StreamingResponse):
+ # Wrap the original stream with our conversion logic
+ original_stream = response.body_iterator
+ converted_stream = self._convert_stream(original_stream)
+
+ # Create a new StreamingResponse with the converted stream
+ return StreamingResponse(
+ content=converted_stream,
+ status_code=response.status_code,
+ headers=dict(response.headers),
+ media_type=response.media_type,
+ )
+
+ return response
+
+ async def _convert_stream(
+ self,
+ original_stream: AsyncGenerator,
+ ) -> AsyncGenerator[bytes, None]:
+ """Convert AgentEvent stream to protocol format.
+
+ Args:
+ original_stream: The original stream yielding serialized
+ AgentEvent objects.
+
+ Yields:
+ Bytes in protocol format.
+ """
+ async for chunk in original_stream:
+ # Decode the chunk if it's bytes
+ if isinstance(chunk, bytes):
+ chunk_str = chunk.decode("utf-8")
+ else:
+ chunk_str = chunk
+
+ # Try to deserialize the chunk as AgentEvent
+ try:
+ # Parse the JSON string to dict
+ event_dict = json.loads(chunk_str)
+
+ # Deserialize to AgentEvent based on the 'type' field
+ agent_event = self._deserialize_event(event_dict)
+
+ # Convert AgentEvent to protocol format
+ protocol_data = self._convert_to_protocol(agent_event)
+
+ # Serialize and yield the protocol data
+ yield json.dumps(protocol_data, ensure_ascii=False).encode(
+ "utf-8",
+ ) + b"\n"
+
+ except (json.JSONDecodeError, KeyError, ValueError):
+ # If deserialization fails, pass through the original chunk
+ # or log the error
+ # For now, we'll pass through the original chunk
+ if isinstance(chunk, bytes):
+ yield chunk
+ else:
+ yield chunk.encode("utf-8")
+
+ def _deserialize_event(self, event_dict: dict) -> AgentEvent:
+ """Deserialize event dictionary to AgentEvent object.
+
+ Args:
+ event_dict: Dictionary containing event data with 'type' field.
+
+ Returns:
+ Deserialized AgentEvent object.
+
+ Raises:
+ ValueError: If event type is unknown or deserialization fails.
+ """
+ from pydantic import Field, TypeAdapter
+ from typing import Annotated
+
+ # Use Pydantic's discriminated union to automatically deserialize
+ # based on the 'type' field
+ adapter = TypeAdapter(
+ Annotated[AgentEvent, Field(discriminator="type")],
+ )
+ return adapter.validate_python(event_dict)
+
+ @abstractmethod
+ def _convert_to_protocol(self, event: AgentEvent) -> dict:
+ """Convert AgentEvent to protocol format.
+
+ This is an abstract method that must be implemented by subclasses
+ to define the conversion logic for their specific protocol.
+
+ Args:
+ event: The AgentEvent object to convert.
+
+ Returns:
+ Dictionary in the target protocol format.
+
+ Example:
+ ```python
+ class AGUIMiddleware(ProtocolMiddlewareBase):
+ def _convert_to_protocol(self, event: AgentEvent) -> dict:
+ # Convert to AGUI format
+ agui_data = event.model_dump()
+ agui_data["agui_version"] = "1.0"
+ return agui_data
+ ```
+ """
diff --git a/src/agentscope/app/_middleware/_tool_offload_middleware.py b/src/agentscope/app/_middleware/_tool_offload_middleware.py
new file mode 100644
index 000000000..955f64ea6
--- /dev/null
+++ b/src/agentscope/app/_middleware/_tool_offload_middleware.py
@@ -0,0 +1,414 @@
+# -*- coding: utf-8 -*-
+"""Middleware that offloads long-running tool calls to background tasks and
+injects their results back into the agent context before the next reasoning
+step.
+"""
+import asyncio
+from typing import Any, AsyncGenerator, Callable
+
+from ...middleware import MiddlewareBase
+from ...tool import ToolChunk, ToolResponse
+from ...message import AssistantMsg, HintBlock, TextBlock, ToolResultState
+from ...agent import Agent
+from .._manager import BackgroundTaskManager
+from ..._logging import logger
+
+
+# Sentinel object used to signal end-of-stream in the drain queue.
+_QUEUE_SENTINEL = object()
+
+
+class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-method
+ """Middleware that offloads timed-out tool calls to background tasks.
+
+ When a tool execution exceeds ``timeout_secs`` this middleware:
+
+ 1. Lets the underlying :mod:`asyncio` task keep running in the
+ background via :class:`~agentscope.app.BackgroundTaskManager`.
+ The task is **never cancelled**.
+ 2. Returns a synthetic :class:`~agentscope.tool.ToolResponse` to the
+ agent immediately so the ReAct loop can continue without blocking.
+ 3. When the background task finishes the real tool result is pushed
+ into :class:`~agentscope.app.BackgroundTaskManager` result storage.
+ 4. Before the next :meth:`on_reasoning` call the pending results are
+ pulled from the manager and injected into ``agent.state.context``
+ so the model is informed of the completed background result.
+
+ .. note::
+ Tools with ``is_state_injected=True`` receive the live
+ ``agent.state`` object. Offloading such tools to a background
+ task may cause concurrent state mutations and is therefore
+ **blocked** — they are always executed synchronously.
+
+ .. code-block:: python
+
+ from agentscope.app import BackgroundTaskManager, ToolOffloadMiddleware
+
+ bg_manager = BackgroundTaskManager()
+ middleware = ToolOffloadMiddleware(
+ bg_manager=bg_manager,
+ timeout_secs=15.0
+ )
+
+ agent = Agent(
+ ...,
+ middlewares=[middleware],
+ )
+
+ Args:
+ bg_manager (`BackgroundTaskManager`):
+ The application-level background task manager shared across
+ all agents and services. Used only for task registration and
+ cancellation via :class:`~agentscope.app.TaskStop`.
+ timeout_secs (`float`, optional):
+ Maximum seconds to wait for a tool execution before offloading
+ it to the background. Defaults to ``15.0``.
+ """
+
+ def __init__(
+ self,
+ bg_manager: "BackgroundTaskManager",
+ timeout_secs: float = 10.0,
+ user_id: str = "",
+ agent_id: str = "",
+ session_manager: Any = None,
+ retrigger_fn: Callable[..., Any] | None = None,
+ ) -> None:
+ """Initialise the middleware.
+
+ Args:
+ bg_manager (`BackgroundTaskManager`):
+ The application-level background task manager.
+ timeout_secs (`float`, optional):
+ Timeout in seconds before a tool call is offloaded.
+ Defaults to ``10.0``.
+ user_id (`str`, optional):
+ The user id for the current request.
+ agent_id (`str`, optional):
+ The agent record ID (not the display name).
+ session_manager:
+ The session manager, used to check if a session is active.
+ retrigger_fn:
+ Async callable ``(session_id, agent_id, user_id) -> None``
+ that triggers a new agent reply when the session is idle.
+ """
+ self._bg_manager = bg_manager
+ self._timeout_secs = timeout_secs
+ self._user_id = user_id
+ self._agent_id = agent_id
+ self._session_manager = session_manager
+ self._retrigger_fn = retrigger_fn
+
+ # ------------------------------------------------------------------
+ # Middleware hooks
+ # ------------------------------------------------------------------
+
+ async def on_reasoning( # type:ignore[override]
+ self,
+ agent: "Agent",
+ input_kwargs: dict,
+ next_handler: Callable[..., AsyncGenerator],
+ ) -> AsyncGenerator:
+ """Inject pending background results before reasoning.
+
+ Pops :class:`~agentscope.message.HintBlock` objects pushed by
+ completed background tasks and appends them to the last assistant
+ message in ``agent.state.context`` (or creates a new one with
+ ``state.reply_id`` if the last message is not from the agent).
+
+ Args:
+ agent (`Agent`):
+ The executing agent.
+ input_kwargs (`dict`):
+ Reasoning input kwargs (contains ``tool_choice``).
+ next_handler (`Callable[..., AsyncGenerator]`):
+ The downstream middleware or core reasoning logic.
+
+ Yields:
+ Events produced by the reasoning process.
+ """
+ hint_blocks = self._bg_manager.pop_results(agent.state.session_id)
+ if hint_blocks:
+ logger.info(
+ "Injecting %d pending background result(s) into context: "
+ "session_id=%s, agent_id=%s",
+ len(hint_blocks),
+ agent.state.session_id,
+ agent.name,
+ )
+ if len(agent.state.context) > 0:
+ last_msg = agent.state.context[-1]
+ if (
+ last_msg.role == "assistant"
+ and last_msg.name == agent.name
+ ):
+ last_msg.content.extend(hint_blocks)
+ else:
+ agent.state.context.append(
+ AssistantMsg(
+ id=agent.state.reply_id,
+ name=agent.name,
+ content=list(hint_blocks),
+ ),
+ )
+ else:
+ agent.state.context.append(
+ AssistantMsg(
+ id=agent.state.reply_id,
+ name=agent.name,
+ content=list(hint_blocks),
+ ),
+ )
+
+ async for evt in next_handler(**input_kwargs):
+ yield evt
+
+ async def on_acting( # type:ignore[override]
+ self,
+ agent: Agent,
+ input_kwargs: dict,
+ next_handler: Callable[..., AsyncGenerator],
+ ) -> AsyncGenerator:
+ """Execute a tool with timeout; offload to background on expiry.
+
+ The inner ``next_handler`` generator is wrapped in an
+ :mod:`asyncio` task whose output is fed through a
+ :class:`asyncio.Queue`. Items are consumed with a rolling
+ deadline. If the deadline fires before the tool finishes:
+
+ - The running task is **not** cancelled.
+ - It is registered with :attr:`_bg_manager` via
+ :meth:`~BackgroundTaskManager.register_task`.
+ - An ``on_complete`` callback (owned by this middleware) drains the
+ queue, builds a ``<system-notification>`` message, and stores it
+ in :attr:`_pending_messages`.
+ - A synthetic :class:`~agentscope.tool.ToolResponse` notifying
+ the agent of the background task id is yielded instead.
+
+ .. note::
+ Tools with ``is_state_injected=True`` or ``is_external_tool=True``
+ bypass this logic and are always executed synchronously.
+
+ Args:
+ agent (`Agent`):
+ The executing agent.
+ input_kwargs (`dict`):
+ Acting input kwargs (contains ``tool_call``).
+ next_handler (`Callable[..., AsyncGenerator]`):
+ The downstream middleware or ``_acting_impl``.
+
+ Yields:
+ `ToolChunk | ToolResponse`:
+ Normal results when the tool finishes in time, or a
+ synthetic ``ToolResponse`` when offloaded.
+ """
+ tool_call = input_kwargs["tool_call"]
+
+ # ----------------------------------------------------------------
+ # Guard: state-injected tools and external tools are never offloaded.
+ # - is_state_injected: the tool receives the live agent.state object;
+ # running it concurrently in a background task could cause race
+ # conditions on agent.state. For now, we fall back to synchronous
+ # execution. Once background tasks can be given an isolated state
+ # snapshot this guard should become a hard RuntimeError instead.
+ # - is_external_tool: external tools wait for a human/external system
+ # to push a result back; offloading them makes no sense because the
+ # agent would lose track of the pending confirmation.
+ registered = agent.toolkit.tools.get(tool_call.name)
+ if registered is not None and (
+ registered.tool.is_state_injected
+ or registered.tool.is_external_tool
+ ):
+ logger.info(
+ "Tool '%s' is state-injected or external, executing "
+ "synchronously: session_id=%s, agent_id=%s",
+ tool_call.name,
+ agent.state.session_id,
+ agent.name,
+ )
+ async for item in next_handler(**input_kwargs):
+ yield item
+ return
+
+ # ----------------------------------------------------------------
+ # Wrap next_handler in a Task, draining output into a Queue
+ # ----------------------------------------------------------------
+ queue: asyncio.Queue = asyncio.Queue()
+
+ async def _drain_to_queue() -> None:
+ """Drain next_handler output into *queue*."""
+ try:
+ async for item in next_handler(**input_kwargs):
+ await queue.put(item)
+ except Exception as exc: # pylint: disable=broad-except
+ await queue.put(exc)
+ finally:
+ await queue.put(_QUEUE_SENTINEL)
+
+ drain_task: asyncio.Task = asyncio.create_task(_drain_to_queue())
+
+ # ----------------------------------------------------------------
+ # Consume items until the deadline or normal completion
+ # ----------------------------------------------------------------
+ loop = asyncio.get_event_loop()
+ deadline = loop.time() + self._timeout_secs
+ pre_collected: list = []
+ completed = False
+
+ while True:
+ remaining = deadline - loop.time()
+ if remaining <= 0:
+ break
+
+ try:
+ item = await asyncio.wait_for(
+ queue.get(),
+ timeout=remaining,
+ )
+ except asyncio.TimeoutError:
+ break
+
+ if item is _QUEUE_SENTINEL:
+ completed = True
+ break
+
+ if isinstance(item, BaseException):
+ drain_task.cancel()
+ raise item
+
+ pre_collected.append(item)
+
+ # ToolResponse is always the terminal item from _acting_impl
+ if isinstance(item, ToolResponse):
+ completed = True
+ break
+
+ if completed:
+ for item in pre_collected:
+ yield item
+ drain_task.cancel()
+ return
+
+ # ----------------------------------------------------------------
+ # Timeout path: build on_complete callback, register, yield synthetic
+ # ----------------------------------------------------------------
+ session_id = agent.state.session_id
+ tool_name = tool_call.name
+ snapshot = list(pre_collected)
+
+ logger.info(
+ "Tool '%s' timed out after %.1fs, offloading to background: "
+ "session_id=%s, agent_id=%s",
+ tool_name,
+ self._timeout_secs,
+ session_id,
+ agent.name,
+ )
+
+ async def _on_complete() -> None:
+ """Drain remaining queue items and push notification message."""
+ remaining_items: list = []
+ while not queue.empty():
+ try:
+ item = queue.get_nowait()
+ if isinstance(item, ToolResponse):
+ remaining_items.append(item)
+ break
+ except asyncio.QueueEmpty:
+ break
+
+ all_items = snapshot + remaining_items
+ response: ToolResponse | None = next(
+ (i for i in all_items if isinstance(i, ToolResponse)),
+ None,
+ )
+
+ if response is not None:
+ texts = [
+ b.text
+ for b in response.content
+ if isinstance(b, TextBlock)
+ ]
+ result_text = "\n".join(texts)
+ hint_text = (
+ f"<system-notification>\n"
+ f"Background task for tool '{tool_name}' has completed.\n"
+ f"Result:\n{result_text}\n"
+ f"</system-notification>"
+ )
+ else:
+ hint_text = (
+ f"<system-notification>\n"
+ f"Background task for tool '{tool_name}' has completed "
+ f"with no result.\n"
+ f"</system-notification>"
+ )
+
+ logger.info(
+ "Background tool '%s' completed, pushing result to pending "
+ "hints: session_id=%s",
+ tool_name,
+ session_id,
+ )
+ self._bg_manager.push_result(
+ session_id,
+ HintBlock(hint=hint_text),
+ )
+
+ # Re-trigger the agent if the session is idle
+ if (
+ self._session_manager is not None
+ and self._retrigger_fn is not None
+ and not self._session_manager.is_running(session_id)
+ ):
+ logger.info(
+ "Session idle after background tool '%s' completed, "
+ "triggering re-invocation: session_id=%s, agent_id=%s",
+ tool_name,
+ session_id,
+ self._agent_id,
+ )
+ asyncio.create_task(
+ self._retrigger_fn(
+ session_id,
+ self._agent_id,
+ self._user_id,
+ ),
+ )
+
+ task_id = await self._bg_manager.register_task(
+ asyncio_task=drain_task,
+ session_id=session_id,
+ agent_id=self._agent_id,
+ user_id=self._user_id,
+ on_complete=_on_complete,
+ )
+
+ logger.info(
+ "Synthetic ToolResponse yielded for offloaded tool '%s': "
+ "task_id=%s, session_id=%s, agent_id=%s",
+ tool_name,
+ task_id,
+ session_id,
+ agent.name,
+ )
+
+ placeholder_text = (
+ f"<system-reminder>Tool '{tool_name}' is taking "
+ f"longer than expected and has been moved to the "
+ f"background (task_id={task_id}). "
+ f"You may continue with other tasks. "
+ f"The result will be injected into the context "
+ f"automatically when finished.</system-reminder>"
+ )
+
+ yield ToolChunk(
+ content=[TextBlock(text=placeholder_text)],
+ state=ToolResultState.SUCCESS,
+ )
+
+ yield ToolResponse(
+ content=[TextBlock(text=placeholder_text)],
+ state=ToolResultState.SUCCESS,
+ id=tool_call.id,
+ )
diff --git a/src/agentscope/app/_router/__init__.py b/src/agentscope/app/_router/__init__.py
new file mode 100644
index 000000000..358a5fcf4
--- /dev/null
+++ b/src/agentscope/app/_router/__init__.py
@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""App routers."""
+from ._agent import agent_router
+from ._background_task import background_task_router
+from ._chat import chat_router
+from ._credential import credential_router
+from ._schedule import schedule_router
+from ._session import session_router
+from ._model import model_router
+from ._workspace import workspace_router
+
+__all__ = [
+ "agent_router",
+ "background_task_router",
+ "model_router",
+ "chat_router",
+ "credential_router",
+ "schedule_router",
+ "session_router",
+ "workspace_router",
+]
diff --git a/src/agentscope/app/_router/_agent.py b/src/agentscope/app/_router/_agent.py
new file mode 100644
index 000000000..3c3f70cca
--- /dev/null
+++ b/src/agentscope/app/_router/_agent.py
@@ -0,0 +1,158 @@
+# -*- coding: utf-8 -*-
+"""Agent router — CRUD endpoints for agent configurations."""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .._deps import get_current_user_id, get_storage
+from .._schema import (
+ ListAgentsResponse,
+ CreateAgentRequest,
+ CreateAgentResponse,
+ UpdateAgentRequest,
+)
+from ..storage import StorageBase, AgentData, AgentRecord
+
+agent_router = APIRouter(
+ prefix="/agent",
+ tags=["agent"],
+ responses={404: {"description": "Not found"}},
+)
+
+
+@agent_router.get(
+ "/",
+ response_model=ListAgentsResponse,
+ summary="List all agents",
+)
+async def list_agents(
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+) -> ListAgentsResponse:
+ """Return all agent records belonging to the authenticated user.
+
+ Args:
+ user_id (`str`):
+ Injected authenticated user ID.
+ storage (`StorageBase`):
+ Injected storage backend.
+
+ Returns:
+ `ListAgentsResponse`:
+ All agent records and their total count.
+ """
+ agents = await storage.list_agents(user_id)
+ return ListAgentsResponse(agents=agents, total=len(agents))
+
+
+@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.
+ """
+ record = AgentRecord(
+ user_id=user_id,
+ data=AgentData(
+ name=body.name,
+ system_prompt=body.system_prompt,
+ context_config=body.context_config,
+ react_config=body.react_config,
+ ),
+ )
+ agent_id = await storage.upsert_agent(user_id, record)
+ return CreateAgentResponse(agent_id=agent_id)
+
+
+@agent_router.patch(
+ "/{agent_id}",
+ response_model=AgentRecord,
+ 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),
+) -> AgentRecord:
+ """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.
+
+ Returns:
+ `AgentRecord`: The full agent record after the update.
+
+ Raises:
+ `HTTPException`: 404 if the agent does not exist or does not belong
+ to the authenticated user.
+ """
+ agents = await storage.list_agents(user_id)
+ existing = next((a for a in agents if a.id == agent_id), None)
+ if existing is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Agent '{agent_id}' not found.",
+ )
+
+ updates = body.model_dump(exclude_none=True)
+ updated_data = existing.data.model_copy(update=updates)
+ updated_agent = existing.model_copy(
+ update={"data": updated_data, "updated_at": datetime.now()},
+ )
+ await storage.upsert_agent(user_id, updated_agent)
+ return updated_agent
+
+
+@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),
+ storage: StorageBase = Depends(get_storage),
+) -> None:
+ """Permanently delete an agent configuration.
+
+ Args:
+ agent_id (`str`): The agent to delete.
+ user_id (`str`): Injected authenticated user ID.
+ storage (`StorageBase`): Injected storage backend.
+
+ Raises:
+ `HTTPException`: 404 if the agent does not exist or does not belong
+ to the authenticated user.
+ """
+ deleted = await storage.delete_agent(user_id, agent_id)
+ if not deleted:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Agent '{agent_id}' not found.",
+ )
diff --git a/src/agentscope/app/_router/_background_task.py b/src/agentscope/app/_router/_background_task.py
new file mode 100644
index 000000000..413cf4287
--- /dev/null
+++ b/src/agentscope/app/_router/_background_task.py
@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""Background-task router — list and cancel per-session background tasks."""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .._deps import get_background_task_manager, get_current_user_id
+from .._manager import BackgroundTaskManager
+from .._schema import (
+ BackgroundTaskInfo,
+ ListBackgroundTasksResponse,
+)
+
+background_task_router = APIRouter(
+ prefix="/background-tasks",
+ tags=["background-tasks"],
+ responses={404: {"description": "Not found"}},
+)
+
+
+@background_task_router.get(
+ "/{session_id}",
+ response_model=ListBackgroundTasksResponse,
+ summary="List running background tasks for a session",
+)
+async def list_background_tasks(
+ session_id: str,
+ _: str = Depends(get_current_user_id),
+ bg_manager: BackgroundTaskManager = Depends(get_background_task_manager),
+) -> ListBackgroundTasksResponse:
+ """List all currently running background tasks for *session_id*.
+
+ Args:
+ session_id (`str`):
+ The session to query.
+ _ (`str`):
+ The authenticated user ID (unused, required for auth check).
+ bg_manager (`BackgroundTaskManager`):
+ The application-wide background task manager.
+
+ Returns:
+ `ListBackgroundTasksResponse`:
+ Tasks belonging to *session_id* and their total count.
+ """
+ tasks = [
+ BackgroundTaskInfo(
+ task_id=task.id,
+ session_id=task.session_id,
+ agent_id=task.agent_id,
+ )
+ for task in bg_manager.tasks.values()
+ if task.session_id == session_id
+ ]
+ return ListBackgroundTasksResponse(tasks=tasks, total=len(tasks))
+
+
+@background_task_router.delete(
+ "/{session_id}/{task_id}",
+ status_code=status.HTTP_204_NO_CONTENT,
+ summary="Cancel a running background task",
+)
+async def cancel_background_task(
+ session_id: str,
+ task_id: str,
+ _: str = Depends(get_current_user_id),
+ bg_manager: BackgroundTaskManager = Depends(get_background_task_manager),
+) -> None:
+ """Cancel a running background task by *task_id*.
+
+ The underlying asyncio task is cancelled immediately. The
+ ``on_complete`` callback will **not** be invoked, so no result
+ notification is injected into the agent context.
+
+ Args:
+ session_id (`str`):
+ The owning session (used to scope the lookup).
+ task_id (`str`):
+ The task to cancel.
+ _ (`str`):
+ The authenticated user ID (unused, required for auth check).
+ bg_manager (`BackgroundTaskManager`):
+ The application-wide background task manager.
+
+ Raises:
+ `HTTPException`:
+ 404 if *task_id* is not found or does not belong to
+ *session_id*.
+ """
+ task = bg_manager.tasks.get(task_id)
+ if task is None or task.session_id != session_id:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Background task '{task_id}' not found for session "
+ f"'{session_id}'.",
+ )
+
+ bg_manager.tasks.pop(task_id, None)
+ task.asyncio_task.cancel()
diff --git a/src/agentscope/app/_router/_chat.py b/src/agentscope/app/_router/_chat.py
new file mode 100644
index 000000000..26b86c48f
--- /dev/null
+++ b/src/agentscope/app/_router/_chat.py
@@ -0,0 +1,113 @@
+# -*- coding: utf-8 -*-
+"""Chat router providing a streaming SSE chat endpoint."""
+from collections.abc import AsyncGenerator
+
+from fastapi import APIRouter, Depends
+from fastapi.responses import StreamingResponse
+
+from .._deps import (
+ get_current_user_id,
+ get_session_manager,
+ get_storage,
+ get_workspace_manager,
+ get_background_task_manager,
+)
+from .._manager import (
+ SessionManager,
+ WorkspaceManagerBase,
+ BackgroundTaskManager,
+)
+from .._schema import ChatRequest
+from .._service import ChatService
+from ..storage import StorageBase
+
+chat_router = APIRouter(
+ prefix="/chat",
+ tags=["chat"],
+ responses={404: {"description": "Not found"}},
+)
+
+
+async def _stream_events(
+ user_id: str,
+ request: ChatRequest,
+ storage: StorageBase,
+ session_manager: SessionManager,
+ workspace_manager: WorkspaceManagerBase,
+ background_task_manager: BackgroundTaskManager,
+) -> AsyncGenerator[str, None]:
+ """Encode :class:`~agentscope.event.AgentEvent` objects as SSE frames.
+
+ All execution + persistence lives in :class:`ChatService`; this is just
+ the HTTP-side encoder.
+
+ Each yielded string is a complete SSE frame: ``data: <json>\\n\\n``.
+ """
+ service = ChatService(
+ storage=storage,
+ session_manager=session_manager,
+ background_task_manager=background_task_manager,
+ workspace_manager=workspace_manager,
+ )
+ async for event in service.stream_chat(
+ user_id=user_id,
+ session_id=request.session_id,
+ agent_id=request.agent_id,
+ input_msg=request.input,
+ ):
+ yield f"data: {event.model_dump_json()}\n\n"
+
+
+@chat_router.post(
+ "/",
+ summary="Chat with an agent (streaming)",
+ response_description="Server-Sent Events stream of AgentEvent objects",
+)
+async def chat(
+ request: ChatRequest,
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ session_manager: SessionManager = Depends(get_session_manager),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+ background_task_manager: BackgroundTaskManager = Depends(
+ get_background_task_manager,
+ ),
+) -> StreamingResponse:
+ """Send a message to an agent and stream back the reply as SSE events.
+
+ The response is a ``text/event-stream`` where each frame carries a
+ JSON-serialised :class:`~agentscope.event.AgentEvent`.
+
+ Args:
+ request (`ChatRequest`):
+ JSON body with ``agent_id``, ``session_id``, and ``input``.
+ user_id (`str`):
+ Injected user id.
+ storage (`StorageBase`):
+ Injected application storage backend.
+ session_manager (`SessionManager`):
+ Injected session manager.
+ workspace_manager (`WorkspaceManagerBase`):
+ Injected workspace manager.
+ background_task_manager (`BackgroundTaskManager`):
+ Injected background task manager.
+
+ Returns:
+ `StreamingResponse`:
+ SSE stream of AgentEvent frames.
+ """
+ return StreamingResponse(
+ _stream_events(
+ user_id,
+ request,
+ storage,
+ session_manager,
+ workspace_manager,
+ background_task_manager,
+ ),
+ media_type="text/event-stream",
+ headers={
+ "Cache-Control": "no-cache",
+ "X-Accel-Buffering": "no",
+ },
+ )
diff --git a/src/agentscope/app/_router/_credential.py b/src/agentscope/app/_router/_credential.py
new file mode 100644
index 000000000..574269c4e
--- /dev/null
+++ b/src/agentscope/app/_router/_credential.py
@@ -0,0 +1,164 @@
+# -*- coding: utf-8 -*-
+"""Credential router — CRUD endpoints for API key credentials."""
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .._deps import get_current_user_id, get_storage
+from .._schema import (
+ CreateCredentialRequest,
+ CreateCredentialResponse,
+ ListCredentialsResponse,
+ ListCredentialSchemasResponse,
+ UpdateCredentialRequest,
+)
+from ..storage import StorageBase, CredentialRecord
+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),
+ storage: StorageBase = Depends(get_storage),
+) -> ListCredentialsResponse:
+ """Return all credential records belonging to the authenticated user.
+
+ Args:
+ user_id (`str`):
+ Injected authenticated user ID.
+ storage (`StorageBase`):
+ Injected storage backend.
+
+ Returns:
+ `ListCredentialsResponse`:
+ All credential records and their total count.
+ """
+ credentials = await storage.list_credentials(user_id)
+ return ListCredentialsResponse(
+ credentials=credentials,
+ total=len(credentials),
+ )
+
+
+@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=CredentialRecord,
+ 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),
+) -> CredentialRecord:
+ """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.
+
+ Returns:
+ `CredentialRecord`: The updated credential record.
+
+ Raises:
+ `HTTPException`: 404 if the credential does not exist or does not
+ belong to the authenticated user.
+ """
+ credentials = await storage.list_credentials(user_id)
+ existing = next((c for c in credentials if c.id == credential_id), None)
+ if existing is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Credential '{credential_id}' not found.",
+ )
+
+ credential = CredentialFactory.from_dict(body.data)
+ credential.id = credential_id
+ await storage.upsert_credential(user_id, credential)
+ # Re-fetch to return the persisted record with updated timestamps.
+ credentials = await storage.list_credentials(user_id)
+ updated = next(c for c in credentials if c.id == credential_id)
+ return updated
+
+
+@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),
+) -> 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.
+
+ Raises:
+ `HTTPException`: 404 if the credential does not exist or does not
+ belong to the authenticated user.
+ """
+ deleted = await storage.delete_credential(user_id, credential_id)
+ if not deleted:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Credential '{credential_id}' not found.",
+ )
diff --git a/src/agentscope/app/_router/_model.py b/src/agentscope/app/_router/_model.py
new file mode 100644
index 000000000..5a71c2742
--- /dev/null
+++ b/src/agentscope/app/_router/_model.py
@@ -0,0 +1,40 @@
+# -*- 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.get_chat_model_class().list_models()
+ return ListModelsResponse(models=models, total=len(models))
diff --git a/src/agentscope/app/_router/_schedule.py b/src/agentscope/app/_router/_schedule.py
new file mode 100644
index 000000000..ab8fc184a
--- /dev/null
+++ b/src/agentscope/app/_router/_schedule.py
@@ -0,0 +1,231 @@
+# -*- coding: utf-8 -*-
+"""Schedule router — CRUD endpoints for scheduled agent tasks."""
+from datetime import datetime
+
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from .._deps import get_current_user_id, get_scheduler_manager, get_storage
+from .._manager import SchedulerManager
+from .._schema import (
+ CreateScheduleRequest,
+ CreateScheduleResponse,
+ ListSchedulesResponse,
+ ScheduleSessionsResponse,
+ UpdateScheduleRequest,
+)
+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),
+ scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> CreateScheduleResponse:
+ """Create a new schedule and register it with the scheduler.
+
+ Args:
+ body (`CreateScheduleRequest`): Schedule configuration.
+ user_id (`str`): Authenticated user ID.
+ storage (`StorageBase`): Storage instance.
+ scheduler (`SchedulerManager`): Scheduler manager.
+
+ Returns:
+ `CreateScheduleResponse`:
+ The ID of the newly created schedule.
+
+ Raises:
+ `HTTPException`: 404 if the specified agent does not exist.
+ """
+ agents = await storage.list_agents(user_id)
+ if not any(a.id == body.agent_id for a in agents):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Agent '{body.agent_id}' not found.",
+ )
+
+ 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,
+ started_at=datetime.now(),
+ ),
+ )
+ await storage.upsert_schedule(user_id, record)
+
+ if record.data.enabled:
+ await scheduler.register_schedule(record)
+
+ 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`` immediately reschedules the
+ APScheduler job. Setting ``enable=False`` removes the job from the
+ scheduler without deleting the record.
+
+ 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.
+ """
+ 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()},
+ )
+ await storage.upsert_schedule(user_id, updated_record)
+
+ # Always remove the existing job first; re-register only if still enabled.
+ await scheduler.remove_schedule(schedule_id)
+ if updated_record.data.enabled:
+ await scheduler.register_schedule(updated_record)
+
+ 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),
+ storage: StorageBase = Depends(get_storage),
+ scheduler: SchedulerManager = Depends(get_scheduler_manager),
+) -> None:
+ """Permanently delete a schedule.
+
+ Removes the record from storage and unregisters the APScheduler job.
+
+ Args:
+ schedule_id (`str`): ID of the schedule to delete.
+ user_id (`str`): Authenticated user ID.
+ storage (`StorageBase`): Storage instance.
+ scheduler (`SchedulerManager`): Scheduler manager.
+
+ Raises:
+ `HTTPException`: 404 if the schedule does not exist.
+ """
+ deleted = await storage.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.remove_schedule(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))
diff --git a/src/agentscope/app/_router/_session.py b/src/agentscope/app/_router/_session.py
new file mode 100644
index 000000000..c7722a083
--- /dev/null
+++ b/src/agentscope/app/_router/_session.py
@@ -0,0 +1,274 @@
+# -*- coding: utf-8 -*-
+"""Session router — create, list, update, delete, and get messages."""
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from .._deps import get_current_user_id, get_session_manager, get_storage
+from .._manager import SessionManager
+from .._schema import (
+ CreateSessionRequest,
+ CreateSessionResponse,
+ ListMessagesResponse,
+ ListSessionsResponse,
+ UpdateSessionRequest,
+)
+from ..storage import StorageBase, SessionConfig, SessionRecord
+
+session_router = APIRouter(
+ prefix="/sessions",
+ tags=["sessions"],
+ responses={404: {"description": "Not found"}},
+)
+
+
+@session_router.get(
+ "/",
+ response_model=ListSessionsResponse,
+ summary="List sessions for an agent",
+)
+async def list_sessions(
+ agent_id: str = Query(description="Filter sessions by agent ID."),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+) -> ListSessionsResponse:
+ """Return all sessions belonging to the authenticated user for a given
+ agent.
+
+ Args:
+ agent_id (`str`): Agent whose sessions to list.
+ user_id (`str`): Injected authenticated user ID.
+ storage (`StorageBase`): Injected storage backend.
+
+ Returns:
+ `ListSessionsResponse`: All matching session records and their count.
+
+ Raises:
+ `HTTPException`: 404 if the agent does not exist or does not belong
+ to the authenticated user.
+ """
+ agents = await storage.list_agents(user_id)
+ if not any(a.id == agent_id for a in agents):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Agent '{agent_id}' not found.",
+ )
+
+ sessions = await storage.list_sessions(user_id, agent_id)
+ return ListSessionsResponse(sessions=sessions, total=len(sessions))
+
+
+@session_router.post(
+ "/",
+ response_model=CreateSessionResponse,
+ status_code=status.HTTP_201_CREATED,
+ summary="Create a new session",
+)
+async def create_session(
+ body: CreateSessionRequest,
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+) -> CreateSessionResponse:
+ """Create (or resume) a session for a given agent and workspace.
+
+ At most one session exists per ``(user_id, agent_id, workspace_id)``
+ triple — a second call with the same triple updates the existing session
+ rather than creating a duplicate.
+
+ Args:
+ body (`CreateSessionRequest`): Agent, workspace, and model config.
+ user_id (`str`): Injected authenticated user ID.
+ storage (`StorageBase`): Injected storage backend.
+
+ Returns:
+ `CreateSessionResponse`: The session identifier.
+
+ Raises:
+ `HTTPException`: 404 if the agent or credential does not exist or
+ does not belong to the authenticated user.
+ """
+ agents = await storage.list_agents(user_id)
+ if not any(a.id == body.agent_id for a in agents):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Agent '{body.agent_id}' not found.",
+ )
+
+ if body.chat_model_config is not None:
+ credentials = await storage.list_credentials(user_id)
+ if not any(
+ c.id == body.chat_model_config.credential_id for c in credentials
+ ):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Credential '{body.chat_model_config.credential_id}' "
+ f"not found.",
+ )
+
+ session_record = await storage.upsert_session(
+ user_id=user_id,
+ agent_id=body.agent_id,
+ config=SessionConfig(
+ workspace_id=body.workspace_id or uuid.uuid4().hex,
+ chat_model_config=body.chat_model_config,
+ **({"name": body.name} if body.name is not None else {}),
+ ),
+ )
+ return CreateSessionResponse(session_id=session_record.id)
+
+
+@session_router.delete(
+ "/{session_id}",
+ status_code=status.HTTP_204_NO_CONTENT,
+ summary="Delete a session",
+)
+async def delete_session(
+ session_id: str,
+ agent_id: str = Query(description="Agent the session belongs to."),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+) -> None:
+ """Permanently delete a session and all its associated state.
+
+ Args:
+ session_id (`str`): The session to delete.
+ user_id (`str`): Injected authenticated user ID.
+ storage (`StorageBase`): Injected storage backend.
+
+ Raises:
+ `HTTPException`: 404 if the session does not exist or does not belong
+ to the authenticated user.
+ """
+ deleted = await storage.delete_session(user_id, agent_id, session_id)
+ if not deleted:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Session '{session_id}' not found.",
+ )
+
+
+@session_router.patch(
+ "/{session_id}",
+ response_model=SessionRecord,
+ summary="Update a session",
+)
+async def update_session(
+ session_id: str,
+ body: UpdateSessionRequest,
+ agent_id: str = Query(description="Agent the session belongs to."),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+) -> SessionRecord:
+ """Update the model configuration of an existing session.
+
+ Args:
+ session_id (`str`): The session to update.
+ body (`UpdateSessionRequest`): Fields to update.
+ user_id (`str`): Injected authenticated user ID.
+ storage (`StorageBase`): Injected storage backend.
+
+ Returns:
+ `SessionRecord`: The full session record after the update.
+
+ Raises:
+ `HTTPException`: 404 if the session, agent, or credential does not
+ exist or does not belong to the authenticated user.
+ """
+ existing = await storage.get_session(user_id, agent_id, session_id)
+ if existing is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Session '{session_id}' not found.",
+ )
+
+ if body.chat_model_config is not None:
+ credentials = await storage.list_credentials(user_id)
+ if not any(
+ c.id == body.chat_model_config.credential_id for c in credentials
+ ):
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=(
+ f"Credential '{body.chat_model_config.credential_id}' "
+ f"not found."
+ ),
+ )
+
+ updated_state = existing.state
+ if body.permission_mode is not None:
+ updated_ctx = existing.state.permission_context.model_copy(
+ update={"mode": body.permission_mode},
+ )
+
+ updated_state = existing.state.model_copy(
+ update={
+ "permission_context": updated_ctx,
+ },
+ )
+
+ config_updates = body.model_dump(
+ exclude_none=True,
+ exclude={"permission_mode"},
+ )
+
+ return await storage.upsert_session(
+ user_id=user_id,
+ agent_id=agent_id,
+ config=existing.config.model_copy(
+ update=dict(config_updates.items()),
+ ),
+ state=updated_state,
+ session_id=session_id,
+ )
+
+
+# ----------------------------------------------------------------------
+# Messages: fetch persisted messages for a session
+# ----------------------------------------------------------------------
+
+
+@session_router.get(
+ "/{session_id}/messages",
+ response_model=ListMessagesResponse,
+ summary="List messages for a session",
+)
+async def list_messages(
+ session_id: str,
+ agent_id: str = Query(description="Agent the session belongs to."),
+ offset: int = Query(0, ge=0, description="Pagination offset."),
+ limit: int = Query(50, ge=1, le=200, description="Max messages."),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ session_manager: SessionManager = Depends(get_session_manager),
+) -> ListMessagesResponse:
+ """Return persisted messages for a session.
+
+ Args:
+ session_id: The session to query.
+ agent_id: Agent the session belongs to.
+ offset: Pagination offset.
+ limit: Maximum number of messages to return.
+ user_id: Injected authenticated user ID.
+ storage: Injected storage backend.
+ session_manager: Injected session manager.
+
+ Returns:
+ Messages and running status.
+ """
+ existing = await storage.get_session(user_id, agent_id, session_id)
+ if existing is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Session '{session_id}' not found.",
+ )
+
+ messages = await storage.list_messages(
+ user_id,
+ session_id,
+ offset=offset,
+ limit=limit,
+ )
+ return ListMessagesResponse(
+ messages=messages,
+ is_running=session_manager.is_running(session_id),
+ )
diff --git a/src/agentscope/app/_router/_workspace.py b/src/agentscope/app/_router/_workspace.py
new file mode 100644
index 000000000..f663b9e0f
--- /dev/null
+++ b/src/agentscope/app/_router/_workspace.py
@@ -0,0 +1,220 @@
+# -*- coding: utf-8 -*-
+"""Workspace router — manage MCP clients and skills on a workspace."""
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+from pydantic import BaseModel, Field
+
+from .._deps import (
+ get_current_user_id,
+ get_storage,
+ get_workspace_manager,
+)
+from .._manager import WorkspaceManagerBase
+from ..storage import StorageBase
+from ...mcp import MCPClient
+from ...skill import Skill
+from ...workspace import WorkspaceBase
+
+workspace_router = APIRouter(prefix="/workspace", tags=["workspace"])
+
+
+class AddSkillRequest(BaseModel):
+ """The request to add skill."""
+
+ skill_path: str
+
+
+class ToolInfo(BaseModel):
+ """The tool info."""
+
+ name: str
+ description: str | None = None
+
+
+class MCPClientStatus(MCPClient):
+ """MCPClient enriched with live tool list and health status."""
+
+ is_healthy: bool = False
+ tools: list[ToolInfo] = Field(default_factory=list)
+
+
+async def _resolve_workspace(
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ storage: StorageBase,
+ workspace_manager: WorkspaceManagerBase,
+) -> WorkspaceBase:
+ """Resolve the workspace for the given session, raising 404 if not
+ found."""
+ session_record = await storage.get_session(user_id, agent_id, session_id)
+ if session_record is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Session {session_id!r} not found.",
+ )
+ return await workspace_manager.get_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ session_record.config.workspace_id,
+ )
+
+
+# ---------------------------------------------------------------------------
+# MCP endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/mcp")
+async def list_mcps(
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[MCPClientStatus]:
+ """Return all MCP clients with live tool list and health status."""
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ clients = await workspace.list_mcps()
+
+ results = []
+ for client in clients:
+ base = client.model_dump()
+ try:
+ mcp_tools = await client.list_tools()
+ tools = [
+ ToolInfo(name=t.name, description=t.description)
+ for t in mcp_tools
+ ]
+ results.append(
+ MCPClientStatus(
+ **base,
+ is_healthy=True,
+ tools=tools,
+ ),
+ )
+ except Exception:
+ results.append(
+ MCPClientStatus(
+ **base,
+ is_healthy=False,
+ ),
+ )
+
+ return results
+
+
+@workspace_router.post("/mcp", status_code=status.HTTP_201_CREATED)
+async def add_mcp(
+ mcp: MCPClient,
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+ """Add an MCP client to the session's workspace."""
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ await workspace.add_mcp(mcp)
+
+
+@workspace_router.delete(
+ "/mcp/{mcp_name}",
+ status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_mcp(
+ mcp_name: str,
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+ """Remove an MCP client from the session's workspace by name."""
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ await workspace.remove_mcp(mcp_name)
+
+
+# ---------------------------------------------------------------------------
+# Skill endpoints
+# ---------------------------------------------------------------------------
+
+
+@workspace_router.get("/skill")
+async def list_skills(
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> list[Skill]:
+ """Return all skills available in the session's workspace."""
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ return await workspace.list_skills()
+
+
+@workspace_router.post("/skill", status_code=status.HTTP_201_CREATED)
+async def add_skill(
+ body: AddSkillRequest,
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+ """Add a skill to the session's workspace from the given path."""
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ await workspace.add_skill(body.skill_path)
+
+
+@workspace_router.delete(
+ "/skill/{skill_name}",
+ status_code=status.HTTP_204_NO_CONTENT,
+)
+async def remove_skill(
+ skill_name: str,
+ agent_id: str = Query(...),
+ session_id: str = Query(...),
+ user_id: str = Depends(get_current_user_id),
+ storage: StorageBase = Depends(get_storage),
+ workspace_manager: WorkspaceManagerBase = Depends(get_workspace_manager),
+) -> None:
+ """Remove a skill from the session's workspace by name."""
+ workspace = await _resolve_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ storage,
+ workspace_manager,
+ )
+ await workspace.remove_skill(skill_name)
diff --git a/src/agentscope/app/_schema/__init__.py b/src/agentscope/app/_schema/__init__.py
new file mode 100644
index 000000000..bd0893c76
--- /dev/null
+++ b/src/agentscope/app/_schema/__init__.py
@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+"""Schema models for the agent service."""
+
+from ._chat import ChatRequest
+from ._model import ListModelsResponse, ListModelsRequest
+from ._schedule import (
+ CreateScheduleRequest,
+ CreateScheduleResponse,
+ ListSchedulesResponse,
+ ScheduleSessionsResponse,
+ UpdateScheduleRequest,
+)
+from ._agent import (
+ ListAgentsResponse,
+ CreateAgentRequest,
+ CreateAgentResponse,
+ UpdateAgentRequest,
+)
+from ._background_task import (
+ ListBackgroundTasksResponse,
+ BackgroundTaskInfo,
+)
+from ._credential import (
+ CreateCredentialRequest,
+ CreateCredentialResponse,
+ UpdateCredentialRequest,
+ ListCredentialsResponse,
+ ListCredentialSchemasResponse,
+)
+from ._session import (
+ CreateSessionRequest,
+ CreateSessionResponse,
+ UpdateSessionRequest,
+ ListSessionsResponse,
+ ListMessagesResponse,
+)
+
+__all__ = [
+ # Agent
+ "ListAgentsResponse",
+ "CreateAgentRequest",
+ "CreateAgentResponse",
+ "UpdateAgentRequest",
+ "ListSchedulesResponse",
+ # Background Task
+ "ListBackgroundTasksResponse",
+ "BackgroundTaskInfo",
+ # Chat
+ "ChatRequest",
+ # Credential
+ "CreateCredentialRequest",
+ "CreateCredentialResponse",
+ "UpdateCredentialRequest",
+ "ListCredentialsResponse",
+ "ListCredentialSchemasResponse",
+ # Model
+ "ListModelsRequest",
+ "ListModelsResponse",
+ # Schedule
+ "CreateScheduleRequest",
+ "CreateScheduleResponse",
+ "ListSchedulesResponse",
+ "ScheduleSessionsResponse",
+ "UpdateScheduleRequest",
+ # Session
+ "CreateSessionRequest",
+ "CreateSessionResponse",
+ "UpdateSessionRequest",
+ "ListSessionsResponse",
+ "ListMessagesResponse",
+]
diff --git a/src/agentscope/app/_schema/_agent.py b/src/agentscope/app/_schema/_agent.py
new file mode 100644
index 000000000..cbca7c38d
--- /dev/null
+++ b/src/agentscope/app/_schema/_agent.py
@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the agent router."""
+from pydantic import BaseModel, Field
+
+from ...agent import ContextConfig, ReActConfig
+from ..storage import AgentRecord
+
+
+class CreateAgentRequest(BaseModel):
+ """Request body for creating a new agent."""
+
+ 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.",
+ )
+ context_config: ContextConfig = Field(
+ default_factory=ContextConfig,
+ description="Context-window management configuration.",
+ )
+ react_config: ReActConfig = Field(
+ default_factory=ReActConfig,
+ description="ReAct loop configuration.",
+ )
+
+
+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.",
+ )
+ context_config: ContextConfig | None = Field(
+ default=None,
+ description="New context configuration.",
+ )
+ react_config: ReActConfig | None = Field(
+ default=None,
+ description="New ReAct loop configuration.",
+ )
+
+
+class ListAgentsResponse(BaseModel):
+ """Response body for listing agents."""
+
+ agents: list[AgentRecord] = Field(description="Agent records.")
+ total: int = Field(description="Total number of agents.")
diff --git a/src/agentscope/app/_schema/_background_task.py b/src/agentscope/app/_schema/_background_task.py
new file mode 100644
index 000000000..643e69c1c
--- /dev/null
+++ b/src/agentscope/app/_schema/_background_task.py
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the background-task router."""
+from pydantic import BaseModel, Field
+
+
+class BackgroundTaskInfo(BaseModel):
+ """Summary of a single running background task."""
+
+ 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.")
+
+
+class ListBackgroundTasksResponse(BaseModel):
+ """Response body for listing background tasks of a session."""
+
+ tasks: list[BackgroundTaskInfo] = Field(
+ description="Running background tasks for the requested session.",
+ )
+ total: int = Field(description="Total number of running tasks.")
diff --git a/src/agentscope/app/_schema/_chat.py b/src/agentscope/app/_schema/_chat.py
new file mode 100644
index 000000000..65b4d954b
--- /dev/null
+++ b/src/agentscope/app/_schema/_chat.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The chat endpoint schema."""
+
+from pydantic import BaseModel, Field
+
+from ...message import Msg
+from ...event import UserConfirmResultEvent, ExternalExecutionResultEvent
+
+
+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
+ | list[Msg]
+ | UserConfirmResultEvent
+ | ExternalExecutionResultEvent
+ | None
+ ) = Field(
+ description="The input message(s), or agent event, or None.",
+ )
diff --git a/src/agentscope/app/_schema/_credential.py b/src/agentscope/app/_schema/_credential.py
new file mode 100644
index 000000000..ee91c55a4
--- /dev/null
+++ b/src/agentscope/app/_schema/_credential.py
@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the credential router."""
+from pydantic import BaseModel, Field
+
+from ..storage import CredentialRecord
+
+
+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[CredentialRecord] = 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.",
+ )
diff --git a/src/agentscope/app/_schema/_mcp.py b/src/agentscope/app/_schema/_mcp.py
new file mode 100644
index 000000000..072b5513e
--- /dev/null
+++ b/src/agentscope/app/_schema/_mcp.py
@@ -0,0 +1,127 @@
+# -*- coding: utf-8 -*-
+"""MCP schemas for API requests and responses."""
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ...mcp import StdioMCPConfig, HttpMCPConfig
+
+
+class ConnectionScope(str, Enum):
+ """MCP connection scope and lifecycle strategy.
+
+ This determines how MCP connections are managed in the service layer.
+ """
+
+ SHARED = "shared"
+ """Shared connection across all agents/users.
+ - One connection per MCP config, shared globally
+ - Created on first use, destroyed on application shutdown
+ - Use case: Stateless HTTP MCP (e.g., weather API, web search)
+ """
+
+ ISOLATED = "isolated"
+ """Isolated connection per agent.
+ - One connection per (MCP config, agent)
+ - Created on first use per agent, destroyed on agent session end
+ - Use case: Stateful MCP (e.g., browser-use), STDIO MCP
+ """
+
+ EPHEMERAL = "ephemeral"
+ """Ephemeral connection per request.
+ - New connection created for each request, destroyed immediately after
+ - No connection pooling
+ - Use case: Low-frequency stateless HTTP MCP
+ """
+
+
+class MCPBase(BaseModel):
+ """Base MCP fields shared across request/response schemas."""
+
+ name: str = Field(
+ title="MCP Name",
+ description="The unique name to identify this MCP configuration.",
+ )
+
+ connection_scope: ConnectionScope = Field(
+ title="Connection Scope",
+ description="The connection scope and lifecycle strategy.",
+ )
+
+ mcp_config: StdioMCPConfig | HttpMCPConfig = Field(
+ discriminator="type",
+ title="MCP Config",
+ description="The base MCP server configuration.",
+ )
+
+ def validate_config(self) -> None:
+ """Validate the configuration.
+
+ Raises:
+ ValueError: If the configuration is invalid.
+ """
+ # STDIO MCP cannot use ephemeral mode
+ if (
+ self.mcp_config.type == "stdio_mcp"
+ and self.connection_scope == ConnectionScope.EPHEMERAL
+ ):
+ raise ValueError(
+ "STDIO MCP does not support ephemeral mode. "
+ "Use 'shared' or 'isolated' instead.",
+ )
+
+
+class MCPCreateRequest(MCPBase):
+ """Request body for creating a new MCP configuration.
+
+ Used in POST /mcp endpoint. Does not include server-generated fields
+ like creator_id, created_at, updated_at.
+ """
+
+
+class MCPUpdateRequest(BaseModel):
+ """Request body for partially updating an MCP configuration.
+
+ Used in PATCH /mcp/{name} endpoint. All fields are optional.
+ """
+
+ connection_scope: ConnectionScope | None = Field(
+ default=None,
+ description="New connection scope.",
+ )
+ mcp_config: StdioMCPConfig | HttpMCPConfig | None = Field(
+ default=None,
+ discriminator="type",
+ description="New MCP server configuration.",
+ )
+
+
+class MCPResponse(MCPBase):
+ """Response model for MCP configuration with server-generated metadata.
+
+ Used in GET /mcp/{name}, GET /mcp (list), and POST /mcp responses.
+ Includes all fields from MCPBase plus server-assigned metadata.
+ """
+
+ creator_id: str = Field(
+ description="User ID of the creator.",
+ )
+
+ created_at: float = Field(
+ description="Creation timestamp (Unix epoch).",
+ )
+
+ updated_at: float = Field(
+ description="Last-updated timestamp (Unix epoch).",
+ )
+
+
+class ListMCPsResponse(BaseModel):
+ """Response model for listing MCP configurations."""
+
+ mcps: list[MCPResponse] = Field(
+ description="List of MCP configurations.",
+ )
+ total: int = Field(
+ description="Total number of MCP configurations.",
+ )
diff --git a/src/agentscope/app/_schema/_model.py b/src/agentscope/app/_schema/_model.py
new file mode 100644
index 000000000..21d5f93ee
--- /dev/null
+++ b/src/agentscope/app/_schema/_model.py
@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""The chat model configuration, used as DTO layer."""
+
+from pydantic import BaseModel, Field
+
+from ...model import ModelCard
+
+
+class ListModelsResponse(BaseModel):
+ """List the candidate models response."""
+
+ models: list[ModelCard] = Field(description="The candidate models.")
+ total: int = Field(description="The total number of candidates.")
+
+
+class ListModelsRequest(BaseModel):
+ """List the candidate models request."""
+
+ provider: str = Field(
+ description="The provider type, e.g. openai, dashscope, etc.",
+ )
diff --git a/src/agentscope/app/_schema/_schedule.py b/src/agentscope/app/_schema/_schedule.py
new file mode 100644
index 000000000..9531c9d31
--- /dev/null
+++ b/src/agentscope/app/_schema/_schedule.py
@@ -0,0 +1,118 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the schedule router."""
+from pydantic import BaseModel, Field
+
+from ..storage import (
+ ScheduleRecord,
+ SessionRecord,
+ ChatModelConfig,
+)
+from ...permission import PermissionMode
+
+
+class CreateScheduleRequest(BaseModel):
+ """Request body for creating a new schedule."""
+
+ name: str = Field(description="Display name of the schedule.")
+
+ description: str = Field(default="", description="Optional description.")
+
+ 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, e.g. 'America/New_York' or "
+ "'Asia/Shanghai'.",
+ )
+
+ agent_id: str = Field(description="Agent to run when the schedule fires.")
+
+ chat_model_config: ChatModelConfig = Field(
+ description="Model configuration for the auto-created session.",
+ )
+
+ enabled: bool = Field(
+ default=True,
+ description="Whether the schedule is active immediately "
+ "after creation.",
+ )
+
+ stateful: bool = Field(
+ default=False,
+ description="If True, consecutive executions share the same session "
+ "context.",
+ )
+
+ permission_mode: PermissionMode = Field(
+ default=PermissionMode.DONT_ASK,
+ description="Permission level for the agent during "
+ "scheduled execution.",
+ )
+
+
+class CreateScheduleResponse(BaseModel):
+ """Response body after creating a schedule."""
+
+ schedule_id: str = Field(
+ description="Server-assigned schedule identifier.",
+ )
+
+
+class UpdateScheduleRequest(BaseModel):
+ """Request body for partially updating a schedule.
+
+ Omit any field to keep its current value. Changing ``cron_expression``
+ or ``timezone`` will reschedule the APScheduler job immediately.
+ Changing ``enable`` to ``False`` removes the job from the scheduler
+ without deleting the record; setting it back to ``True`` re-registers it.
+ """
+
+ name: str | None = Field(default=None, description="New display name.")
+
+ description: str | None = Field(
+ default=None,
+ description="New description.",
+ )
+
+ cron_expression: str | None = Field(
+ default=None,
+ description="New cron expression. Reschedules the task immediately.",
+ )
+
+ timezone: str | None = Field(
+ default=None,
+ description="New IANA timezone name.",
+ )
+
+ enabled: bool | None = Field(
+ default=None,
+ description="Set to False to pause the schedule without deleting it.",
+ )
+
+ stateful: bool | None = Field(
+ default=None,
+ description="Change whether executions share session context.",
+ )
+
+ permission_mode: PermissionMode | None = Field(
+ default=None,
+ description="New permission mode.",
+ )
+
+
+class ListSchedulesResponse(BaseModel):
+ """Response body for listing schedules."""
+
+ schedules: list[ScheduleRecord] = Field(description="Schedule records.")
+ total: int = Field(description="Total number of schedules.")
+
+
+class ScheduleSessionsResponse(BaseModel):
+ """Response body for listing execution sessions of a schedule."""
+
+ sessions: list[SessionRecord] = Field(
+ description="Sessions triggered by this schedule.",
+ )
+ total: int = Field(description="Total number of execution sessions.")
diff --git a/src/agentscope/app/_schema/_session.py b/src/agentscope/app/_schema/_session.py
new file mode 100644
index 000000000..2bae8ccb8
--- /dev/null
+++ b/src/agentscope/app/_schema/_session.py
@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""Request / response schemas for the session router."""
+from pydantic import BaseModel, Field
+
+from ...permission import PermissionMode
+from ..storage._model._session import ChatModelConfig, SessionRecord
+
+
+class CreateSessionRequest(BaseModel):
+ """Request body for creating a new session."""
+
+ agent_id: str = Field(description="Agent this session belongs to.")
+ workspace_id: str | None = Field(
+ default=None,
+ description="Workspace this session belongs to.",
+ )
+ name: str | None = Field(
+ default=None,
+ description="Display name. Defaults to current datetime if omitted.",
+ )
+ chat_model_config: ChatModelConfig | None = Field(
+ default=None,
+ description="Model provider and parameters. "
+ "Can be set later via PATCH.",
+ )
+
+
+class CreateSessionResponse(BaseModel):
+ """Response body after creating a session."""
+
+ session_id: str = Field(description="Server-assigned session identifier.")
+
+
+class UpdateSessionRequest(BaseModel):
+ """Request body for updating an existing session.
+
+ Omit any field to keep its current value.
+ """
+
+ name: str | None = Field(
+ default=None,
+ description="New display name.",
+ )
+ chat_model_config: ChatModelConfig | None = Field(
+ default=None,
+ description="New model configuration. "
+ "Replaces the existing one entirely.",
+ )
+ permission_mode: PermissionMode | None = Field(
+ default=None,
+ description="New permission mode for the session.",
+ )
+
+
+class ListSessionsResponse(BaseModel):
+ """Response body for listing sessions."""
+
+ sessions: list[SessionRecord] = Field(description="Session records.")
+ total: int = Field(description="Total number of sessions.")
+
+
+class ListMessagesResponse(BaseModel):
+ """Response body for listing messages in a session."""
+
+ messages: list = Field(description="Messages in chronological order.")
+ is_running: bool = Field(
+ description="Whether the session is currently running.",
+ )
diff --git a/src/agentscope/app/_service/__init__.py b/src/agentscope/app/_service/__init__.py
new file mode 100644
index 000000000..25d73ebc1
--- /dev/null
+++ b/src/agentscope/app/_service/__init__.py
@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+"""Service layer for the AgentScope app."""
+from ._chat import ChatService
+from ._model import get_model
+from ._agent import get_agent
+
+__all__ = ["ChatService", "get_model", "get_agent"]
diff --git a/src/agentscope/app/_service/_agent.py b/src/agentscope/app/_service/_agent.py
new file mode 100644
index 000000000..139590087
--- /dev/null
+++ b/src/agentscope/app/_service/_agent.py
@@ -0,0 +1,90 @@
+# -*- coding: utf-8 -*-
+"""The agent service layer, responsible for getting the agent class."""
+from fastapi import HTTPException
+
+from ._model import get_model
+from .._manager import WorkspaceManagerBase
+from ..storage import StorageBase
+from ...agent import Agent
+from ...middleware import MiddlewareBase
+from ...tool import Toolkit
+
+
+async def get_agent(
+ storage: StorageBase,
+ workspace_manager: WorkspaceManagerBase,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ middlewares: list[MiddlewareBase] | None = None,
+) -> Agent:
+ """Get the agent class for the given agent ID."""
+
+ # ====================================================================
+ # Step 1. Get the agent configuration
+ # ====================================================================
+ agent_record = await storage.get_agent(
+ user_id=user_id,
+ agent_id=agent_id,
+ )
+
+ cfg = agent_record.data
+
+ # ====================================================================
+ # Step 2. Get the agent state from the session
+ # ====================================================================
+ # TODO: get_session需要agent_id
+ session_record = await storage.get_session(user_id, agent_id, session_id)
+
+ # ====================================================================
+ # Step 2.1. Get the model instance
+ # ====================================================================
+ model_cfg = session_record.config.chat_model_config
+
+ if not model_cfg:
+ # Raise error to the frontend
+ raise HTTPException(
+ status_code=404,
+ detail=f"No model configuration found for agent {agent_id}",
+ )
+
+ model = await get_model(user_id, model_cfg, storage)
+
+ # ====================================================================
+ # Step 2.2. Get the session data, i.e. the agent state
+ # ====================================================================
+ agent_state = session_record.state
+ agent_state.session_id = session_id
+
+ # ====================================================================
+ # Step 2.3. Get the workspace from the manager
+ # ====================================================================
+ workspace = await workspace_manager.get_workspace(
+ user_id,
+ agent_id,
+ session_id,
+ session_record.config.workspace_id,
+ )
+
+ # TODO: should be configurable
+ from agentscope.tool import Bash, Read, Write, Edit
+
+ toolkit = Toolkit(
+ tools=[Bash(), Read(), Write(), Edit()],
+ skills=[],
+ )
+
+ for mcp_client in await workspace.list_mcps():
+ await toolkit.register_mcp(mcp_client)
+
+ return Agent(
+ name=cfg.name,
+ system_prompt=cfg.system_prompt,
+ model=model,
+ toolkit=toolkit,
+ context_config=cfg.context_config,
+ react_config=cfg.react_config,
+ state=agent_state,
+ middlewares=middlewares,
+ # workspace=workspace,
+ )
diff --git a/src/agentscope/app/_service/_chat.py b/src/agentscope/app/_service/_chat.py
new file mode 100644
index 000000000..7a0cd7663
--- /dev/null
+++ b/src/agentscope/app/_service/_chat.py
@@ -0,0 +1,224 @@
+# -*- coding: utf-8 -*-
+"""Chat service encapsulating agent execution + persistence logic.
+
+This is the single source of truth for running an agent against a session.
+Both the HTTP chat endpoint and the schedule trigger call
+:meth:`ChatService.stream_chat`, guaranteeing identical message
+persistence, ``ToolOffloadMiddleware`` wiring, and state handling.
+"""
+from collections.abc import AsyncGenerator
+
+from ..storage import StorageBase
+from .._manager import (
+ BackgroundTaskManager,
+ SessionManager,
+ WorkspaceManagerBase,
+)
+from .._middleware import ToolOffloadMiddleware
+from ._agent import get_agent
+from ..._logging import logger
+from ...event import (
+ AgentEvent,
+ ReplyStartEvent,
+ UserConfirmResultEvent,
+ ExternalExecutionResultEvent,
+)
+from ...message import AssistantMsg, Msg
+
+
+class ChatService:
+ """Run an agent against a session, streaming events while persisting
+ input/reply messages and updated agent state.
+
+ Shared by the HTTP chat endpoint and the schedule trigger so both
+ paths go through identical validation, assembly, and persistence.
+ """
+
+ def __init__(
+ self,
+ storage: StorageBase,
+ session_manager: SessionManager,
+ background_task_manager: BackgroundTaskManager,
+ workspace_manager: WorkspaceManagerBase,
+ ) -> None:
+ """Initialize chat service.
+
+ Args:
+ storage (`StorageBase`):
+ Application storage backend.
+ session_manager (`SessionManager`):
+ Per-session run serializer and event buffer for SSE
+ subscribers.
+ background_task_manager (`BackgroundTaskManager`):
+ Tracks offloaded long-running tool tasks and queues their
+ results for re-injection on the next reasoning step.
+ workspace_manager (`WorkspaceManagerBase`):
+ Provides per-session workspace (tools, MCPs, skills) used
+ during agent assembly.
+ """
+ self._storage = storage
+ self._session_manager = session_manager
+ self._background_task_manager = background_task_manager
+ self._workspace_manager = workspace_manager
+
+ async def stream_chat(
+ self,
+ user_id: str,
+ session_id: str,
+ agent_id: str,
+ input_msg: Msg
+ | list[Msg]
+ | UserConfirmResultEvent
+ | ExternalExecutionResultEvent
+ | None = None,
+ ) -> AsyncGenerator[AgentEvent, None]:
+ """Run the agent and yield events.
+
+ Persists input messages (Case A) or the incoming continuation event
+ applied to the existing reply (Case B), streams the agent's reply
+ while building an ``AssistantMsg`` from the event flow, and
+ persists the reply and updated agent state when finished.
+
+ Args:
+ user_id (`str`):
+ Authenticated caller's user ID.
+ session_id (`str`):
+ Target session ID.
+ agent_id (`str`):
+ Agent to run.
+ input_msg:
+ One of:
+ - ``Msg`` / ``list[Msg]``: new user message(s) (Case A)
+ - ``None``: continue from current state, e.g. a retrigger
+ triggered by a completed background tool (Case A with
+ no input)
+ - ``UserConfirmResultEvent`` /
+ ``ExternalExecutionResultEvent``:
+ resume an awaiting tool call (Case B)
+
+ Yields:
+ AgentEvent: Streamed events from the agent.
+ """
+
+ # ----------------------------------------------------------------
+ # 1. Build middlewares
+ # ----------------------------------------------------------------
+ async def _retrigger(
+ sess_id: str,
+ ag_id: str,
+ uid: str,
+ ) -> None:
+ """Re-invoke the agent to process completed background results."""
+ async for _ in self.stream_chat(
+ user_id=uid,
+ session_id=sess_id,
+ agent_id=ag_id,
+ input_msg=None,
+ ):
+ pass
+
+ middlewares: list = [
+ ToolOffloadMiddleware(
+ self._background_task_manager,
+ user_id=user_id,
+ agent_id=agent_id,
+ session_manager=self._session_manager,
+ retrigger_fn=_retrigger,
+ ),
+ ]
+
+ # ----------------------------------------------------------------
+ # 2. Assemble the agent (loads session/agent/credential/model,
+ # restores state, builds toolkit from workspace)
+ # ----------------------------------------------------------------
+ agent = await get_agent(
+ storage=self._storage,
+ workspace_manager=self._workspace_manager,
+ user_id=user_id,
+ agent_id=agent_id,
+ session_id=session_id,
+ middlewares=middlewares,
+ )
+
+ # ----------------------------------------------------------------
+ # 3. Run the agent inside the session manager context
+ # ----------------------------------------------------------------
+ async with self._session_manager.run(session_id) as run:
+ reply_msg: Msg | None = None
+
+ if input_msg is None or isinstance(input_msg, (Msg, list)):
+ # Case A: new reply (user message(s), or retrigger with
+ # empty input)
+ if isinstance(input_msg, (Msg, list)):
+ input_msgs = (
+ [input_msg]
+ if isinstance(input_msg, Msg)
+ else input_msg
+ )
+ for msg in input_msgs:
+ await self._storage.upsert_message(
+ user_id,
+ session_id,
+ msg,
+ )
+
+ async for event in agent.reply_stream(inputs=input_msg):
+ await run.publish(event)
+ yield event
+ if isinstance(event, ReplyStartEvent):
+ reply_msg = AssistantMsg(
+ id=event.reply_id,
+ name=event.name,
+ content=[],
+ )
+ elif reply_msg is not None:
+ reply_msg.append_event(event)
+
+ else:
+ # Case B: continuation (UserConfirmResult / ExternalExecResult)
+ reply_msg = await self._storage.get_message(
+ user_id,
+ session_id,
+ agent.state.reply_id,
+ )
+
+ if reply_msg is None:
+ logger.warning(
+ "Reply message %r not found in storage for session "
+ "%r; tool-call state changes from the incoming event "
+ "will not be persisted.",
+ agent.state.reply_id,
+ session_id,
+ )
+ elif input_msg:
+ # Apply the incoming event so the persisted message
+ # reflects updated tool-call states before streaming
+ # resumes (e.g. ASKING→ALLOWED/FINISHED for
+ # UserConfirmResultEvent, or appended ToolResultBlocks
+ # for ExternalExecutionResultEvent).
+ reply_msg.append_event(input_msg)
+
+ async for event in agent.reply_stream(inputs=input_msg):
+ await run.publish(event)
+ yield event
+ if reply_msg is not None:
+ reply_msg.append_event(event)
+
+ # Persist the reply Msg (upsert: overwrite if same id, append
+ # if new)
+ if reply_msg is not None:
+ await self._storage.upsert_message(
+ user_id,
+ session_id,
+ reply_msg,
+ )
+
+ # ----------------------------------------------------------------
+ # 4. Persist agent state
+ # ----------------------------------------------------------------
+ await self._storage.update_session_state(
+ user_id=user_id,
+ agent_id=agent_id,
+ session_id=session_id,
+ state=agent.state,
+ )
diff --git a/src/agentscope/app/_service/_model.py b/src/agentscope/app/_service/_model.py
new file mode 100644
index 000000000..d80f4c87a
--- /dev/null
+++ b/src/agentscope/app/_service/_model.py
@@ -0,0 +1,50 @@
+# -*- coding: utf-8 -*-
+"""Model service: builds a ChatModelBase from stored credential + config."""
+from fastapi import HTTPException, status
+
+from ..storage import StorageBase, ChatModelConfig
+from ...credential import CredentialFactory
+from ...model import ChatModelBase
+
+
+async def get_model(
+ user_id: str,
+ config: ChatModelConfig,
+ storage: StorageBase,
+) -> ChatModelBase:
+ """Get the model instance from the configuration and storage.
+
+ Args:
+ user_id (`str`):
+ The user id.
+ config (`ChatModelConfig`):
+ The chat model configuration.
+ storage (`StorageBase`):
+ The storage instance.
+
+ Returns:
+ `ChatModelBase`:
+ The model instance.
+ """
+ credential_record = await storage.get_credential(
+ user_id,
+ config.credential_id,
+ )
+ if credential_record is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail=f"Credential {config.credential_id!r} not found.",
+ )
+
+ credential = CredentialFactory.from_dict(credential_record.data)
+ model_cls = credential.get_chat_model_class()
+ parameters = (
+ model_cls.Parameters(**config.parameters)
+ if config.parameters
+ else None
+ )
+ return model_cls(
+ credential=credential,
+ model=config.model,
+ parameters=parameters,
+ )
diff --git a/src/agentscope/app/storage/__init__.py b/src/agentscope/app/storage/__init__.py
new file mode 100644
index 000000000..1aeee4883
--- /dev/null
+++ b/src/agentscope/app/storage/__init__.py
@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""The storage module in agentscope."""
+
+from ._base import StorageBase
+from ._redis_storage import RedisStorage, RedisKeyConfig
+from ._model import (
+ AgentData,
+ AgentRecord,
+ CredentialRecord,
+ ScheduleData,
+ ScheduleRecord,
+ ScheduleSource,
+ SessionConfig,
+ SessionRecord,
+ SessionSource,
+ ChatModelConfig,
+ UserRecord,
+)
+
+__all__ = [
+ "StorageBase",
+ "RedisKeyConfig",
+ "RedisStorage",
+ "AgentData",
+ "AgentRecord",
+ "CredentialRecord",
+ "SessionConfig",
+ "SessionRecord",
+ "SessionSource",
+ "ChatModelConfig",
+ "UserRecord",
+ "ScheduleData",
+ "ScheduleRecord",
+ "ScheduleSource",
+]
diff --git a/src/agentscope/app/storage/_base.py b/src/agentscope/app/storage/_base.py
new file mode 100644
index 000000000..dc4efbce4
--- /dev/null
+++ b/src/agentscope/app/storage/_base.py
@@ -0,0 +1,425 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-public-methods
+"""The storage base class."""
+from abc import ABC, abstractmethod
+from typing import Any, Self
+
+
+from ._model import (
+ AgentRecord,
+ CredentialRecord,
+ ScheduleRecord,
+ SessionRecord,
+ SessionConfig,
+ SessionSource,
+)
+from ...credential import CredentialBase
+from ...message import Msg
+from ...state import AgentState
+
+
+class StorageBase(ABC):
+ """The storage abstract base class."""
+
+ async def __aenter__(self) -> Self:
+ """Start the storage backend (open connection pool, etc.)."""
+ return self
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc_value: BaseException | None,
+ traceback: Any,
+ ) -> None:
+ """Shut down the storage backend."""
+ await self.aclose()
+
+ async def aclose(self) -> None:
+ """Release underlying connection resources. Default is a no-op."""
+
+ @abstractmethod
+ async def upsert_credential(
+ self,
+ user_id: str,
+ credential_data: CredentialBase,
+ ) -> str:
+ """Create or update a credential in the storage.
+
+ Args:
+ user_id (`str`):
+ The user id.
+ credential_data (`CredentialBase`):
+ The credential data.
+
+ Returns:
+ `str`:
+ The credential id.
+ """
+
+ @abstractmethod
+ async def list_credentials(self, user_id: str) -> list[CredentialRecord]:
+ """List all credentials for a given user.
+
+ Args:
+ user_id (`str`):
+ The user id.
+
+ Returns:
+ `list[CredentialRecord]`:
+ List of all credentials for a given user.
+ """
+
+ @abstractmethod
+ async def get_credential(
+ self,
+ user_id: str,
+ credential_id: str,
+ ) -> CredentialRecord | None:
+ """Fetch a single credential record by id.
+
+ Args:
+ user_id (`str`): The owner user id.
+ credential_id (`str`): The credential id.
+
+ Returns:
+ `CredentialRecord | None`: The record, or ``None`` if not found.
+ """
+
+ @abstractmethod
+ async def delete_credential(
+ self,
+ user_id: str,
+ credential_id: str,
+ ) -> bool:
+ """Delete a credential.
+
+ Args:
+ user_id (`str`):
+ The user id.
+ credential_id (`str`):
+ The credential id.
+
+ Returns:
+ `bool`:
+ True if deleted, False if not found.
+ """
+
+ @abstractmethod
+ async def upsert_agent(
+ self,
+ user_id: str,
+ agent_record: AgentRecord,
+ ) -> str:
+ """Create an agent record in the storage.
+
+ Args:
+ user_id (`str`):
+ The user id.
+ agent_record (`AgentRecord`):
+ The agent record.
+
+ Returns:
+ `str`:
+ The agent id.
+ """
+
+ @abstractmethod
+ async def list_agents(self, user_id: str) -> list[AgentRecord]:
+ """List all agents for a given user.
+
+ Args:
+ user_id (`str`):
+ The user id.
+
+ Returns:
+ `list[AgentRecord]`:
+ List of all agents for a given user.
+ """
+
+ @abstractmethod
+ async def get_agent(
+ self,
+ user_id: str,
+ agent_id: str,
+ ) -> AgentRecord | None:
+ """Fetch a single agent record by id.
+
+ Args:
+ user_id (`str`): The owner user id.
+ agent_id (`str`): The agent id.
+
+ Returns:
+ `AgentRecord | None`: The record, or ``None`` if not found.
+ """
+
+ @abstractmethod
+ async def delete_agent(self, user_id: str, agent_id: str) -> bool:
+ """Delete an agent record.
+
+ Args:
+ user_id (`str`):
+ The user id.
+ agent_id (`str`):
+ The agent id.
+
+ Returns:
+ `bool`:
+ True if deleted, False if not found.
+ """
+
+ @abstractmethod
+ async def upsert_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ config: SessionConfig,
+ state: AgentState | None = None,
+ session_id: str | None = None,
+ source: SessionSource = SessionSource.USER,
+ source_schedule_id: str | None = None,
+ ) -> SessionRecord:
+ """Create or update a session for a (user, agent) pair.
+
+ Args:
+ user_id (`str`): The owner user id.
+ agent_id (`str`): The agent id.
+ config (`SessionConfig`): Immutable session configuration
+ (model, workspace). Required on create; passed unchanged on
+ state-only updates.
+ state (`AgentState | None`, optional): Runtime state to persist.
+ Defaults to a fresh ``AgentState()`` when ``None``.
+ session_id (`str | None`, optional): If provided, update the
+ existing session with this id. If ``None``, create a new
+ session.
+ source (`SessionSource`, optional): The source that created this
+ session. Defaults to ``SessionSource.USER``.
+ source_schedule_id (`str | None`, optional): The schedule that
+ created this session. When set, the session is indexed under
+ the schedule for execution history queries.
+
+ Returns:
+ `SessionRecord`: The created or updated record.
+ """
+
+ @abstractmethod
+ async def update_session_state(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ state: AgentState,
+ ) -> None:
+ """Update only the mutable state of an existing session.
+
+ Convenience method for the hot path (post-chat-turn persistence).
+ Raises ``KeyError`` if the session does not exist.
+
+ Args:
+ user_id (`str`): The owner user id.
+ agent_id (`str`): The agent id.
+ session_id (`str`): The session id.
+ state (`AgentState`): The new agent state to persist.
+ """
+
+ @abstractmethod
+ async def list_sessions(
+ self,
+ user_id: str,
+ agent_id: str,
+ ) -> list[SessionRecord]:
+ """List all sessions for a given user and agent entity.
+
+ Args:
+ user_id (`str`): The user id.
+ agent_id (`str`): The agent id.
+
+ Returns:
+ `list[SessionRecord]`: List of all sessions for the (user, agent).
+ """
+
+ @abstractmethod
+ async def delete_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> bool:
+ """Delete a session.
+
+ Args:
+ user_id (`str`): The user id.
+ agent_id (`str`): The agent id.
+ session_id (`str`): The session id.
+
+ Returns:
+ `bool`: True if deleted, False if not found.
+ """
+
+ @abstractmethod
+ async def get_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> SessionRecord | None:
+ """Fetch a single session record by id.
+
+ Args:
+ user_id (`str`): The owner user id.
+ agent_id (`str`): The agent id.
+ session_id (`str`): The session id.
+
+ Returns:
+ `SessionRecord | None`: The record, or ``None`` if not found.
+ """
+
+ @abstractmethod
+ async def list_sessions_by_schedule(
+ self,
+ user_id: str,
+ schedule_id: str,
+ ) -> list[SessionRecord]:
+ """Return all sessions created by a given schedule.
+
+ Args:
+ user_id (`str`): The owner user id.
+ schedule_id (`str`): The schedule id.
+
+ Returns:
+ `list[SessionRecord]`: Sessions triggered by this schedule,
+ ordered by creation time (newest first).
+ """
+
+ @abstractmethod
+ async def upsert_schedule(
+ self,
+ user_id: str,
+ record: ScheduleRecord,
+ ) -> str:
+ """Persist a cron task record and register it in the user's index.
+
+ Args:
+ user_id (`str`): The owner user id.
+ record (`ScheduleRecord`): The fully-populated record to store.
+
+ Returns:
+ `str`: The id of the stored record.
+ """
+
+ @abstractmethod
+ async def get_schedule(
+ self,
+ user_id: str,
+ schedule_id: str,
+ ) -> ScheduleRecord | None:
+ """Fetch a single cron task record by id.
+
+ Args:
+ user_id (`str`): The owner user id.
+ schedule_id (`str`): The task id.
+
+ Returns:
+ `ScheduleRecord | None`: The record, or ``None`` if not found.
+ """
+
+ @abstractmethod
+ async def list_schedules(
+ self,
+ user_id: str,
+ ) -> list[ScheduleRecord]:
+ """Return all cron task records belonging to the given user.
+
+ Args:
+ user_id (`str`): The owner user id.
+
+ Returns:
+ `list[ScheduleRecord]`: All cron task records for the user.
+ """
+
+ @abstractmethod
+ async def delete_schedule(
+ self,
+ user_id: str,
+ schedule_id: str,
+ ) -> bool:
+ """Delete a cron task record and remove it from the user's index.
+
+ Args:
+ user_id (`str`): The owner user id.
+ schedule_id (`str`): The id of the task to delete.
+
+ Returns:
+ `bool`: ``True`` if deleted, ``False`` if not found.
+ """
+
+ @abstractmethod
+ async def list_all_schedules(self) -> list[ScheduleRecord]:
+ """Return every schedule record across all users.
+
+ Used on startup to restore the in-memory scheduler from persisted
+ state. Normal per-user listing should use :meth:`list_schedules`.
+
+ Returns:
+ `list[ScheduleRecord]`: All schedule records in the store.
+ """
+
+ # ------------------------------------------------------------------
+ # Message persistence
+ # ------------------------------------------------------------------
+
+ @abstractmethod
+ async def upsert_message(
+ self,
+ user_id: str,
+ session_id: str,
+ msg: Msg,
+ ) -> None:
+ """Persist a message to the session's message list.
+
+ If the last message in the list has the same ``id`` as *msg*, it is
+ replaced (merge/overwrite for the same reply_id across continuation
+ calls). Otherwise, *msg* is appended as a new entry.
+
+ Args:
+ user_id (`str`): The owner user id.
+ session_id (`str`): The session id.
+ msg (`Msg`): The message to persist.
+ """
+
+ @abstractmethod
+ async def get_message(
+ self,
+ user_id: str,
+ session_id: str,
+ message_id: str,
+ ) -> Msg | None:
+ """Fetch a single message by id from the session's message list.
+
+ Args:
+ user_id (`str`): The owner user id.
+ session_id (`str`): The session id.
+ message_id (`str`): The message id to look up.
+
+ Returns:
+ `Msg | None`: The message, or ``None`` if not found.
+ """
+
+ @abstractmethod
+ async def list_messages(
+ self,
+ user_id: str,
+ session_id: str,
+ offset: int = 0,
+ limit: int = 50,
+ ) -> list[Msg]:
+ """Return messages for a session with pagination.
+
+ Args:
+ user_id (`str`): The owner user id.
+ session_id (`str`): The session id.
+ offset (`int`): Starting index (0-based). Defaults to 0.
+ limit (`int`): Maximum number of messages to return.
+
+ Returns:
+ `list[Msg]`: Messages in chronological order.
+ """
diff --git a/src/agentscope/app/storage/_model/__init__.py b/src/agentscope/app/storage/_model/__init__.py
new file mode 100644
index 000000000..e58c5acc1
--- /dev/null
+++ b/src/agentscope/app/storage/_model/__init__.py
@@ -0,0 +1,27 @@
+# -*- coding: utf-8 -*-
+"""Storage models for persisted resources."""
+
+from ._agent import AgentRecord, AgentData
+from ._credential import CredentialRecord
+from ._schedule import ScheduleData, ScheduleRecord, ScheduleSource
+from ._session import (
+ SessionRecord,
+ SessionConfig,
+ ChatModelConfig,
+ SessionSource,
+)
+from ._user import UserRecord
+
+__all__ = [
+ "AgentData",
+ "AgentRecord",
+ "CredentialRecord",
+ "ScheduleData",
+ "ScheduleRecord",
+ "ScheduleSource",
+ "SessionConfig",
+ "SessionRecord",
+ "SessionSource",
+ "ChatModelConfig",
+ "UserRecord",
+]
diff --git a/src/agentscope/app/storage/_model/_agent.py b/src/agentscope/app/storage/_model/_agent.py
new file mode 100644
index 000000000..2a20c24eb
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_agent.py
@@ -0,0 +1,48 @@
+# -*- coding: utf-8 -*-
+"""The agent storage class."""
+import uuid
+
+from pydantic import Field, BaseModel
+
+from ._base import _RecordBase
+from ....agent import ContextConfig, ReActConfig
+
+
+class AgentData(BaseModel):
+ """The agent data model."""
+
+ id: str = Field(
+ description="Unique agent id",
+ default_factory=lambda: uuid.uuid4().hex,
+ )
+ """The agent id."""
+
+ name: str = Field(
+ description="The name of the agent.",
+ title="Name",
+ )
+
+ system_prompt: str = Field(
+ description="The system prompt for the agent.",
+ title="System Prompt",
+ )
+
+ context_config: ContextConfig = Field(
+ description="The context config for the agent.",
+ title="Context Config",
+ )
+
+ react_config: ReActConfig = Field(
+ description="The react config for the agent.",
+ title="React Config",
+ )
+
+
+class AgentRecord(_RecordBase):
+ """The agent ORM model."""
+
+ user_id: str
+ """The user id"""
+
+ data: AgentData
+ """The agent data"""
diff --git a/src/agentscope/app/storage/_model/_base.py b/src/agentscope/app/storage/_model/_base.py
new file mode 100644
index 000000000..eb0cbd4a7
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_base.py
@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+"""The base attributes used in storage."""
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class _RecordBase(BaseModel):
+ """The base class for all records."""
+
+ id: str = Field(
+ default_factory=lambda: uuid.uuid4().hex,
+ description="Unique identifier for the credential.",
+ )
+
+ updated_at: datetime = Field(
+ default_factory=datetime.now,
+ )
+ """The updated time."""
+
+ created_at: datetime = Field(
+ default_factory=datetime.now,
+ )
+ """The created time."""
diff --git a/src/agentscope/app/storage/_model/_credential.py b/src/agentscope/app/storage/_model/_credential.py
new file mode 100644
index 000000000..42e97ee62
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_credential.py
@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""The credential record."""
+import uuid
+
+from pydantic import Field
+
+from ._base import _RecordBase
+
+
+class CredentialRecord(_RecordBase):
+ """The credential model used for storing credentials."""
+
+ user_id: str = Field(
+ default_factory=lambda: uuid.uuid4().hex,
+ )
+
+ data: dict
+ """The credential data."""
diff --git a/src/agentscope/app/storage/_model/_schedule.py b/src/agentscope/app/storage/_model/_schedule.py
new file mode 100644
index 000000000..9a2b22261
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_schedule.py
@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""The schedule storage model."""
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ._base import _RecordBase
+from ._session import ChatModelConfig
+from ....permission import PermissionMode
+
+
+class ScheduleSource(str, Enum):
+ """The source that created the schedule.
+
+ Attributes:
+ USER: Created manually by the user via the UI.
+ AGENT: Created automatically by an agent, e.g. via a tool call.
+ """
+
+ USER = "USER"
+ AGENT = "AGENT"
+
+
+class ScheduleData(BaseModel):
+ """The schedule configuration data."""
+
+ name: str = Field(description="Display name of the schedule.")
+
+ description: str = Field(
+ default="",
+ description="The description of the schedule, including its purpose, "
+ "trigger conditions, etc.",
+ )
+
+ enabled: bool = Field(
+ default=True,
+ description="Whether the schedule is active. Disabled schedules are "
+ "retained but will not trigger.",
+ )
+
+ timezone: str = Field(
+ default="UTC",
+ description="IANA timezone name used to evaluate the cron expression, "
+ "e.g. 'America/New_York' or 'Asia/Shanghai'.",
+ )
+
+ cron_expression: str = Field(
+ description="Standard 5-field cron expression, e.g. '0 9 * * 1-5'.",
+ )
+
+ started_at: datetime = Field(
+ description="The date and time the schedule was started.",
+ )
+
+ ended_at: datetime | None = Field(
+ default=None,
+ description="The date and time the schedule was ended.",
+ )
+
+ chat_model_config: ChatModelConfig = Field(
+ description="Model configuration for the auto-created session.",
+ )
+
+ stateful: bool = Field(
+ title="Stateful",
+ default=False,
+ description="Whether consecutive executions share the same session "
+ "context. If not, each execution will have its own state.",
+ )
+
+ permission_mode: PermissionMode = Field(
+ title="Permission mode",
+ default=PermissionMode.DONT_ASK,
+ description="Permission level for the agent during scheduled "
+ "execution. Defaults to DONT_ASK since no user is present to "
+ "answer prompts.",
+ )
+
+ source: ScheduleSource = Field(
+ default=ScheduleSource.USER,
+ description="Indicates how this schedule was created.",
+ )
+
+ source_session_id: str = Field(
+ default="",
+ description="The source session identifier, used for resource "
+ "retrieval.",
+ )
+
+
+class ScheduleRecord(_RecordBase):
+ """Persisted schedule record."""
+
+ user_id: str = Field(description="Owner user id.")
+
+ agent_id: str = Field(
+ description="The agent id that will execute the schedule.",
+ )
+
+ data: ScheduleData = Field(description="Schedule configuration.")
diff --git a/src/agentscope/app/storage/_model/_session.py b/src/agentscope/app/storage/_model/_session.py
new file mode 100644
index 000000000..cc1d47739
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_session.py
@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+"""The session data class for storage."""
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from ._base import _RecordBase
+from ....state import AgentState
+
+
+class SessionSource(str, Enum):
+ """The source that created the session."""
+
+ USER = "user"
+ SCHEDULE = "schedule"
+
+
+class ChatModelConfig(BaseModel):
+ """The model configuration class."""
+
+ type: str
+ """The provider type."""
+
+ credential_id: str
+ """The credential id."""
+
+ model: str
+ """The model name."""
+
+ parameters: dict
+ """The model parameters."""
+
+
+class SessionConfig(BaseModel):
+ """Session configuration — set at creation, updatable via PATCH."""
+
+ workspace_id: str
+ """The workspace id this session is bound to."""
+
+ name: str = Field(
+ default_factory=lambda: datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+ description="Display name for the session.",
+ )
+ """The session display name."""
+
+ chat_model_config: ChatModelConfig | None = None
+ """The chat model config. None means no model has been configured yet."""
+
+
+class SessionRecord(_RecordBase):
+ """The session record."""
+
+ user_id: str
+ """The user id."""
+
+ agent_id: str
+ """The agent id."""
+
+ source: SessionSource = SessionSource.USER
+ """The source that created this session."""
+
+ source_schedule_id: str | None = None
+ """The source schedule Id."""
+
+ config: SessionConfig
+ """Session configuration (workspace, name, model)."""
+
+ state: AgentState = Field(default_factory=AgentState)
+ """Mutable runtime state, updated after each chat turn."""
diff --git a/src/agentscope/app/storage/_model/_user.py b/src/agentscope/app/storage/_model/_user.py
new file mode 100644
index 000000000..7b89bd347
--- /dev/null
+++ b/src/agentscope/app/storage/_model/_user.py
@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+"""The user record for storage."""
+
+from ._base import _RecordBase
+
+
+class UserRecord(_RecordBase):
+ """The user record."""
diff --git a/src/agentscope/app/storage/_redis_storage.py b/src/agentscope/app/storage/_redis_storage.py
new file mode 100644
index 000000000..6e08282fb
--- /dev/null
+++ b/src/agentscope/app/storage/_redis_storage.py
@@ -0,0 +1,849 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=too-many-public-methods
+"""The Redis storage implementation."""
+from datetime import datetime
+from typing import Any, TYPE_CHECKING, Self
+
+from pydantic import BaseModel
+
+from ._base import StorageBase
+from ._model import (
+ AgentRecord,
+ CredentialRecord,
+ ScheduleRecord,
+ SessionRecord,
+ SessionConfig,
+ SessionSource,
+)
+from ._utils import _dump_with_secrets
+from ...credential import CredentialBase
+from ...message import Msg
+from ...state import AgentState
+
+if TYPE_CHECKING:
+ from redis.asyncio import ConnectionPool, Redis
+else:
+ ConnectionPool = Any
+ Redis = Any
+
+
+class RedisKeyConfig(BaseModel):
+ """Key templates for all Redis keys used by RedisStorage."""
+
+ # Record keys
+ credential: str = "agentscope:user:{user_id}:credential:{credential_id}"
+ agent: str = "agentscope:user:{user_id}:agent:{agent_id}"
+ session: str = "agentscope:user:{user_id}:session:{session_id}"
+
+ # Index keys (Redis Sets — store all IDs for a given scope)
+ credential_index: str = "agentscope:user:{user_id}:credentials"
+ agent_index: str = "agentscope:user:{user_id}:agents"
+ session_index: str = "agentscope:user:{user_id}:agent:{agent_id}:sessions"
+
+ # Lookup key: maps (user_id, agent_id) → session_id
+ session_lookup: str = "agentscope:user:{user_id}:agent:{agent_id}:session"
+
+ # Message list key (Redis List — ordered message history per session)
+ messages: str = "agentscope:user:{user_id}:session:{session_id}:messages"
+
+ schedule: str = "agentscope:user:{user_id}:schedule:{schedule_id}"
+ schedule_index: str = "agentscope:user:{user_id}:schedules"
+ schedule_global_index: str = "agentscope:schedules"
+ schedule_session_index: str = (
+ "agentscope:user:{user_id}:schedule:{schedule_id}:sessions"
+ )
+
+
+class RedisStorage(StorageBase):
+ """The Redis storage implementation."""
+
+ def __init__(
+ self,
+ host: str = "localhost",
+ port: int = 6379,
+ db: int = 0,
+ password: str | None = None,
+ connection_pool: ConnectionPool | None = None,
+ key_ttl: int | None = None,
+ key_config: RedisKeyConfig | None = None,
+ **kwargs: Any,
+ ) -> None:
+ """Store connection parameters; the actual pool is created in
+ :meth:`__aenter__`.
+
+ Args:
+ host (`str`, defaults to `"localhost"`): Redis server host.
+ port (`int`, defaults to `6379`): Redis server port.
+ db (`int`, defaults to `0`): Redis database index.
+ password (`str | None`, optional): Redis password if required.
+ connection_pool (`ConnectionPool | None`, optional):
+ An externally managed connection pool. When provided the pool
+ is used as-is and **not** closed by :meth:`aclose` — the
+ caller retains ownership of its lifecycle. When omitted a
+ pool is created from *host*/*port*/*db*/*password* on
+ :meth:`__aenter__` and closed on :meth:`aclose`.
+ Extra ``**kwargs`` (e.g. ``max_connections``) are forwarded to
+ the pool constructor only when the pool is created internally.
+ key_ttl (`int | None`, optional):
+ Expire time in seconds for record keys. Refreshed on every
+ write (sliding TTL). If `None`, keys do not expire.
+ key_config (`RedisKeyConfig | None`, optional):
+ Key template configuration. Defaults to `RedisKeyConfig()`.
+ **kwargs (`Any`):
+ Extra keyword arguments forwarded to
+ ``redis.asyncio.ConnectionPool`` when the pool is created
+ internally (e.g. ``max_connections=20``, ``socket_timeout=5``).
+ """
+ self._host = host
+ self._port = port
+ self._db = db
+ self._password = password
+ self._external_pool: ConnectionPool | None = connection_pool
+ self._kwargs = kwargs
+ self.key_ttl = key_ttl
+ self.key_config = key_config or RedisKeyConfig()
+
+ # Populated in __aenter__; None until the context is entered.
+ self._client: Redis | None = None
+ self._owned_pool: ConnectionPool | None = None
+
+ def _key(self, template: str, **kwargs: str) -> str:
+ """Format a key template with the given keyword arguments."""
+ return template.format(**kwargs)
+
+ async def _set_with_ttl(self, key: str, value: str) -> None:
+ """SET a key and optionally apply the sliding TTL."""
+ await self._client.set(key, value)
+ if self.key_ttl is not None:
+ await self._client.expire(key, self.key_ttl)
+
+ async def __aenter__(self) -> Self:
+ """Create the connection pool and Redis client.
+
+ If an external pool was supplied at construction time it is used
+ directly and its lifecycle remains the caller's responsibility.
+ Otherwise, an internal pool is created from the stored host/port/db
+ parameters and will be closed by :meth:`aclose`.
+ """
+ try:
+ import redis.asyncio as aioredis
+ except ImportError as e:
+ raise ImportError(
+ "The 'redis' package is required for RedisStorage. "
+ "Install it with: pip install redis[async]",
+ ) from e
+
+ if self._external_pool is not None:
+ pool = self._external_pool
+ else:
+ self._owned_pool = aioredis.ConnectionPool(
+ host=self._host,
+ port=self._port,
+ db=self._db,
+ password=self._password,
+ decode_responses=True,
+ **self._kwargs,
+ )
+ pool = self._owned_pool
+
+ self._client = aioredis.Redis(connection_pool=pool)
+ return self
+
+ async def aclose(self) -> None:
+ """Close the connection pool if it was created internally.
+
+ Externally supplied pools are left open — the caller owns them.
+ """
+ if self._owned_pool is not None:
+ await self._owned_pool.aclose()
+ self._owned_pool = None
+ self._client = None
+
+ async def __aexit__(
+ self,
+ exc_type: type[BaseException] | None,
+ exc_value: BaseException | None,
+ traceback: Any,
+ ) -> None:
+ """Exit the async context manager."""
+ await self.aclose()
+
+ def get_client(self) -> Redis:
+ """Get the underlying Redis client instance."""
+ return self._client
+
+ async def _generate_credential_name(
+ self,
+ user_id: str,
+ credential_data: CredentialBase,
+ ) -> str:
+ """Auto-generate a display name for a credential based on its type.
+
+ Produces names like "OpenAI", "OpenAI (2)", "OpenAI (3)", etc.
+ """
+ cred_type = getattr(credential_data, "type", "")
+ base_name = (
+ cred_type.removesuffix("_credential").replace("_", " ").title()
+ )
+ if not base_name:
+ base_name = "Credential"
+
+ existing = await self.list_credentials(user_id)
+ same_type_names = [
+ c.data.get("name", "")
+ for c in existing
+ if c.data.get("type") == cred_type and c.id != credential_data.id
+ ]
+
+ if base_name not in same_type_names:
+ return base_name
+
+ idx = 2
+ while f"{base_name} ({idx})" in same_type_names:
+ idx += 1
+ return f"{base_name} ({idx})"
+
+ async def upsert_credential(
+ self,
+ user_id: str,
+ credential_data: CredentialBase,
+ ) -> str:
+ """Create or update a credential record for the given user.
+
+ If `credential_data.id` is set and the record already exists, the
+ existing record's `data` field is updated in place (preserving
+ `created_at`). If the id is set but no record exists, a new record is
+ created with that id. If `credential_data.id` is ``None``, a new
+ record with a generated id is always created.
+
+ Args:
+ user_id (`str`):
+ The owner user id.
+ credential_data (`CredentialBase`):
+ Input data containing an optional `id` and the credential
+ `data` dict.
+
+ Returns:
+ `str`:
+ The id of the created or updated credential record.
+ """
+ if not credential_data.name:
+ credential_data.name = await self._generate_credential_name(
+ user_id,
+ credential_data,
+ )
+
+ data_dump = _dump_with_secrets(credential_data)
+
+ if credential_data.id:
+ key = self._key(
+ self.key_config.credential,
+ user_id=user_id,
+ credential_id=credential_data.id,
+ )
+ raw = await self._client.get(key)
+ if raw:
+ record = CredentialRecord.model_validate_json(raw)
+ record.data = data_dump
+ record.updated_at = datetime.now()
+ else:
+ record = CredentialRecord(
+ id=credential_data.id,
+ user_id=user_id,
+ data=data_dump,
+ )
+ else:
+ record = CredentialRecord(
+ user_id=user_id,
+ data=data_dump,
+ )
+
+ key = self._key(
+ self.key_config.credential,
+ user_id=user_id,
+ credential_id=record.id,
+ )
+ index_key = self._key(
+ self.key_config.credential_index,
+ user_id=user_id,
+ )
+ await self._set_with_ttl(key, record.model_dump_json())
+ await self._client.sadd(index_key, record.id)
+ return record.id
+
+ async def list_credentials(self, user_id: str) -> list[CredentialRecord]:
+ """Return all credential records belonging to the given user.
+
+ Reads the per-user credential index Set to obtain all ids, then
+ fetches each record individually. Records whose keys have expired or
+ been deleted externally are silently skipped.
+
+ Args:
+ user_id (`str`): The owner user id.
+
+ Returns:
+ `list[CredentialRecord]`: All credential records for the user.
+ """
+ index_key = self._key(
+ self.key_config.credential_index,
+ user_id=user_id,
+ )
+ ids = await self._client.smembers(index_key)
+ records = []
+ for cred_id in ids:
+ raw = await self._client.get(
+ self._key(
+ self.key_config.credential,
+ user_id=user_id,
+ credential_id=cred_id,
+ ),
+ )
+ if raw:
+ records.append(CredentialRecord.model_validate_json(raw))
+ return records
+
+ async def get_credential(
+ self,
+ user_id: str,
+ credential_id: str,
+ ) -> CredentialRecord | None:
+ """Fetch a single credential record by id."""
+ key = self._key(
+ self.key_config.credential,
+ user_id=user_id,
+ credential_id=credential_id,
+ )
+ raw = await self._client.get(key)
+ return CredentialRecord.model_validate_json(raw) if raw else None
+
+ async def delete_credential(
+ self,
+ user_id: str,
+ credential_id: str,
+ ) -> bool:
+ """Delete a credential record and remove it from the user's index.
+
+ Args:
+ user_id (`str`): The owner user id.
+ credential_id (`str`): The id of the credential to delete.
+
+ Returns:
+ `bool`: ``True`` if the record existed and was deleted,
+ ``False`` if it did not exist.
+ """
+ key = self._key(
+ self.key_config.credential,
+ user_id=user_id,
+ credential_id=credential_id,
+ )
+ index_key = self._key(
+ self.key_config.credential_index,
+ user_id=user_id,
+ )
+ deleted = await self._client.delete(key)
+ await self._client.srem(index_key, credential_id)
+ return deleted > 0
+
+ async def upsert_agent(
+ self,
+ user_id: str,
+ agent_record: AgentRecord,
+ ) -> str:
+ """Persist an agent record and register it in the user's agent index.
+
+ The caller is responsible for constructing the full `AgentRecord`
+ (including its `id`). If a record with the same id already exists it
+ will be overwritten.
+
+ Args:
+ user_id (`str`):
+ The owner user id.
+ agent_record (`AgentRecord`):
+ The fully-populated agent record to store.
+
+ Returns:
+ `str`:
+ The id of the stored agent record.
+ """
+ key = self._key(
+ self.key_config.agent,
+ user_id=user_id,
+ agent_id=agent_record.id,
+ )
+ index_key = self._key(self.key_config.agent_index, user_id=user_id)
+ await self._set_with_ttl(key, agent_record.model_dump_json())
+ await self._client.sadd(index_key, agent_record.id)
+ return agent_record.id
+
+ async def list_agents(self, user_id: str) -> list[AgentRecord]:
+ """Return all agent records belonging to the given user.
+
+ Reads the per-user agent index Set to obtain all ids, then fetches
+ each record individually. Records whose keys have expired or been
+ deleted externally are silently skipped.
+
+ Args:
+ user_id (`str`): The owner user id.
+
+ Returns:
+ `list[AgentRecord]`: All agent records for the user.
+ """
+ index_key = self._key(self.key_config.agent_index, user_id=user_id)
+ ids = await self._client.smembers(index_key)
+ records = []
+ for agent_id in ids:
+ raw = await self._client.get(
+ self._key(
+ self.key_config.agent,
+ user_id=user_id,
+ agent_id=agent_id,
+ ),
+ )
+ if raw:
+ records.append(AgentRecord.model_validate_json(raw))
+ return records
+
+ async def get_agent(
+ self,
+ user_id: str,
+ agent_id: str,
+ ) -> AgentRecord | None:
+ """Fetch a single agent record by id."""
+ key = self._key(
+ self.key_config.agent,
+ user_id=user_id,
+ agent_id=agent_id,
+ )
+ raw = await self._client.get(key)
+ return AgentRecord.model_validate_json(raw) if raw else None
+
+ async def delete_agent(self, user_id: str, agent_id: str) -> bool:
+ """Delete an agent record and cascade-delete its sessions and
+ schedules.
+
+ Removes all session records (and their lookup / index keys) that belong
+ to this agent, then removes all schedule records whose
+ ``data.agent_id`` matches. Finally, the agent record itself and its
+ entry in the per-user agent index are deleted.
+
+ Args:
+ user_id (`str`): The owner user id.
+ agent_id (`str`): The id of the agent to delete.
+
+ Returns:
+ `bool`: ``True`` if the agent record existed and was deleted,
+ ``False`` if it did not exist.
+ """
+ # Cascade: sessions
+ sessions = await self.list_sessions(user_id, agent_id)
+ for session in sessions:
+ await self.delete_session(user_id, agent_id, session.id)
+
+ # Cascade: schedules owned by this agent
+ schedules = await self.list_schedules(user_id)
+ for schedule in schedules:
+ if schedule.data.agent_id == agent_id:
+ await self.delete_schedule(user_id, schedule.id)
+
+ key = self._key(
+ self.key_config.agent,
+ user_id=user_id,
+ agent_id=agent_id,
+ )
+ index_key = self._key(self.key_config.agent_index, user_id=user_id)
+ deleted = await self._client.delete(key)
+ await self._client.srem(index_key, agent_id)
+ return deleted > 0
+
+ async def upsert_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ config: SessionConfig,
+ state: AgentState | None = None,
+ session_id: str | None = None,
+ source: SessionSource = SessionSource.USER,
+ source_schedule_id: str | None = None,
+ ) -> SessionRecord:
+ """Create or update a session for a (user, agent) pair.
+
+ When *session_id* is provided the existing session is updated.
+ When *session_id* is ``None`` a new session is always created.
+ """
+ if session_id:
+ key = self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=session_id,
+ )
+ raw = await self._client.get(key)
+ if raw:
+ record = SessionRecord.model_validate_json(raw)
+ record.config = config
+ if state is not None:
+ record.state = state
+ record.updated_at = datetime.now()
+ await self._set_with_ttl(key, record.model_dump_json())
+ return record
+
+ record = SessionRecord(
+ user_id=user_id,
+ agent_id=agent_id,
+ config=config,
+ source=source,
+ source_schedule_id=source_schedule_id,
+ state=state if state is not None else AgentState(),
+ )
+ key = self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=record.id,
+ )
+ index_key = self._key(
+ self.key_config.session_index,
+ user_id=user_id,
+ agent_id=agent_id,
+ )
+ await self._set_with_ttl(key, record.model_dump_json())
+ await self._client.sadd(index_key, record.id)
+
+ if source_schedule_id:
+ schedule_session_key = self._key(
+ self.key_config.schedule_session_index,
+ user_id=user_id,
+ schedule_id=source_schedule_id,
+ )
+ await self._client.sadd(schedule_session_key, record.id)
+
+ return record
+
+ async def update_session_state(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ state: AgentState,
+ ) -> None:
+ """Update only the mutable state of an existing session.
+
+ Raises:
+ KeyError: If the session does not exist.
+ """
+ key = self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=session_id,
+ )
+ raw = await self._client.get(key)
+ if not raw:
+ raise KeyError(f"Session {session_id!r} not found.")
+ record = SessionRecord.model_validate_json(raw)
+ record.state = state
+ record.updated_at = datetime.now()
+ await self._set_with_ttl(key, record.model_dump_json())
+
+ async def list_sessions(
+ self,
+ user_id: str,
+ agent_id: str,
+ ) -> list[SessionRecord]:
+ """Return all session records for a given (user, agent) pair.
+
+ Reads the per-agent session index Set to obtain all session ids, then
+ fetches each record individually. Records whose keys have expired or
+ been deleted externally are silently skipped.
+
+ Args:
+ user_id (`str`): The owner user id.
+ agent_id (`str`): The agent id whose sessions to list.
+
+ Returns:
+ `list[SessionRecord]`: All session records for the (user, agent)
+ pair.
+ """
+ index_key = self._key(
+ self.key_config.session_index,
+ user_id=user_id,
+ agent_id=agent_id,
+ )
+ ids = await self._client.smembers(index_key)
+ records = []
+ for session_id in ids:
+ raw = await self._client.get(
+ self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=session_id,
+ ),
+ )
+ if raw:
+ records.append(SessionRecord.model_validate_json(raw))
+ records.sort(key=lambda r: r.created_at, reverse=True)
+ return records
+
+ async def get_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> SessionRecord | None:
+ """Fetch a single session record by id."""
+ key = self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=session_id,
+ )
+ raw = await self._client.get(key)
+ if not raw:
+ return None
+ return SessionRecord.model_validate_json(raw)
+
+ async def delete_session(
+ self,
+ user_id: str,
+ agent_id: str,
+ session_id: str,
+ ) -> bool:
+ """Delete a session record and clean up all associated keys."""
+ key = self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=session_id,
+ )
+ raw = await self._client.get(key)
+ if not raw:
+ return False
+
+ record = SessionRecord.model_validate_json(raw)
+
+ index_key = self._key(
+ self.key_config.session_index,
+ user_id=user_id,
+ agent_id=agent_id,
+ )
+ msg_key = self._key(
+ self.key_config.messages,
+ user_id=user_id,
+ session_id=session_id,
+ )
+ await self._client.delete(key)
+ await self._client.srem(index_key, session_id)
+ await self._client.delete(msg_key)
+
+ if record.source_schedule_id:
+ schedule_session_key = self._key(
+ self.key_config.schedule_session_index,
+ user_id=user_id,
+ schedule_id=record.source_schedule_id,
+ )
+ await self._client.srem(schedule_session_key, session_id)
+
+ return True
+
+ async def list_sessions_by_schedule(
+ self,
+ user_id: str,
+ schedule_id: str,
+ ) -> list[SessionRecord]:
+ """Return all sessions created by a given schedule."""
+ schedule_session_key = self._key(
+ self.key_config.schedule_session_index,
+ user_id=user_id,
+ schedule_id=schedule_id,
+ )
+ ids = await self._client.smembers(schedule_session_key)
+ records = []
+ for session_id in ids:
+ raw = await self._client.get(
+ self._key(
+ self.key_config.session,
+ user_id=user_id,
+ session_id=session_id,
+ ),
+ )
+ if raw:
+ records.append(SessionRecord.model_validate_json(raw))
+ records.sort(key=lambda r: r.created_at, reverse=True)
+ return records
+
+ async def upsert_schedule(
+ self,
+ user_id: str,
+ record: ScheduleRecord,
+ ) -> str:
+ """Persist a cron task record and register it in the user and global
+ indexes."""
+ key = self._key(
+ self.key_config.schedule,
+ user_id=user_id,
+ schedule_id=record.id,
+ )
+ index_key = self._key(self.key_config.schedule_index, user_id=user_id)
+ await self._set_with_ttl(key, record.model_dump_json())
+ await self._client.sadd(index_key, record.id)
+ await self._client.sadd(
+ self.key_config.schedule_global_index,
+ f"{user_id}:{record.id}",
+ )
+ return record.id
+
+ async def get_schedule(
+ self,
+ user_id: str,
+ schedule_id: str,
+ ) -> ScheduleRecord | None:
+ """Fetch a single cron task record by id."""
+ key = self._key(
+ self.key_config.schedule,
+ user_id=user_id,
+ schedule_id=schedule_id,
+ )
+ raw = await self._client.get(key)
+ if not raw:
+ return None
+ return ScheduleRecord.model_validate_json(raw)
+
+ async def list_schedules(self, user_id: str) -> list[ScheduleRecord]:
+ """Return all cron task records belonging to the given user."""
+ index_key = self._key(
+ self.key_config.schedule_index,
+ user_id=user_id,
+ )
+ ids = await self._client.smembers(index_key)
+ records = []
+ for schedule_id in ids:
+ raw = await self._client.get(
+ self._key(
+ self.key_config.schedule,
+ user_id=user_id,
+ schedule_id=schedule_id,
+ ),
+ )
+ if raw:
+ records.append(ScheduleRecord.model_validate_json(raw))
+ return records
+
+ async def delete_schedule(self, user_id: str, schedule_id: str) -> bool:
+ """Delete a cron task record, cascade-delete its execution sessions,
+ and remove it from the user and global indexes."""
+ key = self._key(
+ self.key_config.schedule,
+ user_id=user_id,
+ schedule_id=schedule_id,
+ )
+ raw = await self._client.get(key)
+ if not raw:
+ return False
+
+ record = ScheduleRecord.model_validate_json(raw)
+
+ # Cascade: delete all sessions created by this schedule
+ sessions = await self.list_sessions_by_schedule(user_id, schedule_id)
+ for session in sessions:
+ await self.delete_session(
+ user_id,
+ record.agent_id,
+ session.id,
+ )
+
+ # Clean up the schedule session index key itself
+ schedule_session_key = self._key(
+ self.key_config.schedule_session_index,
+ user_id=user_id,
+ schedule_id=schedule_id,
+ )
+ await self._client.delete(schedule_session_key)
+
+ # Delete the schedule record and its index entries
+ index_key = self._key(self.key_config.schedule_index, user_id=user_id)
+ await self._client.delete(key)
+ await self._client.srem(index_key, schedule_id)
+ await self._client.srem(
+ self.key_config.schedule_global_index,
+ f"{user_id}:{schedule_id}",
+ )
+ return True
+
+ async def list_all_schedules(self) -> list[ScheduleRecord]:
+ """Return every schedule record across all users.
+
+ Reads the global schedule index (a Redis Set of ``user_id:schedule_id``
+ pairs) and fetches each record individually. Records whose keys have
+ expired or been deleted externally are silently skipped.
+
+ Returns:
+ `list[ScheduleRecord]`: All schedule records in the store.
+ """
+ entries = await self._client.smembers(
+ self.key_config.schedule_global_index,
+ )
+ records = []
+ for entry in entries:
+ user_id, schedule_id = entry.split(":", 1)
+ raw = await self._client.get(
+ self._key(
+ self.key_config.schedule,
+ user_id=user_id,
+ schedule_id=schedule_id,
+ ),
+ )
+ if raw:
+ records.append(ScheduleRecord.model_validate_json(raw))
+ return records
+
+ # ------------------------------------------------------------------
+ # Message persistence
+ # ------------------------------------------------------------------
+
+ def _message_key(self, user_id: str, session_id: str) -> str:
+ """Return the Redis List key for a session's messages."""
+ return self._key(
+ self.key_config.messages,
+ user_id=user_id,
+ session_id=session_id,
+ )
+
+ async def upsert_message(
+ self,
+ user_id: str,
+ session_id: str,
+ msg: Msg,
+ ) -> None:
+ """Persist a message to the session's message list."""
+ key = self._message_key(user_id, session_id)
+ last_raw = await self._client.lindex(key, -1)
+ if last_raw:
+ last_msg = Msg.model_validate_json(last_raw)
+ if last_msg.id == msg.id:
+ await self._client.lset(key, -1, msg.model_dump_json())
+ return
+ await self._client.rpush(key, msg.model_dump_json())
+
+ async def get_message(
+ self,
+ user_id: str,
+ session_id: str,
+ message_id: str,
+ ) -> Msg | None:
+ """Fetch a single message by id from the session's message list."""
+ key = self._message_key(user_id, session_id)
+ length = await self._client.llen(key)
+ for i in range(length - 1, -1, -1):
+ raw = await self._client.lindex(key, i)
+ if raw:
+ msg = Msg.model_validate_json(raw)
+ if msg.id == message_id:
+ return msg
+ return None
+
+ async def list_messages(
+ self,
+ user_id: str,
+ session_id: str,
+ offset: int = 0,
+ limit: int = 50,
+ ) -> list[Msg]:
+ """Return messages for a session with pagination."""
+ key = self._message_key(user_id, session_id)
+ raw_list = await self._client.lrange(key, offset, offset + limit - 1)
+ return [Msg.model_validate_json(raw) for raw in raw_list]
diff --git a/src/agentscope/app/storage/_utils.py b/src/agentscope/app/storage/_utils.py
new file mode 100644
index 000000000..6d08fe6d1
--- /dev/null
+++ b/src/agentscope/app/storage/_utils.py
@@ -0,0 +1,29 @@
+# -*- coding: utf-8 -*-
+"""The utils for storage."""
+
+from pydantic import BaseModel, SecretStr
+
+
+def _dump_with_secrets(model: BaseModel) -> dict:
+ """Dump the BaseModel instance with SecretStr fields. Used for
+ storage.
+
+ Args:
+ model (`BaseModel`):
+ The model instance to dump.
+
+ Returns:
+ `dict`:
+ The dumped JSON with secrets included.
+ """
+ # Use mode='json' so that Pydantic converts non-JSON-native types
+ # (e.g. datetime, UUID) to their JSON-compatible representations.
+ # SecretStr fields will be masked at this step.
+ result = model.model_dump(mode="json")
+
+ for field_name, _ in model.__class__.model_fields.items():
+ value = getattr(model, field_name)
+ if isinstance(value, SecretStr):
+ result[field_name] = value.get_secret_value()
+
+ return result
diff --git a/src/agentscope/credential/__init__.py b/src/agentscope/credential/__init__.py
index 912379148..7368f3b93 100644
--- a/src/agentscope/credential/__init__.py
+++ b/src/agentscope/credential/__init__.py
@@ -1,6 +1,7 @@
# -*- coding: utf-8 -*-
"""The credential module."""
+from ._base import CredentialBase
from ._anthropic import AnthropicCredential
from ._dashscope import DashScopeCredential
from ._deepseek import DeepSeekCredential
@@ -9,8 +10,11 @@ from ._moonshot import MoonshotCredential
from ._ollama import OllamaCredential
from ._openai import OpenAICredential
from ._xai import XAICredential
+from ._factory import CredentialFactory
+
__all__ = [
+ "CredentialBase",
"AnthropicCredential",
"DashScopeCredential",
"DeepSeekCredential",
@@ -19,22 +23,5 @@ __all__ = [
"OllamaCredential",
"OpenAICredential",
"XAICredential",
+ "CredentialFactory",
]
-
-
-def list_credential() -> list[dict]:
- """List the available credential and their schemas, used for frontend to
- render the credential form."""
-
- credentials = [
- AnthropicCredential,
- DashScopeCredential,
- DeepSeekCredential,
- GeminiCredential,
- MoonshotCredential,
- OllamaCredential,
- OpenAICredential,
- XAICredential,
- ]
-
- return [_.model_json_schema() for _ in credentials]
diff --git a/src/agentscope/credential/_anthropic.py b/src/agentscope/credential/_anthropic.py
index 8a007a94d..df5dd8987 100644
--- a/src/agentscope/credential/_anthropic.py
+++ b/src/agentscope/credential/_anthropic.py
@@ -14,7 +14,7 @@ class AnthropicCredential(CredentialBase):
"""The Anthropic credential model."""
model_config = ConfigDict(
- title="Anthropic Credential",
+ title="Anthropic API",
)
type: Literal["anthropic_credential"] = "anthropic_credential"
diff --git a/src/agentscope/credential/_base.py b/src/agentscope/credential/_base.py
index a4db8ccfb..2bcd918b3 100644
--- a/src/agentscope/credential/_base.py
+++ b/src/agentscope/credential/_base.py
@@ -17,6 +17,11 @@ class CredentialBase(BaseModel):
description="The credential id",
)
+ name: str = Field(
+ default="",
+ description="User-facing display name for this credential.",
+ )
+
@classmethod
def get_chat_model_class(cls) -> Type["ChatModelBase"]:
"""Return the :class:`ChatModelBase` subclass that consumes this
@@ -31,7 +36,8 @@ class CredentialBase(BaseModel):
f"{cls.__name__} must implement ``get_chat_model_class``.",
)
- def list_models(self) -> list["ModelCard"]:
+ @classmethod
+ def list_models(cls) -> list["ModelCard"]:
"""List the candidate chat models that are available under this
credential. The default implementation delegates to the
:meth:`ChatModelBase.list_models` of the class returned by
@@ -41,4 +47,4 @@ class CredentialBase(BaseModel):
`list[ModelCard]`:
A list of candidate models described by their model cards.
"""
- return self.get_chat_model_class().list_models()
+ return cls.get_chat_model_class().list_models()
diff --git a/src/agentscope/credential/_dashscope.py b/src/agentscope/credential/_dashscope.py
index dac93481e..1289acd41 100644
--- a/src/agentscope/credential/_dashscope.py
+++ b/src/agentscope/credential/_dashscope.py
@@ -2,7 +2,7 @@
"""The DashScope credential."""
from typing import Literal, Type, TYPE_CHECKING
-from pydantic import Field, SecretStr
+from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
@@ -15,6 +15,10 @@ _DASHSCOPE_BASE_URL = "https://dashscope.aliyuncs.com/compatible-mode/v1"
class DashScopeCredential(CredentialBase):
"""The credential for DashScope API."""
+ model_config = ConfigDict(
+ title="DashScope API",
+ )
+
type: Literal["dashscope_credential"] = "dashscope_credential"
"""The type of the credential."""
diff --git a/src/agentscope/credential/_deepseek.py b/src/agentscope/credential/_deepseek.py
index e337621a8..d12088cb2 100644
--- a/src/agentscope/credential/_deepseek.py
+++ b/src/agentscope/credential/_deepseek.py
@@ -2,7 +2,7 @@
"""The DeepSeek credential."""
from typing import Literal, Type, TYPE_CHECKING
-from pydantic import Field, SecretStr
+from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
@@ -15,6 +15,10 @@ _DEEPSEEK_BASE_URL = "https://api.deepseek.com"
class DeepSeekCredential(CredentialBase):
"""The DeepSeek credential model."""
+ model_config = ConfigDict(
+ title="DeepSeek API",
+ )
+
type: Literal["deepseek_credential"] = "deepseek_credential"
"""The credential type."""
diff --git a/src/agentscope/credential/_factory.py b/src/agentscope/credential/_factory.py
new file mode 100644
index 000000000..2ec7cc551
--- /dev/null
+++ b/src/agentscope/credential/_factory.py
@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+"""The credential factory class."""
+from typing import Annotated, Type, Union, get_args, get_type_hints
+
+from pydantic import TypeAdapter, Field
+
+from ._anthropic import AnthropicCredential
+from ._dashscope import DashScopeCredential
+from ._deepseek import DeepSeekCredential
+from ._gemini import GeminiCredential
+from ._moonshot import MoonshotCredential
+from ._ollama import OllamaCredential
+from ._openai import OpenAICredential
+from ._xai import XAICredential
+from ._base import CredentialBase
+
+
+class CredentialFactory:
+ """Registry and deserializer for :class:`CredentialBase` subclasses.
+
+ Built-in credential types are pre-registered. Call
+ :meth:`register_credential` to add custom types before starting the app.
+
+ Usage::
+
+ # Deserialize from storage
+ credential = CredentialFactory.from_dict(record.data)
+
+ # Register a custom type
+ CredentialFactory.register_credential(MyCredential)
+
+ # List schemas for the frontend form
+ schemas = CredentialFactory.list_schemas()
+ """
+
+ _classes: list[Type[CredentialBase]] = [
+ AnthropicCredential,
+ DashScopeCredential,
+ DeepSeekCredential,
+ GeminiCredential,
+ MoonshotCredential,
+ OllamaCredential,
+ OpenAICredential,
+ XAICredential,
+ ]
+ _adapter: TypeAdapter[CredentialBase] | None = None
+
+ @classmethod
+ def _get_adapter(cls) -> TypeAdapter[CredentialBase]:
+ if cls._adapter is None:
+ union = Annotated[ # type: ignore[valid-type]
+ Union[tuple(cls._classes)],
+ Field(discriminator="type"),
+ ]
+ cls._adapter = TypeAdapter(union)
+ return cls._adapter
+
+ @classmethod
+ def register_credential(cls, credential_cls: Type[CredentialBase]) -> None:
+ """Register a custom :class:`CredentialBase` subclass.
+
+ The class must define a ``type`` field with a unique ``Literal``
+ default so Pydantic can use it as a discriminator.
+
+ Args:
+ credential_cls: The subclass to register.
+ """
+ cls._classes.append(credential_cls)
+ cls._adapter = None # invalidate so it's rebuilt on next use
+
+ @classmethod
+ def from_dict(cls, data: dict) -> CredentialBase:
+ """Deserialize a credential dict (from storage) to a typed instance.
+
+ Args:
+ data: Raw dict containing a ``"type"`` key.
+
+ Returns:
+ A typed :class:`CredentialBase` subclass instance.
+ """
+ return cls._get_adapter().validate_python(data)
+
+ @classmethod
+ def get_credential_class(
+ cls,
+ provider: str,
+ ) -> Type[CredentialBase] | None:
+ """Return the credential class for the given provider type, or None.
+
+ Args:
+ provider: The ``type`` discriminator value (e.g. ``"openai"``).
+
+ Returns:
+ The matching :class:`CredentialBase` subclass, or ``None`` if not
+ found.
+ """
+ for c in cls._classes:
+ hints = get_type_hints(c)
+ type_hint = hints.get("type")
+ if type_hint is None:
+ continue
+ args = get_args(type_hint)
+
+ if args and args[0] == provider:
+ return c
+ return None
+
+ @classmethod
+ def list_schemas(cls) -> list[dict]:
+ """Return JSON schemas for all registered credential types.
+
+ Used by the frontend to render credential forms dynamically.
+ """
+ return [c.model_json_schema() for c in cls._classes]
diff --git a/src/agentscope/credential/_gemini.py b/src/agentscope/credential/_gemini.py
index 6b281e443..67bd65656 100644
--- a/src/agentscope/credential/_gemini.py
+++ b/src/agentscope/credential/_gemini.py
@@ -2,7 +2,7 @@
"""The Google Gemini credential."""
from typing import Literal, Type, TYPE_CHECKING
-from pydantic import Field, SecretStr
+from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
@@ -13,6 +13,10 @@ if TYPE_CHECKING:
class GeminiCredential(CredentialBase):
"""The Google Gemini credential model."""
+ model_config = ConfigDict(
+ title="Gemini API",
+ )
+
type: Literal["gemini_credential"] = "gemini_credential"
"""The credential type."""
diff --git a/docs/tutorial/zh_CN/src/README.md b/src/agentscope/credential/_kimi.py
similarity index 100%
rename from docs/tutorial/zh_CN/src/README.md
rename to src/agentscope/credential/_kimi.py
diff --git a/src/agentscope/credential/_ollama.py b/src/agentscope/credential/_ollama.py
index 43154095e..84bdee4f1 100644
--- a/src/agentscope/credential/_ollama.py
+++ b/src/agentscope/credential/_ollama.py
@@ -2,7 +2,7 @@
"""The Ollama credential."""
from typing import Literal, Type, TYPE_CHECKING
-from pydantic import Field
+from pydantic import ConfigDict, Field
from ._base import CredentialBase
@@ -13,6 +13,10 @@ if TYPE_CHECKING:
class OllamaCredential(CredentialBase):
"""The Ollama credential model (connection settings)."""
+ model_config = ConfigDict(
+ title="Ollama API",
+ )
+
type: Literal["ollama_credential"] = "ollama_credential"
"""The credential type."""
diff --git a/src/agentscope/credential/_openai.py b/src/agentscope/credential/_openai.py
index 24dcc156c..a855ee66a 100644
--- a/src/agentscope/credential/_openai.py
+++ b/src/agentscope/credential/_openai.py
@@ -2,7 +2,7 @@
"""The OpenAI credential."""
from typing import Literal, Type, TYPE_CHECKING
-from pydantic import Field, SecretStr
+from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
@@ -13,6 +13,10 @@ if TYPE_CHECKING:
class OpenAICredential(CredentialBase):
"""The OpenAI credential model."""
+ model_config = ConfigDict(
+ title="OpenAI API",
+ )
+
type: Literal["openai_credential"] = "openai_credential"
"""The credential type."""
diff --git a/src/agentscope/credential/_xai.py b/src/agentscope/credential/_xai.py
index 17dbb1d80..c1f67357a 100644
--- a/src/agentscope/credential/_xai.py
+++ b/src/agentscope/credential/_xai.py
@@ -2,7 +2,7 @@
"""The xAI credential."""
from typing import Literal, Type, TYPE_CHECKING
-from pydantic import Field, SecretStr
+from pydantic import ConfigDict, Field, SecretStr
from ._base import CredentialBase
@@ -13,6 +13,10 @@ if TYPE_CHECKING:
class XAICredential(CredentialBase):
"""The xAI credential model."""
+ model_config = ConfigDict(
+ title="xAI API",
+ )
+
type: Literal["xai_credential"] = "xai_credential"
"""The credential type."""
diff --git a/src/agentscope/event/_event.py b/src/agentscope/event/_event.py
index 41ef96075..8b491052d 100644
--- a/src/agentscope/event/_event.py
+++ b/src/agentscope/event/_event.py
@@ -300,6 +300,8 @@ class ToolResultDataDeltaEvent(EventBase):
"""ID of the reply message this tool result belongs to."""
tool_call_id: str
"""ID of the corresponding tool call."""
+ block_id: str = Field(default_factory=lambda: uuid.uuid4().hex)
+ """Unique identifier of the data block created by this event."""
media_type: str
"""MIME type of the binary content."""
data: str | None = None
@@ -324,7 +326,7 @@ class ToolResultEndEvent(EventBase):
class ExceedMaxItersEvent(EventBase):
- """Exceeded max iterations event."""
+ """Exceeded max iteration event."""
type: Literal[EventType.EXCEED_MAX_ITERS] = EventType.EXCEED_MAX_ITERS
"""Event type."""
diff --git a/src/agentscope/message/_base.py b/src/agentscope/message/_base.py
index 93e689f66..5fa1acf17 100644
--- a/src/agentscope/message/_base.py
+++ b/src/agentscope/message/_base.py
@@ -2,27 +2,34 @@
"""The message class in agentscope."""
import uuid
from datetime import datetime
-from typing import Literal, List, overload, Sequence, Self
+from typing import Literal, List, overload, Sequence, Self, TYPE_CHECKING, Any
from pydantic import BaseModel, Field, model_validator
from ._block import (
TextBlock,
- ToolCallBlock,
+ ThinkingBlock,
+ HintBlock,
DataBlock,
- ContentBlock,
+ Base64Source,
+ URLSource,
+ ToolCallBlock,
+ ToolCallState,
ToolResultBlock,
+ ToolResultState,
+ ContentBlock,
ContentBlockTypes,
- HintBlock,
- ThinkingBlock,
)
+from .._logging import logger
+if TYPE_CHECKING:
+ from ..event import AgentEvent
+else:
+ AgentEvent = Any
-def _assert_user_content_blocks(content: str | Sequence[ContentBlock]) -> None:
- """Assert that the content blocks in user message are valid."""
- if isinstance(content, str):
- return
+def _assert_user_content_blocks(content: Sequence[ContentBlock]) -> None:
+ """Assert that the content blocks in user message are valid."""
for block in content:
if block.type not in ["text", "data"]:
raise ValueError(
@@ -31,25 +38,29 @@ def _assert_user_content_blocks(content: str | Sequence[ContentBlock]) -> None:
def _assert_system_content_blocks(
- content: str | Sequence[ContentBlock],
+ content: Sequence[ContentBlock],
) -> None:
"""Assert that the content blocks in system message are valid."""
- if isinstance(content, str):
- return
-
for block in content:
if block.type not in ["text"]:
raise ValueError("System message can only contain text blocks.")
+def _to_blocks(content: str | list) -> list:
+ """Convert a plain string to a single-element TextBlock list."""
+ if isinstance(content, str):
+ return [TextBlock(text=content)]
+ return content
+
+
class Msg(BaseModel):
"""The message class in AgentScope, responsible for information storage
and transmission among different agents."""
name: str
"""The name of the sender."""
- content: str | list[ContentBlock]
- """The message content, a string or a list of content blocks."""
+ content: list[ContentBlock]
+ """The message content as a list of content blocks."""
role: Literal["user", "assistant", "system"]
"""The role of the sender."""
id: str = Field(default_factory=lambda: uuid.uuid4().hex)
@@ -58,6 +69,8 @@ class Msg(BaseModel):
"""The metadata of the message"""
created_at: str = Field(default_factory=lambda: datetime.now().isoformat())
"""The creation time of the message"""
+ finished_at: str | None = Field(default=None)
+ """The finished time of the message"""
@model_validator(mode="after")
def validate_role_content(self) -> Self:
@@ -89,41 +102,16 @@ class Msg(BaseModel):
`True` if there are content blocks of the given type, `False`
otherwise.
"""
- blocks = self.get_content_blocks()
if block_type is None:
- return len(blocks) > 0
+ return len(self.content) > 0
typs = [block_type] if isinstance(block_type, str) else block_type
- for _ in list(self.get_content_blocks()):
- if _.type in typs:
- return True
- return False
+ return any(b.type in typs for b in self.content)
def get_text_content(self, separator: str = "\n") -> str | None:
- """Get the pure text blocks from the message content.
-
- Args:
- separator (`str`, defaults to `\n`):
- The separator to use when concatenating multiple text blocks.
- Defaults to newline character.
-
- Returns:
- `str | None`:
- The concatenated text content, or `None` if there is no text
- content.
- """
- if isinstance(self.content, str):
- return self.content
-
- gathered_text = []
- for block in self.content:
- if block.type == "text":
- gathered_text.append(block.text)
-
- if gathered_text:
- return separator.join(gathered_text)
-
- return None
+ """Get the concatenated text from all TextBlocks."""
+ gathered = [b.text for b in self.content if b.type == "text"]
+ return separator.join(gathered) if gathered else None
@overload
def get_content_blocks(
@@ -178,8 +166,7 @@ class Msg(BaseModel):
self,
block_type: ContentBlockTypes | List[ContentBlockTypes] | None = None,
) -> Sequence[ContentBlock]:
- """Get the content in block format. If the content is a string,
- it will be converted to a text block.
+ """Get content blocks, optionally filtered by type.
Args:
block_type (`ContentBlockTypes | List[ContentBlockTypes] | None`, \
@@ -191,21 +178,230 @@ class Msg(BaseModel):
`List[ContentBlock]`:
The content blocks.
"""
- blocks = []
- if isinstance(self.content, str):
- blocks.append(
- TextBlock(text=self.content),
+ blocks: list[ContentBlock] = self.content or []
+ if isinstance(block_type, str):
+ blocks = [b for b in blocks if b.type == block_type]
+ elif isinstance(block_type, list):
+ blocks = [b for b in blocks if b.type in block_type]
+ return blocks
+
+ def _find_block(
+ self,
+ block_type: str,
+ block_id: str,
+ ) -> ContentBlock | None:
+ """Find a block in content by type and id."""
+ for block in self.content:
+ if block.type == block_type and block.id == block_id:
+ return block
+ return None
+
+ def append_event(self, event: AgentEvent) -> Self:
+ """Update the message by applying a streaming event.
+
+ Only ``self.content`` and ``self.finished_at`` are ever modified.
+ Events whose ``reply_id`` does not match ``self.id`` are skipped with
+ a warning. Block-level delta/end events whose target block cannot be
+ found are also skipped with a warning.
+
+ Args:
+ event (`AgentEvent`):
+ The event to apply.
+ """
+ from ..event import EventType # local import to avoid circular dep
+
+ if event.reply_id != self.id:
+ logger.warning(
+ "Event %s with reply_id %r does not match message id %r, "
+ "skipping.",
+ event.__class__.__name__,
+ event.reply_id,
+ self.id,
)
- else:
- blocks = self.content or []
+ return self
+
+ match event.type:
+ case EventType.REPLY_END:
+ self.finished_at = event.created_at
+
+ case EventType.TEXT_BLOCK_START:
+ self.content.append(TextBlock(id=event.block_id, text=""))
+
+ case EventType.TEXT_BLOCK_DELTA:
+ block = self._find_block("text", event.block_id)
+ if block is None:
+ logger.warning(
+ "TextBlock %r not found, skipping.",
+ event.block_id,
+ )
+ else:
+ block.text += event.delta
+
+ case EventType.TEXT_BLOCK_END:
+ pass
- if isinstance(block_type, str):
- blocks = [_ for _ in blocks if _.type == block_type]
+ case EventType.DATA_BLOCK_START:
+ self.content.append(
+ DataBlock(
+ id=event.block_id,
+ source=Base64Source(
+ data="",
+ media_type=event.media_type,
+ ),
+ ),
+ )
+
+ case EventType.DATA_BLOCK_DELTA:
+ block = self._find_block("data", event.block_id)
+ if block is None:
+ logger.warning(
+ "DataBlock %s not found, skipping.",
+ event.block_id,
+ )
+ elif event.data:
+ block.source.data += event.data
+
+ case EventType.DATA_BLOCK_END:
+ pass
- elif isinstance(block_type, list):
- blocks = [_ for _ in blocks if _.type in block_type]
+ case EventType.THINKING_BLOCK_START:
+ self.content.append(
+ ThinkingBlock(id=event.block_id, thinking=""),
+ )
+
+ case EventType.THINKING_BLOCK_DELTA:
+ block = self._find_block("thinking", event.block_id)
+ if block is None:
+ logger.warning(
+ "ThinkingBlock %r not found, skipping.",
+ event.block_id,
+ )
+ else:
+ block.thinking += event.delta
+
+ case EventType.THINKING_BLOCK_END:
+ pass
- return blocks
+ case EventType.TOOL_CALL_START:
+ self.content.append(
+ ToolCallBlock(
+ id=event.tool_call_id,
+ name=event.tool_call_name,
+ input="",
+ ),
+ )
+
+ case EventType.TOOL_CALL_DELTA:
+ block = self._find_block("tool_call", event.tool_call_id)
+ if block is None:
+ logger.warning(
+ "ToolCallBlock %r not found, skipping.",
+ event.tool_call_id,
+ )
+ else:
+ assert isinstance(block, ToolCallBlock)
+ block.input += event.delta
+
+ case EventType.TOOL_CALL_END:
+ pass
+
+ case EventType.TOOL_RESULT_START:
+ self.content.append(
+ ToolResultBlock(
+ id=event.tool_call_id,
+ name=event.tool_call_name,
+ output=[],
+ state=ToolResultState.RUNNING,
+ ),
+ )
+
+ case EventType.TOOL_RESULT_TEXT_DELTA:
+ block = self._find_block("tool_result", event.tool_call_id)
+ if block is None:
+ logger.warning(
+ "ToolResultBlock %r not found, skipping.",
+ event.tool_call_id,
+ )
+ else:
+ assert isinstance(block, ToolResultBlock)
+ if isinstance(block.output, str):
+ block.output = [TextBlock(text=block.output)]
+ # Append the text
+ if not block.output or block.output[-1].type != "text":
+ block.output.append(TextBlock(text=event.delta))
+ else:
+ block.output[-1].text += event.delta
+
+ case EventType.TOOL_RESULT_DATA_DELTA:
+ block = self._find_block("tool_result", event.tool_call_id)
+ if block is None:
+ logger.warning(
+ "ToolResultBlock %r not found, skipping.",
+ event.tool_call_id,
+ )
+ else:
+ assert isinstance(block, ToolResultBlock)
+ if isinstance(block.output, str):
+ block.output = [TextBlock(text=block.output)]
+ src = (
+ Base64Source(
+ data=event.data,
+ media_type=event.media_type,
+ )
+ if event.data is not None
+ else URLSource(
+ url=str(event.url),
+ media_type=event.media_type,
+ )
+ )
+ block.output.append(
+ DataBlock(id=event.block_id, source=src),
+ )
+
+ case EventType.TOOL_RESULT_END:
+ block = self._find_block("tool_result", event.tool_call_id)
+ if block is None:
+ logger.warning(
+ "ToolResultBlock %r not found, skipping.",
+ event.tool_call_id,
+ )
+ else:
+ assert isinstance(block, ToolResultBlock)
+ block.state = event.state
+
+ case EventType.REQUIRE_USER_CONFIRM:
+ for tool_call in event.tool_calls:
+ b = self._find_block("tool_call", tool_call.id)
+ if b is not None:
+ assert isinstance(b, ToolCallBlock)
+ # Update the state
+ b.state = ToolCallState.ASKING
+ # Record the suggestions
+ b.suggested_rules = tool_call.suggested_rules
+
+ case EventType.USER_CONFIRM_RESULT:
+ for result in event.confirm_results:
+ b = self._find_block("tool_call", result.tool_call.id)
+ if b is not None:
+ assert isinstance(b, ToolCallBlock)
+ b.state = (
+ ToolCallState.ALLOWED
+ if result.confirmed
+ else ToolCallState.FINISHED
+ )
+
+ case EventType.REQUIRE_EXTERNAL_EXECUTION:
+ for tool_call in event.tool_calls:
+ b = self._find_block("tool_call", tool_call.id)
+ if b is not None:
+ assert isinstance(b, ToolCallBlock)
+ b.state = ToolCallState.SUBMITTED
+
+ case EventType.EXTERNAL_EXECUTION_RESULT:
+ for result in event.execution_results:
+ self.content.append(result)
+
+ return self
def UserMsg(
@@ -213,33 +409,45 @@ def UserMsg(
content: str | list[TextBlock | DataBlock],
metadata: dict | None = None,
created_at: str | None = None,
+ finished_at: str | None = None,
id: str | None = None, # pylint: disable=redefined-builtin
) -> Msg:
- """Create a user message with role "user".
+ """Create a user message with role ``"user"``.
Args:
name (`str`):
- The name of the message sender.
+ The name of the sender.
content (`str | list[TextBlock | DataBlock]`):
- The content of the message. It can be a string or a list of
- TextBlock or DataBlock.
+ The message content. A plain string will be automatically wrapped
+ in a :class:`TextBlock`. Only :class:`TextBlock` and
+ :class:`DataBlock` are allowed for user messages.
metadata (`dict | None`, optional):
- The metadata of the message. Defaults to `None`.
+ Arbitrary key-value metadata attached to the message. Defaults to
+ an empty dict when not provided.
created_at (`str | None`, optional):
- The creation time of the message in ISO format. Defaults to `None`.
+ ISO-format timestamp for when the message was created. Defaults to
+ the current time when not provided.
+ finished_at (`str | None`, optional):
+ ISO-format timestamp for when the message was finished. Defaults to
+ the same value as ``created_at`` when not provided.
id (`str | None`, optional):
- The id of the message. Defaults to `None`.
+ A unique identifier for the message. A random UUID hex string is
+ generated when not provided.
+
Returns:
`Msg`:
- The created user message.
+ A :class:`Msg` instance with ``role="user"``.
"""
-
+ created_at = created_at or datetime.now().isoformat()
+ if finished_at is None:
+ finished_at = created_at
return Msg(
name=name,
- content=content,
+ content=_to_blocks(content),
role="user",
metadata=metadata or {},
- created_at=created_at or datetime.now().isoformat(),
+ created_at=created_at,
+ finished_at=finished_at,
id=id or uuid.uuid4().hex,
)
@@ -249,33 +457,42 @@ def AssistantMsg(
content: str | list[ContentBlock],
metadata: dict | None = None,
created_at: str | None = None,
+ finished_at: str | None = None,
id: str | None = None, # pylint: disable=redefined-builtin
) -> Msg:
- """Create an assistant message with role "assistant".
+ """Create an assistant message with role ``"assistant"``.
Args:
name (`str`):
- The name of the message sender.
+ The name of the sender.
content (`str | list[ContentBlock]`):
- The content of the message. It can be a string or a list of
- ContentBlock.
+ The message content. A plain string will be automatically wrapped
+ in a :class:`TextBlock`. Any :class:`ContentBlock` subtype is
+ permitted for assistant messages.
metadata (`dict | None`, optional):
- The metadata of the message. Defaults to `None`.
+ Arbitrary key-value metadata attached to the message. Defaults to
+ an empty dict when not provided.
created_at (`str | None`, optional):
- The creation time of the message in ISO format. Defaults to `None`.
+ ISO-format timestamp for when the message was created. Defaults to
+ the current time when not provided.
+ finished_at (`str | None`, optional):
+ ISO-format timestamp for when the message was finished. Not set by
+ default for assistant messages.
id (`str | None`, optional):
- The unique identifier of the message.
+ A unique identifier for the message. A random UUID hex string is
+ generated when not provided.
Returns:
`Msg`:
- The created assistant message.
+ A :class:`Msg` instance with ``role="assistant"``.
"""
return Msg(
name=name,
- content=content,
+ content=_to_blocks(content),
role="assistant",
metadata=metadata or {},
created_at=created_at or datetime.now().isoformat(),
+ finished_at=finished_at,
id=id or uuid.uuid4().hex,
)
@@ -285,29 +502,44 @@ def SystemMsg(
content: str | list[TextBlock],
metadata: dict | None = None,
created_at: str | None = None,
+ finished_at: str | None = None,
+ id: str | None = None, # pylint: disable=redefined-builtin
) -> Msg:
- """Create a system message with role "system".
+ """Create a system message with role ``"system"``.
Args:
name (`str`):
- The name of the message sender.
+ The name of the sender.
content (`str | list[TextBlock]`):
- The content of the message. It can be a string or a list of
- TextBlock.
+ The message content. A plain string will be automatically wrapped
+ in a :class:`TextBlock`. Only :class:`TextBlock` is allowed for
+ system messages.
metadata (`dict | None`, optional):
- The metadata of the message. Defaults to `None`.
+ Arbitrary key-value metadata attached to the message. Defaults to
+ an empty dict when not provided.
created_at (`str | None`, optional):
- The creation time of the message in ISO format. Defaults to `None`.
+ ISO-format timestamp for when the message was created. Defaults to
+ the current time when not provided.
+ finished_at (`str | None`, optional):
+ ISO-format timestamp for when the message was finished. Defaults to
+ the same value as ``created_at`` when not provided.
+ id (`str | None`, optional):
+ A unique identifier for the message. A random UUID hex string is
+ generated when not provided.
Returns:
`Msg`:
- The created system message.
+ A :class:`Msg` instance with ``role="system"``.
"""
-
+ created_at = created_at or datetime.now().isoformat()
+ if finished_at is None:
+ finished_at = created_at
return Msg(
name=name,
- content=content,
+ content=_to_blocks(content),
role="system",
metadata=metadata or {},
- created_at=created_at or datetime.now().isoformat(),
+ created_at=created_at,
+ finished_at=finished_at,
+ id=id or uuid.uuid4().hex,
)
diff --git a/src/agentscope/message/_block.py b/src/agentscope/message/_block.py
index 2b557f0b9..bd71ef0a3 100644
--- a/src/agentscope/message/_block.py
+++ b/src/agentscope/message/_block.py
@@ -5,6 +5,8 @@ from enum import StrEnum
from typing import Literal, List, TypeAlias
from pydantic import BaseModel, Field, AnyUrl, field_serializer, ConfigDict
+from agentscope.permission import PermissionRule
+
class TextBlock(BaseModel):
"""The text block."""
@@ -142,6 +144,9 @@ class ToolCallBlock(BaseModel):
submitted
└── ExternalExecutionResultEvent received ─────► finished
"""
+ suggested_rules: list[PermissionRule] = Field(default_factory=list)
+ """The suggestions for this tool call when asking user, used to maintain
+ the suggestions across requests."""
class ToolResultState(StrEnum):
diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.py
index b029793ef..d898ddea4 100644
--- a/src/agentscope/middleware/__init__.py
+++ b/src/agentscope/middleware/__init__.py
@@ -2,10 +2,7 @@
"""Middleware system for AgentScope agents."""
from ._base import MiddlewareBase
-from ._tracing import TracingMiddleware, setup_tracing
__all__ = [
"MiddlewareBase",
- "TracingMiddleware",
- "setup_tracing",
]
diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.py
index 3e8968cf1..bec7d510c 100644
--- a/src/agentscope/middleware/_base.py
+++ b/src/agentscope/middleware/_base.py
@@ -71,9 +71,10 @@ class MiddlewareBase: # pylint: disable=unused-argument
Args:
agent: The Agent instance executing this middleware
input_kwargs: Dictionary containing:
- - msgs: Msg | list[Msg] | None
- - event: UserConfirmResultEvent |
- ExternalExecutionResultEvent | None
+ - inputs: Msg | list[Msg] | UserConfirmResultEvent |
+ ExternalExecutionResultEvent | None — the unified inputs
+ that trigger this reply (new message(s), a resumption
+ event from a previous outside interaction, or None).
next_handler: Callable that executes the next middleware or
original method
@@ -114,17 +115,40 @@ class MiddlewareBase: # pylint: disable=unused-argument
input_kwargs: dict,
next_handler: Callable[..., AsyncGenerator],
) -> AsyncGenerator:
- """Hook for intercepting tool call execution.
+ """Hook for intercepting the raw tool execution.
+
+ This hook wraps **only** the ``toolkit.call_tool`` call — i.e. the
+ pure I/O execution layer. Permission checking, input validation, and
+ context writes are handled by the agent **outside** this hook and are
+ therefore not visible here.
+
+ This separation makes it safe to offload the ``next_handler``
+ coroutine to a background task: it will never mutate agent context
+ on its own.
+
+ .. note::
+ Tools with ``is_state_injected=True`` receive the live
+ ``agent.state`` object. Offloading such tools to a background
+ task may cause concurrent state mutations — guard against this
+ in your middleware implementation.
Args:
- agent: The Agent instance executing this middleware
- input_kwargs: Dictionary containing:
- - tool_call: ToolCallBlock
- next_handler: Callable that executes the next middleware or
- original method
+ agent (`Agent`):
+ The Agent instance executing this middleware.
+ input_kwargs (`dict`):
+ Dictionary containing:
+
+ - ``tool_call`` (``ToolCallBlock``): the tool call to execute.
+ By the time this hook is invoked the tool call has already
+ been validated and permitted.
+ next_handler (`Callable[..., AsyncGenerator]`):
+ Callable that executes the next middleware or
+ ``_acting_impl``.
Yields:
- Events from the tool execution process
+ `ToolChunk | ToolResponse`:
+ Intermediate ``ToolChunk`` objects followed by a final
+ ``ToolResponse`` produced by the tool.
"""
raise RuntimeError(
f"{type(self).__name__} does not implement on_acting",
diff --git a/src/agentscope/middleware/_tracing/__init__.py b/src/agentscope/middleware/_tracing/__init__.py
deleted file mode 100644
index 70811c8d2..000000000
--- a/src/agentscope/middleware/_tracing/__init__.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The tracing interface class in agentscope."""
-
-from ._setup import setup_tracing
-from ._trace import TracingMiddleware
-
-__all__ = [
- "setup_tracing",
- "TracingMiddleware",
-]
diff --git a/src/agentscope/middleware/_tracing/_attributes.py b/src/agentscope/middleware/_tracing/_attributes.py
deleted file mode 100644
index eb5fe3673..000000000
--- a/src/agentscope/middleware/_tracing/_attributes.py
+++ /dev/null
@@ -1,190 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The tracing types class in agentscope."""
-from opentelemetry.semconv._incubating.attributes import (
- gen_ai_attributes as GenAIAttributes,
-)
-
-
-class SpanAttributes:
- """The span attributes."""
-
- # GenAI Common Attributes
- GEN_AI_CONVERSATION_ID = GenAIAttributes.GEN_AI_CONVERSATION_ID
- """The gen ai conversation ID."""
-
- GEN_AI_OPERATION_NAME = GenAIAttributes.GEN_AI_OPERATION_NAME
- """The gen ai operation name."""
-
- GEN_AI_PROVIDER_NAME = GenAIAttributes.GEN_AI_PROVIDER_NAME
- """The gen ai provider name."""
-
- # GenAI Request Attributes
- GEN_AI_REQUEST_MODEL = GenAIAttributes.GEN_AI_REQUEST_MODEL
- """The gen ai request model."""
-
- GEN_AI_REQUEST_TEMPERATURE = GenAIAttributes.GEN_AI_REQUEST_TEMPERATURE
- """The gen ai request temperature."""
-
- GEN_AI_REQUEST_TOP_P = GenAIAttributes.GEN_AI_REQUEST_TOP_P
- """The gen ai request top_p."""
-
- GEN_AI_REQUEST_TOP_K = GenAIAttributes.GEN_AI_REQUEST_TOP_K
- """The gen ai request top_k."""
-
- GEN_AI_REQUEST_MAX_TOKENS = GenAIAttributes.GEN_AI_REQUEST_MAX_TOKENS
- """The gen ai request max_tokens."""
-
- GEN_AI_REQUEST_PRESENCE_PENALTY = (
- GenAIAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY
- )
- """The gen ai request presence_penalty."""
-
- GEN_AI_REQUEST_FREQUENCY_PENALTY = (
- GenAIAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY
- )
- """The gen ai request frequency_penalty."""
-
- GEN_AI_REQUEST_STOP_SEQUENCES = (
- GenAIAttributes.GEN_AI_REQUEST_STOP_SEQUENCES
- )
- """The gen ai request stop_sequences."""
-
- GEN_AI_REQUEST_SEED = GenAIAttributes.GEN_AI_REQUEST_SEED
- """The gen ai request seed."""
-
- # GenAI Response Attributes
- GEN_AI_RESPONSE_ID = GenAIAttributes.GEN_AI_RESPONSE_ID
- """The gen ai response ID."""
-
- GEN_AI_RESPONSE_FINISH_REASONS = (
- GenAIAttributes.GEN_AI_RESPONSE_FINISH_REASONS
- )
- """The gen ai response finish reasons."""
-
- # GenAI Usage Attributes
- GEN_AI_USAGE_INPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_INPUT_TOKENS
- """The gen ai usage input tokens."""
-
- GEN_AI_USAGE_OUTPUT_TOKENS = GenAIAttributes.GEN_AI_USAGE_OUTPUT_TOKENS
- """The gen ai usage output tokens."""
-
- # GenAI Message Attributes
- GEN_AI_INPUT_MESSAGES = GenAIAttributes.GEN_AI_INPUT_MESSAGES
- """The gen ai input messages."""
-
- GEN_AI_OUTPUT_MESSAGES = GenAIAttributes.GEN_AI_OUTPUT_MESSAGES
- """The gen ai output messages."""
-
- # GenAI Agent Attributes
- GEN_AI_AGENT_ID = GenAIAttributes.GEN_AI_AGENT_ID
- """The gen ai agent ID."""
-
- GEN_AI_AGENT_NAME = GenAIAttributes.GEN_AI_AGENT_NAME
- """The gen ai agent name."""
-
- GEN_AI_AGENT_DESCRIPTION = GenAIAttributes.GEN_AI_AGENT_DESCRIPTION
- """The gen ai agent description."""
-
- # GenAI Tool Attributes
- GEN_AI_TOOL_CALL_ID = GenAIAttributes.GEN_AI_TOOL_CALL_ID
- """The gen ai tool call ID."""
-
- GEN_AI_TOOL_NAME = GenAIAttributes.GEN_AI_TOOL_NAME
- """The gen ai tool name."""
-
- GEN_AI_TOOL_DESCRIPTION = GenAIAttributes.GEN_AI_TOOL_DESCRIPTION
- """The gen ai tool description."""
-
- GEN_AI_TOOL_CALL_ARGUMENTS = GenAIAttributes.GEN_AI_TOOL_CALL_ARGUMENTS
- """The gen ai tool call arguments."""
-
- GEN_AI_TOOL_CALL_RESULT = GenAIAttributes.GEN_AI_TOOL_CALL_RESULT
- """The gen ai tool call result."""
-
- GEN_AI_TOOL_DEFINITIONS = GenAIAttributes.GEN_AI_TOOL_DEFINITIONS
- """The gen ai tool definitions."""
-
- AGENTSCOPE_REPLY_ID = "agentscope.agent.reply_id"
- """The reply ID of the current agent reply.
-
- Shared by both calls in a HITL or external-execution chain, allowing
- observers to group the two ``invoke_agent`` spans that belong to the
- same logical reply.
- """
-
- AGENTSCOPE_HITL_PENDING_TOOLS = "agentscope.agent.hitl_pending_tools"
- """JSON list of tool names that are waiting for human confirmation.
-
- Set on the first ``invoke_agent`` span when the agent pauses due to a
- ``RequireUserConfirmEvent``.
- """
-
- AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS = (
- "agentscope.agent.external_execution_pending_tools"
- )
- """JSON list of tool names submitted for external execution.
-
- Set on the first ``invoke_agent`` span when the agent pauses due to a
- ``RequireExternalExecutionEvent``.
- """
-
- AGENTSCOPE_INCOMING_EVENT_TYPE = "agentscope.agent.incoming_event_type"
- """Type of the continuation event passed to the second reply call.
-
- Possible values: ``"user_confirm_result"``,
- ``"external_execution_result"``.
- """
-
- AGENTSCOPE_IS_EXTERNAL_EXECUTION = "agentscope.agent.is_external_execution"
- """Marks a synthetic ``execute_tool`` span that represents a tool executed
- externally (i.e. via ``ExternalExecutionResultEvent``).
-
- The timestamp reflects when the result was received, not when the tool
- actually ran on the external system.
- """
-
-
-class OperationNameValues:
- """The operation name values."""
-
- CHAT = GenAIAttributes.GenAiOperationNameValues.CHAT.value
- """The chat operation name."""
-
- INVOKE_AGENT = GenAIAttributes.GenAiOperationNameValues.INVOKE_AGENT.value
- """The invoke agent operation name."""
-
- EXECUTE_TOOL = GenAIAttributes.GenAiOperationNameValues.EXECUTE_TOOL.value
- """The execute tool operation name."""
-
-
-class ProviderNameValues:
- """The provider name values."""
-
- DASHSCOPE = "dashscope"
- """The dashscope provider name."""
-
- OLLAMA = "ollama"
- """The ollama provider name."""
-
- DEEPSEEK = GenAIAttributes.GenAiProviderNameValues.DEEPSEEK.value
- """The deepseek provider name."""
-
- OPENAI = GenAIAttributes.GenAiProviderNameValues.OPENAI.value
- """The openai provider name."""
-
- ANTHROPIC = GenAIAttributes.GenAiProviderNameValues.ANTHROPIC.value
- """The anthropic provider name."""
-
- GCP_GEMINI = GenAIAttributes.GenAiProviderNameValues.GCP_GEMINI.value
- """The gcp gemini provider name."""
-
- MOONSHOT = "moonshot"
- """The moonshot provider name."""
-
- AZURE_AI_OPENAI = (
- GenAIAttributes.GenAiProviderNameValues.AZURE_AI_OPENAI.value
- )
- """The azure openai provider name."""
-
- AWS_BEDROCK = GenAIAttributes.GenAiProviderNameValues.AWS_BEDROCK.value
- """The aws bedrock provider name."""
diff --git a/src/agentscope/middleware/_tracing/_converter.py b/src/agentscope/middleware/_tracing/_converter.py
deleted file mode 100644
index 040377d7e..000000000
--- a/src/agentscope/middleware/_tracing/_converter.py
+++ /dev/null
@@ -1,125 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Convert ContentBlock to OpenTelemetry GenAI part format."""
-
-import json
-from typing import Any, Dict
-
-from ...message import (
- ContentBlock,
- TextBlock,
- ThinkingBlock,
- ToolCallBlock,
- ToolResultBlock,
- DataBlock,
- Base64Source,
- URLSource,
-)
-
-from ._utils import _serialize_to_str
-
-# Map MIME type prefix to OTel modality name
-_MEDIA_TYPE_TO_MODALITY: Dict[str, str] = {
- "image": "image",
- "audio": "audio",
- "video": "video",
-}
-
-
-def _get_modality(media_type: str) -> str:
- """Derive OTel modality from a MIME type string (e.g. 'image/png')."""
- prefix = media_type.split("/")[0] if media_type else ""
- return _MEDIA_TYPE_TO_MODALITY.get(prefix, "unknown")
-
-
-def _convert_media_block(
- source: Base64Source | URLSource,
-) -> Dict[str, Any] | None:
- """Convert a DataBlock source to OpenTelemetry GenAI part format.
-
- Args:
- source (`Base64Source | URLSource`):
- The data source of the DataBlock.
-
- Returns:
- `Dict[str, Any] | None`:
- Converted part Dictionary or None if the source type is invalid.
- """
- modality = _get_modality(source.media_type)
-
- if isinstance(source, URLSource):
- return {
- "type": "uri",
- "uri": str(source.url),
- "modality": modality,
- }
-
- if isinstance(source, Base64Source):
- return {
- "type": "blob",
- "content": source.data,
- "media_type": source.media_type,
- "modality": modality,
- }
-
- return None
-
-
-def _convert_block_to_part(block: ContentBlock) -> Dict[str, Any] | None:
- """Convert content block to OpenTelemetry GenAI part format.
-
- Converts text, thinking, tool_call, tool_result and data (media) blocks
- to standardized parts.
-
- Args:
- block (`ContentBlock`):
- The content block object to convert. Supported block types:
- - text: Text content block
- - thinking: Reasoning/thinking content block
- - tool_call: Tool call block with id, name, and input
- - tool_result: Tool result block with id and output
- - data: Binary data block (image, audio, video, etc.)
-
- Returns:
- `Dict[str, Any] | None`:
- Standardized part Dictionary in OpenTelemetry GenAI format,
- or None if the block type is unsupported or cannot be converted.
- """
- part: Dict[str, Any] | None = None
-
- if isinstance(block, TextBlock):
- part = {
- "type": "text",
- "content": block.text,
- }
- elif isinstance(block, ThinkingBlock):
- part = {
- "type": "reasoning",
- "content": block.thinking,
- }
- elif isinstance(block, ToolCallBlock):
- try:
- arguments = json.loads(block.input)
- except (json.JSONDecodeError, TypeError):
- arguments = block.input
- part = {
- "type": "tool_call",
- "id": block.id,
- "name": block.name,
- "arguments": arguments,
- }
- elif isinstance(block, ToolResultBlock):
- output = block.output
- if isinstance(output, (list, dict)):
- result = _serialize_to_str(output)
- else:
- result = str(output)
-
- part = {
- "type": "tool_call_response",
- "id": block.id,
- "response": result,
- }
- elif isinstance(block, DataBlock):
- part = _convert_media_block(block.source)
-
- return part
diff --git a/src/agentscope/middleware/_tracing/_extractor.py b/src/agentscope/middleware/_tracing/_extractor.py
deleted file mode 100644
index 5feabbeb4..000000000
--- a/src/agentscope/middleware/_tracing/_extractor.py
+++ /dev/null
@@ -1,609 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Extract attributes from AgentScope components for OpenTelemetry tracing."""
-import inspect
-from typing import Any, Dict, TYPE_CHECKING
-
-from ...message import Msg, ToolCallBlock
-
-from ._attributes import (
- SpanAttributes,
- OperationNameValues,
- ProviderNameValues,
-)
-from ._converter import _convert_block_to_part
-from ._utils import _serialize_to_str
-
-if TYPE_CHECKING:
- from ...agent import Agent
- from ...model import ChatModelBase
- from ...tool import Toolkit, ToolChoice
-
-_CLASS_NAME_MAP = {
- "dashscope": ProviderNameValues.DASHSCOPE,
- "openai": ProviderNameValues.OPENAI,
- "anthropic": ProviderNameValues.ANTHROPIC,
- "gemini": ProviderNameValues.GCP_GEMINI,
- "ollama": ProviderNameValues.OLLAMA,
- "deepseek": ProviderNameValues.DEEPSEEK,
- "trinity": ProviderNameValues.OPENAI,
-}
-
-# Map base URL fragments to provider names for OpenAI-compatible APIs
-_BASE_URL_PROVIDER_MAP = [
- ("api.openai.com", ProviderNameValues.OPENAI),
- ("dashscope", ProviderNameValues.DASHSCOPE),
- ("deepseek", ProviderNameValues.DEEPSEEK),
- ("moonshot", ProviderNameValues.MOONSHOT),
- ("generativelanguage.googleapis.com", ProviderNameValues.GCP_GEMINI),
- ("openai.azure.com", ProviderNameValues.AZURE_AI_OPENAI),
- ("amazonaws.com", ProviderNameValues.AWS_BEDROCK),
-]
-
-
-def _get_common_attributes() -> Dict[str, str]:
- """Get common attributes for all spans.
-
- Returns:
- `Dict[str, str]`:
- Common span attributes including conversation ID
- """
- from ._trace import _current_session_id
-
- session_id = _current_session_id.get()
- return {
- SpanAttributes.GEN_AI_CONVERSATION_ID: (
- session_id if session_id else "[no_session_id]"
- ),
- }
-
-
-def _get_provider_name(instance: "ChatModelBase") -> str:
- """Get provider name from ChatModelBase instance.
-
- Maps ChatModelBase class names to provider names, with special handling
- for OpenAI-compatible APIs that may use different base URLs.
- This follows the implementation pattern from agentscope-java PR #73.
-
- Args:
- instance (`ChatModelBase`):
- The chat model instance to get the provider name for.
-
- Returns:
- `str`:
- Provider name (e.g., "openai", "dashscope", "anthropic")
- """
- classname = instance.__class__.__name__
-
- # Special handling for OpenAIChatModel - check base_url
- if classname == "OpenAIChatModel":
- # Try to get base_url from the client
- base_url = None
- if hasattr(instance, "client") and hasattr(
- instance.client,
- "base_url",
- ):
- base_url = str(instance.client.base_url)
-
- # If base_url is None or empty, return default OpenAI
- if not base_url:
- return ProviderNameValues.OPENAI
-
- # Check base_url fragments to identify provider
- for url_fragment, provider_name in _BASE_URL_PROVIDER_MAP:
- if url_fragment in base_url:
- return provider_name
-
- # If no match found, return openai as default
- return ProviderNameValues.OPENAI
-
- # For other model types, use direct mapping
- prefix_key = (
- classname.removesuffix("ChatModel")
- .removesuffix("MultiAgentModel")
- .lower()
- )
- return _CLASS_NAME_MAP.get(prefix_key, "unknown")
-
-
-def _get_tool_definitions(
- tools: list[dict[str, Any]] | None,
- tool_choice: "ToolChoice | None",
-) -> str | None:
- """Extract and serialize tool definitions for tracing.
-
- Converts AgentScope/OpenAI nested tool format to OpenTelemetry GenAI
- flat format for tracing.
-
- Args:
- tools (`list[dict[str, Any]] | None`, optional):
- List of tool definitions in OpenAI format with nested
- structure: ``[{"type": "function", "function": {...}}]``
- tool_choice (`ToolChoice | None`, optional):
- Tool choice configuration with ``mode`` and optional ``tools``
- fields. If mode is ``"none"``, returns None to indicate tools
- should not be traced.
-
- Returns:
- `str | None`:
- Serialized tool definitions in flat format:
- ``[{"type": "function", "name": ..., "parameters": ...}]``
- or None if tools should not be traced (e.g., tools is None/empty
- or tool_choice is "none").
- """
- # No tools provided
- if tools is None or not isinstance(tools, list) or len(tools) == 0:
- return None
-
- # Tool choice is explicitly "none" (model should not use tools)
- if tool_choice is not None and tool_choice.mode == "none":
- return None
-
- try:
- # Convert nested format to flat format for OpenTelemetry GenAI
- # TODO: Currently only supports "function" type tools. If other tool
- # types are added in the future (e.g., "retrieval", "code_interpreter",
- # "browser"), this conversion logic needs to be updated to handle them.
- flat_tools = []
- for tool in tools:
- if not isinstance(tool, dict) or "function" not in tool:
- continue
-
- func_def = tool["function"]
- flat_tool = {
- "type": tool.get("type", "function"),
- "name": func_def.get("name"),
- "description": func_def.get("description"),
- "parameters": func_def.get("parameters"),
- }
- # Remove None values
- flat_tool = {k: v for k, v in flat_tool.items() if v is not None}
- flat_tools.append(flat_tool)
-
- if flat_tools:
- return _serialize_to_str(flat_tools)
- return None
-
- except Exception:
- return None
-
-
-def _get_llm_request_attributes(
- instance: "ChatModelBase",
- kwargs: Dict[str, Any],
-) -> Dict[str, Any]:
- """Get LLM request attributes for OpenTelemetry tracing.
-
- Extracts request parameters from LLM model calls into GenAI attributes.
-
- Args:
- instance (`ChatModelBase`):
- The chat model instance making the request.
- kwargs (`Dict[str, Any]`):
- Keyword arguments including generation parameters such as
- temperature, top_p, top_k, max_tokens, presence_penalty,
- frequency_penalty, stop_sequences, seed, tools, and tool_choice.
-
- Returns:
- `Dict[str, Any]`:
- OpenTelemetry GenAI attributes with string values, including
- operation name, provider name, model name, generation parameters,
- and tool definitions.
- """
-
- attributes = {
- # required attributes
- SpanAttributes.GEN_AI_OPERATION_NAME: OperationNameValues.CHAT,
- SpanAttributes.GEN_AI_PROVIDER_NAME: _get_provider_name(instance),
- # conditionally required attributes
- SpanAttributes.GEN_AI_REQUEST_MODEL: getattr(
- instance,
- "model",
- "unknown_model",
- ),
- # recommended attributes
- SpanAttributes.GEN_AI_REQUEST_TEMPERATURE: kwargs.get("temperature"),
- SpanAttributes.GEN_AI_REQUEST_TOP_P: kwargs.get("p")
- or kwargs.get("top_p"),
- SpanAttributes.GEN_AI_REQUEST_TOP_K: kwargs.get("top_k"),
- SpanAttributes.GEN_AI_REQUEST_MAX_TOKENS: kwargs.get("max_tokens"),
- SpanAttributes.GEN_AI_REQUEST_PRESENCE_PENALTY: kwargs.get(
- "presence_penalty",
- ),
- SpanAttributes.GEN_AI_REQUEST_FREQUENCY_PENALTY: kwargs.get(
- "frequency_penalty",
- ),
- SpanAttributes.GEN_AI_REQUEST_STOP_SEQUENCES: kwargs.get(
- "stop_sequences",
- ),
- SpanAttributes.GEN_AI_REQUEST_SEED: kwargs.get("seed"),
- }
-
- # Extract tool definitions if provided
- tool_definitions = _get_tool_definitions(
- tools=kwargs.get("tools"),
- tool_choice=kwargs.get("tool_choice"),
- )
- if tool_definitions:
- attributes[SpanAttributes.GEN_AI_TOOL_DEFINITIONS] = tool_definitions
-
- return {k: v for k, v in attributes.items() if v is not None}
-
-
-def _get_llm_span_name(attributes: Dict[str, str]) -> str:
- """Generate span name for LLM operations.
-
- Args:
- attributes (`Dict[str, str]`):
- LLM request attributes dictionary containing operation name and
- model name.
-
- Returns:
- `str`:
- Formatted span name in the format "{operation} {model}",
- e.g., "chat gpt-4" or "chat qwen-plus".
- """
- return (
- f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
- f"{attributes[SpanAttributes.GEN_AI_REQUEST_MODEL]}"
- )
-
-
-def _get_llm_output_messages(
- chat_response: Any,
-) -> list[dict[str, Any]]:
- """Extract and format LLM output messages for tracing.
-
- Converts ChatResponse objects to standardized message format compatible
- with OpenTelemetry GenAI specification.
-
- Args:
- chat_response (`Any`):
- Chat response object with content blocks. Should be a ChatResponse
- instance containing content blocks (text, tool_use, etc.).
-
- Returns:
- `list[dict[str, Any]]`:
- List containing a single formatted message dictionary with role,
- parts, and finish_reason. Returns the original response if it's
- not a ChatResponse instance, or an error message format if
- conversion fails.
- """
- try:
- from agentscope.model import ChatResponse
-
- if not isinstance(chat_response, ChatResponse):
- return chat_response
-
- parts = []
- finish_reason = "stop" # Default finish reason
-
- for block in chat_response.content:
- part = _convert_block_to_part(block)
- if part:
- parts.append(part)
-
- output_message = {
- "role": "assistant",
- "parts": parts,
- "finish_reason": finish_reason,
- }
-
- return [output_message]
-
- except Exception:
- return [
- {
- "role": "assistant",
- "parts": [
- {
- "type": "text",
- "content": "<error processing response>",
- },
- ],
- "finish_reason": "error",
- },
- ]
-
-
-def _get_llm_response_attributes(
- chat_response: Any,
-) -> Dict[str, Any]:
- """Get LLM response attributes for OpenTelemetry tracing.
-
- Extracts response metadata and formats into GenAI attributes.
-
- Args:
- chat_response (`Any`):
- Chat response object with data and usage info. Should have
- attributes like id, usage (with input_tokens and output_tokens),
- and content blocks.
-
- Returns:
- `Dict[str, Any]`:
- OpenTelemetry GenAI response attributes including response ID,
- finish reasons, token usage (input/output tokens), and output
- messages.
- """
- attributes = {
- SpanAttributes.GEN_AI_RESPONSE_ID: getattr(
- chat_response,
- "id",
- "unknown_id",
- ),
- # FIXME: finish reason should be capture in chat response
- SpanAttributes.GEN_AI_RESPONSE_FINISH_REASONS: '["stop"]',
- }
- if hasattr(chat_response, "usage") and chat_response.usage:
- attributes[
- SpanAttributes.GEN_AI_USAGE_INPUT_TOKENS
- ] = chat_response.usage.input_tokens
- attributes[
- SpanAttributes.GEN_AI_USAGE_OUTPUT_TOKENS
- ] = chat_response.usage.output_tokens
-
- output_messages = _get_llm_output_messages(chat_response)
- if output_messages:
- attributes[SpanAttributes.GEN_AI_OUTPUT_MESSAGES] = _serialize_to_str(
- output_messages,
- )
-
- return attributes
-
-
-def _get_agent_messages(
- msg: Msg | list[Msg],
-) -> list[dict[str, Any]]:
- """Convert AgentScope message(s) to standardized parts format.
-
- Transforms Msg objects into OpenTelemetry GenAI format.
-
- Args:
- msg (`Msg | list[Msg]`):
- AgentScope message object or list of message objects with
- content blocks.
-
- Returns:
- `list[dict[str, Any]]`:
- List of formatted message dictionaries with role, parts, name,
- and finish_reason.
- """
- try:
- if isinstance(msg, Msg):
- msg = [msg]
-
- formatted_msgs = []
- for m in msg:
- parts = []
- for block in m.get_content_blocks():
- part = _convert_block_to_part(block)
- if part:
- parts.append(part)
- formatted_msg = {
- "role": m.role,
- "parts": parts,
- "name": m.name,
- "finish_reason": "stop",
- }
- formatted_msgs.append(formatted_msg)
-
- return formatted_msgs
- except Exception:
- # Fallback: try simple attribute access on the original object.
- # If msg was already converted to a list or lacks role/name, return
- # an empty list rather than raising a secondary exception.
- try:
- single = msg[0] if isinstance(msg, list) else msg
- return [
- {
- "role": single.role,
- "parts": [
- {
- "type": "text",
- "content": (
- str(single.content) if single.content else ""
- ),
- },
- ],
- "name": single.name,
- "finish_reason": "stop",
- },
- ]
- except Exception:
- return []
-
-
-def _get_agent_request_attributes(
- instance: "Agent",
- kwargs: Dict[str, Any],
-) -> Dict[str, str]:
- """Get agent request attributes for OpenTelemetry tracing.
-
- Extracts agent metadata and input data into GenAI attributes.
-
- Args:
- instance (`Agent`):
- The agent instance making the request.
- kwargs (`Dict[str, Any]`):
- Keyword arguments passed to the agent's reply method.
-
- Returns:
- `Dict[str, str]`:
- OpenTelemetry GenAI attributes including operation name, agent ID,
- agent name, agent description, and input messages (if provided).
- """
- attributes = {
- SpanAttributes.GEN_AI_OPERATION_NAME: (
- OperationNameValues.INVOKE_AGENT
- ),
- SpanAttributes.GEN_AI_AGENT_ID: getattr(instance, "id", "unknown"),
- SpanAttributes.GEN_AI_AGENT_NAME: getattr(
- instance,
- "name",
- "unknown_agent",
- ),
- SpanAttributes.GEN_AI_AGENT_DESCRIPTION: inspect.getdoc(
- instance.__class__,
- )
- or "No description available",
- }
-
- msg = None
- if "msgs" in kwargs:
- msg = kwargs["msgs"]
- elif "msg" in kwargs:
- msg = kwargs["msg"]
- if msg:
- input_messages = _get_agent_messages(msg)
- attributes[SpanAttributes.GEN_AI_INPUT_MESSAGES] = _serialize_to_str(
- input_messages,
- )
-
- # Record the incoming continuation event type for HITL/external execution
- event = kwargs.get("event")
- if event is not None:
- from ...event import (
- ExternalExecutionResultEvent,
- UserConfirmResultEvent,
- )
-
- if isinstance(event, UserConfirmResultEvent):
- attributes[
- SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE
- ] = "user_confirm_result"
- elif isinstance(event, ExternalExecutionResultEvent):
- attributes[
- SpanAttributes.AGENTSCOPE_INCOMING_EVENT_TYPE
- ] = "external_execution_result"
-
- return attributes
-
-
-def _get_agent_span_name(attributes: Dict[str, str]) -> str:
- """Generate span name for agent operations.
-
- Args:
- attributes (`Dict[str, str]`):
- Agent request attributes dictionary containing operation name and
- agent name.
-
- Returns:
- `str`:
- Formatted span name in the format "{operation} {agent_name}",
- e.g., "invoke_agent MyAgent".
- """
- return (
- f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
- f"{attributes[SpanAttributes.GEN_AI_AGENT_NAME]}"
- )
-
-
-def _get_agent_response_attributes(
- agent_response: Any,
-) -> Dict[str, str]:
- """Get agent response attributes for OpenTelemetry tracing.
-
- Args:
- agent_response (`Any`):
- Response object returned by agent. Should be a Msg object with
- content blocks.
-
- Returns:
- `Dict[str, str]`:
- OpenTelemetry GenAI response attributes including output messages.
- """
- attributes = {
- SpanAttributes.GEN_AI_OUTPUT_MESSAGES: _serialize_to_str(
- _get_agent_messages(agent_response),
- ),
- }
- return attributes
-
-
-def _get_tool_request_attributes(
- instance: "Toolkit",
- tool_call: ToolCallBlock,
-) -> Dict[str, str]:
- """Get tool request attributes for OpenTelemetry tracing.
-
- Extracts tool execution metadata into GenAI attributes.
-
- Args:
- instance (`Toolkit`):
- Toolkit instance with tool definitions. Used to extract tool
- description from the tool's JSON schema.
- tool_call (`ToolCallBlock`):
- Tool use block with call information including id, name, and input
- arguments.
-
- Returns:
- `Dict[str, str]`:
- OpenTelemetry GenAI tool attributes including operation name, tool
- call ID, tool name, tool description (if available), and tool call
- arguments.
- """
- attributes = {
- SpanAttributes.GEN_AI_OPERATION_NAME: (
- OperationNameValues.EXECUTE_TOOL
- ),
- }
-
- if tool_call:
- tool_name = tool_call.name
- attributes[SpanAttributes.GEN_AI_TOOL_CALL_ID] = tool_call.id
- attributes[SpanAttributes.GEN_AI_TOOL_NAME] = tool_name
- # tool_call.input is already a JSON string; pass it directly to avoid
- # double-encoding (e.g. '{"city": "Beijing"}' → '"{\\"city\\"...}"')
- attributes[SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS] = tool_call.input
-
- if tool_name:
- registered = getattr(instance, "tools", {}).get(tool_name)
- if registered is not None:
- tool_obj = getattr(registered, "tool", None)
- description = getattr(tool_obj, "description", None)
- if description:
- attributes[
- SpanAttributes.GEN_AI_TOOL_DESCRIPTION
- ] = description
-
- return attributes
-
-
-def _get_tool_span_name(attributes: Dict[str, str]) -> str:
- """Generate span name for tool operations.
-
- Args:
- attributes (`Dict[str, str]`):
- Tool request attributes dictionary containing operation name and
- tool name.
-
- Returns:
- `str`:
- Formatted span name in the format "{operation} {tool_name}",
- e.g., "execute_tool search".
- """
- return (
- f"{attributes[SpanAttributes.GEN_AI_OPERATION_NAME]} "
- f"{attributes[SpanAttributes.GEN_AI_TOOL_NAME]}"
- )
-
-
-def _get_tool_response_attributes(
- tool_response: Any,
-) -> Dict[str, str]:
- """Get tool response attributes for OpenTelemetry tracing.
-
- Args:
- tool_response (`Any`):
- Response object from tool execution. Can be any serializable object
- returned by the tool function.
-
- Returns:
- `Dict[str, str]`:
- OpenTelemetry GenAI response attributes including tool call result.
- """
- attributes = {
- SpanAttributes.GEN_AI_TOOL_CALL_RESULT: _serialize_to_str(
- tool_response,
- ),
- }
- return attributes
diff --git a/src/agentscope/middleware/_tracing/_setup.py b/src/agentscope/middleware/_tracing/_setup.py
deleted file mode 100644
index 8b956649a..000000000
--- a/src/agentscope/middleware/_tracing/_setup.py
+++ /dev/null
@@ -1,49 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The tracing interface class in agentscope."""
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
- from opentelemetry.trace import Tracer
-else:
- Tracer = "Tracer"
-
-
-def setup_tracing(endpoint: str) -> None:
- """Set up the AgentScope tracing by configuring the endpoint URL.
-
- Args:
- endpoint (`str`):
- The endpoint URL for the tracing exporter.
- """
- # Lazy import
- from opentelemetry import trace
- from opentelemetry.sdk.trace import TracerProvider
- from opentelemetry.sdk.trace.export import BatchSpanProcessor
- from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
- OTLPSpanExporter,
- )
-
- # Prepare a span_processor
- exporter = OTLPSpanExporter(endpoint=endpoint)
- span_processor = BatchSpanProcessor(exporter)
-
- tracer_provider: TracerProvider = trace.get_tracer_provider()
- if isinstance(tracer_provider, TracerProvider):
- # The provider is set outside, just add the span processor
- tracer_provider.add_span_processor(span_processor)
-
- else:
- tracer_provider = TracerProvider()
- tracer_provider.add_span_processor(span_processor)
- trace.set_tracer_provider(tracer_provider)
-
-
-def _get_tracer() -> Tracer:
- """Get the tracer
- Returns:
- `Tracer`: The tracer with the name "agentscope" and version.
- """
- from opentelemetry import trace
- from ..._version import __version__
-
- return trace.get_tracer("agentscope", __version__)
diff --git a/src/agentscope/middleware/_tracing/_trace.py b/src/agentscope/middleware/_tracing/_trace.py
deleted file mode 100644
index 82020fb07..000000000
--- a/src/agentscope/middleware/_tracing/_trace.py
+++ /dev/null
@@ -1,396 +0,0 @@
-# -*- coding: utf-8 -*-
-"""TracingMiddleware and supporting utilities for OpenTelemetry tracing."""
-import json
-from typing import (
- Any,
- AsyncGenerator,
- Callable,
- Awaitable,
- Union,
- TypeVar,
- TYPE_CHECKING,
-)
-
-from contextvars import ContextVar
-
-import aioitertools
-
-from .._base import MiddlewareBase
-from ...message import Msg
-
-from ._attributes import SpanAttributes, OperationNameValues
-from ._extractor import (
- _get_common_attributes,
- _get_agent_request_attributes,
- _get_agent_span_name,
- _get_agent_response_attributes,
- _get_llm_request_attributes,
- _get_llm_span_name,
- _get_llm_response_attributes,
- _get_tool_request_attributes,
- _get_tool_span_name,
- _get_tool_response_attributes,
-)
-from ._setup import _get_tracer
-from ._utils import _serialize_to_str
-
-if TYPE_CHECKING:
- from opentelemetry.trace import Span
-
- from ...agent import Agent
- from ...model import ChatResponse
-
-T = TypeVar("T")
-
-# Context variable to propagate the session ID from agent reply through
-# all inner tracing spans (LLM calls, tool calls, formatter calls, etc.)
-_current_session_id: ContextVar[str] = ContextVar(
- "_current_session_id",
- default="",
-)
-
-
-# ---------------------------------------------------------------------------
-# Utility helpers
-# ---------------------------------------------------------------------------
-
-
-def _check_tracing_enabled() -> bool:
- """Check if the OpenTelemetry tracer is initialised with a real SDK
- TracerProvider (i.e. ``setup_tracing`` was called). Returns ``False``
- when only the default no-op proxy provider is active or when the SDK
- package is not installed.
- """
- try:
- from opentelemetry import trace as otel_trace
- from opentelemetry.sdk.trace import TracerProvider
- except ImportError:
- return False
-
- return isinstance(otel_trace.get_tracer_provider(), TracerProvider)
-
-
-def _set_span_success_status(span: "Span") -> None:
- """Set the span status to OK and end it."""
- from opentelemetry import trace as trace_api
-
- span.set_status(trace_api.StatusCode.OK)
- span.end()
-
-
-def _set_span_error_status(span: "Span", e: BaseException) -> None:
- """Set the span status to ERROR, record the exception and end it."""
- from opentelemetry import trace as trace_api
-
- span.set_status(trace_api.StatusCode.ERROR, str(e))
- span.record_exception(e)
- span.end()
-
-
-async def _trace_async_generator_wrapper(
- res: AsyncGenerator[T, None],
- span: "Span",
-) -> AsyncGenerator[T, None]:
- """Wrap an async generator so that response attributes are captured from
- the last yielded chunk before the span is closed."""
- has_error = False
-
- try:
- last_chunk = None
- async for chunk in aioitertools.iter(res):
- last_chunk = chunk
- yield chunk
-
- except BaseException as e:
- has_error = True
- _set_span_error_status(span, e)
- raise
-
- finally:
- if not has_error:
- if (
- getattr(span, "attributes", {}).get(
- SpanAttributes.GEN_AI_OPERATION_NAME,
- )
- == OperationNameValues.CHAT
- ):
- response_attributes = _get_llm_response_attributes(last_chunk)
- elif (
- getattr(span, "attributes", {}).get(
- SpanAttributes.GEN_AI_OPERATION_NAME,
- )
- == OperationNameValues.EXECUTE_TOOL
- ):
- response_attributes = _get_tool_response_attributes(last_chunk)
- else:
- response_attributes = {}
-
- span.set_attributes(response_attributes)
- _set_span_success_status(span)
-
-
-# ---------------------------------------------------------------------------
-# TracingMiddleware
-# ---------------------------------------------------------------------------
-
-
-class TracingMiddleware(MiddlewareBase):
- """Agent middleware that adds OpenTelemetry tracing to the reply,
- model-call and tool-execution lifecycles.
-
- When tracing has not been configured (``setup_tracing`` was not called),
- every hook short-circuits to ``next_handler`` with near-zero overhead.
-
- Example::
-
- from agentscope.middleware import TracingMiddleware
-
- agent = Agent(
- ...,
- middlewares=[TracingMiddleware()],
- )
- """
-
- # ------------------------------------------------------------------
- # on_reply
- # ------------------------------------------------------------------
- async def on_reply(
- self,
- agent: "Agent",
- input_kwargs: dict,
- next_handler: Callable[..., AsyncGenerator],
- ) -> AsyncGenerator:
- if not _check_tracing_enabled():
- async for item in next_handler(**input_kwargs):
- yield item
- return
-
- session_id = getattr(
- getattr(agent, "state", None),
- "session_id",
- "",
- )
- token = _current_session_id.set(session_id or "")
-
- try:
- tracer = _get_tracer()
- request_attributes = _get_agent_request_attributes(
- agent,
- input_kwargs,
- )
- span_name = _get_agent_span_name(request_attributes)
-
- with tracer.start_as_current_span(
- name=span_name,
- attributes={
- **request_attributes,
- **_get_common_attributes(),
- },
- end_on_exit=False,
- ) as span:
- from ...event import (
- ExternalExecutionResultEvent,
- RequireExternalExecutionEvent as _RequireExtExec,
- RequireUserConfirmEvent as _RequireUserConfirm,
- ReplyStartEvent as _ReplyStart,
- )
-
- # Synthetic execute_tool spans for externally executed tools
- event_arg = input_kwargs.get("event")
- if isinstance(event_arg, ExternalExecutionResultEvent):
- common_attrs = _get_common_attributes()
- for result in event_arg.execution_results:
- tool_attrs: dict[str, Any] = {
- SpanAttributes.GEN_AI_OPERATION_NAME: (
- OperationNameValues.EXECUTE_TOOL
- ),
- SpanAttributes.GEN_AI_TOOL_CALL_ID: result.id,
- SpanAttributes.GEN_AI_TOOL_NAME: result.name,
- SpanAttributes.AGENTSCOPE_IS_EXTERNAL_EXECUTION: (
- True
- ),
- **common_attrs,
- }
- if result.output is not None:
- tool_attrs[
- SpanAttributes.GEN_AI_TOOL_CALL_RESULT
- ] = _serialize_to_str(result.output)
- with tracer.start_as_current_span(
- name=(
- f"{OperationNameValues.EXECUTE_TOOL}"
- f" {result.name}"
- ),
- attributes=tool_attrs,
- ):
- pass
-
- has_error = False
- error_exc: BaseException | None = None
- last_msg: Msg | None = None
- hitl_pending: list[str] = []
- external_pending: list[str] = []
- observed_reply_id: str | None = None
-
- try:
- async for item in next_handler(**input_kwargs):
- if isinstance(item, _ReplyStart):
- observed_reply_id = item.reply_id
- elif isinstance(item, _RequireUserConfirm):
- hitl_pending.extend(
- t.name for t in item.tool_calls
- )
- elif isinstance(item, _RequireExtExec):
- external_pending.extend(
- t.name for t in item.tool_calls
- )
- if isinstance(item, Msg):
- last_msg = item
- yield item
- except BaseException as e:
- has_error = True
- error_exc = e
- raise
- finally:
- reply_id = observed_reply_id or getattr(
- getattr(agent, "state", None),
- "reply_id",
- None,
- )
- if reply_id:
- span.set_attribute(
- SpanAttributes.AGENTSCOPE_REPLY_ID,
- reply_id,
- )
- if hitl_pending:
- span.set_attribute(
- SpanAttributes.AGENTSCOPE_HITL_PENDING_TOOLS,
- json.dumps(hitl_pending),
- )
- if external_pending:
- span.set_attribute(
- SpanAttributes.AGENTSCOPE_EXTERNAL_EXECUTION_PENDING_TOOLS, # noqa
- json.dumps(external_pending),
- )
- if has_error and error_exc is not None:
- _set_span_error_status(span, error_exc)
- else:
- if last_msg is not None:
- span.set_attributes(
- _get_agent_response_attributes(last_msg),
- )
- _set_span_success_status(span)
- finally:
- _current_session_id.reset(token)
-
- # ------------------------------------------------------------------
- # on_model_call
- # ------------------------------------------------------------------
- async def on_model_call(
- self,
- agent: "Agent",
- input_kwargs: dict,
- next_handler: Callable[
- ...,
- Awaitable["ChatResponse" | AsyncGenerator["ChatResponse", None]],
- ],
- ) -> Union["ChatResponse", AsyncGenerator["ChatResponse", None]]:
- if not _check_tracing_enabled():
- return await next_handler(**input_kwargs)
-
- from ...model import ChatModelBase
-
- tracer = _get_tracer()
- model = input_kwargs.get("current_model")
- if not isinstance(model, ChatModelBase):
- raise TypeError(
- f"Expected 'current_model' to be ChatModelBase, "
- f"got {type(model).__name__}",
- )
-
- combined_kwargs = {
- **getattr(model, "generate_kwargs", {}),
- **input_kwargs,
- }
- request_attributes = _get_llm_request_attributes(
- model,
- combined_kwargs,
- )
- span_name = _get_llm_span_name(request_attributes)
-
- with tracer.start_as_current_span(
- name=span_name,
- attributes={
- **request_attributes,
- **_get_common_attributes(),
- },
- end_on_exit=False,
- ) as span:
- try:
- result = await next_handler(**input_kwargs)
-
- if isinstance(result, AsyncGenerator):
- return _trace_async_generator_wrapper(result, span)
-
- span.set_attributes(_get_llm_response_attributes(result))
- _set_span_success_status(span)
- return result
-
- except BaseException as e:
- _set_span_error_status(span, e)
- raise
-
- # ------------------------------------------------------------------
- # on_acting
- # ------------------------------------------------------------------
- async def on_acting(
- self,
- agent: "Agent",
- input_kwargs: dict,
- next_handler: Callable[..., AsyncGenerator],
- ) -> AsyncGenerator:
- if not _check_tracing_enabled():
- async for item in next_handler(**input_kwargs):
- yield item
- return
-
- from ...message import ToolCallBlock
-
- tracer = _get_tracer()
- tool_call = input_kwargs.get("tool_call")
- if not isinstance(tool_call, ToolCallBlock):
- raise TypeError(
- f"Expected 'tool_call' to be ToolCallBlock, "
- f"got {type(tool_call).__name__}",
- )
-
- request_attributes = _get_tool_request_attributes(
- agent.toolkit,
- tool_call,
- )
- span_name = _get_tool_span_name(request_attributes)
-
- with tracer.start_as_current_span(
- name=span_name,
- attributes={
- **request_attributes,
- **_get_common_attributes(),
- },
- end_on_exit=False,
- ) as span:
- has_error = False
- last_item = None
- try:
- async for item in next_handler(**input_kwargs):
- last_item = item
- yield item
- except BaseException as e:
- has_error = True
- _set_span_error_status(span, e)
- raise
- finally:
- if not has_error:
- if last_item is not None:
- span.set_attributes(
- _get_tool_response_attributes(last_item),
- )
- _set_span_success_status(span)
diff --git a/src/agentscope/middleware/_tracing/_utils.py b/src/agentscope/middleware/_tracing/_utils.py
deleted file mode 100644
index b06bbbcb8..000000000
--- a/src/agentscope/middleware/_tracing/_utils.py
+++ /dev/null
@@ -1,78 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Serialize objects to JSON string."""
-import datetime
-import enum
-import inspect
-import json
-from dataclasses import is_dataclass
-from typing import Any
-
-from pydantic import BaseModel
-
-from ...message import Msg
-
-
-def _to_serializable(
- obj: Any,
-) -> Any:
- """Convert an object to a JSON serializable type.
-
- Args:
- obj (`Any`):
- The object to be converted to JSON serializable.
-
- Returns:
- `Any`:
- The converted JSON serializable object
- """
-
- # Handle primitive types first
- if isinstance(obj, (str, int, bool, float, type(None))):
- res = obj
-
- elif isinstance(obj, (list, tuple, set, frozenset)):
- res = [_to_serializable(x) for x in obj]
-
- elif isinstance(obj, dict):
- res = {str(key): _to_serializable(val) for (key, val) in obj.items()}
-
- elif isinstance(obj, (Msg, BaseModel)) or is_dataclass(obj):
- res = repr(obj)
-
- elif inspect.isclass(obj) and issubclass(obj, BaseModel):
- res = repr(obj)
-
- elif isinstance(obj, (datetime.date, datetime.datetime, datetime.time)):
- res = obj.isoformat()
-
- elif isinstance(obj, datetime.timedelta):
- res = obj.total_seconds()
-
- elif isinstance(obj, enum.Enum):
- res = _to_serializable(obj.value)
-
- else:
- res = str(obj)
-
- return res
-
-
-def _serialize_to_str(value: Any) -> str:
- """Serialize input value to JSON string.
-
- Args:
- value (`Any`):
- The input value
-
- Returns:
- `str`:
- JSON serialized string of the input value
- """
- try:
- return json.dumps(value, ensure_ascii=False)
-
- except TypeError:
- return json.dumps(
- _to_serializable(value),
- ensure_ascii=False,
- )
diff --git a/src/agentscope/model/_anthropic/_model.py b/src/agentscope/model/_anthropic/_model.py
index 15ea53d95..b84232be1 100644
--- a/src/agentscope/model/_anthropic/_model.py
+++ b/src/agentscope/model/_anthropic/_model.py
@@ -87,13 +87,13 @@ class AnthropicChatModel(ChatModelBase):
``AnthropicChatFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or AnthropicChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_base.py b/src/agentscope/model/_base.py
index e00cb81f0..de4218a4f 100644
--- a/src/agentscope/model/_base.py
+++ b/src/agentscope/model/_base.py
@@ -14,6 +14,7 @@ from ._model_response import StructuredResponse, ChatResponse
from ._model_card import ModelCard
from .._logging import logger
from .._utils._common import _json_loads_with_repair
+from ..credential import CredentialBase
from ..message import (
Msg,
TextBlock,
@@ -37,6 +38,9 @@ class ChatModelBase:
"""Each subclass should implement this inner class to define its
parameters."""
+ credential: CredentialBase
+ """The API credential."""
+
model: str
"""The model name."""
@@ -51,7 +55,9 @@ class ChatModelBase:
def __init__(
self,
+ credential: CredentialBase,
model: str,
+ parameters: BaseModel,
stream: bool = True,
max_retries: int = 3,
context_size: int = 32768,
@@ -59,8 +65,12 @@ class ChatModelBase:
"""Initialize the chat model base.
Args:
+ credential (CredentialBase):
+ The API credential.
model (`str`):
The model name.
+ parameters (`BaseModel`):
+ The model parameters.
stream (`bool`, defaults to `True`):
Whether to enable streaming output for the LLM.
max_retries (`int`, defaults to `3`):
@@ -68,7 +78,9 @@ class ChatModelBase:
context_size (`int`, defaults to `32768`):
The model context size used for context compression.
"""
+ self.credential = credential
self.model = model
+ self.parameters = parameters
self.stream = stream
self.max_retries = max_retries
self.context_size = context_size
diff --git a/src/agentscope/model/_dashscope/_model.py b/src/agentscope/model/_dashscope/_model.py
index 2d63dbf4a..4737fbeaa 100644
--- a/src/agentscope/model/_dashscope/_model.py
+++ b/src/agentscope/model/_dashscope/_model.py
@@ -128,13 +128,13 @@ class DashScopeChatModel(ChatModelBase):
``DashScopeChatFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or DashScopeChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_dashscope/_models/qwen3.6-max-preview.yaml b/src/agentscope/model/_dashscope/_models/qwen3.6-max-preview.yaml
new file mode 100644
index 000000000..e4978f56f
--- /dev/null
+++ b/src/agentscope/model/_dashscope/_models/qwen3.6-max-preview.yaml
@@ -0,0 +1,16 @@
+name: qwen3.6-max-preview
+label: Qwen3.6-Max-Preview
+status: active
+
+input_types:
+ - text/plain
+
+output_types:
+ - text/plain
+ - application/x-thinking
+
+context_size: 240000
+output_size: 64000
+
+parameter_overrides:
+ max_tokens: {"maximum": 64000}
diff --git a/src/agentscope/model/_deepseek/_model.py b/src/agentscope/model/_deepseek/_model.py
index 74e7d6550..9308f330a 100644
--- a/src/agentscope/model/_deepseek/_model.py
+++ b/src/agentscope/model/_deepseek/_model.py
@@ -97,13 +97,13 @@ class DeepSeekChatModel(ChatModelBase):
``DeepSeekChatFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or DeepSeekChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_gemini/_model.py b/src/agentscope/model/_gemini/_model.py
index 4a0dc5af8..d93dcade0 100644
--- a/src/agentscope/model/_gemini/_model.py
+++ b/src/agentscope/model/_gemini/_model.py
@@ -154,13 +154,13 @@ class GeminiChatModel(ChatModelBase):
``GeminiChatFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or GeminiChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_moonshot/_model.py b/src/agentscope/model/_moonshot/_model.py
index 9739614e0..d130da7dd 100644
--- a/src/agentscope/model/_moonshot/_model.py
+++ b/src/agentscope/model/_moonshot/_model.py
@@ -87,13 +87,13 @@ class MoonshotChatModel(ChatModelBase):
``MoonshotChatFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or MoonshotChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_ollama/_model.py b/src/agentscope/model/_ollama/_model.py
index 934bc315f..cc7f13344 100644
--- a/src/agentscope/model/_ollama/_model.py
+++ b/src/agentscope/model/_ollama/_model.py
@@ -86,14 +86,17 @@ class OllamaChatModel(ChatModelBase):
required by the Ollama API. When ``None``, an
``OllamaChatFormatter`` instance will be used.
"""
+ resolved_credential = credential or OllamaCredential()
+
super().__init__(
+ credential=resolved_credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential or OllamaCredential()
- self.parameters = parameters or self.Parameters()
+
self.formatter = formatter or OllamaChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_openai_chat/_model.py b/src/agentscope/model/_openai_chat/_model.py
index 62802e8d5..a808aeacd 100644
--- a/src/agentscope/model/_openai_chat/_model.py
+++ b/src/agentscope/model/_openai_chat/_model.py
@@ -103,13 +103,13 @@ class OpenAIChatModel(ChatModelBase):
``OpenAIChatFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or OpenAIChatFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_openai_response/_model.py b/src/agentscope/model/_openai_response/_model.py
index 8a7af8347..e7c0d525b 100644
--- a/src/agentscope/model/_openai_response/_model.py
+++ b/src/agentscope/model/_openai_response/_model.py
@@ -95,13 +95,13 @@ class OpenAIResponseModel(ChatModelBase):
``OpenAIResponseFormatter`` instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or OpenAIResponseFormatter()
async def _call_api(
diff --git a/src/agentscope/model/_xai/_model.py b/src/agentscope/model/_xai/_model.py
index ac57c0c84..a7ce506f3 100644
--- a/src/agentscope/model/_xai/_model.py
+++ b/src/agentscope/model/_xai/_model.py
@@ -113,13 +113,13 @@ class XAIChatModel(ChatModelBase):
instance will be used.
"""
super().__init__(
+ credential=credential,
model=model,
+ parameters=parameters or self.Parameters(),
stream=stream,
max_retries=max_retries,
context_size=context_size,
)
- self.credential = credential
- self.parameters = parameters or self.Parameters()
self.formatter = formatter or XAIChatFormatter()
async def _call_api(
diff --git a/src/agentscope/storage/__init__.py b/src/agentscope/storage/__init__.py
deleted file mode 100644
index 7397a1a87..000000000
--- a/src/agentscope/storage/__init__.py
+++ /dev/null
@@ -1,8 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The storage module in agentscope."""
-
-from ._base import StorageBase
-
-__all__ = [
- "StorageBase",
-]
diff --git a/src/agentscope/storage/_base.py b/src/agentscope/storage/_base.py
deleted file mode 100644
index 20f7c3b81..000000000
--- a/src/agentscope/storage/_base.py
+++ /dev/null
@@ -1,49 +0,0 @@
-# -*- coding: utf-8 -*-
-"""The storage base class."""
-from abc import ABC, abstractmethod
-from typing import Any
-
-from ..state import AgentState
-
-
-class StorageBase(ABC):
- """The storage abstract base class."""
-
- @abstractmethod
- async def load_agent_state(
- self,
- session_id: str,
- agent_id: str,
- **kwargs: Any,
- ) -> AgentState:
- """Load the agent state from the storage.
-
- Args:
- session_id (`str`):
- The session id.
- agent_id (`str`):
- The agent id, in case one session has multiple agents.
-
- Returns:
- `AgentState`:
- The loaded agent state.
- """
-
- @abstractmethod
- async def save_agent_state(
- self,
- session_id: str,
- agent_id: str,
- agent_state: AgentState,
- **kwargs: Any,
- ) -> None:
- """Save the agent state to the storage.
-
- Args:
- session_id (`str`):
- The session id.
- agent_id (`str`):
- The agent id, in case one session has multiple agents.
- agent_state (`AgentState`):
- The agent state.
- """
diff --git a/src/agentscope/tool/_base.py b/src/agentscope/tool/_base.py
index c335b1f5e..a56437b1c 100644
--- a/src/agentscope/tool/_base.py
+++ b/src/agentscope/tool/_base.py
@@ -82,8 +82,7 @@ class ToolBase(ABC):
) -> bool:
"""Check if a permission rule matches the tool input.
- .. note:: This is an optional method. The default implementation
- mirrors Claude Code's behavior: a rule with no content (``None``)
+ .. note:: This is an optional method. A rule with no content (``None``)
is a tool-name-level rule that matches every invocation; a rule
with content requires the tool to override this method with its
own matching logic, otherwise it returns ``False``.
@@ -115,8 +114,7 @@ class ToolBase(ABC):
) -> List[PermissionRule]:
"""Generate suggested permission rules for the tool input.
- .. note:: The default implementation mirrors Claude Code's MCP tool
- behavior: suggest a single tool-name-level rule (``rule_content=None``)
+ .. note:: Suggest a single tool-name-level rule (``rule_content=None``)
that allows all invocations of this tool. Tools can override this to
provide finer-grained suggestions.
diff --git a/src/agentscope/tool/_builtin/_read.py b/src/agentscope/tool/_builtin/_read.py
index d85daac25..8d7bd6565 100644
--- a/src/agentscope/tool/_builtin/_read.py
+++ b/src/agentscope/tool/_builtin/_read.py
@@ -33,7 +33,7 @@ Usage:
- By default, it reads up to 2000 lines starting from the beginning of the file
- You can optionally specify a line offset and limit (especially handy for long files), but it's recommended to read the whole file by not providing these parameters
- Results are returned using cat -n format, with line numbers starting at 1
-- This tool allows you to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as Claude Code is a multimodal LLM.
+- This tool allows you to read images (eg PNG, JPG, etc). When reading an image file the contents are presented visually as you're a multimodal LLM.
- This tool can read PDF files (.pdf). For large PDFs (more than 10 pages), you MUST provide the pages parameter to read specific pages.""" # noqa: E501
"""The description presented to the agent."""
diff --git a/src/agentscope/workspace/__init__.py b/src/agentscope/workspace/__init__.py
index a221a9663..ccbe4592d 100644
--- a/src/agentscope/workspace/__init__.py
+++ b/src/agentscope/workspace/__init__.py
@@ -1,10 +1,17 @@
# -*- coding: utf-8 -*-
"""The workspace module in agentscope."""
+from typing import Annotated, Union
+
+from pydantic import Field
+
from ._base import WorkspaceBase
from ._local_workspace import LocalWorkspace
+AnyWorkspace = Annotated[Union[LocalWorkspace], Field(discriminator="type")]
+
__all__ = [
+ "AnyWorkspace",
"WorkspaceBase",
"LocalWorkspace",
]
diff --git a/src/agentscope/workspace/_base.py b/src/agentscope/workspace/_base.py
index ef678262f..d1ce4a8a9 100644
--- a/src/agentscope/workspace/_base.py
+++ b/src/agentscope/workspace/_base.py
@@ -1,60 +1,61 @@
# -*- coding: utf-8 -*-
"""The workspace base class."""
-from abc import abstractmethod, ABC
+from abc import abstractmethod
from typing import Any
+from uuid import uuid4
+from pydantic import BaseModel, Field
+
+from ..mcp import MCPClient
from ..skill import Skill
from ..message import Msg, ToolResultBlock
from ..tool import ToolBase
-class WorkspaceBase(ABC):
+class WorkspaceBase(BaseModel):
"""Abstract base class representing the execution environment of an agent.
- A workspace defines where and how an agent operates, and is
- responsible for:
+ Inherits from ``BaseModel`` so that each workspace instance is directly
+ serialisable via ``model_dump()`` / ``model_validate()``. The ``type``
+ discriminator field enables the manager to reconstruct the correct
+ subclass from ``WorkspaceRecord.data`` without a separate factory.
- - Providing tools scoped to this environment (e.g. Bash, file I/O tools)
- - Offloading compressed context to support agentic retrieval
+ Subclasses must declare ``type: Literal["<name>"] = "<name>"`` and
+ implement all abstract methods.
"""
+ id: str = Field(default_factory=lambda: uuid4().hex)
+ """Unique workspace identifier, assigned at creation."""
+
+ type: str
+ """Discriminator field — subclasses fix this to a Literal value."""
+
+ model_config = {"arbitrary_types_allowed": True}
+
@abstractmethod
async def initialize(self) -> None:
- """Initialize the workspace, e.g. initialize the MCPs, copy the skills
- into the workspace and so on."""
+ """Initialize the workspace (connect MCPs, copy skills, etc.)."""
@abstractmethod
async def close(self) -> None:
- """Close the workspace and clean up resource."""
+ """Close the workspace and release all resources."""
@abstractmethod
async def get_instructions(self) -> str:
- """Retrieve the workspace instructions. The instructions will be
- appended to the system prompt to guide the agent on how to
- interact with this workspace.
-
- Returns:
- `str`:
- The workspace instructions.
- """
+ """Return workspace instructions appended to the agent
+ system prompt."""
@abstractmethod
async def list_tools(self) -> list[ToolBase]:
- """List all tools available in the workspace.
-
- Returns:
- `list[ToolBase]`:
- The list of tools available in the workspace.
- """
+ """Return all tools available in this workspace."""
@abstractmethod
async def list_skills(self) -> list[Skill]:
- """List all skills available in the workspace.
+ """Return all skills available in this workspace."""
- Returns:
- `list[Skill]`:
- The list of skills available in the workspace.
- """
+ @abstractmethod
+ async def list_mcps(self) -> list[MCPClient]:
+ """Return all MCP clients attached to this workspace."""
@abstractmethod
async def offload_context(
@@ -63,7 +64,7 @@ class WorkspaceBase(ABC):
msgs: list[Msg],
**kwargs: Any,
) -> str:
- """Offload the compressed context into agent accessible content."""
+ """Offload compressed context to workspace-accessible storage."""
@abstractmethod
async def offload_tool_result(
@@ -72,4 +73,20 @@ class WorkspaceBase(ABC):
tool_result: ToolResultBlock,
**kwargs: Any,
) -> str:
- """Offload the tool results into agent accessible content."""
+ """Offload a tool result to workspace-accessible storage."""
+
+ @abstractmethod
+ async def add_mcp(self, mcp: MCPClient) -> None:
+ """Add an MCP client and connect it if stateful."""
+
+ @abstractmethod
+ async def remove_mcp(self, mcp_name: str) -> None:
+ """Remove an MCP client by name, disconnecting it if stateful."""
+
+ @abstractmethod
+ async def add_skill(self, skill_path: str) -> None:
+ """Add a skill to the workspace by copying from the given path."""
+
+ @abstractmethod
+ async def remove_skill(self, skill_name: str) -> None:
+ """Remove a skill from the workspace by copying from the given path."""
diff --git a/src/agentscope/workspace/_local_workspace.py b/src/agentscope/workspace/_local_workspace.py
index 68e342753..88fa36a23 100644
--- a/src/agentscope/workspace/_local_workspace.py
+++ b/src/agentscope/workspace/_local_workspace.py
@@ -10,12 +10,12 @@ import re
import shutil
from copy import deepcopy
from pathlib import Path
-from typing import Any, TypedDict
+from typing import Any, Literal, TypedDict
import aiofiles
import aiofiles.ospath
import frontmatter
-from pydantic import AnyUrl
+from pydantic import AnyUrl, Field, PrivateAttr, field_validator
from ._base import WorkspaceBase
from ..mcp import MCPClient
@@ -117,70 +117,60 @@ You are responsible for keeping it clean, structured, and easy to navigate over
class LocalWorkspace(WorkspaceBase):
# pylint: disable=line-too-long
- """The local workspace class, which chooses a local directory as the
- agent workspace. It's organized as
-
- ```
- {workdir}
- ├── data/ # the offloaded multimodal files, e.g. images
- ├── skills/ # the skill directories, each skill has a subdirectory under skills/
- │ ├── {skill_name}/ # the skill directory
- │ │ ├── {skill_files} # the files for the skill
- └── sessions/ # the session directories, each session has a subdirectory under sessions/
- └── {session_id}/ # the session directory
- ├── context.jsonl # the offloaded context for the session, in jsonl format
- └── tool_result-{id}.txt # the offloaded tool results for the session, in txt format
- ```
+ """Local-directory workspace.
+
+ Layout::
+
+ {workdir}/
+ ├── .mcp # persisted MCP client configs (JSON array)
+ ├── data/ # offloaded multimodal files
+ ├── skills/ # skill subdirectories
+ └── sessions/ # per-session context and tool-result files
+
+ ``workdir`` and ``type`` are the only fields serialised to
+ ``WorkspaceRecord.data``. ``default_mcps`` and ``skill_paths`` are
+ service-level defaults that are excluded from serialisation.
""" # noqa: E501
- def __init__(
- self,
- workdir: str,
- skill_paths: list[str] | None = None,
- mcps: list[MCPClient] | None = None,
- instructions: str = _DEFAULT_WORKSPACE_INSTRUCTIONS,
- ) -> None:
- """Initialize the local workspace.
+ type: Literal["local"] = "local"
+ workdir: str
- Args:
- workdir (`str`):
- The agent workdir, used to offload the compressed context for
- agentic retrieval.
- skill_paths (`list[str] | None`, optional):
- A list of skill paths that will be copied into the target
- skill directory when the workspace is first initialized.
- Defaults to `None`.
- instructions (`str`, optional):
- The workspace instructions to guide the agent how to use it.
- """
- self._workdir = os.path.abspath(workdir)
- # Deduplicate skill paths by absolute path
- self._skill_paths = list(
- dict.fromkeys(os.path.abspath(p) for p in (skill_paths or [])),
- )
- self._instructions = instructions
- self._mcps = mcps or []
+ # Excluded from model_dump() — service-level defaults, not user state
+ default_mcps: list[MCPClient] = Field(default_factory=list, exclude=True)
+ skill_paths: list[str] = Field(default_factory=list, exclude=True)
+
+ # Runtime state — not Pydantic fields
+ _mcps: list[MCPClient] = PrivateAttr(default_factory=list)
+ _instructions: str = PrivateAttr(default=_DEFAULT_WORKSPACE_INSTRUCTIONS)
+
+ @field_validator("workdir", mode="before")
+ @classmethod
+ def _normalise_workdir(cls, v: str) -> str:
+ return os.path.abspath(v)
async def initialize(self) -> None:
- """Initialize the local workspace by copying skills to the target
- directory.
-
- Skills are processed sequentially to guarantee correct deduplication:
- 1. Validate each skill and compute its SKILL.md hash
- 2. Skip if the hash already exists in the workspace
- 3. Resolve directory-name and agent-name conflicts with numeric
- suffixes
- 4. Copy the skill, then update the .skills index
+ """Initialise the workspace.
+
+ MCP state is restored from ``.mcp`` if it exists; otherwise
+ ``default_mcps`` are used. ``skill_paths`` are seeded on first use.
"""
- # Initialize the MCP connections
+ # Restore or seed MCPs
+ mcp_file = os.path.join(self.workdir, ".mcp")
+ if await aiofiles.ospath.exists(mcp_file):
+ async with aiofiles.open(mcp_file, "r", encoding="utf-8") as f:
+ self._mcps = [
+ MCPClient.model_validate(m)
+ for m in json.loads(await f.read())
+ ]
+ else:
+ self._mcps = list(self.default_mcps)
+
for mcp in self._mcps:
- if (
- mcp.is_stateful or mcp.mcp_config.type == "stdio_mcp"
- ) and not mcp.is_connected:
+ if mcp.is_stateful and not mcp.is_connected:
await mcp.connect()
- # Copy the skills
- skills_dir = os.path.join(self._workdir, "skills")
+ # Seed skills
+ skills_dir = os.path.join(self.workdir, "skills")
os.makedirs(skills_dir, exist_ok=True)
skills_file = await self._load_skills_file(skills_dir)
@@ -194,7 +184,7 @@ class LocalWorkspace(WorkspaceBase):
existing_dir_names: set[str] = set(existing.keys())
updated = False
- for skill_path in self._skill_paths:
+ for skill_path in self.skill_paths:
result = await self._validate_and_hash_skill(skill_path)
if result is None:
continue
@@ -277,7 +267,7 @@ class LocalWorkspace(WorkspaceBase):
async def get_instructions(self) -> str:
"""Get the workspace instructions."""
- return self._instructions.format(workdir=self._workdir)
+ return self._instructions.format(workdir=self.workdir)
async def _load_skills_file(self, skills_dir: str) -> _SkillsFile:
"""Load the .skills index file, returning an empty structure if absent.
@@ -429,7 +419,7 @@ class LocalWorkspace(WorkspaceBase):
# no need to read and compare bytes.
hash_str = hashlib.sha256(data_block.source.data.encode()).hexdigest()
ext = mimetypes.guess_extension(data_block.source.media_type) or ".bin"
- path = os.path.join(self._workdir, "data", f"{hash_str}{ext}")
+ path = os.path.join(self.workdir, "data", f"{hash_str}{ext}")
# Reuse the existing file directly — same hash ⟹ same content.
if not await aiofiles.ospath.exists(path):
@@ -467,7 +457,7 @@ class LocalWorkspace(WorkspaceBase):
The file path to the offloaded message.
"""
path = os.path.join(
- self._workdir,
+ self.workdir,
"sessions",
session_id,
"context.jsonl",
@@ -523,7 +513,7 @@ class LocalWorkspace(WorkspaceBase):
The file path to the offloaded tool results.
"""
path = os.path.join(
- self._workdir,
+ self.workdir,
"sessions",
session_id,
f"tool_result-{tool_result.id}.txt",
@@ -589,7 +579,7 @@ class LocalWorkspace(WorkspaceBase):
`list[Skill]`:
A list of Skill objects found in the workspace.
"""
- skills_dir = os.path.join(self._workdir, "skills")
+ skills_dir = os.path.join(self.workdir, "skills")
if not await aiofiles.ospath.isdir(skills_dir):
return []
@@ -784,6 +774,194 @@ class LocalWorkspace(WorkspaceBase):
return None
async def list_mcps(self) -> list[MCPClient]:
- """The workspace doesn't need to handle the MCP servers. Just leave
- it empty."""
+ """Return all MCP clients attached to this workspace."""
return self._mcps
+
+ async def _save_mcp_file(self) -> None:
+ """Persist the current MCP client list to ``.mcp`` in workdir."""
+ mcp_file = os.path.join(self.workdir, ".mcp")
+ try:
+ async with aiofiles.open(mcp_file, "w", encoding="utf-8") as f:
+ await f.write(
+ json.dumps(
+ [m.model_dump() for m in self._mcps],
+ indent=2,
+ ensure_ascii=False,
+ ),
+ )
+ except Exception as e:
+ logger.warning("Failed to save .mcp to %s: %s", mcp_file, str(e))
+
+ async def add_mcp(self, mcp: MCPClient) -> None:
+ """Add an MCP client, connect it if stateful, and persist.
+
+ Args:
+ mcp: The MCP client to add.
+ """
+ if mcp.is_stateful and not mcp.is_connected:
+ await mcp.connect()
+ self._mcps.append(mcp)
+ await self._save_mcp_file()
+
+ async def remove_mcp(self, mcp_name: str) -> None:
+ """Remove an MCP client by name, disconnecting it if stateful.
+
+ Args:
+ mcp_name: The ``name`` field of the client to remove.
+ """
+ for i, mcp in enumerate(self._mcps):
+ if mcp.name == mcp_name:
+ if mcp.is_stateful and mcp.is_connected:
+ await mcp.close()
+ self._mcps.pop(i)
+ await self._save_mcp_file()
+ return
+ logger.warning("MCP client %r not found in workspace", mcp_name)
+
+ async def add_skill(self, skill_path: str) -> None:
+ """Add a skill to the workspace by copying from the given path.
+
+ The skill directory must contain a valid ``SKILL.md`` file with
+ ``name`` and ``description`` frontmatter fields. Duplicate skills
+ (identified by the SHA-256 hash of ``SKILL.md``) are silently skipped.
+ Name and directory conflicts are resolved by appending a numeric
+ suffix.
+
+ Args:
+ skill_path (`str`):
+ Absolute or relative path to the skill directory to copy.
+
+ Raises:
+ ValueError: If the skill at ``skill_path`` is invalid (missing or
+ malformed ``SKILL.md``).
+ """
+ skills_dir = os.path.join(self.workdir, "skills")
+ os.makedirs(skills_dir, exist_ok=True)
+
+ result = await self._validate_and_hash_skill(skill_path)
+ if result is None:
+ raise ValueError(
+ f"Invalid skill at {skill_path!r}: missing or malformed "
+ "SKILL.md (requires 'name' and 'description' fields).",
+ )
+
+ _, raw_name, skill_hash = result
+
+ skills_file = await self._load_skills_file(skills_dir)
+ existing: dict[str, _SkillEntry] = skills_file["skills"]
+
+ existing_hashes: set[str] = {e["hash"] for e in existing.values()}
+ if skill_hash in existing_hashes:
+ logger.info(
+ "Skill '%s' (hash: %s...) already exists, skipping",
+ raw_name,
+ skill_hash[:8],
+ )
+ return
+
+ existing_agent_names: set[str] = {
+ e["skill_name"] for e in existing.values()
+ }
+ existing_dir_names: set[str] = set(existing.keys())
+
+ # Resolve agent-facing name conflict
+ agent_name = raw_name
+ counter = 1
+ while agent_name in existing_agent_names:
+ agent_name = f"{raw_name} ({counter})"
+ counter += 1
+
+ # Resolve directory name conflict
+ base_dir = _sanitize_dir_name(raw_name)
+ dir_name = base_dir
+ counter = 1
+ while dir_name in existing_dir_names:
+ dir_name = f"{base_dir}_{counter}"
+ counter += 1
+
+ dest_path = os.path.join(skills_dir, dir_name)
+
+ if not os.path.realpath(dest_path).startswith(
+ os.path.realpath(skills_dir) + os.sep,
+ ):
+ raise ValueError(
+ f"Skill path {skill_path!r} resolves outside skills_dir.",
+ )
+
+ await asyncio.to_thread(
+ shutil.copytree,
+ skill_path,
+ dest_path,
+ dirs_exist_ok=False,
+ )
+
+ logger.info(
+ "Copied skill '%s' (agent name: '%s') from %s to %s",
+ raw_name,
+ agent_name,
+ skill_path,
+ dest_path,
+ )
+
+ existing[dir_name] = {"hash": skill_hash, "skill_name": agent_name}
+ skills_file["skills"] = existing
+ skills_file["skills_dir_mtime"] = await aiofiles.ospath.getmtime(
+ skills_dir,
+ )
+ await self._save_skills_file(skills_dir, skills_file)
+
+ async def remove_skill(self, skill_name: str) -> None:
+ """Remove a skill from the workspace by its agent-facing name.
+
+ The skill directory is deleted from disk and the ``.skills`` index is
+ updated. If no skill with the given name is found, a warning is
+ logged and the method returns without error.
+
+ Args:
+ skill_name (`str`):
+ The agent-facing name of the skill to remove (as stored in the
+ ``.skills`` index, i.e. the ``name`` field from ``SKILL.md``
+ possibly with a numeric suffix for de-duplication).
+ """
+ skills_dir = os.path.join(self.workdir, "skills")
+
+ if not await aiofiles.ospath.isdir(skills_dir):
+ logger.warning(
+ "Skills directory does not exist; cannot remove skill %r",
+ skill_name,
+ )
+ return
+
+ skills_file = await self._load_skills_file(skills_dir)
+ existing: dict[str, _SkillEntry] = skills_file["skills"]
+
+ target_dir: str | None = None
+ for dir_name, entry in existing.items():
+ if entry["skill_name"] == skill_name:
+ target_dir = dir_name
+ break
+
+ if target_dir is None:
+ logger.warning("Skill %r not found in workspace", skill_name)
+ return
+
+ skill_dir_path = os.path.join(skills_dir, target_dir)
+ if await aiofiles.ospath.isdir(skill_dir_path):
+ await asyncio.to_thread(shutil.rmtree, skill_dir_path)
+ logger.info(
+ "Removed skill '%s' from %s",
+ skill_name,
+ skill_dir_path,
+ )
+ else:
+ logger.warning(
+ "Skill directory %r not found on disk; removing index entry",
+ skill_dir_path,
+ )
+
+ del existing[target_dir]
+ skills_file["skills"] = existing
+ skills_file["skills_dir_mtime"] = await aiofiles.ospath.getmtime(
+ skills_dir,
+ )
+ await self._save_skills_file(skills_dir, skills_file)
diff --git a/tests/agent_basic_test.py b/tests/agent_basic_test.py
index faeab6ce1..dda00369e 100644
--- a/tests/agent_basic_test.py
+++ b/tests/agent_basic_test.py
@@ -120,6 +120,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
return {
"id": AnyString(),
"created_at": AnyString(),
+ "finished_at": None,
"metadata": {},
"name": "Friday",
"role": "assistant",
@@ -221,7 +222,14 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
**msg_base,
"name": "user",
"role": "user",
- "content": "Hi",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hi",
+ },
+ ],
+ "finished_at": AnyString(),
},
{
**msg_base,
@@ -253,6 +261,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
},
],
"created_at": AnyString(),
+ "finished_at": None,
"id": AnyString(),
"metadata": {},
},
@@ -264,8 +273,15 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
**msg_base,
"name": "user",
"role": "user",
- "content": "Hi",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hi",
+ },
+ ],
"metadata": {},
+ "finished_at": AnyString(),
},
{
**msg_base,
@@ -284,8 +300,15 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
**msg_base,
"name": "user",
"role": "user",
- "content": "Hi again",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hi again",
+ },
+ ],
"metadata": {},
+ "finished_at": AnyString(),
},
{
**msg_base,
@@ -380,8 +403,15 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
**msg_base,
"name": "user",
"role": "user",
- "content": "Hi",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hi",
+ },
+ ],
"metadata": {},
+ "finished_at": AnyString(),
},
{
**msg_base,
@@ -423,6 +453,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
},
],
"created_at": AnyString(),
+ "finished_at": None,
"id": AnyString(),
"metadata": {},
},
@@ -434,8 +465,15 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
**msg_base,
"name": "user",
"role": "user",
- "content": "Hi",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hi",
+ },
+ ],
"metadata": {},
+ "finished_at": AnyString(),
},
{
**msg_base,
@@ -454,8 +492,15 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
**msg_base,
"name": "user",
"role": "user",
- "content": "Hi again",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Hi again",
+ },
+ ],
"metadata": {},
+ "finished_at": AnyString(),
},
{
**msg_base,
@@ -669,7 +714,14 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": "Test",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Test",
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -684,6 +736,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_sequential_tool",
"input": '{"input": "test1"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -691,6 +744,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_sequential_tool",
"input": '{"input": "test2"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
@@ -905,7 +959,14 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": "Test",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Test",
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -915,6 +976,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_concurrent_tool",
"input": '{"input": "test1"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -922,6 +984,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_concurrent_tool",
"input": '{"input": "test2"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
@@ -1177,7 +1240,14 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": "Test",
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Test",
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -1187,6 +1257,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_sequential_tool",
"input": '{"input": "seq1"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -1194,6 +1265,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_concurrent_tool",
"input": '{"input": "conc1"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -1201,6 +1273,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"name": "mock_concurrent_tool",
"input": '{"input": "conc2"}',
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
diff --git a/tests/agui_protocol_test.py b/tests/agui_protocol_test.py
new file mode 100644
index 000000000..8497c0de9
--- /dev/null
+++ b/tests/agui_protocol_test.py
@@ -0,0 +1,557 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Test cases for AGUI protocol middleware."""
+from unittest.async_case import IsolatedAsyncioTestCase
+from unittest.mock import MagicMock
+
+from agentscope.app import AGUIProtocolMiddleware
+from agentscope.event import (
+ ConfirmResult,
+ DataBlockDeltaEvent,
+ DataBlockEndEvent,
+ DataBlockStartEvent,
+ ExceedMaxItersEvent,
+ ExternalExecutionResultEvent,
+ ModelCallEndEvent,
+ ModelCallStartEvent,
+ ReplyEndEvent,
+ ReplyStartEvent,
+ RequireExternalExecutionEvent,
+ RequireUserConfirmEvent,
+ TextBlockDeltaEvent,
+ TextBlockEndEvent,
+ TextBlockStartEvent,
+ ThinkingBlockDeltaEvent,
+ ThinkingBlockEndEvent,
+ ThinkingBlockStartEvent,
+ ToolCallDeltaEvent,
+ ToolCallEndEvent,
+ ToolCallStartEvent,
+ ToolResultDataDeltaEvent,
+ ToolResultEndEvent,
+ ToolResultStartEvent,
+ ToolResultTextDeltaEvent,
+ UserConfirmResultEvent,
+)
+from agentscope.message import ToolCallBlock, ToolResultBlock, ToolResultState
+
+
+class AGUIProtocolLifecycleTest(IsolatedAsyncioTestCase):
+ """Test lifecycle event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_reply_start_to_run_started(self) -> None:
+ """Test ReplyStartEvent -> RUN_STARTED."""
+ event = ReplyStartEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ name="agent",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "RUN_STARTED")
+ self.assertEqual(result["threadId"], "sess_1")
+ self.assertEqual(result["runId"], "reply_1")
+ self.assertNotIn("name", result)
+
+ async def test_reply_end_to_run_finished(self) -> None:
+ """Test ReplyEndEvent -> RUN_FINISHED."""
+ event = ReplyEndEvent(
+ session_id="sess_1",
+ reply_id="reply_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "RUN_FINISHED")
+ self.assertEqual(result["threadId"], "sess_1")
+ self.assertEqual(result["runId"], "reply_1")
+
+ async def test_exceed_max_iters_to_run_error(self) -> None:
+ """Test ExceedMaxItersEvent -> RUN_ERROR."""
+ event = ExceedMaxItersEvent(
+ reply_id="reply_1",
+ name="my_agent",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "RUN_ERROR")
+ self.assertIn("my_agent", result["message"])
+ self.assertEqual(result["code"], "exceed_max_iters")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolStepTest(IsolatedAsyncioTestCase):
+ """Test model call -> step event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_model_call_start_to_step_started(self) -> None:
+ """Test ModelCallStartEvent -> STEP_STARTED."""
+ event = ModelCallStartEvent(
+ reply_id="reply_1",
+ model_name="gpt-4",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "STEP_STARTED")
+ self.assertEqual(result["stepName"], "gpt-4")
+
+ async def test_model_call_end_to_step_finished(self) -> None:
+ """Test ModelCallEndEvent -> STEP_FINISHED with matching step_name."""
+ start_event = ModelCallStartEvent(
+ reply_id="reply_1",
+ model_name="gpt-4",
+ )
+ self.mw._convert_to_protocol(start_event)
+
+ end_event = ModelCallEndEvent(
+ reply_id="reply_1",
+ input_tokens=100,
+ output_tokens=50,
+ )
+ result = self.mw._convert_to_protocol(end_event)
+
+ self.assertEqual(result["type"], "STEP_FINISHED")
+ self.assertEqual(result["stepName"], "gpt-4")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolTextMessageTest(IsolatedAsyncioTestCase):
+ """Test text block -> text message event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_text_block_start(self) -> None:
+ """Test TextBlockStartEvent -> TEXT_MESSAGE_START."""
+ event = TextBlockStartEvent(
+ reply_id="reply_1",
+ block_id="block_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "TEXT_MESSAGE_START")
+ self.assertEqual(result["messageId"], "block_1")
+
+ async def test_text_block_delta(self) -> None:
+ """Test TextBlockDeltaEvent -> TEXT_MESSAGE_CONTENT."""
+ event = TextBlockDeltaEvent(
+ reply_id="reply_1",
+ block_id="block_1",
+ delta="Hello, ",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "TEXT_MESSAGE_CONTENT")
+ self.assertEqual(result["messageId"], "block_1")
+ self.assertEqual(result["delta"], "Hello, ")
+
+ async def test_text_block_end(self) -> None:
+ """Test TextBlockEndEvent -> TEXT_MESSAGE_END."""
+ event = TextBlockEndEvent(
+ reply_id="reply_1",
+ block_id="block_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "TEXT_MESSAGE_END")
+ self.assertEqual(result["messageId"], "block_1")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolReasoningTest(IsolatedAsyncioTestCase):
+ """Test thinking block -> reasoning message event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_thinking_block_start(self) -> None:
+ """Test ThinkingBlockStartEvent -> REASONING_MESSAGE_START."""
+ event = ThinkingBlockStartEvent(
+ reply_id="reply_1",
+ block_id="think_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "REASONING_MESSAGE_START")
+ self.assertEqual(result["messageId"], "think_1")
+ self.assertEqual(result["role"], "reasoning")
+
+ async def test_thinking_block_delta(self) -> None:
+ """Test ThinkingBlockDeltaEvent -> REASONING_MESSAGE_CONTENT."""
+ event = ThinkingBlockDeltaEvent(
+ reply_id="reply_1",
+ block_id="think_1",
+ delta="Let me think...",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "REASONING_MESSAGE_CONTENT")
+ self.assertEqual(result["messageId"], "think_1")
+ self.assertEqual(result["delta"], "Let me think...")
+
+ async def test_thinking_block_end(self) -> None:
+ """Test ThinkingBlockEndEvent -> REASONING_MESSAGE_END."""
+ event = ThinkingBlockEndEvent(
+ reply_id="reply_1",
+ block_id="think_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "REASONING_MESSAGE_END")
+ self.assertEqual(result["messageId"], "think_1")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolToolCallTest(IsolatedAsyncioTestCase):
+ """Test tool call event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_tool_call_start(self) -> None:
+ """Test ToolCallStartEvent -> TOOL_CALL_START."""
+ event = ToolCallStartEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ tool_call_name="search",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "TOOL_CALL_START")
+ self.assertEqual(result["toolCallId"], "tc_1")
+ self.assertEqual(result["toolCallName"], "search")
+ self.assertEqual(result["parentMessageId"], "reply_1")
+
+ async def test_tool_call_delta(self) -> None:
+ """Test ToolCallDeltaEvent -> TOOL_CALL_ARGS."""
+ event = ToolCallDeltaEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ delta='{"query": "hello"}',
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "TOOL_CALL_ARGS")
+ self.assertEqual(result["toolCallId"], "tc_1")
+ self.assertEqual(result["delta"], '{"query": "hello"}')
+
+ async def test_tool_call_end(self) -> None:
+ """Test ToolCallEndEvent -> TOOL_CALL_END."""
+ event = ToolCallEndEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "TOOL_CALL_END")
+ self.assertEqual(result["toolCallId"], "tc_1")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolToolResultTest(IsolatedAsyncioTestCase):
+ """Test tool result event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_tool_result_end_with_buffered_content(self) -> None:
+ """Test that ToolResultEndEvent carries accumulated text content."""
+ self.mw._convert_to_protocol(
+ ToolResultTextDeltaEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ delta="partial ",
+ ),
+ )
+ self.mw._convert_to_protocol(
+ ToolResultTextDeltaEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ delta="result",
+ ),
+ )
+
+ result = self.mw._convert_to_protocol(
+ ToolResultEndEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ state=ToolResultState.SUCCESS,
+ ),
+ )
+
+ self.assertEqual(result["type"], "TOOL_CALL_RESULT")
+ self.assertEqual(result["toolCallId"], "tc_1")
+ self.assertEqual(result["messageId"], "reply_1")
+ self.assertEqual(result["content"], "partial result")
+
+ async def test_tool_result_end_fallback_to_state(self) -> None:
+ """Test that ToolResultEndEvent falls back to state when no buffer."""
+ result = self.mw._convert_to_protocol(
+ ToolResultEndEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ state=ToolResultState.ERROR,
+ ),
+ )
+
+ self.assertEqual(result["type"], "TOOL_CALL_RESULT")
+ self.assertEqual(result["content"], "error")
+
+ async def test_tool_result_start_to_custom(self) -> None:
+ """Test ToolResultStartEvent -> CUSTOM."""
+ event = ToolResultStartEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ tool_call_name="search",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "tool_result_start")
+ self.assertIsInstance(result["value"], dict)
+
+ async def test_tool_result_text_delta_to_custom(self) -> None:
+ """Test ToolResultTextDeltaEvent -> CUSTOM."""
+ event = ToolResultTextDeltaEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ delta="partial result",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "tool_result_text_delta")
+ self.assertEqual(result["value"]["delta"], "partial result")
+
+ async def test_tool_result_data_delta_to_custom(self) -> None:
+ """Test ToolResultDataDeltaEvent -> CUSTOM."""
+ event = ToolResultDataDeltaEvent(
+ reply_id="reply_1",
+ tool_call_id="tc_1",
+ media_type="image/png",
+ data="base64data",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "tool_result_data_delta")
+ self.assertEqual(result["value"]["media_type"], "image/png")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolDataBlockTest(IsolatedAsyncioTestCase):
+ """Test data block -> custom event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_data_block_start(self) -> None:
+ """Test DataBlockStartEvent -> CUSTOM."""
+ event = DataBlockStartEvent(
+ reply_id="reply_1",
+ block_id="db_1",
+ media_type="image/png",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "data_block_start")
+ self.assertEqual(result["value"]["media_type"], "image/png")
+
+ async def test_data_block_delta(self) -> None:
+ """Test DataBlockDeltaEvent -> CUSTOM."""
+ event = DataBlockDeltaEvent(
+ reply_id="reply_1",
+ block_id="db_1",
+ data="base64chunk",
+ media_type="image/png",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "data_block_delta")
+ self.assertEqual(result["value"]["data"], "base64chunk")
+
+ async def test_data_block_end(self) -> None:
+ """Test DataBlockEndEvent -> CUSTOM."""
+ event = DataBlockEndEvent(
+ reply_id="reply_1",
+ block_id="db_1",
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "data_block_end")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolPermissionTest(IsolatedAsyncioTestCase):
+ """Test permission-related event conversions."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ async def test_require_user_confirm(self) -> None:
+ """Test RequireUserConfirmEvent -> CUSTOM."""
+ event = RequireUserConfirmEvent(
+ reply_id="reply_1",
+ tool_calls=[
+ ToolCallBlock(
+ id="tc_1",
+ name="bash",
+ input='{"command": "ls"}',
+ ),
+ ],
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "require_user_confirm")
+ self.assertIn("tool_calls", result["value"])
+
+ async def test_require_external_execution(self) -> None:
+ """Test RequireExternalExecutionEvent -> CUSTOM."""
+ event = RequireExternalExecutionEvent(
+ reply_id="reply_1",
+ tool_calls=[
+ ToolCallBlock(
+ id="tc_2",
+ name="external_api",
+ input="{}",
+ ),
+ ],
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "require_external_execution")
+
+ async def test_user_confirm_result(self) -> None:
+ """Test UserConfirmResultEvent -> CUSTOM."""
+ event = UserConfirmResultEvent(
+ reply_id="reply_1",
+ confirm_results=[
+ ConfirmResult(
+ confirmed=True,
+ tool_call=ToolCallBlock(
+ id="tc_1",
+ name="bash",
+ input='{"command": "ls"}',
+ ),
+ ),
+ ],
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "user_confirm_result")
+
+ async def test_external_execution_result(self) -> None:
+ """Test ExternalExecutionResultEvent -> CUSTOM."""
+ event = ExternalExecutionResultEvent(
+ reply_id="reply_1",
+ execution_results=[
+ ToolResultBlock(
+ id="tc_2",
+ name="external_api",
+ output="result data",
+ ),
+ ],
+ )
+ result = self.mw._convert_to_protocol(event)
+
+ self.assertEqual(result["type"], "CUSTOM")
+ self.assertEqual(result["name"], "external_execution_result")
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
+
+
+class AGUIProtocolCamelCaseTest(IsolatedAsyncioTestCase):
+ """Verify that all output dicts use camelCase keys as AGUI requires."""
+
+ async def asyncSetUp(self) -> None:
+ """The async setup method."""
+ self.mw = AGUIProtocolMiddleware(app=MagicMock())
+
+ def _assert_no_snake_case_keys(self, d: dict, context: str) -> None:
+ """Assert none of the top-level keys contain underscores."""
+ for key in d:
+ if key == "value":
+ continue
+ self.assertNotIn(
+ "_",
+ key,
+ f"Key '{key}' in {context} should be camelCase",
+ )
+
+ async def test_all_standard_events_produce_camel_case(self) -> None:
+ """Test that all directly-mapped events produce camelCase keys."""
+ events = [
+ ReplyStartEvent(
+ session_id="s",
+ reply_id="r",
+ name="a",
+ ),
+ ReplyEndEvent(session_id="s", reply_id="r"),
+ ModelCallStartEvent(reply_id="r", model_name="m"),
+ ModelCallEndEvent(
+ reply_id="r",
+ input_tokens=1,
+ output_tokens=1,
+ ),
+ TextBlockStartEvent(reply_id="r", block_id="b"),
+ TextBlockDeltaEvent(reply_id="r", block_id="b", delta="x"),
+ TextBlockEndEvent(reply_id="r", block_id="b"),
+ ThinkingBlockStartEvent(reply_id="r", block_id="b"),
+ ThinkingBlockDeltaEvent(reply_id="r", block_id="b", delta="x"),
+ ThinkingBlockEndEvent(reply_id="r", block_id="b"),
+ ToolCallStartEvent(
+ reply_id="r",
+ tool_call_id="t",
+ tool_call_name="n",
+ ),
+ ToolCallDeltaEvent(
+ reply_id="r",
+ tool_call_id="t",
+ delta="x",
+ ),
+ ToolCallEndEvent(reply_id="r", tool_call_id="t"),
+ ExceedMaxItersEvent(reply_id="r", name="a"),
+ ]
+
+ for event in events:
+ result = self.mw._convert_to_protocol(event)
+ self._assert_no_snake_case_keys(
+ result,
+ type(event).__name__,
+ )
+
+ async def asyncTearDown(self) -> None:
+ """The async teardown method."""
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index eed756a24..b006669ae 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -142,14 +142,22 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "1",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "a" * 120,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "a" * 120,
+ },
+ ],
"metadata": {},
},
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -169,11 +177,12 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
{
- "id": "c",
+ "id": AnyString(),
"text": "c" * 40,
"type": "text",
},
@@ -183,9 +192,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "3",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "d" * 40,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "d" * 40,
+ },
+ ],
"metadata": {},
},
],
@@ -221,14 +237,22 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "1",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "a" * 120,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "a" * 120,
+ },
+ ],
"metadata": {},
},
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -253,9 +277,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "3",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "d" * 40,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "d" * 40,
+ },
+ ],
"metadata": {},
},
],
@@ -290,14 +321,22 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "1",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "a" * 120,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "a" * 120,
+ },
+ ],
"metadata": {},
},
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -317,6 +356,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -331,9 +371,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "3",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "d" * 40,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "d" * 40,
+ },
+ ],
"metadata": {},
},
],
@@ -368,9 +415,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "1",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "a" * 120,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "a" * 120,
+ },
+ ],
"metadata": {},
},
],
@@ -381,6 +435,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -400,9 +455,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "3",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "d" * 40,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "d" * 40,
+ },
+ ],
"metadata": {},
},
],
@@ -440,6 +502,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -459,9 +522,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "3",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "d" * 40,
+ "content": [
+ {
+ "id": AnyString(),
+ "type": "text",
+ "text": "d" * 40,
+ },
+ ],
"metadata": {},
},
],
@@ -539,6 +609,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "2",
"created_at": AnyString(),
+ "finished_at": None,
"name": "Friday",
"role": "assistant",
"content": [
@@ -553,9 +624,16 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
{
"id": "3",
"created_at": AnyString(),
+ "finished_at": AnyString(),
"name": "User",
"role": "user",
- "content": "3" * 40,
+ "content": [
+ {
+ "id": AnyString(),
+ "text": "3" * 40,
+ "type": "text",
+ },
+ ],
"metadata": {},
},
],
diff --git a/tests/event_to_message_test.py b/tests/event_to_message_test.py
new file mode 100644
index 000000000..b9d18f343
--- /dev/null
+++ b/tests/event_to_message_test.py
@@ -0,0 +1,867 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for Msg.append_event – event-stream-to-Msg accumulation.
+
+The test drives a single Msg object through a full, realistic streaming
+sequence and asserts the complete model_dump() after every individual event.
+
+Coverage
+--------
+* TextBlock : start / delta (×2) / end
+* ThinkingBlock : start / delta (×2) / end
+* DataBlock (base-64) : start / delta (×2) / end
+* ToolCallBlock streaming : start / delta (×2) / end
+* RequireUserConfirmEvent → ASKING state
+* UserConfirmResultEvent (confirmed=True) → ALLOWED state
+* UserConfirmResultEvent (confirmed=False) → FINISHED state
+* ToolResultBlock text output : start / text-delta (×2) / end (SUCCESS)
+* RequireExternalExecutionEvent → SUBMITTED state
+* ExternalExecutionResultEvent → ToolResultBlock appended directly
+* ToolResultBlock data output : base-64 delta + URL delta / end (ERROR)
+* ReplyEndEvent → finished_at stamped
+* Wrong reply_id → event silently skipped
+* Missing block → warning, no crash
+"""
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from utils import AnyString
+
+from agentscope.event import (
+ ConfirmResult,
+ DataBlockDeltaEvent,
+ DataBlockEndEvent,
+ DataBlockStartEvent,
+ ExternalExecutionResultEvent,
+ ReplyEndEvent,
+ RequireExternalExecutionEvent,
+ RequireUserConfirmEvent,
+ TextBlockDeltaEvent,
+ TextBlockEndEvent,
+ TextBlockStartEvent,
+ ThinkingBlockDeltaEvent,
+ ThinkingBlockEndEvent,
+ ThinkingBlockStartEvent,
+ ToolCallDeltaEvent,
+ ToolCallEndEvent,
+ ToolCallStartEvent,
+ ToolResultDataDeltaEvent,
+ ToolResultEndEvent,
+ ToolResultStartEvent,
+ ToolResultTextDeltaEvent,
+ UserConfirmResultEvent,
+)
+from agentscope.message import (
+ Msg,
+ ToolCallBlock,
+ ToolResultBlock,
+ ToolResultState,
+)
+
+# ---------------------------------------------------------------------------
+# Fixed IDs used throughout – hard-coded so ground-truth dicts are readable.
+# ---------------------------------------------------------------------------
+_REPLY_ID = "reply_001"
+_SESSION_ID = "session_001"
+
+_B_TEXT = "b_text_001" # TextBlock id
+_B_THINK = "b_think_001" # ThinkingBlock id
+_B_DATA = "b_data_001" # DataBlock id
+
+_TC_ALLOW = "tc_allow_001" # tool call that gets confirmed → allowed
+_TC_DENY = "tc_deny_001" # tool call that gets denied → finished
+_TC_EXT = "tc_ext_001" # tool call for external execution
+_TC_IMG = "tc_img_001" # tool call whose result has data blocks
+
+_RES_DATA_B = "res_data_001" # DataBlock inside tool-result (base-64)
+_RES_URL_B = "res_url_001" # DataBlock inside tool-result (URL)
+
+_FIXED_END_TS = "2026-01-01T12:00:00" # deterministic finished_at
+
+
+# ---------------------------------------------------------------------------
+# Block-dict helpers – each call returns a fresh dict to avoid aliasing.
+# ---------------------------------------------------------------------------
+
+
+def _tb(block_id: str, text: str) -> dict:
+ """Text block dict."""
+ return {"type": "text", "id": block_id, "text": text}
+
+
+def _thb(block_id: str, thinking: str) -> dict:
+ """Thinking block dict."""
+ return {"type": "thinking", "id": block_id, "thinking": thinking}
+
+
+def _db_b64(block_id: str, data: str, media_type: str) -> dict:
+ """DataBlock (base-64 source) dict."""
+ return {
+ "type": "data",
+ "id": block_id,
+ "source": {"type": "base64", "data": data, "media_type": media_type},
+ "name": None,
+ }
+
+
+def _db_url(block_id: str, url: str, media_type: str) -> dict:
+ """DataBlock (URL source) dict."""
+ return {
+ "type": "data",
+ "id": block_id,
+ "source": {"type": "url", "url": url, "media_type": media_type},
+ "name": None,
+ }
+
+
+def _tcb(tc_id: str, name: str, inp: str, state: str) -> dict:
+ """ToolCallBlock dict."""
+ return {
+ "type": "tool_call",
+ "id": tc_id,
+ "name": name,
+ "input": inp,
+ "state": state,
+ "suggested_rules": [],
+ }
+
+
+def _trb(tc_id: str, name: str, output: Any, state: str) -> dict:
+ """ToolResultBlock dict."""
+ return {
+ "type": "tool_result",
+ "id": tc_id,
+ "name": name,
+ "output": output,
+ "state": state,
+ }
+
+
+class EventToMessageTest(IsolatedAsyncioTestCase):
+ """Test Msg.append_event across a full streaming event sequence."""
+
+ # ------------------------------------------------------------------
+ # asyncSetUp: build self.events and self.ground_truths in lock-step.
+ # ------------------------------------------------------------------
+
+ async def asyncSetUp(self) -> None:
+ """Build the Msg, the event list, and the ground-truth list."""
+ self.msg = Msg(
+ id=_REPLY_ID,
+ name="TestAgent",
+ role="assistant",
+ content=[],
+ )
+ _created_at = self.msg.created_at
+
+ def _base(content: list, finished_at: str | None = None) -> dict:
+ """Return the expected model_dump() of self.msg."""
+ return {
+ "name": "TestAgent",
+ "role": "assistant",
+ "id": _REPLY_ID,
+ "metadata": {},
+ "created_at": _created_at,
+ "finished_at": finished_at,
+ "content": content,
+ }
+
+ # ================================================================
+ # Stage 1 – Text block streaming
+ # ================================================================
+ ev_text_start = TextBlockStartEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_TEXT,
+ )
+ gt_text_start = _base([_tb(_B_TEXT, "")])
+
+ ev_text_delta1 = TextBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_TEXT,
+ delta="Hello",
+ )
+ gt_text_delta1 = _base([_tb(_B_TEXT, "Hello")])
+
+ ev_text_delta2 = TextBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_TEXT,
+ delta=" World",
+ )
+ gt_text_delta2 = _base([_tb(_B_TEXT, "Hello World")])
+
+ ev_text_end = TextBlockEndEvent(reply_id=_REPLY_ID, block_id=_B_TEXT)
+ gt_text_end = _base([_tb(_B_TEXT, "Hello World")]) # unchanged
+
+ # ================================================================
+ # Stage 2 – Thinking block streaming
+ # ================================================================
+ ev_think_start = ThinkingBlockStartEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_THINK,
+ )
+ gt_think_start = _base(
+ [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, ""),
+ ],
+ )
+
+ ev_think_delta1 = ThinkingBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_THINK,
+ delta="Let me",
+ )
+ gt_think_delta1 = _base(
+ [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me"),
+ ],
+ )
+
+ ev_think_delta2 = ThinkingBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_THINK,
+ delta=" think",
+ )
+ gt_think_delta2 = _base(
+ [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ ],
+ )
+
+ ev_think_end = ThinkingBlockEndEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_THINK,
+ )
+ gt_think_end = _base(
+ [ # unchanged
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ ],
+ )
+
+ # ================================================================
+ # Stage 3 – Data block streaming (base-64)
+ # ================================================================
+ ev_data_start = DataBlockStartEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_DATA,
+ media_type="image/png",
+ )
+ gt_data_start = _base(
+ [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ _db_b64(_B_DATA, "", "image/png"),
+ ],
+ )
+
+ ev_data_delta1 = DataBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_DATA,
+ data="abc",
+ media_type="image/png",
+ )
+ gt_data_delta1 = _base(
+ [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ _db_b64(_B_DATA, "abc", "image/png"),
+ ],
+ )
+
+ ev_data_delta2 = DataBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id=_B_DATA,
+ data="def",
+ media_type="image/png",
+ )
+ gt_data_delta2 = _base(
+ [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ _db_b64(_B_DATA, "abcdef", "image/png"),
+ ],
+ )
+
+ ev_data_end = DataBlockEndEvent(reply_id=_REPLY_ID, block_id=_B_DATA)
+ gt_data_end = _base(
+ [ # unchanged
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ _db_b64(_B_DATA, "abcdef", "image/png"),
+ ],
+ )
+
+ # ================================================================
+ # Stage 4 – ToolCall (TC_ALLOW): stream → confirm → allowed
+ # + text tool-result (SUCCESS)
+ # ================================================================
+ ev_tc_allow_start = ToolCallStartEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ tool_call_name="search",
+ )
+ _s4_prefix = [
+ _tb(_B_TEXT, "Hello World"),
+ _thb(_B_THINK, "Let me think"),
+ _db_b64(_B_DATA, "abcdef", "image/png"),
+ ]
+ gt_tc_allow_start = _base(
+ _s4_prefix + [_tcb(_TC_ALLOW, "search", "", "pending")],
+ )
+
+ ev_tc_allow_delta1 = ToolCallDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ delta='{"q"',
+ )
+ gt_tc_allow_delta1 = _base(
+ _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q"', "pending")],
+ )
+
+ ev_tc_allow_delta2 = ToolCallDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ delta=': "hi"}',
+ )
+ gt_tc_allow_delta2 = _base(
+ _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "pending")],
+ )
+
+ ev_tc_allow_end = ToolCallEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ )
+ gt_tc_allow_end = _base( # unchanged
+ _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "pending")],
+ )
+
+ # RequireUserConfirmEvent → state: pending → asking
+ _tc_allow_block = ToolCallBlock(
+ id=_TC_ALLOW,
+ name="search",
+ input='{"q": "hi"}',
+ )
+ ev_require_confirm = RequireUserConfirmEvent(
+ reply_id=_REPLY_ID,
+ tool_calls=[_tc_allow_block],
+ )
+ gt_require_confirm = _base(
+ _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "asking")],
+ )
+
+ # UserConfirmResultEvent (confirmed=True) → state: asking → allowed
+ ev_user_confirmed = UserConfirmResultEvent(
+ reply_id=_REPLY_ID,
+ confirm_results=[
+ ConfirmResult(confirmed=True, tool_call=_tc_allow_block),
+ ],
+ )
+ gt_user_confirmed = _base(
+ _s4_prefix + [_tcb(_TC_ALLOW, "search", '{"q": "hi"}', "allowed")],
+ )
+
+ # ToolResult for _TC_ALLOW – text output
+ ev_result_start = ToolResultStartEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ tool_call_name="search",
+ )
+ _s4b_prefix = _s4_prefix + [
+ _tcb(_TC_ALLOW, "search", '{"q": "hi"}', "allowed"),
+ ]
+ gt_result_start = _base(
+ _s4b_prefix + [_trb(_TC_ALLOW, "search", [], "running")],
+ )
+
+ # First text-delta creates a new TextBlock with auto-generated ID.
+ ev_result_text1 = ToolResultTextDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ delta="Found:",
+ )
+ gt_result_text1 = _base(
+ _s4b_prefix
+ + [
+ _trb(
+ _TC_ALLOW,
+ "search",
+ [{"type": "text", "id": AnyString(), "text": "Found:"}],
+ "running",
+ ),
+ ],
+ )
+
+ # Second text-delta appends to the SAME TextBlock.
+ ev_result_text2 = ToolResultTextDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ delta=" 3 items",
+ )
+ gt_result_text2 = _base(
+ _s4b_prefix
+ + [
+ _trb(
+ _TC_ALLOW,
+ "search",
+ [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Found: 3 items",
+ },
+ ],
+ "running",
+ ),
+ ],
+ )
+
+ ev_result_end_ok = ToolResultEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_ALLOW,
+ state=ToolResultState.SUCCESS,
+ )
+ gt_result_end_ok = _base(
+ _s4b_prefix
+ + [
+ _trb(
+ _TC_ALLOW,
+ "search",
+ [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Found: 3 items",
+ },
+ ],
+ "success",
+ ),
+ ],
+ )
+
+ # ================================================================
+ # Stage 5 – ToolCall (TC_DENY): stream → confirm → denied (finished)
+ # ================================================================
+ _s5_prefix = _s4b_prefix + [
+ _trb(
+ _TC_ALLOW,
+ "search",
+ [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": "Found: 3 items",
+ },
+ ],
+ "success",
+ ),
+ ]
+
+ ev_tc_deny_start = ToolCallStartEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_DENY,
+ tool_call_name="delete",
+ )
+ gt_tc_deny_start = _base(
+ _s5_prefix + [_tcb(_TC_DENY, "delete", "", "pending")],
+ )
+
+ ev_tc_deny_end = ToolCallEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_DENY,
+ )
+ gt_tc_deny_end = _base( # unchanged
+ _s5_prefix + [_tcb(_TC_DENY, "delete", "", "pending")],
+ )
+
+ _tc_deny_block = ToolCallBlock(id=_TC_DENY, name="delete", input="")
+ ev_require_confirm_deny = RequireUserConfirmEvent(
+ reply_id=_REPLY_ID,
+ tool_calls=[_tc_deny_block],
+ )
+ gt_require_confirm_deny = _base(
+ _s5_prefix + [_tcb(_TC_DENY, "delete", "", "asking")],
+ )
+
+ # UserConfirmResultEvent (confirmed=False) → state: asking → finished
+ ev_user_denied = UserConfirmResultEvent(
+ reply_id=_REPLY_ID,
+ confirm_results=[
+ ConfirmResult(confirmed=False, tool_call=_tc_deny_block),
+ ],
+ )
+ gt_user_denied = _base(
+ _s5_prefix + [_tcb(_TC_DENY, "delete", "", "finished")],
+ )
+
+ # ================================================================
+ # Stage 6 – ToolCall (TC_EXT): external execution flow
+ # ================================================================
+ _s6_prefix = _s5_prefix + [_tcb(_TC_DENY, "delete", "", "finished")]
+
+ ev_tc_ext_start = ToolCallStartEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_EXT,
+ tool_call_name="run_code",
+ )
+ gt_tc_ext_start = _base(
+ _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "pending")],
+ )
+
+ ev_tc_ext_end = ToolCallEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_EXT,
+ )
+ gt_tc_ext_end = _base( # unchanged
+ _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "pending")],
+ )
+
+ _tc_ext_block = ToolCallBlock(id=_TC_EXT, name="run_code", input="")
+ ev_require_ext = RequireExternalExecutionEvent(
+ reply_id=_REPLY_ID,
+ tool_calls=[_tc_ext_block],
+ )
+ gt_require_ext = _base(
+ _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "submitted")],
+ )
+
+ # ExternalExecutionResultEvent – appends a ToolResultBlock directly.
+ _ext_result_block = ToolResultBlock(
+ id=_TC_EXT,
+ name="run_code",
+ output="output: hello",
+ state=ToolResultState.SUCCESS,
+ )
+ ev_ext_result = ExternalExecutionResultEvent(
+ reply_id=_REPLY_ID,
+ execution_results=[_ext_result_block],
+ )
+ _s6b_prefix = _s6_prefix + [_tcb(_TC_EXT, "run_code", "", "submitted")]
+ gt_ext_result = _base(
+ _s6b_prefix
+ + [_trb(_TC_EXT, "run_code", "output: hello", "success")],
+ )
+
+ # ================================================================
+ # Stage 7 – ToolResult with data output: base-64 + URL blocks
+ # ================================================================
+ _s7_prefix = _s6b_prefix + [
+ _trb(_TC_EXT, "run_code", "output: hello", "success"),
+ ]
+
+ ev_tc_img_start = ToolCallStartEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_IMG,
+ tool_call_name="screenshot",
+ )
+ gt_tc_img_start = _base(
+ _s7_prefix + [_tcb(_TC_IMG, "screenshot", "", "pending")],
+ )
+
+ ev_tc_img_end = ToolCallEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_IMG,
+ )
+ gt_tc_img_end = _base( # unchanged
+ _s7_prefix + [_tcb(_TC_IMG, "screenshot", "", "pending")],
+ )
+
+ ev_res_img_start = ToolResultStartEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_IMG,
+ tool_call_name="screenshot",
+ )
+ _s7b_prefix = _s7_prefix + [_tcb(_TC_IMG, "screenshot", "", "pending")]
+ gt_res_img_start = _base(
+ _s7b_prefix + [_trb(_TC_IMG, "screenshot", [], "running")],
+ )
+
+ # Base-64 data delta → DataBlock(base64) appended to output
+ ev_res_img_b64 = ToolResultDataDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_IMG,
+ block_id=_RES_DATA_B,
+ media_type="image/png",
+ data="iVBOR==",
+ )
+ gt_res_img_b64 = _base(
+ _s7b_prefix
+ + [
+ _trb(
+ _TC_IMG,
+ "screenshot",
+ [_db_b64(_RES_DATA_B, "iVBOR==", "image/png")],
+ "running",
+ ),
+ ],
+ )
+
+ # URL data delta → DataBlock(url) appended to output
+ ev_res_img_url = ToolResultDataDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_IMG,
+ block_id=_RES_URL_B,
+ media_type="image/jpeg",
+ url="https://example.com/img.jpg",
+ )
+ gt_res_img_url = _base(
+ _s7b_prefix
+ + [
+ _trb(
+ _TC_IMG,
+ "screenshot",
+ [
+ _db_b64(_RES_DATA_B, "iVBOR==", "image/png"),
+ _db_url(
+ _RES_URL_B,
+ "https://example.com/img.jpg",
+ "image/jpeg",
+ ),
+ ],
+ "running",
+ ),
+ ],
+ )
+
+ ev_res_img_end = ToolResultEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id=_TC_IMG,
+ state=ToolResultState.ERROR,
+ )
+ gt_res_img_end = _base(
+ _s7b_prefix
+ + [
+ _trb(
+ _TC_IMG,
+ "screenshot",
+ [
+ _db_b64(_RES_DATA_B, "iVBOR==", "image/png"),
+ _db_url(
+ _RES_URL_B,
+ "https://example.com/img.jpg",
+ "image/jpeg",
+ ),
+ ],
+ "error",
+ ),
+ ],
+ )
+
+ # ================================================================
+ # Stage 8 – ReplyEndEvent
+ # ================================================================
+ _final_content = _s7b_prefix + [
+ _trb(
+ _TC_IMG,
+ "screenshot",
+ [
+ _db_b64(_RES_DATA_B, "iVBOR==", "image/png"),
+ _db_url(
+ _RES_URL_B,
+ "https://example.com/img.jpg",
+ "image/jpeg",
+ ),
+ ],
+ "error",
+ ),
+ ]
+ ev_reply_end = ReplyEndEvent(
+ reply_id=_REPLY_ID,
+ session_id=_SESSION_ID,
+ created_at=_FIXED_END_TS,
+ )
+ gt_reply_end = _base(_final_content, finished_at=_FIXED_END_TS)
+
+ # ================================================================
+ # Assemble the two parallel lists
+ # ================================================================
+ self.events = [
+ # Stage 1: Text
+ ev_text_start,
+ ev_text_delta1,
+ ev_text_delta2,
+ ev_text_end,
+ # Stage 2: Thinking
+ ev_think_start,
+ ev_think_delta1,
+ ev_think_delta2,
+ ev_think_end,
+ # Stage 3: Data (base-64)
+ ev_data_start,
+ ev_data_delta1,
+ ev_data_delta2,
+ ev_data_end,
+ # Stage 4: ToolCall → confirm (allowed) + text result (success)
+ ev_tc_allow_start,
+ ev_tc_allow_delta1,
+ ev_tc_allow_delta2,
+ ev_tc_allow_end,
+ ev_require_confirm,
+ ev_user_confirmed,
+ ev_result_start,
+ ev_result_text1,
+ ev_result_text2,
+ ev_result_end_ok,
+ # Stage 5: ToolCall → confirm (denied)
+ ev_tc_deny_start,
+ ev_tc_deny_end,
+ ev_require_confirm_deny,
+ ev_user_denied,
+ # Stage 6: ToolCall → external execution
+ ev_tc_ext_start,
+ ev_tc_ext_end,
+ ev_require_ext,
+ ev_ext_result,
+ # Stage 7: ToolResult with data output (base-64 + URL)
+ ev_tc_img_start,
+ ev_tc_img_end,
+ ev_res_img_start,
+ ev_res_img_b64,
+ ev_res_img_url,
+ ev_res_img_end,
+ # Stage 8: REPLY_END
+ ev_reply_end,
+ ]
+ self.ground_truths = [
+ # Stage 1
+ gt_text_start,
+ gt_text_delta1,
+ gt_text_delta2,
+ gt_text_end,
+ # Stage 2
+ gt_think_start,
+ gt_think_delta1,
+ gt_think_delta2,
+ gt_think_end,
+ # Stage 3
+ gt_data_start,
+ gt_data_delta1,
+ gt_data_delta2,
+ gt_data_end,
+ # Stage 4
+ gt_tc_allow_start,
+ gt_tc_allow_delta1,
+ gt_tc_allow_delta2,
+ gt_tc_allow_end,
+ gt_require_confirm,
+ gt_user_confirmed,
+ gt_result_start,
+ gt_result_text1,
+ gt_result_text2,
+ gt_result_end_ok,
+ # Stage 5
+ gt_tc_deny_start,
+ gt_tc_deny_end,
+ gt_require_confirm_deny,
+ gt_user_denied,
+ # Stage 6
+ gt_tc_ext_start,
+ gt_tc_ext_end,
+ gt_require_ext,
+ gt_ext_result,
+ # Stage 7
+ gt_tc_img_start,
+ gt_tc_img_end,
+ gt_res_img_start,
+ gt_res_img_b64,
+ gt_res_img_url,
+ gt_res_img_end,
+ # Stage 8
+ gt_reply_end,
+ ]
+
+ # ------------------------------------------------------------------
+ # Tests
+ # ------------------------------------------------------------------
+
+ async def test_append_event_stream(self) -> None:
+ """Apply every event in order and assert the full Msg state after each.
+
+ Uses a zip loop over self.events / self.ground_truths so that the
+ event index is clear from the assertion failure message.
+ """
+ self.assertEqual(
+ len(self.events),
+ len(self.ground_truths),
+ "events and ground_truths must have equal length",
+ )
+ for idx, (event, expected) in enumerate(
+ zip(self.events, self.ground_truths),
+ ):
+ self.msg.append_event(event)
+ self.assertDictEqual(
+ self.msg.model_dump(),
+ expected,
+ msg=f"Mismatch after event[{idx}] ({event.type})",
+ )
+
+ async def test_wrong_reply_id_is_skipped(self) -> None:
+ """An event whose reply_id does not match msg.id must be ignored."""
+ original_dump = self.msg.model_dump()
+ wrong_event = TextBlockStartEvent(
+ reply_id="totally_wrong_id",
+ block_id="should_not_appear",
+ )
+ self.msg.append_event(wrong_event)
+ self.assertDictEqual(
+ self.msg.model_dump(),
+ original_dump,
+ msg="Msg must not change when event.reply_id does not match",
+ )
+
+ async def test_missing_block_does_not_crash(self) -> None:
+ """Sending a delta for a non-existent block must log a warning only."""
+ original_dump = self.msg.model_dump()
+
+ # Delta events for blocks that were never started
+ ghost_events = [
+ TextBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id="ghost_text",
+ delta="x",
+ ),
+ ThinkingBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id="ghost_think",
+ delta="x",
+ ),
+ DataBlockDeltaEvent(
+ reply_id=_REPLY_ID,
+ block_id="ghost_data",
+ data="x",
+ media_type="image/png",
+ ),
+ ToolCallDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id="ghost_tc",
+ delta="x",
+ ),
+ ToolResultTextDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id="ghost_tr",
+ delta="x",
+ ),
+ ToolResultDataDeltaEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id="ghost_tr",
+ media_type="image/png",
+ data="x",
+ ),
+ ToolResultEndEvent(
+ reply_id=_REPLY_ID,
+ tool_call_id="ghost_tr",
+ state=ToolResultState.SUCCESS,
+ ),
+ ]
+ for ev in ghost_events:
+ self.msg.append_event(ev) # must not raise
+
+ self.assertDictEqual(
+ self.msg.model_dump(),
+ original_dump,
+ msg="Msg must not change when delta targets a missing block",
+ )
+
+ async def asyncTearDown(self) -> None:
+ """No teardown needed."""
diff --git a/tests/hitl_external_execution_test.py b/tests/hitl_external_execution_test.py
index b37fb0332..16faaafa2 100644
--- a/tests/hitl_external_execution_test.py
+++ b/tests/hitl_external_execution_test.py
@@ -179,6 +179,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
return {
"id": AnyString(),
"created_at": AnyString(),
+ "finished_at": None,
"metadata": {},
"name": "Friday",
"role": "assistant",
@@ -252,6 +253,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": name,
"input": tool_input,
"state": "submitted",
+ "suggested_rules": [],
},
],
},
@@ -353,7 +355,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -363,6 +372,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "submitted",
+ "suggested_rules": [],
},
],
},
@@ -389,7 +399,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
# Second call: resume with external execution result
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -412,7 +422,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -422,6 +439,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
@@ -566,7 +584,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -576,6 +601,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "submitted",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -583,6 +609,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_2,
"state": "pending",
+ "suggested_rules": [],
},
],
},
@@ -609,7 +636,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
# Second call: resume with external execution result
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -648,7 +675,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
events = []
async for evnt in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(evnt.model_dump())
@@ -673,7 +700,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -683,6 +717,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -690,6 +725,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_2,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
@@ -853,7 +889,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -863,6 +906,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "submitted",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -870,6 +914,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "submitted",
+ "suggested_rules": [],
},
],
},
@@ -896,7 +941,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
# Second call: resume with external execution result
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -929,7 +974,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -955,7 +1000,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -965,6 +1017,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -972,6 +1025,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
@@ -1129,7 +1183,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -1139,6 +1200,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "submitted",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -1146,6 +1208,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "submitted",
+ "suggested_rules": [],
},
],
},
@@ -1178,7 +1241,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -1206,7 +1269,14 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -1216,6 +1286,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_call",
@@ -1223,6 +1294,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "finished",
+ "suggested_rules": [],
},
{
"type": "tool_result",
diff --git a/tests/hitl_mixed_interrupt.py b/tests/hitl_mixed_interrupt.py
index 6b29fce59..07ce2a171 100644
--- a/tests/hitl_mixed_interrupt.py
+++ b/tests/hitl_mixed_interrupt.py
@@ -444,7 +444,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
)
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
expected_events_resume = self._get_require_external_execution_events(
@@ -493,7 +493,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -669,7 +669,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
)
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
expected_events_resume = self._get_require_external_execution_events(
@@ -725,7 +725,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -800,7 +800,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
)
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
expected_events_after_second_confirm = (
@@ -832,7 +832,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
@@ -1039,7 +1039,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
)
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
self.assertEqual(len(events), 4)
@@ -1124,7 +1124,7 @@ class AgentMixTest(IsolatedAsyncioTestCase):
events = []
async for event in self.agent.reply_stream(
- event=external_result_event,
+ inputs=external_result_event,
):
events.append(event.model_dump())
diff --git a/tests/hitl_user_confirmation_test.py b/tests/hitl_user_confirmation_test.py
index 1e10734dd..26880418b 100644
--- a/tests/hitl_user_confirmation_test.py
+++ b/tests/hitl_user_confirmation_test.py
@@ -228,6 +228,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
return {
"id": AnyString(),
"created_at": AnyString(),
+ "finished_at": None,
"metadata": {},
"name": "Friday",
"role": "assistant",
@@ -317,6 +318,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -334,7 +343,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -344,6 +360,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -369,7 +393,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
# Second call: resume with user confirmation result
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
# Verify events after resumption
@@ -393,7 +417,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -403,6 +434,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_result",
@@ -538,6 +577,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -555,7 +602,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -565,6 +619,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_call",
@@ -572,6 +634,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_2,
"state": "pending",
+ "suggested_rules": [],
},
],
},
@@ -597,7 +660,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
# resume with user confirmation result
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
# Verify events after resumption (sequential execution)
@@ -616,6 +679,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_2,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -643,7 +714,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
# Second call: resume with user confirmation result
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
expected_events_resume_2 = [
@@ -665,7 +736,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -675,6 +753,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_call",
@@ -682,6 +768,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.sequential_tool_name,
"input": self.tool_input_2,
"state": "finished",
+ "suggested_rules": [
+ {
+ "tool_name": self.sequential_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_result",
@@ -828,6 +922,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -841,6 +943,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -858,7 +968,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -868,6 +985,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_call",
@@ -875,6 +1000,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -900,7 +1033,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
# resume with user confirmation result
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
# Verify events for tool call 1 after resumption
@@ -932,7 +1065,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
)
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
expected_events = [
@@ -954,7 +1087,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -964,6 +1104,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "finished",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_call",
@@ -971,6 +1119,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "finished",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_result",
@@ -1115,6 +1271,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -1128,6 +1292,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -1141,7 +1313,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
+ "finished_at": AnyString(),
},
{
"content": [
@@ -1151,6 +1330,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_1,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
{
"type": "tool_call",
@@ -1158,6 +1345,14 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"name": self.concurrent_tool_name,
"input": self.tool_input_2,
"state": "asking",
+ "suggested_rules": [
+ {
+ "tool_name": self.concurrent_tool_name,
+ "rule_content": None,
+ "behavior": PermissionBehavior.ALLOW,
+ "source": "suggested",
+ },
+ ],
},
],
},
@@ -1189,7 +1384,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
)
events = []
- async for event in self.agent.reply_stream(event=user_confirm_event):
+ async for event in self.agent.reply_stream(inputs=user_confirm_event):
events.append(event.model_dump())
tool_events = events[:6]
@@ -1239,10 +1434,17 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
{
"id": AnyString(),
"created_at": AnyString(),
+ "finished_at": AnyString(),
"metadata": {},
"name": "user",
"role": "user",
- "content": self.user_input_text,
+ "content": [
+ {
+ "type": "text",
+ "id": AnyString(),
+ "text": self.user_input_text,
+ },
+ ],
},
)
diff --git a/tests/message_test.py b/tests/message_test.py
index 7d89b65c8..465f3de95 100644
--- a/tests/message_test.py
+++ b/tests/message_test.py
@@ -15,6 +15,7 @@ from agentscope.message import (
Msg,
ToolCallBlock,
ToolResultBlock,
+ ToolResultState,
)
@@ -31,9 +32,16 @@ class MessageTest(IsolatedAsyncioTestCase):
"id": AnyString(),
"name": "user",
"role": "user",
- "content": "hello world",
+ "content": [
+ {
+ "id": AnyString(),
+ "text": "hello world",
+ "type": "text",
+ },
+ ],
"metadata": {},
"created_at": AnyString(),
+ "finished_at": AnyString(),
},
)
@@ -54,6 +62,7 @@ class MessageTest(IsolatedAsyncioTestCase):
],
"metadata": {},
"created_at": AnyString(),
+ "finished_at": AnyString(),
},
)
@@ -108,6 +117,7 @@ class MessageTest(IsolatedAsyncioTestCase):
],
"metadata": {},
"created_at": AnyString(),
+ "finished_at": AnyString(),
},
)
@@ -131,6 +141,7 @@ class MessageTest(IsolatedAsyncioTestCase):
],
"metadata": {},
"created_at": AnyString(),
+ "finished_at": None,
},
)
@@ -150,6 +161,7 @@ class MessageTest(IsolatedAsyncioTestCase):
],
"metadata": {},
"created_at": AnyString(),
+ "finished_at": None,
},
)
@@ -189,7 +201,7 @@ class MessageTest(IsolatedAsyncioTestCase):
id="1",
name="tool",
output="result",
- state="success",
+ state=ToolResultState.SUCCESS,
),
],
)
@@ -243,7 +255,7 @@ class MessageTest(IsolatedAsyncioTestCase):
id="1",
name="tool",
output="result",
- state="success",
+ state=ToolResultState.SUCCESS,
),
],
)
diff --git a/tests/middleware_background_acting_test.py b/tests/middleware_background_acting_test.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/tests/middleware_test.py b/tests/middleware_test.py
index 0b2b1b989..0e4ddbcce 100644
--- a/tests/middleware_test.py
+++ b/tests/middleware_test.py
@@ -5,13 +5,24 @@ from unittest.async_case import IsolatedAsyncioTestCase
from typing import Any, AsyncGenerator, Callable, Union
from utils import MockModel
-
+from pydantic import BaseModel
from agentscope.event import AgentEvent
from agentscope.agent import Agent
from agentscope.middleware import MiddlewareBase
from agentscope.model import ChatResponse
-from agentscope.message import TextBlock, UserMsg, Msg
-from agentscope.tool import Toolkit
+from agentscope.message import (
+ TextBlock,
+ UserMsg,
+ SystemMsg,
+ Msg,
+ ToolCallBlock,
+)
+from agentscope.tool import Toolkit, ToolBase, ToolChunk
+from agentscope.permission import (
+ PermissionContext,
+ PermissionDecision,
+ PermissionBehavior,
+)
class TestMiddleware(IsolatedAsyncioTestCase):
@@ -488,18 +499,15 @@ class TestMiddleware(IsolatedAsyncioTestCase):
input_kwargs: dict,
next_handler: Callable[..., AsyncGenerator],
) -> AsyncGenerator:
- """Modify msgs before passing to next handler."""
+ """Modify inputs before passing to next handler."""
# Modify the message content
- msgs = input_kwargs["msgs"]
- if isinstance(msgs, Msg):
+ inputs = input_kwargs["inputs"]
+ if isinstance(inputs, Msg):
modified_msg = UserMsg(
- name=msgs.name,
- content="MODIFIED: " + msgs.content,
+ name=inputs.name,
+ content="MODIFIED: " + inputs.get_text_content(),
)
- async for item in next_handler(
- msgs=modified_msg,
- event=input_kwargs.get("event"),
- ):
+ async for item in next_handler(inputs=modified_msg):
yield item
else:
async for item in next_handler(**input_kwargs):
@@ -546,7 +554,10 @@ class TestMiddleware(IsolatedAsyncioTestCase):
# Verify the model received the modified message
user_messages = [m for m in received_messages if m.role == "user"]
self.assertTrue(len(user_messages) > 0)
- self.assertIn("MODIFIED: original message", user_messages[-1].content)
+ self.assertIn(
+ "MODIFIED: original message",
+ user_messages[-1].get_text_content(),
+ )
async def test_on_reasoning_middleware_modify_input(self) -> None:
"""Test that on_reasoning middleware can modify tool_choice input."""
@@ -606,15 +617,69 @@ class TestMiddleware(IsolatedAsyncioTestCase):
# Verify the model received tool_choice='none'
self.assertIn("none", received_tool_choices)
- async def test_on_acting_middleware_modify_input(self) -> None:
- """Test that on_acting middleware can modify tool_call input."""
- from agentscope.message import ToolCallBlock
+ async def test_on_acting_middleware_intercepts_tool_execution(
+ self,
+ ) -> None:
+ """Test that on_acting middleware intercepts raw tool execution.
+
+ After the refactor, ``on_acting`` wraps only ``_acting_impl``
+ (i.e. ``toolkit.call_tool``). Permission checking and context
+ writes are handled by ``_execute_tool_call`` *outside* the hook.
+ This test verifies that the middleware can observe and modify the
+ ``tool_call`` passed to the actual tool function.
+ """
+
+ # ------------------------------------------------------------------ #
+ # A minimal tool that records the raw input it receives. #
+ # ------------------------------------------------------------------ #
+ received_inputs: list[str] = []
+
+ class _EchoParams(BaseModel):
+ value: str
+
+ class EchoTool(ToolBase):
+ """Tool that echoes its input and records it."""
+
+ name: str = "echo"
+ description: str = "Echo the value."
+ input_schema: dict = _EchoParams.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
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Always allow."""
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message="allowed",
+ )
- # Track what tool_call the implementation receives
- received_tool_calls = []
+ async def __call__(
+ self,
+ value: str,
+ ) -> ToolChunk:
+ """Record the value and return it."""
+ received_inputs.append(value)
+ return ToolChunk(
+ content=[TextBlock(text=f"echo:{value}")],
+ )
- class ModifyToolCallMiddleware(MiddlewareBase):
- """Middleware that modifies the tool_call input."""
+ toolkit_with_tool = Toolkit(tools=[EchoTool()])
+
+ # ------------------------------------------------------------------ #
+ # Middleware that renames the tool_call.input before forwarding. #
+ # ------------------------------------------------------------------ #
+ intercepted_tool_calls: list[str] = []
+
+ class ObserveActingMiddleware(MiddlewareBase):
+ """Middleware that records the tool_call seen at acting level."""
async def on_acting(
self,
@@ -622,54 +687,57 @@ class TestMiddleware(IsolatedAsyncioTestCase):
input_kwargs: dict,
next_handler: Callable[..., AsyncGenerator],
) -> AsyncGenerator:
- """Modify tool_call.input before execution."""
+ """Record the tool_call and forward to next handler."""
tool_call = input_kwargs["tool_call"]
- # Create a modified tool call with different input
- modified_tool_call = ToolCallBlock(
+ intercepted_tool_calls.append(tool_call.input)
+ # Modify the input before execution
+ import json
+
+ modified = ToolCallBlock(
id=tool_call.id,
name=tool_call.name,
- input='{"value": "MODIFIED"}',
+ input=json.dumps({"value": "MODIFIED"}),
state=tool_call.state,
)
- # Track what we're passing to next handler
- received_tool_calls.append(modified_tool_call.input)
- async for item in next_handler(tool_call=modified_tool_call):
- yield item
+ async for chunk in next_handler(tool_call=modified):
+ yield chunk
- middleware = ModifyToolCallMiddleware()
+ middleware = ObserveActingMiddleware()
+ self.mock_model.set_responses(
+ [
+ ChatResponse(
+ content=[TextBlock(text="done")],
+ is_last=True,
+ ),
+ ],
+ )
- # Create a mock agent with the middleware
agent_instance = Agent(
name="test_agent",
system_prompt="test prompt",
model=self.mock_model,
- toolkit=self.toolkit,
+ toolkit=toolkit_with_tool,
middlewares=[middleware],
)
- # Directly call _execute_tool_call to test the middleware chain
- original_tool_call = ToolCallBlock(
+ # Call _execute_tool_call with a valid tool call.
+ tool_call = ToolCallBlock(
id="call_1",
- name="test_tool",
+ name="echo",
input='{"value": "ORIGINAL"}',
)
-
- # Collect events from the middleware chain
events = []
- try:
- # pylint: disable=protected-access
- async for evt in agent_instance._execute_tool_call(
- original_tool_call,
- ):
- events.append(evt)
- except Exception:
- # Expected to fail since tool doesn't exist, but we can still
- # verify the middleware modified the input
- pass
-
- # Verify the middleware modified the tool_call.input
- self.assertEqual(len(received_tool_calls), 1)
- self.assertIn("MODIFIED", received_tool_calls[0])
+ # pylint: disable=protected-access
+ async for evt in agent_instance._execute_tool_call(tool_call):
+ events.append(evt)
+
+ # Middleware intercepted the tool call at execution level
+ self.assertEqual(len(intercepted_tool_calls), 1)
+ self.assertIn("ORIGINAL", intercepted_tool_calls[0])
+
+ # The tool actually received the MODIFIED value
+ self.assertEqual(len(received_inputs), 1)
+ self.assertEqual(received_inputs[0], "MODIFIED")
async def test_on_model_call_middleware_modify_input(self) -> None:
"""Test that on_model_call middleware can modify messages and model."""
@@ -686,10 +754,9 @@ class TestMiddleware(IsolatedAsyncioTestCase):
"""Prepend a system message to the messages list."""
messages = input_kwargs["messages"]
modified_messages = [
- Msg(
+ SystemMsg(
name="system",
content="INJECTED SYSTEM MESSAGE",
- role="system",
),
] + messages
@@ -743,7 +810,8 @@ class TestMiddleware(IsolatedAsyncioTestCase):
system_messages = [m for m in received_messages if m.role == "system"]
self.assertTrue(
any(
- "INJECTED SYSTEM MESSAGE" in m.content for m in system_messages
+ "INJECTED SYSTEM MESSAGE" in m.get_text_content()
+ for m in system_messages
),
)
diff --git a/tests/storage_redis_test.py b/tests/storage_redis_test.py
new file mode 100644
index 000000000..cdfb000bb
--- /dev/null
+++ b/tests/storage_redis_test.py
@@ -0,0 +1,582 @@
+# -*- coding: utf-8 -*-
+"""Unit tests for RedisStorage using fakeredis."""
+from unittest.async_case import IsolatedAsyncioTestCase
+
+import fakeredis.aioredis
+
+from agentscope.app.storage import (
+ RedisStorage,
+ RedisKeyConfig,
+ AgentRecord,
+ SessionConfig,
+ ChatModelConfig,
+ ScheduleRecord,
+ ScheduleData,
+ SessionSource,
+)
+from agentscope.credential import OllamaCredential
+from agentscope.app.storage._model._agent import AgentData
+from agentscope.agent import ContextConfig, ReActConfig
+from agentscope.message import UserMsg, AssistantMsg, TextBlock
+
+
+def make_storage() -> RedisStorage:
+ """Create a RedisStorage instance backed by fakeredis."""
+ storage = RedisStorage.__new__(RedisStorage)
+ # pylint: disable=protected-access
+ storage._client = fakeredis.aioredis.FakeRedis(decode_responses=True)
+ storage.key_ttl = None
+ storage.key_config = RedisKeyConfig()
+ return storage
+
+
+def make_agent_record(user_id: str) -> AgentRecord:
+ """Create a test AgentRecord with all-default sub-configs."""
+ return AgentRecord(
+ user_id=user_id,
+ data=AgentData(
+ id="agent-data-id",
+ name="test-agent",
+ system_prompt="You are a helpful assistant.",
+ context_config=ContextConfig(),
+ react_config=ReActConfig(),
+ ),
+ )
+
+
+def make_session_config(workspace_id: str = "ws-1") -> SessionConfig:
+ """Create a test SessionConfig with a chat model config."""
+ return SessionConfig(
+ workspace_id=workspace_id,
+ chat_model_config=ChatModelConfig(
+ type="openai",
+ credential_id="cred-1",
+ model="gpt-4",
+ parameters={},
+ ),
+ )
+
+
+class TestCredential(IsolatedAsyncioTestCase):
+ """Tests for credential CRUD and cascading operations."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up test fixtures."""
+ self.storage = make_storage()
+ self.user_id = "user-1"
+
+ async def test_create(self) -> None:
+ """Create a credential and verify it is retrievable via list."""
+ cred_id = await self.storage.upsert_credential(
+ self.user_id,
+ OllamaCredential(host="http://localhost:11434"),
+ )
+ records = await self.storage.list_credentials(self.user_id)
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0].id, cred_id)
+ self.assertEqual(records[0].data.get("type"), "ollama_credential")
+ self.assertEqual(
+ records[0].data.get("host"),
+ "http://localhost:11434",
+ )
+
+ async def test_list_empty(self) -> None:
+ """Verify list returns empty when no records exist."""
+ records = await self.storage.list_credentials(self.user_id)
+ self.assertEqual(records, [])
+
+ async def test_update_in_place(self) -> None:
+ """Update a credential and verify data changed without adding
+ a new record."""
+ cred_id = await self.storage.upsert_credential(
+ self.user_id,
+ OllamaCredential(host="http://old-host:11434"),
+ )
+ await self.storage.upsert_credential(
+ self.user_id,
+ OllamaCredential(id=cred_id, host="http://new-host:11434"),
+ )
+ records = await self.storage.list_credentials(self.user_id)
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0].data.get("host"), "http://new-host:11434")
+
+ async def test_delete(self) -> None:
+ """Delete a credential and verify it is gone from Redis."""
+ cred_id = await self.storage.upsert_credential(
+ self.user_id,
+ OllamaCredential(host="http://localhost:11434"),
+ )
+ result = await self.storage.delete_credential(self.user_id, cred_id)
+ self.assertTrue(result)
+ records = await self.storage.list_credentials(self.user_id)
+ self.assertEqual(records, [])
+
+ async def test_delete_nonexistent(self) -> None:
+ """Verify delete returns False for non-existent record."""
+ result = await self.storage.delete_credential(
+ self.user_id,
+ "no-such-id",
+ )
+ self.assertFalse(result)
+
+ async def test_user_isolation(self) -> None:
+ """Verify different users cannot see each other's records."""
+ await self.storage.upsert_credential(
+ "user-A",
+ OllamaCredential(host="http://localhost:11434"),
+ )
+ records = await self.storage.list_credentials("user-B")
+ self.assertEqual(records, [])
+
+
+class TestAgent(IsolatedAsyncioTestCase):
+ """Tests for agent CRUD and cascading operations."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up test fixtures."""
+ self.storage = make_storage()
+ self.user_id = "user-1"
+
+ async def test_create(self) -> None:
+ """Create an agent and verify it is retrievable via list."""
+ record = make_agent_record(self.user_id)
+ agent_id = await self.storage.upsert_agent(self.user_id, record)
+ records = await self.storage.list_agents(self.user_id)
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0].id, agent_id)
+ self.assertEqual(records[0].data.name, "test-agent")
+
+ async def test_list_empty(self) -> None:
+ """Verify list returns empty when no records exist."""
+ records = await self.storage.list_agents(self.user_id)
+ self.assertEqual(records, [])
+
+ async def test_delete(self) -> None:
+ """Delete an agent and verify it is gone from Redis."""
+ record = make_agent_record(self.user_id)
+ await self.storage.upsert_agent(self.user_id, record)
+ result = await self.storage.delete_agent(self.user_id, record.id)
+ self.assertTrue(result)
+ records = await self.storage.list_agents(self.user_id)
+ self.assertEqual(records, [])
+
+ async def test_delete_nonexistent(self) -> None:
+ """Verify delete returns False for non-existent record."""
+ result = await self.storage.delete_agent(self.user_id, "no-such-id")
+ self.assertFalse(result)
+
+ async def test_user_isolation(self) -> None:
+ """Verify different users cannot see each other's records."""
+ await self.storage.upsert_agent("user-A", make_agent_record("user-A"))
+ records = await self.storage.list_agents("user-B")
+ self.assertEqual(records, [])
+
+
+class TestSession(IsolatedAsyncioTestCase):
+ """Tests for session CRUD and cascading operations."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up test fixtures."""
+ self.storage = make_storage()
+ self.user_id = "user-1"
+ self.agent_id = "agent-1"
+ self.workspace_id = "ws-1"
+
+ async def test_create(self) -> None:
+ """Create a session and verify it is retrievable via list."""
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(self.workspace_id),
+ )
+ records = await self.storage.list_sessions(self.user_id, self.agent_id)
+ self.assertEqual(len(records), 1)
+ self.assertEqual(records[0].config.workspace_id, self.workspace_id)
+ self.assertEqual(records[0].agent_id, self.agent_id)
+
+ async def test_list_empty(self) -> None:
+ """Verify list returns empty when no records exist."""
+ records = await self.storage.list_sessions(self.user_id, self.agent_id)
+ self.assertEqual(records, [])
+
+ async def test_upsert_same_triple_updates_in_place(self) -> None:
+ """Second upsert with the same session_id must update the existing
+ record, not create a second one."""
+ session = await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(self.workspace_id),
+ )
+ first_id = session.id
+
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(self.workspace_id),
+ session_id=first_id,
+ )
+ records_after = await self.storage.list_sessions(
+ self.user_id,
+ self.agent_id,
+ )
+ self.assertEqual(len(records_after), 1)
+ self.assertEqual(records_after[0].id, first_id)
+
+ async def test_delete(self) -> None:
+ """Delete a session and verify it is gone from Redis."""
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(self.workspace_id),
+ )
+ records = await self.storage.list_sessions(self.user_id, self.agent_id)
+ result = await self.storage.delete_session(
+ self.user_id,
+ self.agent_id,
+ records[0].id,
+ )
+ self.assertTrue(result)
+ remaining = await self.storage.list_sessions(
+ self.user_id,
+ self.agent_id,
+ )
+ self.assertEqual(remaining, [])
+
+ async def test_delete_cascades_lookup_key(self) -> None:
+ """Deleting a session must remove the lookup key so a subsequent upsert
+ for the same (user, agent) pair creates a fresh session with a new
+ id."""
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(self.workspace_id),
+ )
+ records = await self.storage.list_sessions(self.user_id, self.agent_id)
+ old_id = records[0].id
+
+ await self.storage.delete_session(self.user_id, self.agent_id, old_id)
+
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(self.workspace_id),
+ )
+ new_records = await self.storage.list_sessions(
+ self.user_id,
+ self.agent_id,
+ )
+ self.assertEqual(len(new_records), 1)
+ self.assertNotEqual(new_records[0].id, old_id)
+
+ async def test_delete_nonexistent(self) -> None:
+ """Verify delete returns False for non-existent record."""
+ result = await self.storage.delete_session(
+ self.user_id,
+ self.agent_id,
+ "no-such-id",
+ )
+ self.assertFalse(result)
+
+ async def test_agent_isolation(self) -> None:
+ """Verify different agents cannot see each other's sessions."""
+ await self.storage.upsert_session(
+ self.user_id,
+ "agent-A",
+ make_session_config(self.workspace_id),
+ )
+ records = await self.storage.list_sessions(self.user_id, "agent-B")
+ self.assertEqual(records, [])
+
+
+class TestMessage(IsolatedAsyncioTestCase):
+ """Tests for message persistence: upsert_message, get_message and
+ list_messages."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up test fixtures."""
+ self.storage = make_storage()
+ self.user_id = "user-1"
+ self.session_id = "session-1"
+
+ async def test_upsert_appends_new_message(self) -> None:
+ """Upserting a new message appends it to the session list."""
+ msg = UserMsg(name="alice", content="hello")
+ await self.storage.upsert_message(self.user_id, self.session_id, msg)
+ messages = await self.storage.list_messages(
+ self.user_id,
+ self.session_id,
+ )
+ self.assertListEqual(
+ [m.model_dump() for m in messages],
+ [msg.model_dump()],
+ )
+
+ async def test_upsert_replaces_last_message_with_same_id(self) -> None:
+ """Upserting a message whose id matches the last entry replaces it
+ in-place (streaming overwrite), rather than creating a duplicate."""
+ msg = AssistantMsg(name="bot", content="v1")
+ await self.storage.upsert_message(self.user_id, self.session_id, msg)
+
+ # Keep the same id but replace content — simulates a streaming update.
+ updated = msg.model_copy(
+ update={"content": [TextBlock(text="v2")]},
+ )
+ await self.storage.upsert_message(
+ self.user_id,
+ self.session_id,
+ updated,
+ )
+
+ messages = await self.storage.list_messages(
+ self.user_id,
+ self.session_id,
+ )
+ self.assertListEqual(
+ [m.model_dump() for m in messages],
+ [updated.model_dump()],
+ "Duplicate must not be created; existing entry must be replaced.",
+ )
+
+ async def test_upsert_appends_when_id_differs_from_last(self) -> None:
+ """Upserting a message with a different id than the last always
+ appends, even if an earlier message shares the same id."""
+ msg1 = UserMsg(name="alice", content="first")
+ msg2 = UserMsg(name="alice", content="second")
+ await self.storage.upsert_message(self.user_id, self.session_id, msg1)
+ await self.storage.upsert_message(self.user_id, self.session_id, msg2)
+ messages = await self.storage.list_messages(
+ self.user_id,
+ self.session_id,
+ )
+ self.assertListEqual(
+ [m.model_dump() for m in messages],
+ [msg1.model_dump(), msg2.model_dump()],
+ )
+
+ async def test_get_message_returns_correct_message(self) -> None:
+ """get_message fetches the message matching the given id."""
+ msg1 = UserMsg(name="alice", content="first")
+ msg2 = UserMsg(name="alice", content="second")
+ await self.storage.upsert_message(self.user_id, self.session_id, msg1)
+ await self.storage.upsert_message(self.user_id, self.session_id, msg2)
+
+ fetched = await self.storage.get_message(
+ self.user_id,
+ self.session_id,
+ msg1.id,
+ )
+ self.assertIsNotNone(fetched)
+ self.assertDictEqual(fetched.model_dump(), msg1.model_dump())
+
+ async def test_get_message_nonexistent_returns_none(self) -> None:
+ """get_message returns None when the message id does not exist."""
+ result = await self.storage.get_message(
+ self.user_id,
+ self.session_id,
+ "no-such-id",
+ )
+ self.assertIsNone(result)
+
+ async def test_list_messages_empty_session(self) -> None:
+ """list_messages returns an empty list for a session with no
+ messages."""
+ messages = await self.storage.list_messages(
+ self.user_id,
+ self.session_id,
+ )
+ self.assertListEqual(messages, [])
+
+ async def test_list_messages_pagination(self) -> None:
+ """list_messages respects offset and limit parameters."""
+ msgs = [UserMsg(name="alice", content=f"msg-{i}") for i in range(5)]
+ for m in msgs:
+ await self.storage.upsert_message(
+ self.user_id,
+ self.session_id,
+ m,
+ )
+
+ # Fetch the middle slice: offset=1, limit=3 → msgs[1], msgs[2], msgs[3]
+ page = await self.storage.list_messages(
+ self.user_id,
+ self.session_id,
+ offset=1,
+ limit=3,
+ )
+ self.assertListEqual(
+ [m.model_dump() for m in page],
+ [m.model_dump() for m in msgs[1:4]],
+ )
+
+ async def test_list_messages_order_preserved(self) -> None:
+ """Messages are returned in the insertion order (chronological)."""
+ msgs = [
+ UserMsg(name="alice", content=text)
+ for text in ["alpha", "beta", "gamma"]
+ ]
+ for m in msgs:
+ await self.storage.upsert_message(
+ self.user_id,
+ self.session_id,
+ m,
+ )
+ messages = await self.storage.list_messages(
+ self.user_id,
+ self.session_id,
+ )
+ self.assertListEqual(
+ [m.model_dump() for m in messages],
+ [m.model_dump() for m in msgs],
+ )
+
+ async def test_session_isolation(self) -> None:
+ """Messages belonging to different sessions do not interfere."""
+ await self.storage.upsert_message(
+ self.user_id,
+ "session-A",
+ UserMsg(name="alice", content="in A"),
+ )
+ messages = await self.storage.list_messages(
+ self.user_id,
+ "session-B",
+ )
+ self.assertListEqual(messages, [])
+
+
+def make_schedule_record(user_id: str, agent_id: str) -> ScheduleRecord:
+ """Create a test ScheduleRecord."""
+ return ScheduleRecord(
+ user_id=user_id,
+ agent_id=agent_id,
+ data=ScheduleData(
+ name="test-schedule",
+ cron_expression="0 9 * * *",
+ started_at="2026-01-01T00:00:00",
+ chat_model_config=ChatModelConfig(
+ type="openai",
+ credential_id="cred-1",
+ model="gpt-4",
+ parameters={},
+ ),
+ ),
+ )
+
+
+class TestScheduleSession(IsolatedAsyncioTestCase):
+ """Tests for schedule-session index and cascade deletion."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up test fixtures."""
+ self.storage = make_storage()
+ self.user_id = "user-1"
+ self.agent_id = "agent-1"
+
+ async def test_list_sessions_by_schedule(self) -> None:
+ """Sessions created with source_schedule_id are queryable by
+ schedule."""
+ schedule = make_schedule_record(self.user_id, self.agent_id)
+ await self.storage.upsert_schedule(self.user_id, schedule)
+
+ session = await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(),
+ source=SessionSource.SCHEDULE,
+ source_schedule_id=schedule.id,
+ )
+
+ results = await self.storage.list_sessions_by_schedule(
+ self.user_id,
+ schedule.id,
+ )
+ self.assertEqual(len(results), 1)
+ self.assertEqual(results[0].id, session.id)
+ self.assertEqual(results[0].source_schedule_id, schedule.id)
+
+ async def test_list_sessions_by_schedule_empty(self) -> None:
+ """Returns empty list when no sessions exist for a schedule."""
+ results = await self.storage.list_sessions_by_schedule(
+ self.user_id,
+ "nonexistent-schedule",
+ )
+ self.assertEqual(results, [])
+
+ async def test_schedule_session_also_in_agent_index(self) -> None:
+ """A schedule-created session appears in both the schedule and agent
+ session indexes."""
+ schedule = make_schedule_record(self.user_id, self.agent_id)
+ await self.storage.upsert_schedule(self.user_id, schedule)
+
+ session = await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(),
+ source=SessionSource.SCHEDULE,
+ source_schedule_id=schedule.id,
+ )
+
+ agent_sessions = await self.storage.list_sessions(
+ self.user_id,
+ self.agent_id,
+ )
+ self.assertEqual(len(agent_sessions), 1)
+ self.assertEqual(agent_sessions[0].id, session.id)
+
+ async def test_delete_schedule_cascades_sessions(self) -> None:
+ """Deleting a schedule removes all its execution sessions."""
+ schedule = make_schedule_record(self.user_id, self.agent_id)
+ await self.storage.upsert_schedule(self.user_id, schedule)
+
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(),
+ source=SessionSource.SCHEDULE,
+ source_schedule_id=schedule.id,
+ )
+ await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(),
+ source=SessionSource.SCHEDULE,
+ source_schedule_id=schedule.id,
+ )
+
+ await self.storage.delete_schedule(self.user_id, schedule.id)
+
+ schedule_sessions = await self.storage.list_sessions_by_schedule(
+ self.user_id,
+ schedule.id,
+ )
+ self.assertEqual(schedule_sessions, [])
+
+ agent_sessions = await self.storage.list_sessions(
+ self.user_id,
+ self.agent_id,
+ )
+ self.assertEqual(agent_sessions, [])
+
+ async def test_delete_session_cleans_schedule_index(self) -> None:
+ """Deleting a session removes it from the schedule session index."""
+ schedule = make_schedule_record(self.user_id, self.agent_id)
+ await self.storage.upsert_schedule(self.user_id, schedule)
+
+ session = await self.storage.upsert_session(
+ self.user_id,
+ self.agent_id,
+ make_session_config(),
+ source=SessionSource.SCHEDULE,
+ source_schedule_id=schedule.id,
+ )
+
+ await self.storage.delete_session(
+ self.user_id,
+ self.agent_id,
+ session.id,
+ )
+
+ results = await self.storage.list_sessions_by_schedule(
+ self.user_id,
+ schedule.id,
+ )
+ self.assertEqual(results, [])
diff --git a/tests/tool_offload_middleware_test.py b/tests/tool_offload_middleware_test.py
new file mode 100644
index 000000000..593e7065d
--- /dev/null
+++ b/tests/tool_offload_middleware_test.py
@@ -0,0 +1,346 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=protected-access
+"""Unit tests for ToolOffloadMiddleware."""
+import asyncio
+import json
+from typing import Any
+from unittest.async_case import IsolatedAsyncioTestCase
+
+from pydantic import BaseModel
+from utils import MockModel
+
+from agentscope.agent import Agent
+from agentscope.app import BackgroundTaskManager, ToolOffloadMiddleware
+from agentscope.message import HintBlock, TextBlock, UserMsg, ToolCallBlock
+from agentscope.model import ChatResponse
+from agentscope.permission import (
+ PermissionContext,
+ PermissionDecision,
+ PermissionBehavior,
+)
+from agentscope.tool import ToolBase, ToolChunk, Toolkit, ToolResponse
+
+
+class _SlowToolParams(BaseModel):
+ """Parameters for the slow test tool."""
+
+ delay: float
+
+
+class SlowTool(ToolBase):
+ """A tool that sleeps for ``delay`` seconds before returning."""
+
+ name: str = "slow_tool"
+ description: str = "A slow tool for testing background offload."
+ input_schema: dict = _SlowToolParams.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
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Always allow.
+
+ Args:
+ tool_input (`dict[str, Any]`):
+ The tool input parameters.
+ context (`PermissionContext`):
+ The permission context.
+
+ Returns:
+ `PermissionDecision`:
+ Always ALLOW.
+ """
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message="allowed",
+ )
+
+ async def __call__( # type: ignore[override]
+ self,
+ delay: float,
+ ) -> ToolChunk:
+ """Sleep for *delay* seconds then return a result.
+
+ Args:
+ delay (`float`):
+ Seconds to sleep.
+
+ Returns:
+ `ToolChunk`:
+ A chunk containing the result text.
+ """
+ await asyncio.sleep(delay)
+ return ToolChunk(
+ content=[TextBlock(text=f"SlowTool finished after {delay}s")],
+ )
+
+
+class _FastToolParams(BaseModel):
+ """Parameters for the fast test tool."""
+
+ value: str
+
+
+class FastTool(ToolBase):
+ """A tool that returns immediately."""
+
+ name: str = "fast_tool"
+ description: str = "A fast tool for testing normal execution."
+ input_schema: dict = _FastToolParams.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
+
+ async def check_permissions(
+ self,
+ tool_input: dict[str, Any],
+ context: PermissionContext,
+ ) -> PermissionDecision:
+ """Always allow.
+
+ Args:
+ tool_input (`dict[str, Any]`):
+ The tool input parameters.
+ context (`PermissionContext`):
+ The permission context.
+
+ Returns:
+ `PermissionDecision`:
+ Always ALLOW.
+ """
+ return PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message="allowed",
+ )
+
+ async def __call__( # type: ignore[override]
+ self,
+ value: str,
+ ) -> ToolChunk:
+ """Return a chunk with *value*.
+
+ Args:
+ value (`str`):
+ The value to echo.
+
+ Returns:
+ `ToolChunk`:
+ A chunk containing the value.
+ """
+ return ToolChunk(
+ content=[TextBlock(text=f"FastTool: {value}")],
+ )
+
+
+class ToolOffloadMiddlewareTest(IsolatedAsyncioTestCase):
+ """Test cases for the ToolOffloadMiddleware."""
+
+ async def asyncSetUp(self) -> None:
+ """Set up test fixtures."""
+ self.mock_model = MockModel()
+ self.bg_manager = BackgroundTaskManager()
+
+ # ------------------------------------------------------------------
+ # Helper
+ # ------------------------------------------------------------------
+
+ def _make_agent(
+ self,
+ toolkit: Toolkit,
+ timeout_secs: float,
+ ) -> tuple[Agent, ToolOffloadMiddleware]:
+ """Create an agent with ToolOffloadMiddleware attached.
+
+ Args:
+ toolkit (`Toolkit`):
+ The toolkit to attach to the agent.
+ timeout_secs (`float`):
+ The middleware timeout.
+
+ Returns:
+ `tuple[Agent, ToolOffloadMiddleware]`:
+ The configured agent and the middleware instance.
+ """
+ middleware = ToolOffloadMiddleware(
+ bg_manager=self.bg_manager,
+ timeout_secs=timeout_secs,
+ )
+ agent = Agent(
+ name="test_agent",
+ system_prompt="test prompt",
+ model=self.mock_model,
+ toolkit=toolkit,
+ middlewares=[middleware],
+ )
+ return agent, middleware
+
+ # ------------------------------------------------------------------
+ # Tests
+ # ------------------------------------------------------------------
+
+ async def test_fast_tool_completes_normally(self) -> None:
+ """A tool that finishes within the timeout yields its real result."""
+
+ toolkit = Toolkit(tools=[FastTool()])
+ agent, _ = self._make_agent(toolkit, timeout_secs=5.0)
+
+ tool_call = ToolCallBlock(
+ id="call_fast",
+ name="fast_tool",
+ input=json.dumps({"value": "hello"}),
+ )
+
+ results: list = []
+ # pylint: disable=protected-access
+ async for item in agent._acting(tool_call):
+ results.append(item)
+
+ # Should yield real ToolResponse (not synthetic)
+ responses = [r for r in results if isinstance(r, ToolResponse)]
+ self.assertEqual(len(responses), 1)
+ text = responses[0].content[0].text # type: ignore[union-attr]
+ self.assertIn("FastTool: hello", text)
+ # No background tasks registered
+ self.assertEqual(len(self.bg_manager.tasks), 0)
+
+ async def test_slow_tool_offloaded_to_background(self) -> None:
+ """A tool that exceeds timeout returns a synthetic result."""
+
+ toolkit = Toolkit(tools=[SlowTool()])
+ # Set a very short timeout so the 0.5s tool is always offloaded
+ agent, _ = self._make_agent(toolkit, timeout_secs=0.05)
+
+ tool_call = ToolCallBlock(
+ id="call_slow",
+ name="slow_tool",
+ input=json.dumps({"delay": 0.5}),
+ )
+
+ results: list = []
+ # pylint: disable=protected-access
+ async for item in agent._acting(tool_call):
+ results.append(item)
+
+ # Should yield a synthetic ToolResponse immediately
+ responses = [r for r in results if isinstance(r, ToolResponse)]
+ self.assertEqual(len(responses), 1)
+ text = responses[0].content[0].text # type: ignore[union-attr]
+ self.assertIn("background", text)
+ self.assertIn("task_id=", text)
+
+ # Background task should be registered
+ self.assertEqual(len(self.bg_manager.tasks), 1)
+
+ async def test_background_task_result_injected_into_context(
+ self,
+ ) -> None:
+ """After the background tool finishes, the result is pushed to the
+ BackgroundTaskManager as a HintBlock."""
+
+ toolkit = Toolkit(tools=[SlowTool()])
+ agent, _ = self._make_agent(toolkit, timeout_secs=0.05)
+
+ tool_call = ToolCallBlock(
+ id="call_bg",
+ name="slow_tool",
+ input=json.dumps({"delay": 0.2}),
+ )
+
+ # Trigger offload
+ # pylint: disable=protected-access
+ async for _ in agent._acting(tool_call):
+ pass
+
+ # Wait long enough for the background tool (0.2s) to finish
+ await asyncio.sleep(0.4)
+
+ # The completed result should now be available on the manager
+ pending = self.bg_manager.pop_results(agent.state.session_id)
+ self.assertEqual(len(pending), 1)
+ self.assertIsInstance(pending[0], HintBlock)
+ hint_text = pending[0].hint
+ self.assertIn("SlowTool finished", hint_text)
+ self.assertIn("<system-notification>", hint_text)
+
+ async def test_on_reasoning_injects_pending_messages(self) -> None:
+ """on_reasoning hook injects pending HintBlocks into the agent
+ context as part of an assistant message."""
+ session_id = "session_test_inject"
+
+ self.mock_model.set_responses(
+ [
+ ChatResponse(
+ content=[TextBlock(text="ok")],
+ is_last=True,
+ ),
+ ],
+ )
+
+ toolkit = Toolkit()
+ agent, _ = self._make_agent(toolkit, timeout_secs=5.0)
+
+ # Override the agent's session_id and pre-populate a pending hint
+ # for that session on the manager.
+ agent.state.session_id = session_id
+ self.bg_manager.push_result(
+ session_id,
+ HintBlock(hint="Background result: done"),
+ )
+
+ await agent.reply(UserMsg("user", "anything"))
+
+ # Context should contain a HintBlock (injected before reasoning) on
+ # an assistant message authored by this agent.
+ injected_hints = [
+ block.hint
+ for m in agent.state.context
+ if m.role == "assistant" and m.name == agent.name
+ for block in m.content
+ if isinstance(block, HintBlock)
+ ]
+ self.assertTrue(
+ any("Background result" in t for t in injected_hints),
+ )
+
+ async def test_task_stop_cancels_background_task(self) -> None:
+ """TaskStop tool cancels the running background asyncio task."""
+
+ toolkit = Toolkit(tools=[SlowTool()])
+ agent, _ = self._make_agent(toolkit, timeout_secs=0.05)
+
+ tool_call = ToolCallBlock(
+ id="call_cancel",
+ name="slow_tool",
+ input=json.dumps({"delay": 10.0}),
+ )
+
+ # Offload the slow tool
+ # pylint: disable=protected-access
+ async for _ in agent._acting(tool_call):
+ pass
+
+ self.assertEqual(len(self.bg_manager.tasks), 1)
+ task_id = next(iter(self.bg_manager.tasks))
+ asyncio_task = self.bg_manager.tasks[task_id].asyncio_task
+
+ # Call TaskStop
+ task_stop_tools = await self.bg_manager.list_tools()
+ task_stop = task_stop_tools[0]
+ result = await task_stop(task_id=task_id)
+ text = result.content[0].text # type: ignore[union-attr]
+ self.assertIn("stopped successfully", text)
+
+ # The asyncio task should be cancelling
+ self.assertTrue(asyncio_task.cancelled() or asyncio_task.cancelling())
+ # Removed from manager
+ self.assertEqual(len(self.bg_manager.tasks), 0)
diff --git a/tests/tracing_test.py b/tests/tracing_test.py
deleted file mode 100644
index 9c4312646..000000000
--- a/tests/tracing_test.py
+++ /dev/null
@@ -1,846 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Unit tests for the tracing module using an in-memory OTel exporter."""
-import json
-from typing import Any
-from unittest.async_case import IsolatedAsyncioTestCase
-
-from opentelemetry import trace as otel_trace
-from opentelemetry.sdk.trace import TracerProvider
-from opentelemetry.sdk.trace.export import SimpleSpanProcessor
-from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
- InMemorySpanExporter,
-)
-
-from utils import MockModel
-
-from agentscope.agent import Agent
-from agentscope.event import (
- ConfirmResult,
- ExternalExecutionResultEvent,
- RequireExternalExecutionEvent,
- RequireUserConfirmEvent,
- UserConfirmResultEvent,
-)
-from agentscope.message import (
- TextBlock,
- ToolCallBlock,
- ToolResultBlock,
- ToolResultState,
- UserMsg,
-)
-from agentscope.model import ChatResponse, ChatUsage
-from agentscope.permission import (
- PermissionContext,
- PermissionDecision,
- PermissionBehavior,
-)
-from agentscope.tool import Toolkit, ToolBase
-from agentscope.middleware import TracingMiddleware
-
-
-# ---------------------------------------------------------------------------
-# Shared test fixtures
-# ---------------------------------------------------------------------------
-
-
-class WeatherTool(ToolBase):
- """Stub weather tool for tracing tests."""
-
- name: str = "get_weather"
- description: str = "Return stub weather for a city."
- input_schema: dict = {
- "type": "object",
- "properties": {"city": {"type": "string"}},
- "required": ["city"],
- }
- is_concurrency_safe: bool = True
- is_read_only: bool = True
- is_external_tool: bool = False
- is_mcp: bool = False
-
- async def check_permissions(
- self,
- tool_input: dict[str, Any],
- context: PermissionContext,
- ) -> PermissionDecision:
- return PermissionDecision(
- behavior=PermissionBehavior.ALLOW,
- message="always allowed",
- )
-
- async def execute(self, city: str) -> str:
- """Stub weather tool for tracing tests."""
- return f"{city}: sunny, 25°C."
-
-
-class HitlWeatherTool(ToolBase):
- """Weather tool that always asks user for confirmation (HITL)."""
-
- name: str = "get_weather"
- description: str = "Return weather for a city, requires user confirmation."
- input_schema: dict = {
- "type": "object",
- "properties": {"city": {"type": "string"}},
- "required": ["city"],
- }
- is_concurrency_safe: bool = True
- is_read_only: bool = True
- is_external_tool: bool = False
- is_mcp: bool = False
-
- async def check_permissions(
- self,
- tool_input: dict[str, Any],
- context: PermissionContext,
- ) -> PermissionDecision:
- return PermissionDecision(
- behavior=PermissionBehavior.ASK,
- message="user must confirm this tool call",
- )
-
- async def execute(self, city: str) -> str:
- """Stub weather tool for tracing tests."""
- return f"{city}: sunny, 25°C."
-
-
-class ExternalWeatherTool(ToolBase):
- """Weather tool that is always executed externally."""
-
- name: str = "get_weather"
- description: str = "Return weather for a city via external execution."
- input_schema: dict = {
- "type": "object",
- "properties": {"city": {"type": "string"}},
- "required": ["city"],
- }
- is_concurrency_safe: bool = True
- is_read_only: bool = True
- is_external_tool: bool = True # Mark as external
- is_mcp: bool = False
-
- async def check_permissions(
- self,
- tool_input: dict[str, Any],
- context: PermissionContext,
- ) -> PermissionDecision:
- return PermissionDecision(
- behavior=PermissionBehavior.ALLOW,
- message="always allowed",
- )
-
- async def execute(self, city: str) -> str:
- """Stub weather tool for tracing tests."""
- return f"{city}: sunny, 25°C."
-
-
-def _make_tool_call_response(tool_id: str, city: str) -> ChatResponse:
- return ChatResponse(
- content=[
- ToolCallBlock(
- id=tool_id,
- name="get_weather",
- input=json.dumps({"city": city}),
- ),
- ],
- is_last=True,
- usage=ChatUsage(input_tokens=10, output_tokens=5, time=0.05),
- )
-
-
-def _make_text_response(text: str) -> ChatResponse:
- return ChatResponse(
- content=[TextBlock(text=text)],
- is_last=True,
- usage=ChatUsage(input_tokens=15, output_tokens=8, time=0.05),
- )
-
-
-class TracingTest(IsolatedAsyncioTestCase):
- """Tests that OTel spans are emitted with correct attributes.
-
- The in-memory exporter is set up once per class (setUpClass) because
- the OTel global TracerProvider cannot be replaced once installed.
- setUp only creates fresh model/agent and clears the exporter.
- """
-
- exporter: InMemorySpanExporter
-
- @classmethod
- def setUpClass(cls) -> None:
- """Configure an in-memory OTel provider once for the whole class."""
- cls.exporter = InMemorySpanExporter()
- provider = TracerProvider()
- provider.add_span_processor(SimpleSpanProcessor(cls.exporter))
- otel_trace.set_tracer_provider(provider)
-
- def setUp(self) -> None:
- """Create a fresh agent and clear accumulated spans before each
- test."""
- self.exporter.clear()
- self.model = MockModel()
- self.agent = Agent(
- name="test-agent",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[WeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
-
- # -----------------------------------------------------------------------
- # Helpers
- # -----------------------------------------------------------------------
-
- def _spans_by_name(self, fragment: str) -> list:
- return [
- s
- for s in self.exporter.get_finished_spans()
- if fragment in (s.name or "")
- ]
-
- def _all_conv_ids(self) -> set:
- return {
- dict(s.attributes or {}).get("gen_ai.conversation.id")
- for s in self.exporter.get_finished_spans()
- if "gen_ai.conversation.id" in (s.attributes or {})
- }
-
- # -----------------------------------------------------------------------
- # Tests: Agent.reply
- # -----------------------------------------------------------------------
-
- async def test_reply_spans_share_conversation_id(self) -> None:
- """All spans from a single reply must share the same
- conversation_id."""
- self.model.set_responses(
- [
- _make_tool_call_response("c3", "Guangzhou"),
- _make_text_response("Guangzhou is sunny."),
- ],
- )
- msg = UserMsg(name="user", content="Weather in Guangzhou?")
- await self.agent.reply(msg)
-
- conv_ids = self._all_conv_ids()
- self.assertEqual(
- len(conv_ids),
- 1,
- f"All spans must share exactly one conversation_id, "
- f"got: {conv_ids}",
- )
-
- async def test_invoke_agent_span_has_response_attributes(self) -> None:
- """invoke_agent span must carry gen_ai.output.messages attribute."""
- self.model.set_responses(
- [
- _make_tool_call_response("c4", "Wuhan"),
- _make_text_response("Wuhan weather: clear sky."),
- ],
- )
- msg = UserMsg(name="user", content="Weather in Wuhan?")
- await self.agent.reply(msg)
-
- agent_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(agent_spans),
- 1,
- "Expected exactly one invoke_agent span",
- )
- span_attrs = dict(agent_spans[0].attributes or {})
- output_raw = span_attrs.get("gen_ai.output.messages")
- assert isinstance(
- output_raw,
- str,
- ), "invoke_agent span gen_ai.output.messages should be a string"
- output = json.loads(output_raw)
- self.assertEqual(
- output,
- [
- {
- "role": "assistant",
- "parts": [
- {
- "type": "text",
- "content": "Wuhan weather: clear sky.",
- },
- ],
- "name": "test-agent",
- "finish_reason": "stop",
- },
- ],
- )
-
- async def test_invoke_agent_span_has_input_attributes(self) -> None:
- """invoke_agent span must carry gen_ai.input.messages attribute."""
- self.model.set_responses(
- [
- _make_text_response("Simple answer."),
- ],
- )
- msg = UserMsg(name="user", content="Simple question?")
- await self.agent.reply(msg)
-
- agent_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(agent_spans),
- 1,
- "Expected exactly one invoke_agent span",
- )
- span_attrs = dict(agent_spans[0].attributes or {})
- input_raw = span_attrs.get("gen_ai.input.messages")
- assert isinstance(
- input_raw,
- str,
- ), "invoke_agent span gen_ai.input.messages should be a string"
- input_msgs = json.loads(input_raw)
- self.assertEqual(
- input_msgs,
- [
- {
- "role": "user",
- "parts": [
- {"type": "text", "content": "Simple question?"},
- ],
- "name": "user",
- "finish_reason": "stop",
- },
- ],
- )
-
- async def test_execute_tool_span_has_tool_name_attribute(self) -> None:
- """execute_tool span must have the correct gen_ai.tool.name
- attribute."""
- self.model.set_responses(
- [
- _make_tool_call_response("c8", "Nanjing"),
- _make_text_response("Nanjing result."),
- ],
- )
- msg = UserMsg(name="user", content="Weather in Nanjing?")
- await self.agent.reply(msg)
-
- tool_spans = self._spans_by_name("execute_tool")
- self.assertEqual(
- len(tool_spans),
- 1,
- "Expected exactly one execute_tool span",
- )
- span_attrs = dict(tool_spans[0].attributes or {})
- self.assertEqual(
- span_attrs.get("gen_ai.tool.name"),
- "get_weather",
- "execute_tool span should have gen_ai.tool.name = get_weather",
- )
-
- # -----------------------------------------------------------------------
- # Tests: chat (LLM) span
- # -----------------------------------------------------------------------
-
- async def test_chat_span_has_model_and_provider(self) -> None:
- """chat span must carry gen_ai.request.model and
- gen_ai.provider.name."""
- self.model.set_responses(
- [_make_text_response("Hello from model.")],
- )
- msg = UserMsg(name="user", content="Hello?")
- await self.agent.reply(msg)
-
- chat_spans = self._spans_by_name("chat")
- self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")
- span_attrs = dict(chat_spans[0].attributes or {})
- self.assertEqual(
- span_attrs.get("gen_ai.request.model"),
- "mock-model",
- "chat span gen_ai.request.model should equal mock-model",
- )
- self.assertEqual(
- span_attrs.get("gen_ai.operation.name"),
- "chat",
- "chat span gen_ai.operation.name should equal chat",
- )
-
- async def test_chat_span_has_output_messages(self) -> None:
- """chat span must carry gen_ai.output.messages with response
- content."""
- self.model.set_responses(
- [_make_text_response("Weather is fine.")],
- )
- msg = UserMsg(name="user", content="How is the weather?")
- await self.agent.reply(msg)
-
- chat_spans = self._spans_by_name("chat")
- self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")
- span_attrs = dict(chat_spans[0].attributes or {})
- output_raw = span_attrs.get("gen_ai.output.messages")
- assert isinstance(
- output_raw,
- str,
- ), "chat span gen_ai.output.messages should be a string"
- output = json.loads(output_raw)
- self.assertEqual(
- output,
- [
- {
- "role": "assistant",
- "parts": [
- {"type": "text", "content": "Weather is fine."},
- ],
- "finish_reason": "stop",
- },
- ],
- )
-
- async def test_chat_span_has_usage_tokens(self) -> None:
- """chat span must carry input/output token counts from usage."""
- self.model.set_responses(
- [_make_text_response("Token test.")],
- )
- msg = UserMsg(name="user", content="Count tokens?")
- await self.agent.reply(msg)
-
- chat_spans = self._spans_by_name("chat")
- self.assertEqual(len(chat_spans), 1, "Expected exactly one chat span")
- span_attrs = dict(chat_spans[0].attributes or {})
- self.assertEqual(
- span_attrs.get("gen_ai.usage.input_tokens"),
- 15,
- "chat span gen_ai.usage.input_tokens should equal 15",
- )
- self.assertEqual(
- span_attrs.get("gen_ai.usage.output_tokens"),
- 8,
- "chat span gen_ai.usage.output_tokens should equal 8",
- )
-
- # -----------------------------------------------------------------------
- # Tests: reply_id attribute
- # -----------------------------------------------------------------------
-
- async def test_invoke_agent_span_has_reply_id(self) -> None:
- """invoke_agent span from a normal reply must carry reply_id.
-
- reply() delegates to _reply(), which is the only decorated entry
- point, so there is exactly one invoke_agent span. We search by
- attribute rather than relying on list order for robustness.
- """
- self.model.set_responses(
- [
- _make_tool_call_response("r1", "Wuhan"),
- _make_text_response("Wuhan: clear sky."),
- ],
- )
- msg = UserMsg(name="user", content="Weather in Wuhan?")
- await self.agent.reply(msg)
-
- agent_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(agent_spans),
- 1,
- "Expected exactly one invoke_agent span",
- )
- span_attrs = dict(agent_spans[0].attributes or {})
- self.assertIn(
- "agentscope.agent.reply_id",
- span_attrs,
- "invoke_agent span should have agentscope.agent.reply_id",
- )
-
- # -----------------------------------------------------------------------
- # Tests: HITL (Human-in-the-loop)
- # -----------------------------------------------------------------------
-
- async def test_hitl_first_call_has_hitl_pending_attribute(self) -> None:
- """First call in HITL flow must have
- agentscope.agent.hitl_pending_tools."""
- hitl_agent = Agent(
- name="hitl-agent",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[HitlWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
- # The HITL tool returns ASK;
- # first call ends with RequireUserConfirmEvent
- self.model.set_responses(
- [_make_tool_call_response("h1", "Beijing")],
- )
- self.exporter.clear()
-
- msg = UserMsg(name="user", content="Weather in Beijing?")
- async for _ in hitl_agent.reply_stream(msg):
- pass
-
- first_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(first_spans),
- 1,
- "Expected exactly one invoke_agent span from first HITL call",
- )
- span_attrs = dict(first_spans[0].attributes or {})
- self.assertIn(
- "agentscope.agent.hitl_pending_tools",
- span_attrs,
- "First HITL span should carry agentscope.agent.hitl_pending_tools",
- )
- pending = json.loads(span_attrs["agentscope.agent.hitl_pending_tools"])
- self.assertEqual(pending, ["get_weather"])
-
- async def test_hitl_spans_share_reply_id(self) -> None:
- """Both HITL calls must share the same agentscope.agent.reply_id."""
- hitl_agent = Agent(
- name="hitl-agent2",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[HitlWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
-
- # First call: agent asks for confirmation
- self.model.set_responses(
- [_make_tool_call_response("h2", "Shanghai")],
- )
- self.exporter.clear()
-
- require_confirm_event = None
- async for evt in hitl_agent.reply_stream(
- UserMsg(name="user", content="Weather in Shanghai?"),
- ):
- if isinstance(evt, RequireUserConfirmEvent):
- require_confirm_event = evt
-
- self.assertIsNotNone(
- require_confirm_event,
- "Expected RequireUserConfirmEvent",
- )
-
- first_spans = self._spans_by_name("invoke_agent")
- first_reply_ids = {
- dict(s.attributes or {}).get("agentscope.agent.reply_id")
- for s in first_spans
- if "agentscope.agent.reply_id" in (s.attributes or {})
- }
- self.assertEqual(len(first_reply_ids), 1)
- reply_id_first = next(iter(first_reply_ids))
-
- # Second call: user confirms
- self.model.set_responses(
- [_make_text_response("Shanghai: 18°C, raining.")],
- )
- self.exporter.clear()
-
- confirm_event = UserConfirmResultEvent(
- reply_id=require_confirm_event.reply_id,
- confirm_results=[
- ConfirmResult(
- confirmed=True,
- tool_call=require_confirm_event.tool_calls[0],
- ),
- ],
- )
- await hitl_agent.reply(event=confirm_event)
-
- second_spans = self._spans_by_name("invoke_agent")
- second_reply_ids = {
- dict(s.attributes or {}).get("agentscope.agent.reply_id")
- for s in second_spans
- if "agentscope.agent.reply_id" in (s.attributes or {})
- }
- self.assertEqual(len(second_reply_ids), 1)
- reply_id_second = next(iter(second_reply_ids))
-
- self.assertEqual(
- reply_id_first,
- reply_id_second,
- "Both HITL calls must share the same reply_id",
- )
-
- async def test_hitl_second_call_has_incoming_event_type(self) -> None:
- """Second call in HITL flow must carry
- incoming_event_type=user_confirm_result."""
- hitl_agent = Agent(
- name="hitl-agent3",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[HitlWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
-
- # First call: agent asks for confirmation
- self.model.set_responses(
- [_make_tool_call_response("h3", "Tianjin")],
- )
- self.exporter.clear()
-
- require_confirm_event = None
- async for evt in hitl_agent.reply_stream(
- UserMsg(name="user", content="Weather in Tianjin?"),
- ):
- if isinstance(evt, RequireUserConfirmEvent):
- require_confirm_event = evt
-
- self.assertIsNotNone(
- require_confirm_event,
- "Expected RequireUserConfirmEvent",
- )
-
- # Second call: user confirms
- self.model.set_responses(
- [_make_text_response("Tianjin: windy, 12°C.")],
- )
- self.exporter.clear()
-
- confirm_event = UserConfirmResultEvent(
- reply_id=require_confirm_event.reply_id,
- confirm_results=[
- ConfirmResult(
- confirmed=True,
- tool_call=require_confirm_event.tool_calls[0],
- ),
- ],
- )
- await hitl_agent.reply(event=confirm_event)
-
- agent_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(agent_spans),
- 1,
- "Expected exactly one invoke_agent span from second HITL call",
- )
- span_attrs = dict(agent_spans[0].attributes or {})
- self.assertEqual(
- span_attrs.get("agentscope.agent.incoming_event_type"),
- "user_confirm_result",
- "Second HITL invoke_agent span should have "
- "incoming_event_type=user_confirm_result",
- )
-
- # -----------------------------------------------------------------------
- # Tests: External execution
- # -----------------------------------------------------------------------
-
- async def test_external_execution_first_call_has_pending_attribute(
- self,
- ) -> None:
- """First call must have
- agentscope.agent.external_execution_pending_tools."""
- ext_agent = Agent(
- name="ext-agent",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[ExternalWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
- self.model.set_responses(
- [_make_tool_call_response("e1", "Guangzhou")],
- )
- self.exporter.clear()
-
- async for _ in ext_agent.reply_stream(
- UserMsg(name="user", content="Weather in Guangzhou?"),
- ):
- pass
-
- first_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(first_spans),
- 1,
- "Expected exactly one invoke_agent span",
- )
- span_attrs = dict(first_spans[0].attributes or {})
- self.assertIn(
- "agentscope.agent.external_execution_pending_tools",
- span_attrs,
- "First external-execution span should carry "
- "agentscope.agent.external_execution_pending_tools",
- )
- pending = json.loads(
- span_attrs["agentscope.agent.external_execution_pending_tools"],
- )
- self.assertEqual(pending, ["get_weather"])
-
- async def test_external_execution_spans_share_reply_id(self) -> None:
- """Both external-execution calls must share the same reply_id."""
- ext_agent = Agent(
- name="ext-agent-rid",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[ExternalWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
-
- # First call: agent requires external execution
- self.model.set_responses(
- [_make_tool_call_response("ex-r1", "Nanjing")],
- )
- self.exporter.clear()
-
- require_ext_event = None
- async for evt in ext_agent.reply_stream(
- UserMsg(name="user", content="Weather in Nanjing?"),
- ):
- if isinstance(evt, RequireExternalExecutionEvent):
- require_ext_event = evt
-
- self.assertIsNotNone(
- require_ext_event,
- "Expected RequireExternalExecutionEvent",
- )
-
- first_spans = self._spans_by_name("invoke_agent")
- first_reply_ids = {
- dict(s.attributes or {}).get("agentscope.agent.reply_id")
- for s in first_spans
- if "agentscope.agent.reply_id" in (s.attributes or {})
- }
- self.assertEqual(len(first_reply_ids), 1)
- reply_id_first = next(iter(first_reply_ids))
-
- # Second call: inject external result
- self.model.set_responses(
- [_make_text_response("Nanjing: clear, 18°C.")],
- )
- self.exporter.clear()
-
- ext_result = ExternalExecutionResultEvent(
- reply_id=require_ext_event.reply_id,
- execution_results=[
- ToolResultBlock(
- id=require_ext_event.tool_calls[0].id,
- name="get_weather",
- output="Nanjing: clear, 18°C.",
- state=ToolResultState.SUCCESS,
- ),
- ],
- )
- await ext_agent.reply(event=ext_result)
-
- second_spans = self._spans_by_name("invoke_agent")
- second_reply_ids = {
- dict(s.attributes or {}).get("agentscope.agent.reply_id")
- for s in second_spans
- if "agentscope.agent.reply_id" in (s.attributes or {})
- }
- self.assertEqual(len(second_reply_ids), 1)
- reply_id_second = next(iter(second_reply_ids))
-
- self.assertEqual(
- reply_id_first,
- reply_id_second,
- "Both external-execution calls must share the same reply_id",
- )
-
- async def test_external_execution_second_call_has_synthetic_tool_span(
- self,
- ) -> None:
- """Second call with ExternalExecutionResultEvent must produce
- execute_tool span."""
- ext_agent = Agent(
- name="ext-agent2",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[ExternalWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
-
- # First call
- self.model.set_responses(
- [_make_tool_call_response("e2", "Shenzhen")],
- )
- self.exporter.clear()
-
- require_ext_event = None
- async for evt in ext_agent.reply_stream(
- UserMsg(name="user", content="Weather in Shenzhen?"),
- ):
- if isinstance(evt, RequireExternalExecutionEvent):
- require_ext_event = evt
-
- self.assertIsNotNone(require_ext_event)
-
- # Second call: inject external result
- self.model.set_responses(
- [_make_text_response("Shenzhen: warm, 28°C.")],
- )
- self.exporter.clear()
-
- ext_result = ExternalExecutionResultEvent(
- reply_id=require_ext_event.reply_id,
- execution_results=[
- ToolResultBlock(
- id=require_ext_event.tool_calls[0].id,
- name="get_weather",
- output="Shenzhen: warm, 28°C.",
- state=ToolResultState.SUCCESS,
- ),
- ],
- )
- await ext_agent.reply(event=ext_result)
-
- tool_spans = self._spans_by_name("execute_tool")
- self.assertEqual(
- len(tool_spans),
- 1,
- "Expected exactly one synthetic execute_tool span",
- )
- span_attrs = dict(tool_spans[0].attributes or {})
- self.assertEqual(
- span_attrs.get("agentscope.agent.is_external_execution"),
- True,
- "Synthetic execute_tool span should have "
- "is_external_execution=True",
- )
- self.assertEqual(span_attrs.get("gen_ai.tool.name"), "get_weather")
-
- async def test_external_execution_second_call_has_incoming_event_type(
- self,
- ) -> None:
- """Second call span must have
- incoming_event_type=external_execution_result."""
- ext_agent = Agent(
- name="ext-agent3",
- system_prompt="You are a test assistant.",
- model=self.model,
- toolkit=Toolkit(tools=[ExternalWeatherTool()]),
- middlewares=[TracingMiddleware()],
- )
-
- # First call
- self.model.set_responses(
- [_make_tool_call_response("e3", "Chengdu")],
- )
- self.exporter.clear()
-
- require_ext_event = None
- async for evt in ext_agent.reply_stream(
- UserMsg(name="user", content="Weather in Chengdu?"),
- ):
- if isinstance(evt, RequireExternalExecutionEvent):
- require_ext_event = evt
-
- # Second call
- self.model.set_responses([_make_text_response("Chengdu: cloudy.")])
- self.exporter.clear()
-
- ext_result = ExternalExecutionResultEvent(
- reply_id=require_ext_event.reply_id,
- execution_results=[
- ToolResultBlock(
- id=require_ext_event.tool_calls[0].id,
- name="get_weather",
- output="Chengdu: cloudy, 15°C.",
- state=ToolResultState.SUCCESS,
- ),
- ],
- )
- await ext_agent.reply(event=ext_result)
-
- agent_spans = self._spans_by_name("invoke_agent")
- self.assertEqual(
- len(agent_spans),
- 1,
- "Expected exactly one invoke_agent span",
- )
- span_attrs = dict(agent_spans[0].attributes or {})
- self.assertEqual(
- span_attrs.get("agentscope.agent.incoming_event_type"),
- "external_execution_result",
- )
diff --git a/tests/utils.py b/tests/utils.py
index dc8356cee..c0d5c585e 100644
--- a/tests/utils.py
+++ b/tests/utils.py
@@ -4,6 +4,7 @@ from typing import Any, AsyncGenerator, Type
from pydantic import BaseModel
+from agentscope.credential import CredentialBase
from agentscope.message import Msg
from agentscope.model import ChatModelBase, ChatResponse, StructuredResponse
@@ -20,9 +21,21 @@ class AnyString:
return "<AnyString>"
+class MockCredential(CredentialBase):
+ """The mock credential class."""
+
+ @classmethod
+ def get_chat_model_class(cls) -> Type["ChatModelBase"]:
+ """Return the mock model class."""
+ return MockModel
+
+
class MockModel(ChatModelBase):
"""A mock model for testing."""
+ class Parameters(BaseModel):
+ """The parameters."""
+
def __init__(
self,
model: str = "mock-model",
@@ -32,7 +45,9 @@ class MockModel(ChatModelBase):
) -> None:
"""Initialize the mock model."""
super().__init__(
+ credential=MockCredential(),
model=model,
+ parameters=MockModel.Parameters(),
context_size=context_size,
)
self.mock_chat_responses = mock_chat_responses or []