This page provides technical definitions and implementation details for the core concepts, abbreviations, and domain-specific terms used within the AgentScope codebase.
The fundamental unit of execution in AgentScope. An Agent encapsulates a Large Language Model (LLM), a Toolkit, and a set of Middleware to perform reasoning and actions.
Agent class [src/agentscope/agent/_agent.py:112-129].reply or reply_stream methods [src/agentscope/agent/_agent.py:228-260].The Reasoning-Acting cycle where the agent iteratively generates reasoning (thoughts) and actions (tool calls) until a termination condition is met or the maximum iterations are reached.
ReActConfig [src/agentscope/agent/_config.py:186-218]._reply_impl [src/agentscope/agent/_agent.py:382-446] which orchestrates _reasoning and _acting phases. It handles structured output via _GenerateStructuredOutput [src/agentscope/agent/_agent.py:103-103].A system of composable hooks that wrap agent operations (onion pattern). Middlewares can intercept and modify data at various stages: model calls, tool execution, system prompt generation, and context compression.
MiddlewareBase [src/agentscope/middleware/_base.py:17-48].on_reply, on_model_call, and on_acting are filtered by implemented hooks and triggered during the agent's lifecycle [src/agentscope/agent/_agent.py:191-212].A registry and execution manager for tools, MCP clients, and skills. It handles the generation of JSON schemas for LLM consumption and the dispatching of tool calls.
Toolkit class [src/agentscope/tool/_toolkit.py:66-86].get_tool_schemas [src/agentscope/tool/_toolkit.py:171-186] translates Python functions/tools into LLM-readable definitions, including support for MCP tools [src/agentscope/tool/_toolkit.py:77-80].An isolated environment for agent execution, file storage, and tool provisioning. Workspaces provide resources (skills), tools (MCPs), and offloading persistence.
WorkspaceBase [src/agentscope/workspace/_base.py:65-90].LocalWorkspace [src/agentscope/workspace/_local_workspace.py:65-86] manages local directories for sessions, data, and skills..mcp, data/, skills/, and sessions/ [src/agentscope/workspace/_base.py:38-42].| Term | Definition | Code Reference |
|---|---|---|
| Msg | The unified message object used for communication between agents and models. | [src/agentscope/message/_message.py:84-118] |
| ContentBlock | A structured unit within a Msg, such as TextBlock, ThinkingBlock, ToolCallBlock, or ToolResultBlock. | [src/agentscope/message/_block.py:22-45] |
| HITL | Human-In-The-Loop. A mechanism for requiring human confirmation before sensitive actions (e.g., shell commands). | [src/agentscope/agent/_agent.py:53-56] |
| MCP | Model Context Protocol. A standard for agents to interact with external tools and data sources via MCPClient. | [src/agentscope/tool/_toolkit.py:32-33] |
| Offloader | A component responsible for moving large tool results or old context to persistent storage to save context window space. | [src/agentscope/agent/_agent.py:104-104] |
| RAG | Retrieval-Augmented Generation. A system for retrieving relevant documents via KnowledgeBase to augment the agent's prompt. | [src/agentscope/rag/init.py:9-17] |
| SSE | Server-Sent Events. The protocol used to stream agent events from the backend service to the Web UI. | [src/agentscope/event/_event.py:1-20] |
| ToolChunk | A granular unit of tool execution output, used for streaming tool results. | [src/agentscope/tool/_response.py:23-23] |
| Console | A terminal-based interface for testing and debugging agents without a full Web UI. | [src/agentscope/console/_console.py:1-20] |
This diagram maps the conceptual "Agent" to the specific classes and data structures that implement it.
Title: SDK Entity Mapping
Sources: [src/agentscope/agent/_agent.py:112-129], [src/agentscope/tool/_toolkit.py:66-86], [src/agentscope/state/_state.py:25-45].
This diagram bridges the concept of "Calling a Tool" to the internal execution and permission checking pipeline.
Title: Tool Execution Pipeline
Sources: [src/agentscope/agent/_agent.py:628-660], [src/agentscope/permission/_engine.py:20-45], [src/agentscope/tool/_toolkit.py:230-260], [src/agentscope/tool/_base.py:22-40].
A system that evaluates PermissionRule objects against a PermissionContext to decide if an action is allowed.
ALLOW, DENY, ASK (triggers HITL/UserConfirmResultEvent).PermissionEngine [src/agentscope/permission/_engine.py:15-35].Adapters that translate AgentScope's internal Msg objects into the specific payload formats required by different LLM providers (OpenAI, Gemini, Anthropic, etc.).
FormatterBase [src/agentscope/formatter/_base.py:10-25].src/agentscope/formatter/ directory.An abstraction over vector databases and document parsers used to provide agents with external information.
KnowledgeBase, VectorStoreBase, and ParserBase.QdrantStore, MilvusLiteStore, MongoDBStore, and ElasticsearchStore [src/agentscope/rag/init.py:18-27].Instructions, scripts, and resources that extend agent capabilities. Unlike tools, skills are not called directly; agents use the SkillViewer tool to read instructions and then execute them using existing tools [src/agentscope/tool/_toolkit.py:51-63].
SkillLoaderBase and Skill objects [src/agentscope/skill/init.py].The process of persisting context or tool results to external storage (e.g., local disk or cloud) to maintain a lean context window for the LLM.
Offloader and implemented in workspaces like LocalWorkspace via offload_context [src/agentscope/workspace/_local_workspace.py:207-220].Sources: