agentcore-graph 0.1.12

Native agent-graph runtime with C++ execution, explicit state patches, resumable checkpoints, and Python bindings.

AgentCore

Native agent graphs for fast, inspectable, long-running workflows.

AgentCore is a C++20 agent-graph runtime with a compact Python API for stateful workflows, persistent subgraphs, structured memory, graph-store hydration, replay, MCP interoperability, and OpenTelemetry.

Install · Quick Start · Python Guide · API Reference · Benchmarks · Docs

AgentCore is designed for graph-shaped agent systems where latency, durability, and state visibility matter at the same time. The runtime keeps graph execution native, makes state mutation explicit through patches, and records checkpoints and traces from the same execution path used by normal runs.

The Python surface is intentionally familiar: define a StateGraph, add nodes and edges, compile it, and invoke it. The difference is underneath. Graph metadata, state commits, scheduling, checkpointing, message merging, persistent subgraph sessions, knowledge-graph reads, and supported intelligence/context queries run through the native runtime instead of being rebuilt in Python at each step.

AgentCore is an independent project. It is not affiliated with Amazon Web Services, AWS AgentCore, or any related AWS-branded product or service.

Start Here

Use it from Python	Install, then follow the quick start or the full Python guide.
Migrate graph code	Use the migration guide for builder patterns, reducers, message state, and current compatibility notes.
Understand the runtime	Read the runtime model for state patches, scheduler behavior, checkpointing, sessions, intelligence records, and knowledge-graph state.
Integrate with tools	See MCP, graph stores, OpenTelemetry, and the API reference.
Validate performance	Use the validation guide and current benchmark notes.

Why This Exists

Many agent workflows start simple and then become expensive in the wrong places: message history grows, branches join, tools wait, subgraphs need memory, and replay becomes a separate problem from execution. AgentCore tries to keep those concerns in one runtime model.

The core design choices are:

• compiled graph metadata instead of ad hoc per-step graph interpretation
• explicit state patches instead of hidden shared mutation
• typed hot state plus blob references for larger payloads
• deterministic commit ordering for branches, joins, checkpoints, and replay
• persistent child sessions for reusable subgraphs without shared mutable child state
• native knowledge-graph and intelligence records for workflows that need structured context
• opt-in observability and durability profiles so metadata does not always dominate the hot path

This does not make AgentCore a planner, prompt framework, vector database, or agent marketplace. It is the execution layer those pieces can sit on.

Install

python3 -m pip install agentcore-graph

The package published to PyPI is agentcore-graph; the Python import package is agentcore.

For OpenTelemetry dependencies:

python3 -m pip install "agentcore-graph[otel]"

For optional Neo4j graph-store support:

python3 -m pip install "agentcore-graph[neo4j]"

The package also installs MCP helper commands:

agentcore-mcp
agentcore-mcp-server
agentcore-mcp-config

Current published wheels target Linux x86_64 for CPython 3.9 through 3.12. Source builds remain available from this repository.

Quick Start

from agentcore.graph import END, START, StateGraph


def step(state, config):
    return {"count": int(state.get("count", 0)) + 1}


def route(state, config):
    return END if state["count"] >= 3 else "step"


graph = StateGraph(dict, name="counter", worker_count=2)
graph.add_node("step", step)
graph.add_edge(START, "step")
graph.add_conditional_edges("step", route, {END: END, "step": "step"})

compiled = graph.compile()
final_state = compiled.invoke({"count": 0})
print(final_state["count"])

From the same compiled graph you can also stream events, inspect metadata, pause and resume, register tools and models, mirror MCP tools, emit OpenTelemetry spans, and compose persistent subgraphs.

Useful next reads:

• Python quickstart
• API reference
• Runtime model

What Is Implemented

AgentCore currently includes:

• native C++ runtime with Python bindings
• StateGraph-style Python builder with conditional edges, joins, subgraphs, streaming, batch execution, and pause/resume
• native join reducers for list concatenation and ID-aware message history merging
• multi-worker scheduling with async wait handling
• checkpointing, trace events, proof digests, and replay-oriented metadata
• persistent subgraph sessions with isolated child state and deterministic session revisions
• structured intelligence state for tasks, claims, evidence, decisions, and memories
• graph-native context assembly from messages, intelligence records, native knowledge-graph triples, and state fields, with a native context-graph ranking path for intelligence and knowledge selectors
• knowledge-graph-backed state and reactive execution hooks
• external graph-store hydration with an in-memory reference backend and optional Neo4j adapter
• deterministic memoization for supported pure nodes
• prompt templates for text, chat, and MCP-rendered prompts
• tool and model registries with built-in HTTP JSON, SQLite-style, local model, OpenAI-compatible, xAI Grok, and Gemini adapters
• MCP over stdio, including tools, prompts, resources, completions, roots, sampling, elicitation, logging, subscriptions, and installable MCP server launchers
• opt-in OpenTelemetry spans and metrics
• native and Python benchmark and smoke-test coverage

Core Python Features

Message State

Agent workflows often keep conversation history in a messages field. AgentCore exposes MessagesState and add_messages so message joins can run in the native merge path: messages with matching non-empty id values replace earlier messages in place, while messages without ids append.

from agentcore.graph import MessagesState, StateGraph


class AgentState(MessagesState, total=False):
    summary: str


graph = StateGraph(AgentState, name="agent", worker_count=4)

See the Python quickstart and API reference.

Persistent Subgraphs

Persistent subgraph sessions let the same child graph run across many session_id values with isolated child state, checkpoints, task journal, knowledge graph, and stream metadata. Distinct sessions can run concurrently; concurrent reuse of the same session is rejected deterministically.

See the runtime model and Python quickstart.

Context Assembly

Nodes can declare a ContextSpec and then call runtime.context.view() to assemble a deterministic context view from message history, intelligence records, native knowledge-graph triples, selected state fields, and optional graph-shaped state carried by the workflow. For intelligence and knowledge selectors, AgentCore compiles the request into a native context-graph query plan, ranks connected task/claim/evidence/decision/memory/triple records with deterministic activation scoring, and returns a kind-balanced top-k. The Python context graph remains as a compatibility fallback and as the final merge layer when a view also includes message or arbitrary state selectors.

The returned ContextView includes citations, provenance, budget stats, conflict metadata, prompt/message rendering helpers, and a stable digest that is surfaced through invoke_with_metadata(...).

from agentcore.graph import ContextSpec


graph.add_node(
    "answer",
    answer,
    context=ContextSpec(
        goal_key="question",
        include=["messages.recent", "claims.supported", "evidence.relevant"],
        budget_tokens=2400,
        require_citations=True,
    ),
)


def answer(state, config, runtime):
    context = runtime.context.view()
    prompt = context.to_prompt(system="Answer using cited evidence.")
    result = runtime.invoke_model("default", prompt, decode="text")
    return {"answer": result, "context_digest": context.digest}

See the Python quickstart and runtime model.

Intelligence State

The intelligence layer stores operational records inside runtime state:

• tasks
• claims
• evidence
• decisions
• memories

Python nodes use runtime.intelligence to write and query those records. The records participate in normal patch commits, checkpoints, replay, and persistent subgraph sessions.

def analyze(state, config, runtime):
    runtime.intelligence.upsert_task(
        "triage",
        title="Triage incoming request",
        owner="planner",
        status="in_progress",
        priority=5,
    )
    runtime.intelligence.upsert_claim(
        "needs-followup",
        subject="request",
        relation="requires",
        object="followup",
        confidence=0.72,
    )
    next_task = runtime.intelligence.next_task(owner="planner")
    return {"next_task": None if next_task is None else next_task["key"]}

See the runtime model and Python guide.

External Graph Stores

Native knowledge-graph state is useful during execution because it participates in patches, checkpoints, context assembly, and replay. When the source of truth lives elsewhere, AgentCore lets a node explicitly hydrate runtime knowledge from a registered graph store, then optionally sync selected runtime triples back out.

from agentcore.graph import END, START, StateGraph


def retrieve(state, config, runtime):
    loaded = runtime.knowledge.load_neighborhood(
        "Incident",
        store="ops_graph",
        depth=2,
        limit=20,
    )
    return {"loaded_triples": len(loaded["triples"])}


graph = StateGraph(dict, name="ops_graph_demo")
graph.add_node("retrieve", retrieve)
graph.add_edge(START, "retrieve")
graph.add_edge("retrieve", END)

compiled = graph.compile()
compiled.graph_stores.register_memory(
    "ops_graph",
    triples=[("Incident", "affects", "checkout API")],
)

The first shipped backends are InMemoryGraphStore and Neo4jGraphStore. The connector contract is intentionally entity/triple/neighborhood based so other graph databases can implement the same surface without changing the runtime.

The Neo4j adapter has an optional live Docker validation path in addition to the default dependency-free graph-store smoke test. That path exercises batch writes, neighborhood reads, filtered queries, runtime hydration, context assembly, and sync-back persistence against a real Neo4j process.

See the graph-store integration guide, Python guide, and runtime model.

MCP Interoperability

AgentCore can consume MCP servers and expose AgentCore-owned tools, prompts, resources, and graph surfaces through MCP.

compiled.tools.register_mcp_stdio(
    ["python3", "./my_mcp_server.py"],
    prefix="remote",
)

Installed helper commands can also produce client configuration snippets for common MCP clients:

agentcore-mcp-config claude --name local-agentcore --target ./server.py:build_server
agentcore-mcp-config codex --name local-agentcore --target ./server.py:build_server
agentcore-mcp-config gemini --name local-agentcore --target ./server.py:build_server

See the MCP integration guide.

OpenTelemetry

Telemetry is opt-in. Passing telemetry=True or an OpenTelemetryObserver emits run spans, optional node spans, and run/node metrics using the Python OpenTelemetry API.

from agentcore.observability import OpenTelemetryObserver


observer = OpenTelemetryObserver()
details = compiled.invoke_with_metadata({"count": 0}, telemetry=observer)

See the OpenTelemetry guide.

Performance

AgentCore's performance work is focused on native graph execution, branch/join overhead, persistent subgraph sessions, resume behavior, context retrieval, and structured state operations. Current benchmark snapshots and exact reproduction commands live in the comparison document and the validation guide.

The latest snapshot in this repository was generated on April 22, 2026. On that machine and workload set, AgentCore's compatibility surface was about 2.22x to 3.01x faster on the same-code builder path, while native persistent-session workloads were about 2.50x to 13.11x faster with lower measured memory use. Treat those as workload-specific measurements, not universal claims.

The native context graph path is tracked separately because it is not a direct head-to-head framework benchmark. In the current Release validation run, the native C++ context graph benchmark selected 24 records from a 1,024-record intelligence/knowledge workload with context_graph_cold_rank_ns=454200 and cached warm selection at context_graph_warm_rank_avg_ns=52. Through the Python API benchmark, runtime.context.view() measured 567840 ns warm average on the native-backed path, while the retained Python graph-ranker path measured 9231312 ns on the same benchmark selector set.

For local validation, start with:

ctest --test-dir build --output-on-failure
python3 python/benchmarks/langgraph_head_to_head.py

See the validation guide for release, sanitizer, replay, and benchmark commands.

Related Ideas And Papers

AgentCore is an implementation project, not a research paper. Its design is influenced by several lines of work and industry practice:

• Context graphs argue that production agents need durable, connected decision context rather than only chat history. AgentCore's intelligence records and knowledge-graph state are a runtime substrate for that style of workflow, with explicit commits and replay.
• ReAct frames agents as interleaved reasoning and action. In AgentCore, that loop is represented as graph structure, node outputs, tool/model calls, and inspectable state transitions.
• Reflexion explores feedback and memory for language agents. AgentCore's memories, decisions, evidence, and persistent sessions give applications a structured place to store those artifacts.
• Retrieval-Augmented Generation and GraphRAG motivate external knowledge and graph-shaped retrieval. AgentCore does not replace a retrieval system, but it can carry retrieved evidence, claims, and graph memory through a deterministic workflow.
• Pregel and Apache Beam inform the broader design language around graph execution, deterministic progress, durable state, and replayable dataflow.

Build From Source

For a normal local build:

cmake -S . -B build
cmake --build build -j
ctest --test-dir build --output-on-failure

For optimized validation and benchmarks:

cmake --preset release-perf
cmake --build --preset release-perf -j
ctest --preset release-perf
./build/release-perf/agentcore_runtime_benchmark
./build/release-perf/agentcore_persistent_subgraph_session_benchmark

The repository also includes relwithdebinfo-perf, asan, ubsan, and tsan presets.

Documentation Map

The main docs index is docs/README.md.

Area	Document
Python workflow authoring	docs/quickstarts/python.md
Native C++ embedding	docs/quickstarts/cpp.md
Runtime semantics	docs/concepts/runtime-model.md
Python and C++ API surface	docs/reference/api.md
MCP integration	docs/integrations/mcp.md
Graph stores	docs/integrations/graph-stores.md
OpenTelemetry	docs/integrations/opentelemetry.md
Migration notes	docs/migration/langgraph-to-agentcore.md
Validation and benchmarks	docs/operations/validation.md
Head-to-head benchmark notes	docs/comparisons/langgraph-head-to-head.md

Repository Map

• agentcore/include and agentcore/src: native runtime
• agentcore/adapters: built-in tool and model adapters
• agentcore/tests and agentcore/benchmarks: native tests and benchmark entry points
• python/agentcore: Python package layered over the native module
• python/tests and python/benchmarks: Python smoke tests and benchmark entry points
• docs: guides, concepts, reference material, migration notes, and validation docs
• assets: README and documentation images

Acknowledgements

AgentCore is independent and is not affiliated with or endorsed by LangChain Inc.

I am grateful to the projects and ideas that helped clarify the design space for graph-oriented agent runtimes:

• LangGraph and its documentation for making graph-based agent orchestration concrete and accessible
• NetworkX for graph-first modeling vocabulary
• Model Context Protocol for a practical interoperability layer for tools, prompts, and resources
• OpenTelemetry for the standard observability vocabulary AgentCore plugs into

License

This repository is licensed under the MIT License. See LICENSE and NOTICE.