### Install and Start Web UI

Source: https://github.com/agentscope-ai/agentscope/blob/main/README.md

Navigate to the web UI directory, install dependencies using pnpm, and then start the development server.

```bash
cd agentscope/examples/web_ui

# start the webui
pnpm install
pnpm dev
```

--------------------------------

### Start Agent Service

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/agent_service/README.md

Navigate to the agent service example directory and run the main Python script to start the service.

```bash
cd examples/agent_service

python main.py
```

--------------------------------

### Example Directory Structure

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

The recommended directory structure for new examples in the AgentScope repository. Each example should have its own subdirectory with a main script and README.

```bash
examples/
└── <example-name>/
    ├── main.py
    ├── README.md   # explain the example's purpose, how to run it, and expected output
    └── ...
```

--------------------------------

### Start Redis Server (Linux)

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/agent_service/README.md

Install and start the Redis server on Linux using systemd. Redis is used as the backend storage for the agent service.

```bash
# Linux (systemd)
sudo apt install redis-server
sudo systemctl start redis-server
```

--------------------------------

### Start Redis Server (macOS)

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/agent_service/README.md

Install and start the Redis server on macOS using Homebrew. Redis is used as the backend storage for the agent service.

```bash
# macOS (Homebrew)
brew install redis
brew services start redis
```

--------------------------------

### Install AgentScope from Source

Source: https://github.com/agentscope-ai/agentscope/blob/main/README.md

Clone the repository and install the package in editable mode.

```bash
# Pull the source code from GitHub
git clone -b main https://github.com/agentscope-ai/agentscope.git

# Install the package in editable mode
cd agentscope

uv pip install -e .
# or
# pip install -e .
```

--------------------------------

### OpenAI Chat Completions Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Demonstrates basic chat completions, tool calls, and structured output with OpenAI models. Requires appropriate API key setup.

```python
from agentscope.agents import Agent, finish, User, Assistant
from agentscope.message import Msg
from agentscope.models import OpenAIWrapper

# Initialize the OpenAI model wrapper
model = OpenAIWrapper(model="gpt-4-turbo-preview", api_key="YOUR_API_KEY")

# Define a tool for the model to use
@finish
def get_weather(city: str) -> str:
    """Get the current weather in a given city."""
    return f"The weather in {city} is sunny and 25°C."

# Create an assistant agent with the model and tool
assistant = Agent(
    name="assistant",
    model=model,
    tools=["get_weather"],
    instruction="You are a helpful assistant."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="What is the weather in London?"))

# The assistant will use the tool and respond
response = assistant.reply(user.last_message)
print(response)

# Example of structured output (requires model support, e.g., gpt-4-turbo-preview)
# assistant.reply(Msg(content="Tell me about Paris in JSON format.", output_format="json"))

```

--------------------------------

### Install and Run Web UI

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/agent_service/README.md

Install dependencies and run the Web UI in development mode. This provides a chat-style interface for the agent service.

```bash
cd examples/web_ui/

pnpm install
# or npm install

# Run in dev mode
pnpm dev
```

--------------------------------

### Start Agent Service Backend

Source: https://github.com/agentscope-ai/agentscope/blob/main/README.md

Run the main Python script to start the agent service backend. Ensure you are in the correct directory after cloning.

```bash
python main.py
```

--------------------------------

### Install AgentScope from PyPI

Source: https://github.com/agentscope-ai/agentscope/blob/main/README.md

Use this command to install the AgentScope package using pip or uv.

```bash
uv pip install agentscope
# or
# pip install agentscope
```

--------------------------------

### Start Redis Server (Docker)

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/agent_service/README.md

Run a Redis server using Docker. This is a cross-platform method to start Redis for the agent service.

```bash
# Docker (cross-platform)
docker run --rm -p 6379:6379 redis:7
```

--------------------------------

### Install AgentScope

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/agent_service/README.md

Install AgentScope with full features using uv pip. This command installs the necessary packages to run the agent service.

```bash
uv pip install agentscope[full]
# or
# uv pip install -e [full]
```

--------------------------------

### Install AgentScope with mem0 dependency

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Install AgentScope including the mem0 optional dependency. Set the DASHSCOPE_API_KEY for the OSS backend. Platform path keys are commented out.

```bash
# mem0 is an optional AgentScope dependency — pull it via the extra:
pip install "agentscope[mem0]"      # resolves to mem0ai>=2.0.0,<3.0.0
# (equivalent to `pip install agentscope mem0ai>=2.0.0,<3.0.0`)

export DASHSCOPE_API_KEY=sk-...     # OSS path
# Platform path (only if you switch):
# export MEM0_API_KEY=m0-...
# export OPENAI_API_KEY=sk-...      # only needed if your agent's chat model is OpenAI
```

--------------------------------

### Alibaba DashScope / Qwen Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Shows how to use Alibaba's DashScope (Qwen) models for chat completions. Requires a DashScope API key.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import DashScopeWrapper

# Initialize the DashScope model wrapper
model = DashScopeWrapper(model="qwen-turbo", api_key="YOUR_DASHSCOPE_API_KEY")

# Create an agent with the DashScope model
qwen_agent = Agent(
    name="qwen_agent",
    model=model,
    instruction="You are a helpful assistant powered by Alibaba Qwen."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="Explain the difference between supervised and unsupervised learning."))

# The agent responds
response = qwen_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Run Individual Model Example Scripts

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Execute any script independently after setting the necessary environment variables. These scripts demonstrate various agent functionalities.

```bash
python scripts/model_examples/openai_chat_call.py
python scripts/model_examples/dashscope_multiagent.py
python scripts/model_examples/ollama_multimodal.py
```

--------------------------------

### xAI Grok Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Shows how to use xAI's Grok models for chat completions. Requires an xAI API key.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import XaiWrapper

# Initialize the xAI model wrapper
model = XaiWrapper(model="grok-1", api_key="YOUR_XAI_API_KEY")

# Create an agent with the Grok model
xai_agent = Agent(
    name="xai_agent",
    model=model,
    instruction="You are a helpful assistant powered by xAI Grok."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="What are the ethical considerations of artificial general intelligence?", prompt_type="user"))

# The agent responds
response = xai_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Set Up Local Development Environment

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Create an isolated Python environment and install AgentScope in editable mode with development dependencies. This ensures you have all necessary tools for development and testing.

```bash
# Create an isolated environment (uv shown; virtualenv / conda also fine)
uv venv
source .venv/bin/activate

# Install AgentScope in editable mode with the dev extras
pip install -e ".[dev]"
# or, equivalently, with uv:
uv pip install -e ".[dev]"

# Enable the git pre-commit hooks
pre-commit install
```

--------------------------------

### Construct Mem0Middleware with OSS Backend Client

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Provide a pre-built mem0 OSS backend client (AsyncMemory) to the middleware for full control over the mem0 setup. The user_id and mode are specified.

```python
# 3. Client — bring your own pre-built mem0 client. Accepts EITHER
#    backend: `mem0.AsyncMemory` (open-source / self-hosted) or
#    `mem0.AsyncMemoryClient` (hosted Platform). Use this when you
#    want full control over the mem0 setup — custom subclass, a
#    pre-warmed client shared across many agents, exotic config
#    that doesn't fit the `build_mem0_config` helper, etc.
#
# OSS backend (you assemble the AsyncMemory yourself):
Mem0Middleware(
    user_id="alice",
    client=AsyncMemory(),  # or AsyncMemory.from_config({...})
    mode="both",
)
```

--------------------------------

### Add ESLint for React-Specific Rules

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/web_ui/frontend/README.md

Integrate 'eslint-plugin-react-x' and 'eslint-plugin-react-dom' for enhanced React and React DOM linting. This requires installing these plugins and configuring them in your ESLint setup.

```javascript
// eslint.config.js
import reactX from 'eslint-plugin-react-x';
import reactDom from 'eslint-plugin-react-dom';

export default defineConfig([
	globalIgnores(['dist']),
	{
		files: ['**/*.{ts,tsx}']
		extends: [
			// Other configs...
			// Enable lint rules for React
			reactX.configs['recommended-typescript'],
			// Enable lint rules for React DOM
			reactDom.configs.recommended,
		],
		languageOptions: {
			parserOptions: {
				project: ['./tsconfig.node.json', './tsconfig.app.json'],
				tscofigRootDir: import.meta.dirname,
			},
			// other options...
		},
	},
]);
```

--------------------------------

### Google Gemini Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Shows how to use Google Gemini models for chat completions. Requires a Google API key.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import GeminiWrapper

# Initialize the Gemini model wrapper
model = GeminiWrapper(model="gemini-1.5-pro-latest", api_key="YOUR_GOOGLE_API_KEY")

# Create an agent with the Gemini model
gemini_agent = Agent(
    name="gemini_agent",
    model=model,
    instruction="You are a helpful assistant powered by Google Gemini."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="Write a short poem about the stars."))

# The agent responds
response = gemini_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Start Ollama Service

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Before running Ollama-based scripts, ensure the Ollama service is running locally. This command starts the service.

```bash
ollama serve
```

--------------------------------

### Start and Pull Model for Ollama

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

For local testing with Ollama, ensure the server is running and pull the necessary model. No API key is required for Ollama.

```bash
ollama serve
ollama pull qwen3:14b   # pull the default model used in the scripts
```

--------------------------------

### DeepSeek Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Demonstrates chat completions using DeepSeek models. Note that DeepSeek currently does not support multimodal inputs.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import DeepSeekWrapper

# Initialize the DeepSeek model wrapper
model = DeepSeekWrapper(model="deepseek-chat", api_key="YOUR_DEEPSEEK_API_KEY")

# Create an agent with the DeepSeek model
deepseek_agent = Agent(
    name="deepseek_agent",
    model=model,
    instruction="You are a helpful assistant powered by DeepSeek."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="What are the latest advancements in natural language processing?", prompt_type="user"))

# The agent responds
response = deepseek_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Conventional Commits Type Examples

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Examples of commit messages demonstrating different types like 'feat', 'fix', 'docs', 'refactor', and 'ci'.

```bash
feat(models): add support for Claude-3 model
fix(agent): resolve memory leak in ReActAgent
docs(readme): update installation instructions
refactor(formatter): simplify message formatting logic
ci(models): add unit tests for OpenAI integration
```

--------------------------------

### Chat Model Card YAML Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

An example of a model card YAML file required for contributing a new chat model. It specifies model details, supported input/output types, and context size.

```yaml
name: claude-sonnet-4-6
label: Claude Sonnet 4.6
status: active
input_types:
  - text/plain
  - image/jpeg
output_types:
  - text/plain
context_size: 1000000
output_size: 65536
parameter_overrides:
  max_tokens: {"maximum": 65536}
```

--------------------------------

### Ollama Local Model Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Demonstrates chat completions using Ollama for local models. Requires a running Ollama server and a model downloaded via Ollama.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import OllamaWrapper

# Initialize the Ollama model wrapper
# Ensure Ollama server is running and the model (e.g., 'llama3') is downloaded
model = OllamaWrapper(model="llama3", base_url="http://localhost:11434")

# Create an agent with the Ollama model
olama_agent = Agent(
    name="olama_agent",
    model=model,
    instruction="You are a helpful assistant running locally via Ollama."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="Tell me a short story about a robot."))

# The agent responds
response = ollama_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Moonshot AI (Kimi) Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Demonstrates chat completions using Moonshot AI's Kimi models. Requires a Moonshot API key.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import MoonshotWrapper

# Initialize the Moonshot model wrapper
model = MoonshotWrapper(model="moonshot-v1-8k", api_key="YOUR_MOONSHOT_API_KEY")

# Create an agent with the Moonshot model
moonshot_agent = Agent(
    name="moonshot_agent",
    model=model,
    instruction="You are a helpful assistant powered by Moonshot AI."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="Summarize the main points of the theory of relativity."))

# The agent responds
response = moonshot_agent.reply(user.last_message)
print(response)

```

--------------------------------

### OpenAI Chat Multi-Agent Conversation Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Illustrates a multi-agent conversation using OpenAI Chat Completions. Ensure multiple agents are configured and can communicate.

```python
from agentscope.agents import Agent, User, Assistant
from agentscope.message import Msg
from agentscope.models import OpenAIWrapper

# Initialize the OpenAI model wrapper
model = OpenAIWrapper(model="gpt-4-turbo-preview", api_key="YOUR_API_KEY")

# Create two agents that will converse
agent1 = Agent(
    name="agent1",
    model=model,
    instruction="You are agent 1. Respond concisely."
)
agent2 = Agent(
    name="agent2",
    model=model,
    instruction="You are agent 2. Respond with more detail."
)

# Start the conversation with a user message
user = User()
user.reply(Msg(content="Hello agent1, please start a discussion about AI ethics."))

# Agent 1 responds to the user
agent1.reply(user.last_message)

# Agent 2 responds to Agent 1
agent2.reply(agent1.last_message)

# Agent 1 responds to Agent 2
agent1.reply(agent2.last_message)

# Continue the conversation as needed...

```

--------------------------------

### OpenAI Chat Multimodal Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Demonstrates multimodal chat completions with OpenAI, allowing both image and text inputs. Requires a model that supports multimodal inputs.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import OpenAIWrapper

# Initialize the OpenAI model wrapper for multimodal
model = OpenAIWrapper(model="gpt-4-vision-preview", api_key="YOUR_API_KEY")

# Create an agent that can handle multimodal input
multimodal_agent = Agent(
    name="multimodal_agent",
    model=model,
    instruction="Describe the image and answer the question."
)

# Create a user agent
user = User()

# Send a message with both text and an image
# Ensure 'test.jpeg' is in the same directory or provide a full path
user.reply(
    Msg(
        content="What is in this image? And what is the main color?",
        image="test.jpeg"
    )
)

# The agent processes the multimodal message
response = multimodal_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Anthropic Claude Chat Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Demonstrates basic chat completions using Anthropic's Claude models. Requires an Anthropic API key.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import AnthropicWrapper

# Initialize the Anthropic model wrapper
model = AnthropicWrapper(model="claude-3-opus-20240229", api_key="YOUR_ANTHROPIC_API_KEY")

# Create an agent with the Anthropic model
claude_agent = Agent(
    name="claude_agent",
    model=model,
    instruction="You are a helpful assistant powered by Anthropic Claude."
)

# Create a user agent
user = User()

# Start a conversation
user.reply(Msg(content="What are the main benefits of using large language models?", prompt_type="human"))

# The agent responds
response = claude_agent.reply(user.last_message)
print(response)

```

--------------------------------

### OpenAI Responses API Example

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Utilizes the OpenAI Responses API for reasoning models (o1/o3). This API is suitable for tasks requiring more direct reasoning capabilities.

```python
from agentscope.agents import Agent, User
from agentscope.message import Msg
from agentscope.models import OpenAIWrapper

# Initialize the OpenAI model wrapper for Responses API
# Use a model that supports the Responses API, e.g., 'gpt-4-turbo-preview' or specific reasoning models
model = OpenAIWrapper(model="gpt-4-turbo-preview", api_key="YOUR_API_KEY", use_responses_api=True)

# Create an agent using the Responses API model
reasoning_agent = Agent(
    name="reasoning_agent",
    model=model,
    instruction="Analyze the following problem and provide a step-by-step solution."
)

# Create a user agent
user = User()

# Send a problem to the agent
user.reply(Msg(content="Explain the concept of recursion with a simple example."))

# The agent provides a reasoned response
response = reasoning_agent.reply(user.last_message)
print(response)

```

--------------------------------

### Agent Control Middleware Setup

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Configure the middleware in `agent_control` mode and expose its memory tools to the agent's toolkit. This mode allows the agent to explicitly call memory search and add functions.

```python
mw = Mem0Middleware(..., mode="agent_control")
agent = Agent(
    ...,
    toolkit=Toolkit(tools=await mw.list_tools()),
    middlewares=[mw],
)
```

--------------------------------

### Check Provider Availability

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Verify which AI providers are configured and available for testing by running the availability check script. This helps in identifying missing API keys or setup issues.

```bash
python scripts/model_examples/run_tests.py --list
```

--------------------------------

### Valid and Invalid Pull Request Titles

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Examples illustrating valid and invalid pull request titles based on Conventional Commits rules, particularly regarding scope casing.

```text
✅ Valid:
feat(memory): add redis cache support
fix(agent): resolve memory leak in ReActAgent
docs(tutorial): update installation guide
ci(workflow): add PR title validation
refactor(my-feature): simplify logic

❌ Invalid:
feat(Memory): add cache          # Scope must be lowercase
feat(MEMORY): add cache          # Scope must be lowercase
feat(MyFeature): add feature     # Scope must be lowercase
```

--------------------------------

### Create and Interact with a Basic Agent

Source: https://github.com/agentscope-ai/agentscope/blob/main/README.md

This Python script demonstrates how to initialize an Agent with a system prompt, a model, and a toolkit, and then interact with it using a streaming reply. Ensure the DASHSCOPE_API_KEY environment variable is set.

```python
from agentscope.agent import Agent
from agentscope.tool import Toolkit, Bash, Grep, Glob, Read, Write, Edit
from agentscope.credential import DashScopeCredential
from agentscope.model import DashScopeChatModel
from agentscope.message import UserMsg
from agentscope.event import EventType

import os, asyncio


async def main() -> None:
    agent = Agent(
        name="Friday",
        system_prompt="You're a helpful assistant named Friday.",
        model=DashScopeChatModel(
            credential=DashScopeCredential(
              api_key=os.environ["DASHSCOPE_API_KEY"]
            ),
            model="qwen3.6-plus",
        ),
        toolkit=Toolkit(
            tools=[
                Bash(),
                Grep(),
                Glob(),
                Read(),
                Write(),
                Edit(),
            ]
        ),
    )

    async for evt in agent.reply_stream(UserMsg("Tony", "Hi, Friday!")):
        # Handle the event stream, e.g., print the message, update UI, etc.
        match evt.type:
            case EventType.REPLY_START:
                ...
            case EventType.MODEL_CALL_START:
                ...
            case EventType.TEXT_BLOCK_START:
                ...
            case EventType.TEXT_BLOCK_DELTA:
                ...
            case EventType.TEXT_BLOCK_END:
                ...

            # Handle other event types

asyncio.run(main())
```

--------------------------------

### Construct Mem0Middleware with Hosted Platform Client

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Provide a pre-built mem0 hosted Platform client (AsyncMemoryClient) to the middleware, specifying the API key. The user_id and mode are also set.

```python
# Hosted Platform backend:
Mem0Middleware(
    user_id="alice",
    client=AsyncMemoryClient(api_key="m0-..."),
    mode="both",
)
```

--------------------------------

### Run Qdrant in Docker

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Deploy Qdrant as a Docker service for robust, multi-process compatible storage. This avoids file-lock contention issues common with local on-disk Qdrant, especially on Windows.

```bash
docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant
```

--------------------------------

### Construct Mem0Middleware using Models

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Build a local OSS AsyncMemory wired to your AgentScope chat and embedding models. Defaults are used for other mem0 configurations.

```python
# 1. Models — build a local OSS AsyncMemory wired to your AgentScope
#    chat + embedding model. mem0 defaults for everything else.
Mem0Middleware(
    user_id="alice",
    chat_model=my_chat_model,
    embedding_model=my_embedding_model,
    mode="both",
)
```

--------------------------------

### Import Mem0Middleware and Toolkit

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Import the Mem0Middleware class from the agentscope.middleware package and Toolkit from agentscope.tool.

```python
from agentscope.middleware import Mem0Middleware
from agentscope.tool import Toolkit
```

--------------------------------

### Clone Repo and Set Up Remotes

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Clone your fork of the AgentScope repository and add the upstream remote for tracking the main project. This is a standard Git workflow for contributing to open-source projects.

```bash
git clone https://github.com/<your-username>/agentscope.git
cd agentscope
git remote add upstream https://github.com/agentscope-ai/agentscope.git
```

--------------------------------

### Configure Mem0Middleware to Use Dockerized Qdrant

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Configure Mem0Middleware to connect to a Qdrant instance running in Docker by specifying connection details like host, port, and collection name within MemoryConfig.

```python
from mem0.configs.base import MemoryConfig
from mem0.vector_stores.configs import VectorStoreConfig

mem0_cfg = MemoryConfig(
    vector_store=VectorStoreConfig(
        provider="qdrant",
        config={
            "collection_name": "mem0",
            "host": "localhost",     # the Docker container
            "port": 6333,
            "embedding_model_dims": 1536,
        },
    ),
)
Mem0Middleware(
    user_id="alice",
    chat_model=chat_model,
    embedding_model=embedding_model,
    mem0_config=mem0_cfg,
)
```

--------------------------------

### Export API Keys for Providers

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Set the environment variables for the AI providers you intend to use for testing. Ensure you replace the placeholder keys with your actual API keys.

```bash
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export DASHSCOPE_API_KEY="sk-..."
export DEEPSEEK_API_KEY="sk-..."
export GEMINI_API_KEY="AIza..."
export MOONSHOT_API_KEY="sk-..."
export XAI_API_KEY="xai-..."
```

--------------------------------

### Run All Available Tests

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Execute all configured tests against the available AI providers. The script automatically detects credentials and skips providers without them.

```bash
python scripts/model_examples/run_tests.py
```

--------------------------------

### Construct Mem0Middleware with Models and Custom Config

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Use custom mem0 configurations, such as a specific vector store or history database path, while overriding the LLM and embedder with AgentScope adapters. Other mem0_config fields are preserved.

```python
# 2. Models + custom mem0_config — same as (1), but start from your
#    customized MemoryConfig (custom vector store, history DB, 
#    reranker, ...). `chat_model` / `embedding_model` always WIN:
#    if mem0_config already specifies an .llm or .embedder, it gets
#    OVERWRITTEN by the AgentScope adapter built from your model.
#    Every other field of mem0_config (vector_store, history_db_path, 
#    reranker, etc.) is preserved as-is.
Mem0Middleware(
    user_id="alice",
    chat_model=my_chat_model,
    embedding_model=my_embedding_model,
    mem0_config=MemoryConfig(
        vector_store=VectorStoreConfig(
            provider="qdrant",
            config={"host": "my-qdrant", "port": 6333},
        ),
        history_db_path="/data/mem0_history.db",
    ),
    mode="both",
)
```

--------------------------------

### Run Pre-commit Hooks and Tests

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Before submitting a pull request, run pre-commit hooks for auto-formatting and linting, and execute the unit test suite. This ensures code quality and adherence to project standards.

```bash
# Auto-format and lint
pre-commit run --all-files

# Run the unit tests
pytest tests
```

--------------------------------

### Share Mem0Middleware Instance Across Agents

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Instantiate Mem0Middleware once and pass it to multiple agents to share the same memory. This avoids Qdrant's exclusive lock error when multiple instances try to access the same storage folder.

```python
mw = Mem0Middleware(
    user_id="alice",
    chat_model=chat_model,
    embedding_model=embedding_model,
    mode="both",
)
agent_a = Agent(
    ...,
    toolkit=Toolkit(tools=await mw.list_tools()),
    middlewares=[mw],
)
agent_b = Agent(
    ...,
    toolkit=Toolkit(tools=await mw.list_tools()),
    middlewares=[mw],
)
```

--------------------------------

### Configure Mem0 Middleware Factory for agentscope.app

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/long_term_memory/mem0/README.md

Use this factory function to create Mem0Middleware instances for agentscope.app deployments. The factory is called once per agent assembly and returns fresh middleware instances that share a single underlying mem0 client. Ensure the mem0 client is built once at module scope to avoid deadlocks.

```python
from agentscope.app import create_app
from agentscope.middleware import Mem0Middleware
from agentscope.middleware._longterm_memory._mem0._agentscope_adapter \
    import build_mem0_config
from mem0 import AsyncMemory

# Build the mem0 client ONCE at module scope — local OSS Qdrant
# takes an exclusive lock on its storage folder; per-request
# construction would deadlock under concurrent traffic.
chat_model = ...     # shared AgentScope ChatModelBase
emb_model  = ...     # shared AgentScope EmbeddingModelBase
mem0_client = AsyncMemory(
    config=build_mem0_config(
        chat_model=chat_model,
        embedding_model=emb_model,
    ),
)


async def long_term_memory_factory(
    user_id: str,         # ← from the authenticated X-User-ID header
    agent_id: str,
    session_id: str,
) -> list:
    return [
        Mem0Middleware(
            user_id=user_id,
            client=mem0_client,    # shared across all requests
            mode="both",
        ),
    ]


app = create_app(
    ...,
    extra_agent_middlewares=long_term_memory_factory,
)
```

--------------------------------

### Run Specific Providers and Test Types

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Execute tests for specific providers and test types. This is useful for targeted testing or when only a subset of providers/tests are relevant.

```bash
python scripts/model_examples/run_tests.py --providers openai_chat,anthropic
```

```bash
python scripts/model_examples/run_tests.py --tests call
```

```bash
python scripts/model_examples/run_tests.py -p dashscope,deepseek -t call,multiagent
```

```bash
python scripts/model_examples/run_tests.py --tests multimodal,multiagent_multimodal
```

--------------------------------

### Clone AgentScope Repository

Source: https://github.com/agentscope-ai/agentscope/blob/main/README.md

Clone the AgentScope repository from GitHub. This command fetches the latest main branch.

```bash
git clone -b main https://github.com/agentscope-ai/agentscope.git
cd agentscope/examples/agent_service
```

--------------------------------

### Pull Ollama Model

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Download the specific model required by the scripts. Replace 'qwen3:14b' with the model name used in your script.

```bash
ollama pull qwen3:14b
```

--------------------------------

### Set Ollama Host Environment Variable

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

If your Ollama service is running on a non-default address, set this environment variable to the correct host and port.

```bash
export OLLAMA_HOST=http://your-host:11434
```

--------------------------------

### Lazy Import Optional Dependencies

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

When using optional dependencies not listed in the base project dependencies, import them at the point of use rather than at the module top level. This keeps the base import lightweight and defers potential ImportErrors.

```python
def some_function():
    import google.genai  # from the `gemini` extra — lazy-imported
    # ... use google.genai here
```

--------------------------------

### Expand ESLint for Type-Checked Rules

Source: https://github.com/agentscope-ai/agentscope/blob/main/examples/web_ui/frontend/README.md

Configure ESLint to enable type-aware lint rules for TypeScript files. Ensure 'tsconfig.node.json' and 'tsconfig.app.json' are correctly specified.

```javascript
export default defineConfig([
	globalIgnores(['dist']),
	{
		files: ['**/*.{ts,tsx}']
		extends: [
			// Other configs...

			// Remove tseslint.configs.recommended and replace with this
			tseslint.configs.recommendedTypeChecked,
			// Alternatively, use this for stricter rules
			tseslint.configs.strictTypeChecked,
			// Optionally, add this for stylistic rules
			tseslint.configs.stylisticTypeChecked,

			// Other configs...
		],
		languageOptions: {
			parserOptions: {
				project: ['./tsconfig.node.json', './tsconfig.app.json'],
				tscofigRootDir: import.meta.dirname,
			},
			// other options...
		},
	},
]);
```

--------------------------------

### Create Feature Branch

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Create a new topic branch for your feature or fix, based on the latest main branch from the upstream repository. Use a descriptive branch name indicating the type of change.

```bash
git checkout main
git pull upstream main
git checkout -b feat/<short-description>
```

--------------------------------

### Conventional Commits Message Format

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Use this format for commit messages to ensure readability and enable automatic changelog generation. It includes a type, optional scope, and a subject.

```text
<type>(<scope>): <subject>
```

--------------------------------

### Increase Per-Script Timeout

Source: https://github.com/agentscope-ai/agentscope/blob/main/scripts/model_examples/README.md

Adjust the timeout for individual test scripts. Increase this value if tests are timing out due to long execution times.

```bash
python scripts/model_examples/run_tests.py --timeout 180
```

--------------------------------

### Pull Request Title Format

Source: https://github.com/agentscope-ai/agentscope/blob/main/CONTRIBUTING.md

Pull request titles must also follow the Conventional Commits format. This is automatically validated by GitHub Actions.

```text
<type>(<scope>): <description>
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.