agentscope-core

ReAct (Reasoning and Acting) Agent implementation.

AgentScope version and User-Agent information.

Complete agent interface combining all capabilities.

Abstract base class for all agents in the AgentScope framework.

A single-use, lazy execution handle.

Interface for agents that can be called to process messages.

An event emitted during streaming agent execution.

@deprecated since 2.0.0.

Types of events emitted during agent execution.

Interface for agents that can observe messages without generating replies.

Runtime-only control for one execution; never stored in conversation state.

Per-call metadata for an agent run: session-scoped fields plus a thread-safe attribute bag and an optional `ToolExecutionContext` (tool-POJO / DI layer).

Configuration options for the `Agent#stream` API.

Interface for agents that support streaming events during execution.

Internal hook implementation for streaming events.

A lightweight channel that allows synchronously-invoked subagents to push their `Event`s into the parent agent's `Flux<Event>` stream.

Content accumulator interface for accumulating streaming content blocks.

Reasoning context that manages all state and content accumulation for a single reasoning round.

Text content accumulator for accumulating streaming text chunks.

Thinking content accumulator for accumulating streaming thinking chunks.

Tool calls accumulator for accumulating streaming tool call chunks.

Observer notified when a fallback model (`ModelConfig#fallbackModel()`) takes over from a failed primary model.

Model invocation configuration.

Reasoning-loop configuration.

Stream-based user input implementation that reads from any InputStream and writes to any OutputStream.

UserAgent class for handling user interaction within the agent framework.

Strategy interface for handling user input from different sources.

Data class that holds user input information with dual representation.

Credential metadata for a model provider.

Credential for the DeepSeek API.

Credential for the Kimi (Moonshot AI) API.

Description of one candidate chat model under a provider.

Credential for the xAI API.

Emitted when an agent finishes processing an invocation.

Base class for all fine-grained agent events.

Public interface for emitting `AgentEvent`s into the parent agent's `streamEvents()` event stream from within tool execution code.

Fine-grained event types emitted during agent execution.

Emitted when an agent successfully finishes processing an invocation, carrying the final result message.

Emitted when an agent begins processing an invocation.

Emitted during the acting phase when all tool calls from the most recent reasoning step were denied (by user HITL confirmation or by permission rules).

Represents the result of a single user confirmation decision for a tool call.

Generic extensible event for signals that don't fit a specific `AgentEvent` subtype.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

Emitted when the agent's ReAct loop exceeds the configured maximum iterations.

Emitted after externally-executed tool results are provided back to the agent.

One-shot hint block event.

Emitted when the agent finishes a model (LLM) call.

Emitted when the agent starts a model (LLM) call.

Requests the agent to pause execution after the current phase completes.

Emitted when tool calls require external (out-of-process) execution.

Emitted when the agent requires user confirmation before executing tool calls (HITL).

Emitted when a spawned subagent is exposed as a user-addressable entry point via `agent_spawn(expose_to_user=true)`.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

Emitted as tool call input arguments are streamed incrementally.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

A class in io.agentscope.core.event that carries structured messages and events between agents, models and UIs.

Emitted after the user has responded to a `RequireUserConfirmEvent`.

A class in io.agentscope.core.exception that provides shared types and foundational utilities.

Abstract base formatter providing common functionality for all formatter implementations.

Formatter interface for converting between AgentScope and provider-specific formats.

Exception thrown when formatter encounters an error during message formatting or response parsing.

JSON Schema definition for structured outputs.

Utility class for handling media files in multimodal content.

Response format configuration for model APIs.

Event fired during tool execution streaming.

Base class for tool execution (acting) related events.

Event fired when an error occurs during agent execution.

Hook interface for monitoring and intercepting agent execution.

Base class for all hook events.

Enum representing all hook event types.

Encapsulates all legacy `HookEvent` construction and dispatch logic.

Event fired after tool execution completes.

Event fired after agent completes processing.

Event fired after LLM reasoning completes.

Event fired after summary generation completes.

Event fired before tool execution.

Event fired before agent starts processing.

Event fired before LLM reasoning.

Event fired before summary generation when max iterations is reached.

Event fired during reasoning streaming.

Base class for reasoning-related events.

Event fired during summary streaming.

Base class for summary-related events.

A built-in, out-of-the-box JSONL trace exporter based on the Hook event system.

Context information about an interruption.

A runtime-only cooperative interrupt signal owned by one execution, never by a session.

Enum representing the source of an interruption.

Read-only `Memory` adapter that proxies `#getMessages()` to a live `AgentState#getContext()` resolved at call time.

In-memory implementation of Memory with state persistence support.

Abstract base class for long-term memory implementations.

Defines how long-term memory is integrated with agent behavior.

Tool adapter that exposes long-term memory operations as agent-callable tools.

Interface for memory components that store and manage conversation history.

A `Memory` implementation that delegates all reads and writes to `AgentState#contextMutable()`.

Static Long-Term Memory Hook for automatic memory management.

A `Msg` with `MsgRole#ASSISTANT` pinned at construction time.

Represents audio content in a message.

Represents Base64-encoded media content with media type and data.

Base sealed class for all content blocks in messages.

Unified data block for arbitrary binary media (image / audio / video / file).

Represents the reason why a message was generated by an agent.

A content block that provides hints to the LLM during reasoning.

Represents image content in a message with URL or Base64 source.

Constants for well-known message metadata keys.

Represents a message in the AgentScope framework.

Defines the role of a message participant in agent conversations.

Base class for media sources (URL or Base64).

A `Msg` with `MsgRole#SYSTEM` pinned at construction time.

Represents plain text content in a message.

Represents reasoning or thinking content in a message.

A enum in io.agentscope.core.message that defines enum values used when components carries structured messages and events between agents, models and UIs.

Represents the result of a tool execution.

A `Msg` with `MsgRole#TOOL` pinned at construction time.

A enum in io.agentscope.core.message that defines enum values used when components carries structured messages and events between agents, models and UIs.

Represents a tool use request within a message.

Represents URL-based media content.

A `Msg` with `MsgRole#USER` pinned at construction time.

Represents video content in a message.

Input context for `MiddlewareBase#onActing`.

Input context for `MiddlewareBase#onAgent`.

Exposes only the text from the final reasoning round of a ReAct stream.

Middleware provides interception mechanisms at 5 key execution points in the Agent lifecycle.

Builds an onion-style middleware chain for a given interception point.

Input context for `MiddlewareBase#onModelCall`.

Input context for `MiddlewareBase#onReasoning`.

Keeps the agent's todo list in front of the model so long-running tasks don't drift.

Controls whether `ModelRegistry` caches models created with a `ModelCreationContext`.

Abstract base class for all models in the AgentScope framework.

Represents a chat completion response from a language model.

Represents token usage information for chat completion responses.

Unified execution configuration for timeout and retry behavior.

Immutable generation options for LLM models.

An interface in io.agentscope.core.model that defines the contract for components that talks to model services and returns generated or embedded output.

Known context window sizes for popular models.

Provider-neutral model creation context used by `ModelRegistry` and model provider SPI implementations.

Exception thrown when model operations fail.

Exception contract for model providers that can expose an HTTP status code.

Shared helpers for model providers.

Registry for resolving `Model` instances from string identifiers (named instances or `provider:model` patterns).

Utility class for common Model operations.

Configuration for how to ensure the model calls generate_response tool in structured output mode.

Represents the tool choice behavior for LLM model calls.

Immutable tool schema definition.

Service Provider Interface for model adapters discovered from extension modules.

HTTP request encapsulation for the transport layer.

HTTP response encapsulation for the transport layer.

HTTP transport layer interface for making HTTP requests.

Configuration for HTTP transport layer.

Exception thrown when HTTP transport operations fail.

Factory for managing HttpTransport instances.

HTTP version.

Pure JDK implementation of the HttpTransport interface.

OkHttp implementation of the HttpTransport interface.

Configuration for HTTP and SOCKS proxy.

Enumeration of supported proxy types.

Constants for HTTP transport layer.

WebSocket client interface.

WebSocket connection close information.

WebSocket connection implementation based on JDK WebSocket.

WebSocket client implementation based on JDK 11+ HttpClient.

WebSocket connection implementation based on OkHttp WebSocket.

WebSocket client implementation based on OkHttp.

WebSocket connection interface.

WebSocket connection request configuration.

Configuration for WebSocket clients.

WebSocket transport layer exception.

A directory included in a permission context's working scope.

Outcome of a permission rule or tool self-check.

Permission evaluation context: mode + working directories + three rule tables.

Decision returned by a permission rule match or a tool self-check.

Evaluates tool execution requests against configured permission rules.

Permission mode controlling how the engine evaluates tool execution requests.

A single permission rule pinned to a tool name.

Generic RAG Hook for automatic knowledge retrieval before reasoning.

Interface for knowledge bases.

Knowledge retrieval tools for Agentic RAG mode.

RAG (Retrieval-Augmented Generation) mode enumeration.

Document class representing a document chunk in the RAG system.

Document metadata containing content and chunking information.

Configuration for document retrieval operations.

JVM hook for SIGTERM graceful shutdown entry.

Exception thrown when request is rejected or interrupted during shutdown.

Configuration for graceful shutdown behavior of the agent system.

Global manager for graceful shutdown lifecycle and active request tracking.

System middleware that integrates graceful shutdown into the agent lifecycle.

Policy for handling incomplete reasoning content on shutdown interruption.

AgentStateStore binding used for shutdown checkpoint persistence.

Global framework shutdown state.

Strategy for persisting `AgentState` during graceful shutdown.

Represents an agent skill that can be loaded and used by agents.

Generates skill system prompts for agents to understand available skills.

Dynamically composes skills from an ordered list of repositories (`AgentSkillRepository`) on every `call()` via `#onSystemPrompt(Agent, RuntimeContext, String)`, replacing the static skill prompt with a per-call view that supports per-user skill isolation and one-click marketplace integration.

Manages a collection of `AgentSkill` instances and exposes them as tools.

Filter for deciding whether a skill resource should be uploaded.

Immutable filter that decides which skills are allowed in a prompt.

Injects the skill catalog prompt into the unified system message on `PreCallEvent` via `PreCallEvent#appendSystemContent(String)`.

Repository interface for AgentSkill persistence operations.

Metadata about a skill repository.

ClasspathSkillRepository - Loads skills from classpath resources and JAR files.

File system based implementation of AgentSkillRepository.

A skill repository whose visible contents depend on the current request context.

Utility for parsing and generating Markdown files with YAML frontmatter.

Utility class for file system operations related to skills.

Utility class for creating AgentSkill instances.

Mutable per-agent runtime state.

Persistent storage interface for AgentScope agent state.

Thrown when an optimistic-concurrency save fails because another writer changed the same session slot since it was loaded.

Policy applied when an optimistic-concurrency save of agent session state conflicts with another writer's update.

In-memory implementation of the `AgentStateStore` interface.

JSON file-based `AgentStateStore` implementation.

Utility for loading v1 session data into the 2.0 `AgentState` format.

Utility class for computing hash values of state lists.

Persisted plan-mode flag for an agent.

Snapshot of a file's contents kept in the tool read cache.

Information about a session.

Marker interface for persistable state objects.

Persistent agent task record carried inside `TaskContextState`.

Mutable bag of `Task`s carried by `AgentState`.

Read-cache backing for file-touching tools (Read / Write / Edit).

A state value paired with its optimistic-concurrency version from an `AgentStateStore`.

Deserialization shape for the v1 `toolkit_activeGroups` session entry.

Interface for agent tools that can be called by models.

Storage layer abstraction for tool execution context.

Default implementation of ToolResultConverter.

Interface for extended model that adds properties to tool parameters.

A no-op implementation of ToolEmitter that silently discards all emitted chunks.

An external tool implementation that only contains schema definition without execution logic.

Simple implementation of ExtendedModel using maps.

A `ToolGroup` that is bound to a specific skill.

Annotation to mark a method as a tool that can be invoked by AI agents.

Abstract base class for tools that participate in permission evaluation and ReAct execution.

Parameters for tool invocation.

Defaults for the dangerous-path and dangerous-command lists consulted by tool self-checks.

Interface for emitting streaming responses during tool execution.

Facade for passing custom POJOs to tool methods via priority-based resolution.

@deprecated Part of the {@link ToolExecutionContext} layer which is superseded by {@link io.agentscope.core.agent.RuntimeContext}.

Represents a named group of tools with activation state.

Defines who manages a `ToolGroup`'s activation lifecycle.

Enum defining how externally injected tools (e.g.

Annotation to describe parameters of a tool method.

Immutable per-call tool request config.

Converts tool method return values to ToolResultBlock.

Utility class for building tool result messages from ToolResultBlock objects.

A victools JSON Schema `Module` that reads `ToolParam` annotations to populate `"description"` and `"required"` in the generated schema.

Exception thrown to signal that a tool execution should be suspended and handled externally.

Unified validator for tool-related operations.

Toolkit manages the registration, retrieval, and execution of agent tools.

Configuration for Toolkit execution behavior.

Built-in task-list tool that lets the agent maintain a structured todo list for the current session, mirroring opencode's `todowrite`.

Interface for validating shell commands before execution.

Tool for executing shell commands with security validation.

Command validator for Unix-like systems (Linux, macOS).

Command validator for Windows systems.

Utility methods shared by text file tools.

Tool for viewing text file content with optional line range specification and listing directory contents.

Text file writing and insertion tools.

Wrapper for asynchronous MCP clients using Project Reactor.

Builder for creating MCP client wrappers with fluent configuration.

Abstract wrapper for MCP (Model Context Protocol) clients.

Utility class for converting between MCP content types and AgentScope content blocks.

Type-namespace marker for MCP (Model Context Protocol) request metadata.

Wrapper for synchronous MCP clients that converts blocking calls to reactive Mono types.

`ToolBase` subclass that wraps an MCP (Model Context Protocol) tool.

Configuration for sub-agent registration.

Factory interface for creating agent instances.

AgentTool implementation that wraps a sub-agent for multi-turn conversation.

@deprecated since 2.0.0.

Middleware that adds OpenTelemetry tracing to the agent lifecycle.

@deprecated since 2.0.0.

Registry for the global `Tracer` instance.

Utility methods for exception handling.

Jackson-based implementation of `JsonCodec`.

Interface for JSON serialization and deserialization operations.

Runtime exception for JSON processing errors.

Utility class for JSON Schema operations.

Utility class for accessing the global `JsonCodec` instance.

Utility methods for message processing and extraction.

Utility class for type-safe operations.