Metadata-Version: 2.4
Name: agentcore-sdk
Version: 0.1.0
Summary: Open-source orchestration framework for agentic AI systems with multi-agent coordination, tool integration, and workflow management
Project-URL: Homepage, https://github.com/Mathews-Tom/AgentCore
Project-URL: Documentation, https://github.com/Mathews-Tom/AgentCore#readme
Project-URL: Repository, https://github.com/Mathews-Tom/AgentCore
Project-URL: Issues, https://github.com/Mathews-Tom/AgentCore/issues
Project-URL: Changelog, https://github.com/Mathews-Tom/AgentCore/blob/main/CHANGELOG.md
Author-email: AgentCore Team <team@agentcore.ai>
License: MIT
License-File: LICENSE
Keywords: a2a,agent-framework,agent2agent,agents,ai,automation,cli,distributed-systems,fastapi,jsonrpc,llm,multi-agent,orchestration,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: aiodocker>=0.24.0
Requires-Dist: aiosqlite>=0.21.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: anthropic==0.40.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: bandit>=1.8.6
Requires-Dist: cloudpickle>=3.1.1
Requires-Dist: croniter>=6.0.0
Requires-Dist: docker>=7.1.0
Requires-Dist: dspy-ai>=2.5.43
Requires-Dist: fastapi-websocket-rpc>=0.1.25
Requires-Dist: fastapi>=0.104.0
Requires-Dist: google-generativeai==0.8.3
Requires-Dist: httpx[http2]==0.24.1
Requires-Dist: mlflow>=3.5.1
Requires-Dist: neo4j>=5.15.0
Requires-Dist: networkx>=3.2
Requires-Dist: openai==1.54.0
Requires-Dist: opentelemetry-api>=1.21.0
Requires-Dist: opentelemetry-exporter-otlp>=1.21.0
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.42b0
Requires-Dist: opentelemetry-sdk>=1.21.0
Requires-Dist: pgvector>=0.4.1
Requires-Dist: portkey-ai>=1.15.1
Requires-Dist: prometheus-client>=0.19.0
Requires-Dist: prometheus-fastapi-instrumentator>=7.1.0
Requires-Dist: psutil>=7.1.0
Requires-Dist: pydantic-settings>=2.11.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pytest-rerunfailures>=16.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: redis>=5.0.0
Requires-Dist: restrictedpython>=8.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.16.2
Requires-Dist: sentence-transformers>=5.1.1
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: sse-starlette>=3.0.2
Requires-Dist: structlog>=23.2.0
Requires-Dist: testcontainers>=4.0.0
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: torch>=2.9.0
Requires-Dist: typer[all]>=0.9.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: uvloop>=0.21.0
Provides-Extra: dev
Requires-Dist: httpx==0.24.1; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: testcontainers[neo4j]>=4.0.0; extra == 'dev'
Requires-Dist: testcontainers[redis]>=3.7.0; extra == 'dev'
Provides-Extra: test
Requires-Dist: httpx==0.24.1; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.1.0; extra == 'test'
Requires-Dist: pytest-mock>=3.12.0; extra == 'test'
Requires-Dist: pytest>=7.4.0; extra == 'test'
Requires-Dist: testcontainers[redis]>=3.7.0; extra == 'test'
Description-Content-Type: text/markdown

# AgentCore - Production-Ready Agentic AI Framework

**AgentCore** is an open-source orchestration framework for building, training, and deploying intelligent agent systems at scale. Built on Google's A2A (Agent-to-Agent) protocol v0.2, it provides enterprise-grade infrastructure for multi-agent collaboration, automated prompt optimization, and cross-platform LLM integration.

[![Tests](https://img.shields.io/badge/tests-4598%20passing-brightgreen)](./tests)
[![Coverage](https://img.shields.io/badge/coverage-94.2%25-brightgreen)](./htmlcov)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)

---

## 🎯 Key Features

### 🤖 Agent-to-Agent Protocol (A2A)

- **JSON-RPC 2.0** compliant API for standardized agent communication
- **Agent discovery** via `.well-known/agent.json` endpoints
- **Task coordination** with lifecycle management (create, assign, execute, complete)
- **Real-time messaging** via WebSocket and Server-Sent Events (SSE)
- **Distributed tracing** with A2A context propagation

### 🧠 DSPy Optimization Framework

- **Automated prompt optimization** using MIPROv2, BootstrapFewShot, and GEPA algorithms
- **Continuous learning pipeline** with online optimization and drift detection
- **A/B testing framework** for prompt variant comparison
- **MLflow integration** for experiment tracking and model versioning
- **Performance analytics** with ROI tracking and improvement recommendations
- **GPU acceleration** support for high-throughput optimization
- **Custom algorithm plugins** for domain-specific optimization strategies

### 🔌 LLM Gateway

- **Multi-provider support**: OpenAI (GPT-5), Anthropic (Claude 4.5), Google (Gemini 2.5)
- **Intelligent routing** with automatic failover and load balancing
- **Cost tracking** and budget management
- **Rate limit handling** with exponential backoff
- **Caching** for duplicate request optimization
- **Model selection** based on task requirements and constraints

### 🎭 Agent Runtime

- **Chain-of-Thought (CoT)** reasoning engine
- **Multi-tool integration** with external API connectors
- **Memory management** with context preservation
- **Error recovery** and retry mechanisms
- **Bounded context** for consistent agent behavior
- **State persistence** and checkpointing

### 📊 Orchestration & Workflows

- **Graph-based workflow** planning with topological sorting
- **Event-driven architecture** with 15k+ events/sec throughput
- **Parallel execution** with automatic dependency resolution
- **Performance monitoring** with Prometheus metrics
- **Health checks** and circuit breakers

### 🔐 Security & Compliance

- **JWT authentication** with role-based access control (RBAC)
- **PII detection** and data anonymization
- **Audit logging** for compliance tracking
- **Secure credential management** via Kubernetes secrets
- **Network isolation** with service mesh integration

---

## 🚀 Quick Start

### Prerequisites

- Python 3.12+
- PostgreSQL 14+
- Redis 7+
- (Optional) MLflow server for experiment tracking
- (Optional) GPU for accelerated optimization

### Installation

```bash
# Clone the repository
git clone https://github.com/Mathews-Tom/AgentCore.git
cd AgentCore

# Install dependencies using uv
uv sync

# Set up environment variables
cp .env.test.template .env
# Edit .env with your configuration
```

### Running with Docker Compose

```bash
# Start all services (PostgreSQL, Redis, AgentCore)
docker compose -f docker-compose.dev.yml up

# API available at http://localhost:8001
# API docs at http://localhost:8001/docs (DEBUG mode only)
```

### Running Locally

```bash
# Start database and Redis
docker compose -f docker-compose.dev.yml up postgres redis

# Source environment variables
set -a && source .env && set +a

# Run migrations
uv run alembic upgrade head

# Start development server
uv run uvicorn agentcore.a2a_protocol.main:app --host 0.0.0.0 --port 8001 --reload
```

---

## 📖 Documentation

### Core Documentation

- **[Architecture Overview](./docs/architecture/)** - System design and component interactions
- **[API Reference](./docs/api/)** - JSON-RPC method specifications
- **[Deployment Guide](./docs/deployment/)** - Production deployment with Kubernetes
- **[Development Guide](./CLAUDE.md)** - Contributing and development workflow

### DSPy Optimization

- **[DSPy Specification](./docs/specs/dspy-optimization/spec.md)** - Detailed requirements and design
- **[DSPy Implementation Plan](./docs/specs/dspy-optimization/plan.md)** - Architecture and integration
- **[DSPy User Guide](./docs/dspy-optimization/user-guide.md)** - Getting started with optimization
- **[DSPy Best Practices](./docs/dspy-optimization/best-practices.md)** - Tips and patterns

### LLM Integration

- **[LLM Client Service](./docs/llm-client-service/README.md)** - Multi-provider LLM integration
- **[Configuration Guide](./docs/llm-client-service/configuration-guide.md)** - Provider setup
- **[Model Selection](./docs/specs/llm-client-service/spec.md)** - Intelligent model routing

### Research & Future Work

- **[Parallax & OpenEnv Analysis](./docs/research/parallax-openenv-analysis.md)** - Future enhancements
- **[Integration Proposal](./docs/research/parallax-openenv-integration-proposal.md)** - Technical specifications
- **[Implementation Roadmap](./docs/research/parallax-openenv-roadmap.md)** - Execution plan

---

## 🧪 Testing

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/agentcore --cov-report=html

# Run specific test categories
uv run pytest -m unit              # Unit tests only
uv run pytest -m integration       # Integration tests
uv run pytest -m performance       # Performance benchmarks
uv run pytest -m slow              # Long-running tests

# Run specific test file
uv run pytest tests/unit/test_llm_service.py

# Run with verbose output
uv run pytest -v

# Performance benchmarks
uv run pytest -m performance --durations=20
```

### Test Coverage

Current test coverage: **94.2%** (Target: >90%)

- **Unit Tests**: 2,847 tests
- **Integration Tests**: 1,312 tests
- **Performance Tests**: 312 tests
- **E2E Tests**: 127 tests

**Total**: 4,598 tests passing

---

## 🏗️ Architecture

### Component Overview

```plaintext
agentcore/
├── a2a_protocol/           # A2A protocol implementation
│   ├── models/             # Pydantic models (AgentCard, Task, Event, etc.)
│   ├── services/           # Business logic (AgentManager, TaskManager, etc.)
│   ├── routers/            # FastAPI endpoints
│   ├── database/           # PostgreSQL models and repositories
│   └── metrics/            # Prometheus metrics collection
│
├── agent_runtime/          # Agent execution engine
│   ├── engines/            # CoT reasoning, planning
│   ├── services/           # Tool integration, memory management
│   └── config/             # Runtime configuration
│
├── dspy_optimization/      # DSPy optimization framework
│   ├── algorithms/         # MIPROv2, GEPA, BootstrapFewShot
│   ├── analytics/          # Performance analytics, ROI tracking
│   ├── learning/           # Online learning, drift detection
│   ├── monitoring/         # Metrics collection, baselines
│   ├── plugins/            # Custom algorithm registry
│   ├── testing/            # A/B testing, experiments
│   └── tracking/           # MLflow integration
│
├── llm_gateway/            # Multi-provider LLM integration
│   ├── providers/          # OpenAI, Anthropic, Gemini clients
│   ├── models.py           # Request/response models
│   ├── failover.py         # Automatic failover logic
│   ├── cost_tracker.py     # Cost monitoring
│   └── cache_service.py    # Response caching
│
├── orchestration/          # Workflow orchestration
│   ├── engines/            # Graph planning, execution
│   ├── events/             # Event streaming
│   └── performance/        # Benchmarking, optimization
│
├── gateway/                # API gateway services
│   ├── routing.py          # Request routing
│   ├── health_monitor.py   # Health checks
│   └── load_balancer.py    # Load distribution
│
└── integration/            # External service integrations
    ├── api/                # API connectors
    ├── storage/            # Blob storage (Azure, S3)
    └── security/           # Credential management
```

### Technology Stack

**Backend**:

- Python 3.12+ with asyncio
- FastAPI for HTTP/WebSocket APIs
- PostgreSQL 14+ (async via asyncpg)
- Redis 7+ for caching and pub/sub

**Optimization**:

- DSPy for prompt optimization
- MLflow for experiment tracking
- SciPy for statistical analysis
- NetworkX for graph algorithms

**Observability**:

- Prometheus for metrics
- Grafana for dashboards
- OpenTelemetry for distributed tracing
- Structured logging with structlog

**Deployment**:

- Kubernetes for orchestration
- Docker for containerization
- Alembic for database migrations
- GitHub Actions for CI/CD

---

## 🎓 Example Usage

### Registering an Agent

```python
import httpx

# Agent registration
agent_card = {
    "agent_id": "my-agent-001",
    "name": "My Agent",
    "description": "A sample intelligent agent",
    "capabilities": ["text_generation", "data_analysis"],
    "version": "1.0.0",
    "owner": "team@example.com"
}

request = {
    "jsonrpc": "2.0",
    "method": "agent.register",
    "params": {"agent_card": agent_card},
    "id": "1"
}

async with httpx.AsyncClient() as client:
    response = await client.post(
        "http://localhost:8001/api/v1/jsonrpc",
        json=request
    )
    print(response.json())
```

### Running DSPy Optimization

```python
from agentcore.dspy_optimization.pipeline import DSPyOptimizationPipeline
from agentcore.dspy_optimization.models import OptimizationRequest

# Initialize pipeline
pipeline = DSPyOptimizationPipeline()

# Configure optimization
request = OptimizationRequest(
    target="prompt_template",
    objective="maximize_accuracy",
    algorithm="miprov2",
    evaluation_metric="f1_score",
    max_iterations=100
)

# Run optimization
result = await pipeline.optimize(request)
print(f"Optimized prompt: {result.optimized_prompt}")
print(f"Performance improvement: {result.improvement_percentage}%")
```

### Creating and Executing Tasks

```python
# Create task
task_definition = {
    "description": "Analyze customer feedback and extract insights",
    "requirements": ["text_analysis", "sentiment_detection"],
    "priority": "high",
    "timeout_seconds": 300
}

create_request = {
    "jsonrpc": "2.0",
    "method": "task.create",
    "params": {
        "task_definition": task_definition,
        "auto_assign": True
    },
    "id": "2"
}

response = await client.post(
    "http://localhost:8001/api/v1/jsonrpc",
    json=create_request
)
execution_id = response.json()["result"]["execution_id"]

# Monitor task progress via WebSocket
async with client.websocket_connect("ws://localhost:8001/ws") as ws:
    subscribe_msg = {
        "jsonrpc": "2.0",
        "method": "event.subscribe",
        "params": {
            "event_types": ["task.updated", "task.completed"],
            "filters": {"execution_id": execution_id}
        },
        "id": "3"
    }
    await ws.send_json(subscribe_msg)

    # Receive real-time updates
    async for message in ws:
        event = message.json()
        print(f"Task update: {event['event_type']}")
        if event["event_type"] == "task.completed":
            break
```

---

## 🔬 Performance Benchmarks

### Optimization Performance

- **Graph Planning**: <1s for 1000+ node workflows
- **Event Processing**: 15,000+ events/second
- **DSPy Optimization**: <5 minutes for typical prompts
- **LLM Latency**: P95 <500ms (with caching)

### Scalability

- **Concurrent Agents**: 1000+ agents per instance
- **Task Throughput**: 500+ tasks/second
- **WebSocket Connections**: 10,000+ concurrent
- **Database**: 100,000+ ops/second with PostgreSQL

### Resource Usage

- **Memory**: ~500MB baseline, scales with workload
- **CPU**: 2-4 cores typical, scales with parallelism
- **GPU** (optional): 1x GPU for DSPy acceleration

---

## 🛠️ Development

### Setting Up Development Environment

```bash
# Install development dependencies
uv sync --dev

# Run linting
uv run ruff check src/ tests/

# Auto-fix linting issues
uv run ruff check --fix src/ tests/

# Type checking
uv run mypy src/

# Run tests with coverage
uv run pytest --cov=src/agentcore --cov-report=html
```

### Code Quality Standards

- **Test Coverage**: Minimum 90% required
- **Type Safety**: Mypy strict mode enabled
- **Linting**: Ruff with project-specific rules
- **Formatting**: Black-compatible (via Ruff)
- **Documentation**: Docstrings for all public APIs

### Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes with tests
4. Ensure all tests pass (`uv run pytest`)
5. Commit your changes (`git commit -m 'feat: add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

---

## 📦 Deployment

### Kubernetes Deployment

```bash
# Apply Kubernetes manifests
kubectl apply -f k8s/

# Verify deployment
kubectl get pods -n agentcore
kubectl get svc -n agentcore

# Check logs
kubectl logs -f deployment/agentcore-api -n agentcore

# Scale deployment
kubectl scale deployment/agentcore-api --replicas=3 -n agentcore
```

### Environment Variables

```bash
# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agentcore
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=agentcore
POSTGRES_USER=agentcore
POSTGRES_PASSWORD=secure_password

# Redis
REDIS_URL=redis://localhost:6379/0
REDIS_PASSWORD=secure_password

# Security
JWT_SECRET_KEY=your-secret-key-here
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# LLM Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=AI...

# MLflow (Optional)
MLFLOW_TRACKING_URI=http://mlflow:5000
MLFLOW_EXPERIMENT_NAME=agentcore-optimization

# Monitoring
ENABLE_METRICS=true
PROMETHEUS_PORT=9090
LOG_LEVEL=INFO
```

---

## 📊 Monitoring & Observability

### Prometheus Metrics

- `agentcore_agent_count`: Number of registered agents
- `agentcore_task_count`: Total tasks by status
- `agentcore_llm_requests_total`: LLM API requests
- `agentcore_llm_latency_seconds`: LLM response latency
- `agentcore_optimization_runs_total`: DSPy optimization runs
- `agentcore_event_throughput`: Event processing rate

### Grafana Dashboards

- Agent health and activity
- Task execution metrics
- LLM usage and costs
- DSPy optimization performance
- System resource utilization

### Distributed Tracing

All requests include A2A context with:

- `trace_id`: End-to-end request tracking
- `source_agent`: Originating agent
- `target_agent`: Destination agent
- `session_id`: User session tracking
- `timestamp`: Request timestamp

---

## 🤝 Community & Support

- **GitHub Issues**: [Report bugs or request features](https://github.com/Mathews-Tom/AgentCore/issues)
- **Discussions**: [Ask questions and share ideas](https://github.com/Mathews-Tom/AgentCore/discussions)
- **Documentation**: [Full documentation](./docs/)
- **Examples**: [Sample implementations](./examples/)

---

## 📄 License

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

---

## 🙏 Acknowledgments

- **Google A2A Protocol** - Standardized agent communication
- **DSPy Framework** - Prompt optimization algorithms
- **Stanford NLP** - Research and innovation
- **FastAPI** - Modern Python web framework
- **Pydantic** - Data validation and settings management

---

## 🗺️ Roadmap

### Q4 2025

- ✅ DSPy optimization framework integration
- ✅ Multi-provider LLM gateway with cost tracking
- ✅ Production-ready deployment configurations
- 🔄 OpenEnv training environment integration (planned)

### Q1 2026

- 🔮 Parallax POC for self-hosted LLM inference
- 🔮 Enhanced monitoring and alerting
- 🔮 Advanced workflow orchestration patterns
- 🔮 Plugin marketplace for custom algorithms

### Q2-Q3 2026

- 🔮 Multi-region deployment support
- 🔮 Advanced security features (SAML, SSO)
- 🔮 Graph-based memory and knowledge management
- 🔮 Enterprise SLA guarantees

---

**Built with ❤️ by the AgentCore team**
