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.

---

What is AgentCore?

AgentCore is a production-grade, enterprise AI agent framework built on 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

# 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

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)

# 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

# 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)

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
Framework layer	docs/architecture/framework_layer_design.md
Agents layer	docs/architecture/agents_layer_design.md
Mediator layer	docs/architecture/mediator_layer_design.md
Shared layer	docs/architecture/shared_layer_design.md
AutonomousBaseGraph	docs/architecture/autonomous_base_graph.md
HTTP API design	docs/api/routers_design.md
ADR index	docs/adr/README.md
Environment / pyproject tiered isolation	docs/env-pyproject.md
Setup guide	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:

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 — Copyright (c) 2026 The AgentCore Authors