ڎja 8 d Z ddlZddlZddlmZ ddlmZmZmZm Z ddl
Z
ddl m Z ddl
mZmZmZ ddlmZmZ dd lmZ dd
lmZmZ d d lmZmZ dd
l m Z d dl m Z m Z d dl!m"Z"m#Z#m$Z$ d dl
m%Z% d dl&m'Z'm(Z(m)Z) ddl*m+Z+ d dl,m-Z- d dl.m/Z/ dZ0dZ1 G d d Z2dS )z/The toolkit class for tool calls in AgentScope. N) OrderedDict)AsyncGeneratorType GeneratorSequence)Template) BaseModelField create_model )
ResetTools SkillViewer)ToolBase) ToolResponse ToolChunk )SkillLoaderBaseSkill)RegisteredTool)_describe_exception_json_loads_with_repair)DeveloperOrientedExceptionToolNotFoundErrorToolGroupInactiveError) MCPClient)
ToolCallBlock TextBlockToolResultState) ToolGroup)logger)
AgentStateaC {% if groups | length == 0 %}All tool groups are currently deactivated.{% else %}The currently activated tool group(s): {{ groups | map(attribute='name') | join(', ') }}.{% if groups | selectattr('instructions', 'ne', None) | list | length > 0 %}
The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.
{% for group in groups %}{% if group.instructions %}{{ group.instructions }}{% endif %}{% endfor %}
{% endif %}{% endif %}a:
Skills are a collection of instructions, scripts, and resources to extend your capabilities.
**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `{{ skill_viewer }}` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.
# Available Skills:{% for skill in skills %}
{{ skill.name }}
{{ skill.description }}
{{ skill.dir }}
{% endfor %}
c * e Zd ZdZddddeefdee dz dee e
z e z dz dee dz dee
dz de de d dfd
Z d d ee dz d ee fd Zd
eded eeez df fdZ d d ee dz d ee e
f fdZ d dee dz d e dz fdZd ee dz d ee ef fdZde dee d efdZde d edz fdZ d e e fdZ d dZ d!deee z d e d dfd Z!de ee z d dfd Z"dS )"Toolkita Toolkit is the core module to register, manage and delete tool
functions, MCP clients, Agent skills in AgentScope.
About tool functions:
- Register and parse JSON schemas from their docstrings automatically.
- Group-wise tools management, and agentic tools activation/deactivation.
- Extend the tool function JSON schema dynamically with Pydantic BaseModel.
- Tool function execution with unified streaming interface.
About MCP clients:
- Register tool functions from MCP clients directly.
- Client-level tool functions removal.
About Agent skills:
- Register agent skills from the given directory.
- Provide prompt for the registered skills to the agent.
Ntoolsskills_or_loadersmcps tool_groupsmeta_tool_response_templateskill_instruction_templatereturnc t |(t d |D rt d t d|pg |pg |pg g|pg z | _ t t d | j D t | j k rt d | j D ]2}|j D ](}|j r |j st d|j d )3|| _
|| _ t t | j |
| _ t t | j | _ dS )
a\ Initialize the toolkit.
Args:
tools (`list[ToolBase] | None`, optional):
The tool objects that belong to the "basic" tool group.
skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, optional):
The agent skill directories to be registered in the "basic"
tool group.
mcps (`list[MCPClient] | None`, optional):
The mcp clients to be registered in the "basic" tool group.
tool_groups (`list[ToolGroup] | None`, optional):
The tool groups to be registered.
meta_tool_response_template (`str`, optional):
The template for meta tool responses.
skill_instruction_template (`str`):
A Jinja2 template for generating the agent skill instruction.
Nc 3 , K | ]}|j d k V dS )basicNname.0_s FC:\Projects\DSCons\.venv\Lib\site-packages\agentscope\tool\_toolkit.py z#Toolkit.__init__..u s: +
+
"#AFg +
+
+
+
+
+
zThe 'basic' tool group is reserved for the default tool group. Don't include 'basic' in the tool_groups argument when you also provide tools, skills or mcps in the constructor.r- )r/ r$ r% r& c 3 $ K | ] }|j V d S Nr. r0 s r3 r4 z#Toolkit.__init__.. s$ 44a16444444r5 z3Tool groups must not contain duplicate tool groups.zThe MCP client 'z!' is stateful, but not connected.)groupsresponse_template)tool)get_skills_method)any
ValueErrorr r' lensetr& is_stateful is_connectedr/ r( r) r r
builtin_meta_toolr _get_available_skillsbuiltin_skill_viewer) selfr$ r% r& r' r( r) groupclients r3 __init__zToolkit.__init__X s : "s +
+
'2+
+
+
(
(
"
kr"3"9rZR
B s444#344444 5 5 :
:
E
% E *
% f.A $*6; * * *
,G(*D'!/ '"= "
"
"
%3 "&"< %
%
%
!!!r5 r8 c K g }| | d{V }| D ])}| | *|S )a Get the JSON schemas of the currently available tool functions
based on the given activated tool groups.
.. note:: The preset keyword arguments is removed from the JSON
schema, and the extended model is applied if it is set.
Args:
groups (`list[str] | None`, optional):
A list of group names to filter the tool function. The "basic"
group will always be included regardless of the filter. If not
provided, only the "basic" group will be included.
Example:
.. code-block:: JSON
:caption: Example of tool function JSON schemas
[
{
"type": "function",
"function": {
"name": "google_search",
"description": "Search on Google.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query."
}
},
"required": ["query"]
}
}
},
...
]
Returns:
`list[dict]`:
A list of function JSON schemas.
N)_get_available_toolsvaluesappendget_tool_schema)rE r8 function_schemas
tools_dictr: s r3 get_tool_schemaszToolkit.get_tool_schemas sz Z 44V<<<<<<<<
%%'' < z%Toolkit.call_tool.. s 9991999r5 )r8 "ToolGroupInactiveError: The tool ' ' in group 'M' is currently inactive. You should first activate the group by calling the '' tool.)text)contentrR #ToolNotFoundError: The tool named '' doesn't exist. _agent_statezoThe tool function must return a ToolChunk object, or an AsyncGenerator/Generator of ToolChunk objects, but got .r\ z&Error occurred when calling MCP tool: )typer\ zRThe tool call has been interrupted by the user.rV )%r rT rJ tool_contextactivated_groupsr/ r' rF r r rB r: r ERROR append_chunkr inputis_state_injectedis_mcpis_external_toolinspectiscoroutinefunction__call__
isinstancer r r rb mcpshared
exceptionsMcpError ExceptionstrasyncioCancelledError INTERRUPTED) rE rQ rR
tool_responseavailable_tools all_tools
group_namechunk tool_funckwargsreses r3 call_toolzToolkit.call_tool s , % 555
!% 9 9 /!
!
> 0 0 " 7 799(8999 8 I ~** &y~ 6 <
!!!N$-N!N !N@J!N !N %)$:$?$D !N !N !N
*/
#00777777 = %N = = = &+ E KKKK ,,U33 3 3 3 3 F $IN38 [ ,Y_==F +
/!(
/ "2
/
*/~&*9+=>>
* %I / / / /////// i))&))#y))
**3//// C 00
#& 6 6 6 6 6 6 6% KKKK!..u5555 $'3
C++
6 6E KKKK!..u55556
1, #Cyy, , , z$- . . . # Ia I I &+ E KKKK & &u - - - - - - - - . . .! 788
"T! # VV &+ E KKKK & &u - - - - - - - -% . . . # - &1 E KKKK & &u - - - - - .$ - s_ B%I8 =H A3I8 6N> 8N4AK N>
N4+A*MN> AN41N> 3N44N> >Oc K dg|pg z }t }| j D ]\}|j |vr | d{V D ]5}|j |v r t j d|j |j |||j < 6]|S )a A unified method to collect all skills from the registered skill
loaders.
Args:
groups (`list[str] | None`, optional):
A list of group names to filter the skill loaders. The "basic"
group will always be included regardless of the filter. If not
provided, only the "basic" group will be included.
Returns:
`dict[str, Skill]`:
A dictionary of skill name and their corresponding Skill
objects.
r- Nz>Duplicate skill name '%s' found in group '%s', overwriting it.)r r' r/ list_skillsr warning)rE r8
groups_filterskillsrF skills r3 rC z Toolkit._get_available_skills s $ ! V\r2
% + +Ez .. $ 0 0 2 2222222
+
+:''N*
&+uz""
+
r5 rd c $ K |d | j D }| | d{V }t | dk rdS t | j }| | | j j j S )a Get the prompt for all registered agent skills, which can be
attached to the system prompt for the agent.
The prompt is consisted of an overall instruction and the detailed
descriptions of each skill, including its name, description, and
directory.
.. note:: If no skill is registered, None will be returned.
Args:
activated_groups (`list[str] | None`, optional):
The currently activated tool groups. If omitted, all groups
will be included for backwards compatibility.
Returns:
`str | None`:
The combined prompt for registered agent skills, or None
if no skill is registered.
Nc g | ] }|j
S rV r. r0 s r3 rW z2Toolkit.get_skill_instructions.. s A A A1 A A Ar5 r )r skill_viewer)
r' rC r> r r) renderrK rD r: r/ )rE rd r templates r3 get_skill_instructionsz Toolkit.get_skill_instructions s . # A A0@ A A A 11
v;;! 4 D ;<<==?? 27<
r5 c ^ K i }| | d{V }t | r| j || j j j < t | j dk r| j d j dk st | j dk r| j || j j j < dg|pg z }| j D ]}|j |vr g }|j D ]}| | |j D ]u} |
| d{V 1# t $ r8} t j d|j |j t | Y d} ~ nd} ~ ww xY w|D ]I}|j |v r t j d|j |j t! ||j ||j < J|S )a Return the currently available tools based on the given
activated tool groups. Tools in the ``"basic"`` group are always
included. When at least one tool group is registered, the built-in
meta tool is also included.
Args:
groups (`list[str]`):
The list of currently activated tool group names.
Returns:
`dict[str, RegisteredTool]`:
The dictionary of available tool name and their corresponding
RegisteredTool objects.
Nr r r- zASkipping MCP '%s' in group '%s': listing its tools failed with %s=Duplicate tool name '%s' found in group '%s', overwriting it.)r: rF )rC r> rD r: r/ r' rB r$ rL r& extend
list_toolsrs r r r r )
rE r8 ry r r rF cache_toolsr: rG r s
r3 rJ z Toolkit._get_available_tools sN $ 11&99999999 v;; * )
).3
! !Q & & #(G334#$$q(( &
&+0
! V\r2
% ' ' Ez .. K
)
)""4(((( *
&&V->->-@-@'@'@'@'@'@'@AAAA
N/
+A.. $
9//N*
.< *. . . **
s --D
E %.EE tool_namec K | | d{V }||vrt d| d || j }|dk r,||vr(t d| d| d| j j j d || j S ) a Check if the tool is available now. If not, raise the
agent-oriented exception.
Args:
tool_name (`str`):
The name of the tool to be checked.
activated_groups (`list[str]`):
The currently activated tool groups.
Returns:
`ToolBase`:
If the tool is available, return the corresponding ToolBase
object. Otherwise, raise the agent-oriented exception with the
error message.
Nr^ r_ r- rX rY rZ r[ )rJ r rF r rB r: r/ )rE r rd r$ r{ s r3 check_tool_availablez Toolkit.check_tool_available( s ( //0@AAAAAAAA E ! !#i
9%+
Z7G%G%G(>Y > > > > */4> > >
Y $$r5 r/ c K | d | j D d{V }| |d }|dS |j S )zGet tool instance by its name.
Args:
name (`str`):
The name of the tool to be checked.
Returns:
`ToolBase | None`:
The tool instance, or `None` if no tool is found.
c g | ] }|j
S rV r. r0 s r3 rW z$Toolkit.get_tool..Z s . . .QV . . .r5 N)rJ r' getr: )rE r/ r$ registered_tools r3 get_toolzToolkit.get_toolN sx // . .T - . . .
))D$// "4 ##r5 c i }| j D ]3}|j dk rt t d|j f||j < 4t di |S )z:Get the meta tool schema based on the current tool groups.r- F)default description
_DynamicModel)r )r' r/ boolr
r r )rE fieldsrF s r3 _get_meta_tool_schemaz Toolkit._get_meta_tool_schemaa sn % EzW$$ ! % 1 "F5: 66v666r5 c 8 | j dS )z,Clear the registered tools, skills and MCPs.N)r' clear)rE s r3 r z
Toolkit.clearp s r5 r- r: r{ c K t |t r|n|g}| j D ]}|j |k rd |j D }|D ]|j |v r=t j dj |j fd|j D gz |_ H|j | j } dS t d| dd | j D d ) zAdd tool to the toolkit on-the-fly.
Args:
tool (`ToolBase | list[ToolBase]`):
The tool to be added.
group_name (`str`):
The group name of the tool to be added.
c h | ] }|j
S rV r. r0 s r3 z#Toolkit.add_tool.. s !>!>!>Q!&!>!>!>r5 r c 4 g | ]}|j j k |S rV r. )r1 tnew_tools r3 rW z$Toolkit.add_tool.. s. ' ' '"#af
6M6MA6M6M6Mr5 NzCannot find group 'z' in toolkit, only c g | ] }|j
S rV r. r0 s r3 rW z$Toolkit.add_tool.. s 1111111r5 z are available.)
rn listr' r/ r$ r r rL addr= )rE r: r{ new_toolsrF existing_toolsr s @r3 add_toolzToolkit.add_toolt sY 'tT 2 2>DD % EzZ''!>!>%+!>!>!> ) : :H }66 . $M !J ' ' ' '',{' ' ' %J'' **8444&**8=9999% ((
C*
C
C11 0111
C
C
C
r5 c K t t rg| j D ]}fd|j D |_ dS )zRemove tool from the toolkit on-the-fly.
Args:
tool_name (`str | list[str]`):
The name of the tool to be removed.
c & g | ]
}|j v |S rV r. )r1 r: r s r3 rW z'Toolkit.remove_tool.. s, 0J0J0J0J0Jr5 N)rn rt r' r$ )rE r rF s ` r3 remove_toolzToolkit.remove_tool sl i % % $" I% E !& EKK r5 r7 )r* N)r- )#__name__
__module__ __qualname____doc__#DEFAULT_META_TOOL_RESPONSE_TEMPLATEDEFAULT_SKILL_INSTRUCTIONr r r rt r r r r rH dictrP r r! r r r r rC r r rJ r r r r r r r r rV r5 r3 r# r# B s . (,'+.2+N*CQ
Q
H~$Q
$C%K/$AB
Q
9o$ Q
)_t+
Q
&)Q
%(Q
Q
Q
Q
Q
j $(4 4 S D 4
d4 4 4 4 lc c c
L0$6 7 c c c c N $(# #S D #
c5j # # # #N .2(
(
s)d*(
t(
(
(
(
TQ S D Q
c>! "Q Q Q Q f$%$% s)$%
$% $% $% $%L$3 $8d? $ $ $ $&
7tI
7
7
7
7 ! ! ! ! "(
(
h '(
(
(
(
(
(
T
3c?
t
r5 r# )3r ru rk collectionsr typingr r r r ro jinja2r pydanticr r
r _builtinr
r _baser _responser r r r r _typesr _utils._commonr r exceptionr r r r messager r r _tool_groupr _loggingr rR r! r r r# rV r5 r3 r s< 5 5 # # # # # #
. - - - - - - - . . . . . . . . * * * * * * * * " " " " " " I I I I I I I I
# " " " " " '. # i i i i i i i i i i r5