Metadata-Version: 2.4
Name: semantic-kernel-agent-factory
Version: 0.0.3
Summary: SDK for creating and managing OpenAI agents with MCP server integration
Author-email: Jiahao Zhu <jiahzhu@outlook.com>
License: MIT
Project-URL: Repository, https://github.com/jhzhu89/semantic-kernel-agent-factory
Project-URL: Issues, https://github.com/jhzhu89/semantic-kernel-agent-factory/issues
Project-URL: Documentation, https://github.com/jhzhu89/semantic-kernel-agent-factory/tree/main/docs
Keywords: semantic-kernel,agent,mcp,server,factory,sdk,service,sse,http
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.9.0
Requires-Dist: semantic-kernel>=1.31.0
Requires-Dist: pydantic>=2.11.4
Requires-Dist: pydantic-settings>=2.9.1
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: click>=8.2.1
Requires-Dist: typing-extensions>=4.13.2
Requires-Dist: textual>=0.85.0
Requires-Dist: anyio>=4.9.0
Requires-Dist: a2a-sdk>=0.2.4
Requires-Dist: starlette>=0.46.2
Requires-Dist: opentelemetry-api>=1.33.1
Requires-Dist: opentelemetry-sdk>=1.33.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.16.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.20250516; extra == "dev"
Requires-Dist: types-click>=7.1.0; extra == "dev"
Requires-Dist: flake8>=7.2.0; extra == "dev"
Provides-Extra: web
Requires-Dist: fastapi>=0.115.12; extra == "web"
Requires-Dist: uvicorn>=0.34.2; extra == "web"
Requires-Dist: httpx>=0.28.1; extra == "web"
Provides-Extra: monitoring
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "monitoring"
Requires-Dist: opentelemetry-exporter-prometheus>=1.12.0rc1; extra == "monitoring"
Requires-Dist: prometheus-client>=0.19.0; extra == "monitoring"
Provides-Extra: docs
Requires-Dist: sphinx>=7.1.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=1.24.0; extra == "docs"
Dynamic: license-file

# Semantic Kernel Agent Factory

A comprehensive SDK for creating and managing AI agents powered by Microsoft Semantic Kernel with MCP (Model Context Protocol) server integration. Build sophisticated conversational agents with tool integration, deploy them as web services, or interact with them through a rich terminal interface.

## Features

- 🤖 **Agent Factory**: Create and manage multiple Semantic Kernel-based agents with different configurations
- 🔗 **MCP Integration**: Connect agents to external tools via Model Context Protocol (stdio and SSE servers)
- 🖥️ **Interactive Console**: Rich terminal-based chat interface with multi-agent support powered by Textual
- 🌐 **Web Service Factory**: Deploy agents as HTTP/REST APIs with A2A (Agent-to-Agent) protocol support
- ⚡ **Streaming Support**: Real-time response streaming for both console and web interfaces
- 📊 **Health Monitoring**: Built-in MCP server health checks and status monitoring
- 🔧 **Flexible Configuration**: YAML-based configuration with environment variable support
- 📈 **Observability**: OpenTelemetry integration for tracing and monitoring

## Installation

### Basic Installation

```bash
# Install core functionality only
pip install semantic-kernel-agent-factory
```

### Installation with Optional Features

```bash
# For development (includes testing, linting, and type checking tools)
pip install semantic-kernel-agent-factory[dev]

# For web service deployment
pip install semantic-kernel-agent-factory[web]

# For enhanced monitoring and observability
pip install semantic-kernel-agent-factory[monitoring]

# For documentation generation
pip install semantic-kernel-agent-factory[docs]

# Install multiple feature sets
pip install semantic-kernel-agent-factory[dev,web,monitoring]
```

### Development Installation

For local development:

```bash
# Clone the repository
git clone https://github.com/jhzhu89/semantic-kernel-agent-factory
cd semantic-kernel-agent-factory

# Install in editable mode with development dependencies
pip install -e ".[dev]"
```

## Quick Start

### 1. Console Application

Create a configuration file `config.yaml`:

```yaml
agent_factory:
  agents:
    GeneralAssistant:
      name: "GeneralAssistant"
      instructions: |
        You are a helpful AI assistant.
        Answer questions clearly and concisely.
      model: "gpt-4"
      model_settings:
        temperature: 0.7

  openai_models:
    gpt-4:
      model: "gpt-4"
      api_key: "${OPENAI_API_KEY}"
      endpoint: "${AZURE_OPENAI_ENDPOINT}"
```

Run the interactive console:

```bash
agent-factory chat -c config.yaml
```

### 2. Python API - Agent Factory

```python
import asyncio
from agent_factory import AgentFactory, AgentFactoryConfig, AgentConfig

async def main():
    # Create configuration
    config = AgentFactoryConfig(
        agents={
            "assistant": AgentConfig(
                name="assistant",
                instructions="You are a helpful AI assistant",
                model="gpt-4"
            )
        },
        openai_models={
            "gpt-4": {
                "model": "gpt-4",
                "api_key": "your-api-key",
                "endpoint": "your-endpoint"
            }
        }
    )
    
    # Create and use agents
    async with AgentFactory(config) as factory:
        agent = factory.get_agent("assistant")
        # Use the agent for conversations
        
asyncio.run(main())
```

### 3. Web Service Deployment

Create a service configuration `service_config.yaml`:

```yaml
agent_factory:
  agents:
    ChatBot:
      name: "ChatBot"
      instructions: "You are a helpful chatbot"
      model: "gpt-4"
  
  openai_models:
    gpt-4:
      model: "gpt-4"
      api_key: "${OPENAI_API_KEY}"
      endpoint: "${AZURE_OPENAI_ENDPOINT}"

service_factory:
  services:
    ChatBot:
      card:
        name: "ChatBot"
        description: "AI-powered chatbot service"
      enable_token_streaming: true
```

Deploy as web service:

```python
from agent_factory import AgentServiceFactory, AgentServiceFactoryConfig
import uvicorn

async def create_app():
    config = AgentServiceFactoryConfig.from_file("service_config.yaml")
    
    async with AgentServiceFactory(config) as factory:
        app = await factory.create_application()
        return app

if __name__ == "__main__":
    uvicorn.run("main:create_app", host="0.0.0.0", port=8000)
```

## MCP Server Integration

Connect agents to external tools using Model Context Protocol servers:

```yaml
agent_factory:
  agents:
    ToolAgent:
      name: "ToolAgent"
      instructions: "You have access to various tools"
      model: "gpt-4"
      mcp_servers: ["time", "kubernetes"]
  
  mcp_servers:
    time:
      type: "stdio"
      command: "python"
      args: ["-m", "mcp_server_time"]
    
    kubernetes:
      type: "sse"
      url: "https://k8s-mcp-server.example.com/sse"
      timeout: 10
```

## Console Features

The interactive console provides:

- **Multi-Agent Chat**: Switch between different agents in tabbed interface
- **Real-time Streaming**: See responses as they're generated
- **MCP Status Monitoring**: Live health checks of connected MCP servers
- **Function Call Visibility**: See tool calls and results in real-time
- **Keyboard shortcuts**:
  - `Ctrl+Enter`: Send message
  - `Ctrl+L`: Clear chat
  - `F1`: Toggle agent panel
  - `F2`: Toggle logs
  - `Ctrl+W`: Close tab

## Configuration

### Agent Configuration

```yaml
agent_factory:
  agents:
    MyAgent:
      name: "MyAgent"
      instructions: "System prompt for the agent"
      model: "gpt-4"
      model_settings:
        temperature: 0.7
        max_tokens: 2000
        response_json_schema:  # Optional structured output
          type: "object"
          properties:
            answer: 
              type: "string"
      mcp_servers: ["tool1", "tool2"]
```

### OpenAI Models

```yaml
agent_factory:
  openai_models:
    gpt-4:
      model: "gpt-4"
      api_key: "${OPENAI_API_KEY}"
      endpoint: "${AZURE_OPENAI_ENDPOINT}"
    
    gpt-3.5-turbo:
      model: "gpt-3.5-turbo"
      api_key: "${OPENAI_API_KEY}"
      endpoint: "${AZURE_OPENAI_ENDPOINT}"
```

### MCP Server Types

**Stdio servers** (local processes):
```yaml
mcp_servers:
  local_tool:
    type: "stdio"
    command: "python"
    args: ["-m", "my_mcp_server"]
    env:
      DEBUG: "true"
```

**SSE servers** (HTTP-based):
```yaml
mcp_servers:
  remote_tool:
    type: "sse"
    url: "https://api.example.com/mcp"
    timeout: 15
```

## CLI Commands

```bash
# Start interactive chat
agent-factory chat -c config.yaml

# List configured agents
agent-factory list -c config.yaml

# Enable verbose logging
agent-factory chat -c config.yaml --verbose

# Custom log directory
agent-factory chat -c config.yaml --log-dir /path/to/logs
```

## Environment Variables

Configure using environment variables:

```bash
# OpenAI Configuration
export OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"

# Agent Factory Settings
export AGENT_FACTORY__MODEL_SELECTION="cost"  # first, cost, latency, quality
export AGENT_FACTORY__MCP_FAILURE_STRATEGY="lenient"  # strict, lenient
```

## Examples

See the `examples/` directory for:
- [`cli_example.yaml`](examples/cli_example.yaml) - Console application setup
- [`agent_service_factory_config.yaml`](examples/agent_service_factory_config.yaml) - Web service configuration
- [`web_service.py`](examples/web_service.py) - Web service deployment example

## Development

### Quick Setup

```bash
# Clone repository
git clone https://github.com/jhzhu89/semantic-kernel-agent-factory
cd semantic-kernel-agent-factory

# Install in editable mode with all development dependencies
pip install -e ".[dev]"
```

### Available Development Tools

The `[dev]` extra includes:
- **Testing**: pytest, pytest-asyncio, pytest-cov, pytest-mock
- **Code Formatting**: black, isort, ruff
- **Type Checking**: mypy with type stubs
- **Coverage**: pytest-cov for test coverage reports

### Development Commands

```bash
# Run tests
pytest

# Run tests with coverage
pytest --cov=agent_factory --cov-report=html

# Format code
black .
isort .

# Lint code
ruff check .

# Type checking
mypy agent_factory

# Run all quality checks
make test-cov  # Runs tests with coverage
make format    # Formats code
make type-check # Type checking
```

### Optional Development Features

```bash
# Install with all development tools
pip install -e ".[dev]"

# For web service development
pip install -e ".[dev,web]"

# Install monitoring tools for development
pip install -e ".[dev,monitoring]"

# Install documentation tools
pip install -e ".[dev,docs]"
```

## Architecture

The Semantic Kernel Agent Factory consists of several key components:

- **AgentFactory**: Core factory for creating and managing Semantic Kernel agents
- **AgentServiceFactory**: Web service wrapper that exposes agents as HTTP APIs (requires `[web]` extra)
- **MCPProvider**: Manages connections to Model Context Protocol servers
- **Console Application**: Terminal-based interface for interactive agent chat
- **Configuration System**: YAML-based configuration with validation
- **Observability**: OpenTelemetry integration for monitoring (enhanced with `[monitoring]` extra)

### Optional Components

Different installation options enable additional features:

- **`[web]`**: FastAPI-based web services, uvicorn server, HTTP clients
- **`[monitoring]`**: Enhanced observability with Prometheus metrics and OpenTelemetry instrumentation
- **`[docs]`**: Sphinx-based documentation generation
- **`[dev]`**: Development tools for testing, linting, and type checking

## Requirements

- Python 3.10+
- Microsoft Semantic Kernel
- Azure OpenAI or OpenAI API access
- Optional: MCP-compatible tool servers

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Install development dependencies: `pip install -e ".[dev]"`
4. Add tests for new functionality
5. Run the test suite and ensure all checks pass:
   ```bash
   # Run tests
   pytest
   
   # Format code
   black .
   isort .
   
   # Lint code
   ruff check .
   
   # Type checking
   mypy agent_factory
   ```
6. Submit a pull request

### Development Environment Setup

```bash
# Install with all development tools
pip install -e ".[dev]"

# For web service development
pip install -e ".[dev,web]"

# For full development environment
pip install -e ".[dev,web,monitoring,docs]"
```

### Project Structure

- `agent_factory/` - Core library code
- `tests/` - Test suite
- `examples/` - Usage examples
- `docs/` - Documentation (when using `[docs]` extra)

### Code Quality Standards

This project uses:
- **Black** for code formatting
- **isort** for import sorting  
- **Ruff** for linting
- **mypy** for type checking
- **pytest** for testing with >80% coverage requirement

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support & Documentation

- 📖 [GitHub Repository](https://github.com/jhzhu89/semantic-kernel-agent-factory)
- 🐛 [Issue Tracker](https://github.com/jhzhu89/semantic-kernel-agent-factory/issues)
- 💬 [Discussions](https://github.com/jhzhu89/semantic-kernel-agent-factory/discussions)
- 📚 [Examples](https://github.com/jhzhu89/semantic-kernel-agent-factory/tree/main/examples)

## Related Projects

- [Microsoft Semantic Kernel](https://github.com/microsoft/semantic-kernel)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Textual](https://github.com/Textualize/textual) - Powers the console interface
