AgentScope

Implements a ReActAgent base class that orchestrates reasoning-action-observation loops by leveraging LLM native tool-calling capabilities rather than rigid prompt engineering. The framework uses a message protocol with structured content blocks to pass tool schemas directly to models (OpenAI, Anthropic, Gemini, etc.), enabling models to decide when and how to invoke tools. Tool execution is mediated through a Toolkit registry with middleware support for pre/post-processing, allowing dynamic tool composition without hardcoded function chains.

Provides a MsgHub message broker that enables inter-agent communication through a publish-subscribe architecture with support for both synchronous request-reply and asynchronous broadcast patterns. Agents register as subscribers to message topics and can broadcast messages containing structured content blocks. The system supports distributed deployment where agents run on separate processes/machines and communicate through Redis or in-memory message queues, with automatic message routing based on subscriber filters.

Enables agents to process and generate multimodal content including text, images, audio, and realtime voice streams. Agents can receive voice input via realtime APIs (OpenAI Realtime, etc.), process it with speech-to-text, reason over multimodal context, and respond with text-to-speech output. Message protocol supports content blocks for different modalities (text, image, audio), and agents can compose multimodal responses. Realtime voice integration enables low-latency voice conversations without explicit turn-taking.

Enables agents to pause execution and request human input or approval at critical decision points. Agents can define interruption handlers that pause reasoning, present options to humans, and resume based on human feedback. Supports approval workflows where agents propose actions and wait for human confirmation before execution. Integrates with UserAgent for human interaction, and supports both synchronous (blocking) and asynchronous (callback-based) human input.

Provides lifecycle hooks (before_step, after_step, on_error, on_complete) that enable custom logic at each agent execution phase. Hooks are called automatically during agent reasoning, allowing middleware-like behavior without modifying core agent code. Supports extending AgentBase with custom agent types, custom message formatters for new LLM providers, and custom memory implementations. Extension points are designed to be composable, enabling multiple extensions to coexist without conflicts.

Provides a tuner framework for finetuning agent behaviors through reinforcement learning or supervised finetuning. Agents can be trained on task datasets to improve performance on specific domains. Supports both offline finetuning (on collected trajectories) and online finetuning (with environment interaction). Integrates with evaluation framework to measure finetuning progress and detect overfitting. Supports multiple finetuning strategies (behavior cloning, reward-based RL, etc.) with pluggable reward models.

Provides a planning system with PlanNotebook that enables agents to decompose complex tasks into subtasks and track progress. Agents can create hierarchical plans, mark subtasks as complete, and adjust plans based on execution results. PlanNotebook maintains structured task state (goals, subtasks, dependencies, status) and integrates with agent reasoning to enable plan-aware decision making. Supports dynamic replanning when execution deviates from plan.

Abstracts multiple LLM providers (OpenAI, Anthropic, Google Gemini, Alibaba DashScope, Ollama, etc.) behind a ChatModelBase interface that handles provider-specific API differences. Supports streaming responses with token-by-token callbacks, structured output extraction via JSON schema validation, and tool-calling schema generation. Message formatters convert between AgentScope's internal message protocol and provider-specific formats (e.g., OpenAI's chat completion format vs Anthropic's native tool-use blocks), enabling seamless provider switching.

Manages agent conversation history and context through a working memory system that stores messages in a session-scoped memory store. Implements memory compression strategies (e.g., summarization, token-based pruning) to keep context windows manageable as conversations grow. Supports Redis-backed memory for multi-tenant deployments where each session has isolated memory, enabling horizontal scaling. Memory can be queried by content, timestamp, or metadata, and integrates with RAG systems for semantic search over conversation history.

Integrates external long-term memory systems (Mem0 for persistent user profiles, ReME for relational memory extraction) that augment agent working memory with persistent knowledge across sessions. Agents can store and retrieve facts, preferences, and relationships that persist beyond individual conversations. The system uses embedding-based retrieval to surface relevant long-term memories during agent reasoning, enabling personalization and context continuity across sessions without retraining.

Provides a Toolkit abstraction that registers tools as callable functions with JSON schema definitions. Tools can be implemented as native Python functions or wrapped as Model Context Protocol (MCP) servers for language-agnostic tool integration. Middleware system enables pre-processing (e.g., input validation, rate limiting) and post-processing (e.g., output formatting, error handling) of tool invocations. Tool groups enable hierarchical organization and selective exposure of tools to agents based on capabilities or permissions.

Provides a RAG (Retrieval-Augmented Generation) system that indexes documents into vector stores (Faiss, Milvus, Pinecone, etc.) and retrieves semantically similar chunks during agent reasoning. Documents are chunked, embedded using configurable embedding models, and stored with metadata for filtering. Agents can query the RAG system to augment their context with relevant external knowledge before generating responses, enabling knowledge-grounded reasoning without fine-tuning.

Enables deployment of agents across multiple processes, machines, or Kubernetes clusters with built-in OpenTelemetry instrumentation for distributed tracing. Agents emit traces for each step (LLM calls, tool invocations, memory operations) with automatic context propagation across process boundaries. Traces can be exported to observability backends (Jaeger, Datadog, etc.) for visualization and debugging. Includes decorators for custom span creation and automatic latency tracking for performance monitoring.

Provides an evaluation framework for assessing agent performance on tasks using multiple evaluation strategies (exact match, semantic similarity, LLM-as-judge, custom metrics). Integrates with OpenJudge for standardized evaluation benchmarks. Evaluators can be composed into evaluation pipelines that run agents on test datasets and compute aggregate metrics. Results are tracked and compared across agent versions for regression detection.

Provides serialization and checkpointing mechanisms that save agent state (memory, reasoning traces, tool results) to persistent storage at configurable intervals. Agents can be resumed from checkpoints after failures, enabling fault-tolerant long-running tasks. Checkpoints include full agent state (working memory, long-term memory references, execution context) and can be versioned for rollback. Supports multiple checkpoint backends (local filesystem, cloud storage, databases).