Metadata-Version: 2.4
Name: agentcore-sdk
Version: 0.1.1
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: AGPL-3.0
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 :: GNU Affero General Public License v3
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 orchestration framework for agentic AI systems implementing Google's A2A (Agent-to-Agent) protocol v0.2.

[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue)](./LICENSE)
[![Tests](https://img.shields.io/badge/tests-8000%2B-brightgreen)](./tests)

---

## Features

### A2A Protocol Implementation

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

### Agent Runtime

- **Chain-of-Thought (CoT)** reasoning engine
- **ReAct** pattern for iterative reasoning and action
- **Autonomous execution** mode for complex multi-step tasks
- **Multi-tool integration** with API connectors, code execution, and file operations
- **Plugin system** with version management and validation
- **State persistence** with backup and recovery
- **Sandbox execution** with security profiles

### Memory Service

- **Hierarchical memory** with working, episodic, and semantic layers
- **Entity-Centric Learning (ECL)** pipeline for knowledge extraction
- **Graph-based memory** with Neo4j integration
- **Hybrid search** combining vector similarity and graph traversal
- **MEMify optimization** for memory consolidation and pruning
- **Context compression** and expansion for efficient token usage

### LLM Client Service

- **Multi-provider support**: OpenAI, Anthropic, Google Gemini
- **Intelligent model selection** based on task requirements
- **Automatic failover** with provider health monitoring
- **Cost tracking** and budget management
- **Response caching** for optimization

### ACE (Adaptive Capability Engine)

- **Performance monitoring** with baseline tracking
- **Capability evaluation** and fitness scoring
- **Intervention engine** with trigger-based decisions
- **Playbook management** for automated responses
- **Delta generation** for capability improvements

### DSPy Optimization

- **MIPROv2** and **GEPA** optimization algorithms
- **MLflow integration** for experiment tracking
- **A/B testing framework** for prompt variants
- **Continuous learning** with drift detection
- **GPU acceleration** support

### Coordination Service

- **Multi-agent coordination** with consensus protocols
- **Workflow orchestration** with graph-based execution
- **CQRS pattern** with event sourcing
- **Saga pattern** for distributed transactions
- **Parallel execution** with dependency resolution

### Integration Layer

- **Cloud storage**: S3, GCS, Azure Blob
- **Database connectors**: PostgreSQL with async support
- **Webhook management** with delivery tracking
- **Resilience patterns**: Circuit breaker, bulkhead, timeout
- **Security**: Credential management, compliance scanning

### Training System

- **GRPO** (Group Relative Policy Optimization)
- **Trajectory recording** and replay
- **Custom reward registry**
- **Credit assignment** algorithms
- **Job management** with budget controls

### CLI

- **4-layer architecture**: CLI, Service, Protocol, Transport
- **Agent management**: register, list, info, remove
- **Task operations**: create, list, status tracking
- **Session management**: create, list, pause
- **Workflow control**: start, monitor, manage
- **Configuration**: show, set, validate

---

## Quick Start

### Prerequisites

- Python 3.12+
- PostgreSQL 14+
- Redis 7+
- Neo4j 5+ (optional, for graph memory)

### 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
cp .env.test.template .env
```

### Running with Docker Compose

```bash
# Start all services
docker compose -f docker-compose.dev.yml up

# API available at http://localhost:8001
# API docs at http://localhost:8001/docs
```

### Running Locally

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

# Apply 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
```

### CLI Usage

```bash
# Register an agent
agentcore agent register --name "my-agent" --capabilities "text_generation,analysis"

# List agents
agentcore agent list

# Create a task
agentcore task create --description "Analyze customer feedback"

# Start a session
agentcore session create --name "analysis-session"
```

---

## Architecture

```plaintext
src/agentcore/
├── a2a_protocol/          # A2A protocol implementation
│   ├── models/            # Pydantic models (AgentCard, Task, Event)
│   ├── services/          # Business logic and JSON-RPC handlers
│   ├── routers/           # FastAPI endpoints
│   └── database/          # PostgreSQL models and repositories
│
├── agent_runtime/         # Agent execution engine
│   ├── engines/           # CoT, ReAct, Autonomous engines
│   ├── services/          # Lifecycle, tools, state management
│   └── tools/             # Built-in and custom tool support
│
├── ace/                   # Adaptive Capability Engine
│   ├── capability/        # Evaluation and scoring
│   ├── intervention/      # Trigger-based decisions
│   └── monitors/          # Performance tracking
│
├── dspy_optimization/     # DSPy optimization framework
│   ├── algorithms/        # MIPROv2, GEPA
│   ├── learning/          # Continuous learning, drift detection
│   └── tracking/          # MLflow integration
│
├── gateway/               # API gateway services
├── integration/           # External service integrations
├── orchestration/         # Workflow orchestration (CQRS, Saga)
├── reasoning/             # Reasoning strategies
└── training/              # RL training system

src/agentcore_cli/         # Command-line interface
├── commands/              # CLI command handlers
├── services/              # Service layer
├── protocol/              # JSON-RPC client
└── transport/             # HTTP transport
```

---

## Testing

```bash
# Run all tests
uv run pytest

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

# Run specific test categories
uv run pytest tests/unit/
uv run pytest tests/integration/
uv run pytest tests/cli/

# Load testing
uv run locust -f tests/load/locustfile.py
```

---

## Development

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

# Run linter
uv run ruff check src/ tests/

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

# Type checking
uv run mypy src/
```

### Database Migrations

```bash
# Create migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head

# Rollback
uv run alembic downgrade -1
```

---

## Configuration

All settings via environment variables or `.env`:

```bash
# Database
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/agentcore

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

# Security
JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256

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

# Monitoring
ENABLE_METRICS=true
LOG_LEVEL=INFO
```

---

## Documentation

- [API Reference](./docs/api/) - JSON-RPC method specifications
- [Architecture](./docs/architecture/) - System design documents
- [CLI Reference](./docs/cli/) - Command-line interface guide
- [Deployment](./docs/deployment/) - Production deployment guides
- [Security](./docs/security/) - Security audit and compliance

---

## License

AGPL-3.0 License - see [LICENSE](./LICENSE) for details.
