OpenSearch Agent Server

A multi-agent orchestration server for OpenSearch Dashboards with context-aware routing and Model Context Protocol (MCP) integration.

Overview

OpenSearch Agent Server enables intelligent agent-based interactions within OpenSearch Dashboards by:

• Multi-Agent Orchestration — Routes requests to specialized agents based on context
• OpenSearch Integration — Connects to OpenSearch via MCP for real-time data access
• AG-UI Protocol — Implements OpenSearch Dashboard's agent UI protocol with SSE streaming
• Flexible LLM Support — Works with AWS Bedrock, Ollama, or other LLM providers
• Production Ready — Includes authentication, rate limiting, error recovery, and observability

Demo

https://github.com/user-attachments/assets/d465d805-40c9-4158-8e4b-0805c675df45

Architecture

OpenSearch Dashboards (AG-UI)
            ↓
    OpenSearch Agent Server
    ├── Router (context-based)
    ├── Agent Registry
    │   ├── ART Agent (strands-agents)
    │   └── Default Agent
    └── OpenSearch MCP Server
            ↓
    OpenSearch Cluster

Features

• Context-Aware Routing — Automatically selects the appropriate agent based on request context
• Streaming Responses — Real-time SSE streaming for interactive user experiences
• Tool Execution — Agents can execute tools and visualize results in the dashboard
• Authentication & Authorization — JWT-based auth with configurable policies
• Rate Limiting — Protects backend services from overload
• Error Recovery — Automatic retry with exponential backoff
• Observability — Structured logging with request tracking

Prerequisites

• Python 3.12+
• OpenSearch 2.x (local or remote cluster)
• LLM Provider (choose one):
  • AWS Bedrock (requires AWS credentials)
  • Ollama (local installation)

Installation

1. Clone the repository

   git clone https://github.com/opensearch-project/opensearch-agent-server.git
   cd opensearch-agent-server
   

2. Create virtual environment

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies

   pip install -e .
   

4. Configure environment

   cp .env.example .env
   # Edit .env with your configuration
   

Configuration

Create a .env file with the following settings:

# OpenSearch Connection
OPENSEARCH_URL=https://localhost:9200
OPENSEARCH_USERNAME=admin
OPENSEARCH_PASSWORD=admin

# Authentication (set to false for local development)
AG_UI_AUTH_ENABLED=false

# CORS (allow OpenSearch Dashboards origin)
AG_UI_CORS_ORIGINS=http://localhost:5601

# LLM Provider — Option 1: AWS Bedrock
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1
BEDROCK_INFERENCE_PROFILE_ARN=arn:aws:bedrock:...

# LLM Provider — Option 2: Ollama (local)
OLLAMA_MODEL=llama3

# Logging
AG_UI_LOG_FORMAT=human
AG_UI_LOG_LEVEL=INFO

Quick Start

./scripts/quickstart.sh

This clones, builds, and starts everything in one command:

1. Clones search-relevance and OpenSearch Dashboards (with the dashboards-search-relevance plugin)
2. Bootstraps OSD and starts OpenSearch via ./gradlew run
3. Starts MCP Server (port 3001), OSD (port 5601), and Agent Server (port 8001)
4. Creates a workspace with a local data source and loads demo data
5. Runs a smoke test against all services

Prerequisites: Java 21+, Node.js 20+, Python 3.12+, uv, yarn, jq, curl

Access the Chat: Open http://localhost:5601 and click the chat icon in the header.

PyPI Installation

If you already have an OpenSearch cluster running and don't need the full quickstart setup, you can install and run the agent server directly from PyPI:

pip install opensearch-agent-server

Configure your environment:

export OPENSEARCH_URL=https://localhost:9200
export OPENSEARCH_USERNAME=admin
export OPENSEARCH_PASSWORD=admin
export AG_UI_AUTH_ENABLED=false

Start the agent server and MCP server together:

opensearch-agent-server --with-mcp

This starts both the OpenSearch MCP Server (port 3001) and the Agent Server (port 8001) in a single process. Both stop together on Ctrl+C.

# Verify
curl http://localhost:8001/health    # {"status": "ok"}
curl http://localhost:8001/agents    # list registered agents

You can also customize the MCP server port and config:

opensearch-agent-server --with-mcp --mcp-port 3002 --mcp-config ./custom_mcp.yml

Manual Setup

To run each component separately:

Terminal 1 - OpenSearch

# Start OpenSearch on port 9200
docker run -d -p 9200:9200 -p 9600:9600 \
  -e "discovery.type=single-node" \
  -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=Admin1234!" \
  opensearchproject/opensearch:latest

# Verify
curl http://localhost:9200 -u admin:Admin1234!

Terminal 2 - Agent Server

cd opensearch-agent-server
cp .env.example .env
# Edit .env with your settings
source .venv/bin/activate
python run_server.py

# Server starts on http://localhost:8001

Terminal 3 - OpenSearch Dashboards

cd OpenSearch-Dashboards
# Ensure config/opensearch_dashboards.yml has chat.agUiUrl configured
yarn start --no-base-path

# Dashboard opens on http://localhost:5601

Access the Chat

• Open http://localhost:5601
• Click the chat icon in the top-right header
• Start asking questions about your data!

Usage

Start the Server

python run_server.py

Or using uvicorn directly:

uvicorn server.ag_ui_app:app --host 0.0.0.0 --port 8001

The server will start on http://localhost:8001

Verify Installation

# Check server health
curl http://localhost:8001/health

# List available agents
curl http://localhost:8001/agents

# Test agent interaction (requires OpenSearch running)
curl -X POST http://localhost:8001/runs \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Show me recent logs",
    "context": [{"appId": "discover"}]
  }'

Integration with OpenSearch Dashboards

1. Start OpenSearch (port 9200)

   # Using Docker
   docker run -d -p 9200:9200 -p 9600:9600 \
     -e "discovery.type=single-node" \
     -e "OPENSEARCH_INITIAL_ADMIN_PASSWORD=Admin1234!" \
     opensearchproject/opensearch:latest
   
   # Or use your local OpenSearch installation
   

2. Start OpenSearch Agent Server (port 8001)

   cd opensearch-agent-server
   source .venv/bin/activate
   python run_server.py
   

3. Configure OpenSearch Dashboards

   Edit config/opensearch_dashboards.yml:

   # OpenSearch connection
   opensearch.hosts: ["http://localhost:9200"]
   opensearch.ssl.verificationMode: none
   
   # Enable new UI header (required for chat button)
   uiSettings:
     overrides:
       "home:useNewHomePage": true
   
   # Enable context provider (sends page context to agent)
   contextProvider:
     enabled: true
   
   # Enable chat with opensearch agent server
   chat:
     enabled: true
     agUiUrl: "http://localhost:8001/runs"
   

4. Start OpenSearch Dashboards (port 5601)

   cd OpenSearch-Dashboards
   yarn start --no-base-path
   

5. Access the Chat Interface

   • Open http://localhost:5601 in your browser
   • Look for the chat icon in the top-right header
   • Click to open the assistant panel
   • Start chatting with your data!

Development

Install Development Dependencies

pip install -e ".[dev]"

Run Tests

pytest

Code Formatting

ruff format .
ruff check .

Project Structure

opensearch-agent-server/
├── src/
│   ├── agents/                    # Agent implementations
│   │   ├── art/                   # ART (Search Relevance Testing) agent
│   │   │   ├── art_agent.py       # ART orchestrator agent
│   │   │   └── specialized_agents.py  # Hypothesis, evaluation, UBI sub-agents
│   │   ├── base.py                # Agent protocol / base types
│   │   └── default_agent.py       # General OpenSearch assistant
│   ├── orchestrator/              # Routing and registry
│   │   ├── router.py              # Context-based routing
│   │   └── registry.py            # Agent registry
│   ├── server/                    # FastAPI application
│   │   ├── ag_ui_app.py           # Main FastAPI app and lifespan
│   │   ├── cli.py                 # CLI entry point (opensearch-agent-server command)
│   │   ├── agent_orchestrator.py  # Orchestrator: routes requests to agents
│   │   ├── run_routes.py          # AG-UI protocol endpoints
│   │   ├── config.py              # Configuration management
│   │   └── ...                    # Middleware, auth, rate limiting, etc.
│   ├── tools/                     # Agent tools (local computation)
│   │   └── art/                   # ART-specific tools
│   │       └── experiment_tools.py  # Experiment results aggregation
│   └── utils/                     # Shared utilities
│       ├── mcp_connection.py      # OpenSearch MCP client
│       ├── logging_helpers.py     # Structured logging
│       ├── monitored_tool.py      # Tool instrumentation wrapper
│       └── ...                    # Persistence, activity monitor, etc.
├── tests/
│   ├── helpers/                   # Shared test helpers
│   ├── integration/               # Integration tests
│   └── unit/                      # Unit tests
├── run_server.py                  # Entry point
├── pyproject.toml                 # Project metadata and dependencies
└── .env.example                   # Environment template

API Endpoints

Health Check

GET /health

Returns server health status.

List Agents

GET /agents

Returns available agents and their capabilities.

Create Run (AG-UI Protocol)

POST /runs

Creates a new agent run with streaming responses via SSE.

Get Run Status

GET /runs/{run_id}

Returns the status of a specific run.

Troubleshooting

OpenSearch Connection Issues

• Verify OpenSearch is running: curl http://localhost:9200
• Check credentials in .env
• Disable SSL verification for local development

LLM Provider Issues

• AWS Bedrock: Ensure AWS credentials are configured
• Ollama: Verify Ollama is running: ollama list

Port Conflicts

If port 8001 is in use, modify the startup command:

uvicorn server.ag_ui_app:app --host 0.0.0.0 --port 8002

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Acknowledgments

• Built with strands-agents for multi-agent orchestration
• Implements AG-UI Protocol for OpenSearch Dashboards
• Uses Model Context Protocol (MCP) for OpenSearch integration