Metadata-Version: 2.4
Name: agenticstar-agentcore
Version: 1.0.3
Summary: AgentCore — enterprise AI agent framework, part of the AGENTIC STAR platform
Author: The AgentCore Authors
License-Expression: MIT
Project-URL: Homepage, https://agenticstar.io
Project-URL: Repository, https://github.com/teppei-miyashita/agenticstar-agentcore
Project-URL: Changelog, https://github.com/teppei-miyashita/agenticstar-agentcore/blob/main/CHANGELOG.md
Keywords: ai,agents,langgraph,langchain,enterprise,multi-agent,llm,agentic-star
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agenticstar-platform==0.5.32
Requires-Dist: langgraph==1.1.10
Requires-Dist: langchain==1.2.18
Requires-Dist: langchain-core==1.5.4
Requires-Dist: fastapi==0.136.0
Requires-Dist: uvicorn[standard]==0.46.0
Requires-Dist: httpx==0.28.1
Requires-Dist: pyjwt==2.7.0
Requires-Dist: pydantic==2.12.5
Requires-Dist: pydantic-settings==2.13.1
Requires-Dist: pyyaml==6.0.1
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: simpleeval==1.0.7
Requires-Dist: cachetools==7.1.1
Provides-Extra: anthropic
Requires-Dist: langchain-anthropic==1.4.3; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: langchain-openai==1.3.0; extra == "openai"
Provides-Extra: bedrock
Requires-Dist: langchain-aws==1.5.1; extra == "bedrock"
Provides-Extra: redis
Requires-Dist: redis==8.0.0; extra == "redis"
Provides-Extra: pinecone
Requires-Dist: pinecone-client==6.0.0; extra == "pinecone"
Provides-Extra: vault
Requires-Dist: hvac==2.4.0; extra == "vault"
Provides-Extra: aws-sm
Requires-Dist: boto3==1.34.46; extra == "aws-sm"
Provides-Extra: marketplace
Requires-Dist: agenticstar-platform[runner]==0.5.32; extra == "marketplace"
Provides-Extra: platform-db
Requires-Dist: agenticstar-platform[db]==0.5.32; extra == "platform-db"
Provides-Extra: platform-rag
Requires-Dist: agenticstar-platform[rag]==0.5.32; extra == "platform-rag"
Provides-Extra: platform-memory
Requires-Dist: agenticstar-platform[memory]==0.5.32; extra == "platform-memory"
Provides-Extra: platform-storage-azure
Requires-Dist: agenticstar-platform[storage-azure]==0.5.32; extra == "platform-storage-azure"
Provides-Extra: ns-base
Requires-Dist: langchain-anthropic==1.4.3; extra == "ns-base"
Requires-Dist: langchain-openai==1.3.0; extra == "ns-base"
Provides-Extra: ns-customer-support
Requires-Dist: langchain-anthropic==1.4.3; extra == "ns-customer-support"
Provides-Extra: ns-hr
Requires-Dist: langchain-anthropic==1.4.3; extra == "ns-hr"
Provides-Extra: ns-legal
Requires-Dist: langchain-anthropic==1.4.3; extra == "ns-legal"
Provides-Extra: all
Requires-Dist: langchain-anthropic==1.4.3; extra == "all"
Requires-Dist: langchain-openai==1.3.0; extra == "all"
Requires-Dist: langchain-aws==1.5.1; extra == "all"
Requires-Dist: pinecone-client==6.0.0; extra == "all"
Requires-Dist: redis==8.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: ruff==0.15.10; extra == "dev"
Requires-Dist: mypy==2.1.0; extra == "dev"
Requires-Dist: types-PyYAML==6.0.12.20260518; extra == "dev"
Requires-Dist: build==1.5.0; extra == "dev"
Requires-Dist: twine==6.2.0; extra == "dev"
Dynamic: license-file

# AgentCore — Part of AGENTIC STAR

> **AGENTIC STAR** is the enterprise platform for AI agent development.
> **AgentCore** is its open-source framework layer — the foundation that every agent in the platform is built on.

[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/agenticstar-agentcore)](https://pypi.org/project/agenticstar-agentcore/)

---

## What is AgentCore?

AgentCore is a **production-grade, enterprise AI agent framework** built on [LangGraph](https://github.com/langchain-ai/langgraph).
It provides a structured, opinionated foundation for building, deploying, and orchestrating AI agents at scale.

**Core problems it solves:**

- **Consistency at scale** — 1,000+ agents all follow the same architectural contract; no snowflakes
- **Security by design** — 5-layer security model (S-1 through S-5) enforced at the framework level, not by convention
- **Namespace isolation** — multi-tenant secret and environment isolation; HR keys never touch Legal agents
- **Cost visibility** — per-agent LLM cost accumulation and budget enforcement built into every invocation
- **Pluggable LLM providers** — Anthropic, OpenAI, Amazon Bedrock via optional extras; swap without rewriting agents

---

## Architecture

AgentCore uses a **4-layer architecture** — each layer has a single responsibility and dependencies flow in one direction only.

```
api/           ← Entry points (HTTP / FastAPI) — no business logic
 ↓
mediator/      ← Infrastructure: Gateway, Registry, Factory, Middleware
 ↓
agents/        ← Agent implementations (base: reusable; domain: business-specific)
 ↓
shared/        ← Cross-agent infrastructure: LLM clients, secret providers, tools
 ↓
framework/     ← Abstract core: graphs, nodes, schemas, errors — never modified directly
```

**Import rule:** dependencies are top-down only. `framework/` imports nothing above it.

### Two base graph types

| Type | Use case | Control |
|------|----------|---------|
| `AgentBaseGraph` | Structured, human-directed pipelines | Fixed 5-step: init → pre-process → execute → post-process → finalize |
| `AutonomousBaseGraph` | LLM-directed iterative loops | Think → Act → Observe → repeat (with safety ceiling) |

---

## Security Model (S-1 through S-5)

| Layer | What it enforces |
|-------|-----------------|
| **S-1** Trust Gate | `TrustLevel` (ANONYMOUS / VERIFIED_EXTERNAL / INTERNAL) checked before any node executes |
| **S-2** JWT Auth | `AuthMiddleware` validates Bearer tokens on every HTTP request |
| **S-3** Secret Isolation | `SecretProvider` / `ContextVar` runtime isolation — no cross-namespace key leakage |
| **S-4** Import Isolation | Vendor SDKs installed per-namespace as optional extras; no forced installs |
| **S-5** Budget Enforcement | Per-agent USD budget cap enforced via `CostAccumulator`; hard stop on overrun |

---

## Quick Install

```bash
# Core framework (LangGraph + FastAPI + JWT + Pydantic)
pip install agenticstar-agentcore

# With Anthropic Claude support
pip install "agenticstar-agentcore[anthropic]"

# With OpenAI support
pip install "agenticstar-agentcore[openai]"

# With Amazon Bedrock support
pip install "agenticstar-agentcore[bedrock]"

# Full install (all LLM providers + vector store + cache)
pip install "agenticstar-agentcore[all]"
```

**Requires Python 3.11+**

---

## Optional Extras

| Extra | Installs | Use case |
|-------|----------|---------|
| `anthropic` | `langchain-anthropic` | Anthropic Claude models |
| `openai` | `langchain-openai` | OpenAI GPT models |
| `bedrock` | `langchain-aws` | Amazon Bedrock models |
| `redis` | `redis` | Session state, caching |
| `pinecone` | `pinecone-client` | Vector search (RAG) |
| `vault` | `hvac` | HashiCorp Vault secret provider |
| `aws-sm` | `boto3` | AWS Secrets Manager provider |
| `all` | All LLM + vector store + cache | Full installation |

---

## Quick Start

### 1. Create a simple agent

```python
from framework.graph.agent_base_graph import AgentBaseGraph
from framework.schemas.agent_state import AgentState
from framework.nodes.base_node import BaseNode


class MyProcessNode(BaseNode):
    def execute(self, state: AgentState) -> dict:
        # Your business logic here
        return {"response": f"Processed: {state['user_input']}"}


class MyAgent(AgentBaseGraph):
    @property
    def name(self) -> str:
        return "my_agent"

    @property
    def state_schema(self) -> type:
        return AgentState

    def register_nodes(self):
        super().register_nodes()
        self._nodes["main"] = MyProcessNode()  # slot into fixed pipeline

    def get_output(self, state) -> dict:
        return {"response": state.get("response"), "status": state.get("status")}
```

### 2. Run via the mediator (HTTP)

```bash
# Set up environment
cp env/platform/.env.example env/platform/.env
# Edit .env with your LLM API keys

# Start the platform
uvicorn api.main:app --reload
```

```bash
# Call your agent
curl -X POST http://localhost:8000/agents/demo/my_agent \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"user_input": "Hello, agent!"}'
```

### 3. Direct invocation (no HTTP)

```python
from mediator.gateway.agent_gateway import AgentGateway
from framework.schemas.trust_level import TrustLevel

gateway = AgentGateway()
result = await gateway.invoke(
    agent_name="my_agent",
    user_input="Hello, agent!",
    namespace="demo",
    caller_trust_level=TrustLevel.INTERNAL,
)
print(result["response"])
```

---

## Project Structure

```
agentcore/
├── framework/        # Abstract core — graphs, nodes, schemas, errors, secrets
├── agents/
│   ├── base/         # Reusable base agents (RAGAgent, ChatAgent, ReactAgent, DocGenAgent)
│   └── domain/       # Business-specific agents (hr_chat, legal_rag, support_rag)
├── shared/           # Cross-agent: LLM clients, secret providers, tools, utilities
├── mediator/         # Infrastructure: Gateway, Registry, Factory, middleware
├── api/              # HTTP entry points (FastAPI routers, dependencies, main.py)
├── config/           # Runtime configuration (gitignored)
├── env/              # Tiered .env files (platform / namespaces / agents)
├── docs/             # Full documentation
│   ├── architecture/ # Layer-by-layer design documents
│   ├── adr/          # Architecture Decision Records
│   └── api/          # HTTP API layer documents
└── tests/            # Unit and integration tests
```

---

## Full Documentation

| Topic | Location |
|-------|----------|
| Platform overview | [docs/architecture/multi_agent_platform.md](docs/architecture/multi_agent_platform.md) |
| Framework layer | [docs/architecture/framework_layer_design.md](docs/architecture/framework_layer_design.md) |
| Agents layer | [docs/architecture/agents_layer_design.md](docs/architecture/agents_layer_design.md) |
| Mediator layer | [docs/architecture/mediator_layer_design.md](docs/architecture/mediator_layer_design.md) |
| Shared layer | [docs/architecture/shared_layer_design.md](docs/architecture/shared_layer_design.md) |
| AutonomousBaseGraph | [docs/architecture/autonomous_base_graph.md](docs/architecture/autonomous_base_graph.md) |
| HTTP API design | [docs/api/routers_design.md](docs/api/routers_design.md) |
| ADR index | [docs/adr/README.md](docs/adr/README.md) |
| Environment / pyproject tiered isolation | [docs/env-pyproject.md](docs/env-pyproject.md) |
| Setup guide | [SETUP.md](SETUP.md) |

---

## Testing

Tests are organized by type under `tests/`:

```
tests/
├── unit/          # node classes, services, schemas in isolation
│   ├── agents/    # per-agent unit tests (base/ and domain/)
│   └── shared/    # shared utilities and services
├── integration/   # full graph invocations (no external calls)
├── e2e/           # HTTP-level end-to-end via FastAPI TestClient
└── fixtures/      # reusable test agents (HITL stubs)
```

Run the full suite:

```bash
pytest                                                              # all tests
pytest --cov=framework --cov=mediator --cov=agents --cov=shared   # with coverage
pytest tests/unit/agents/base/chat_agent/                          # one agent (unit)
pytest tests/integration/agents/domain/hr_chat/                    # one agent (integration)
pytest -k "unit"                                                   # unit only
pytest -k "integration"                                            # integration only
```

---

## Requirements

- **Python:** 3.11 or higher
- **Core dependencies:** LangGraph ≥ 0.2, LangChain ≥ 0.3, FastAPI ≥ 0.115, Pydantic ≥ 2.9
- **LLM provider:** at least one of `[anthropic]`, `[openai]`, `[bedrock]` extras

---

## License

[MIT](LICENSE) — Copyright (c) 2026 The AgentCore Authors
