This directory is meant to help you move from "what is this?" to "I can ship a graph with it" without reading the whole repository.
If you are new to AgentCore, start with the path that matches what you are trying to do. The deeper reference pages are still here, but most users should not need to read them front to back on day one.
| I want to... | Start here | What you will learn |
|---|---|---|
| Build a graph from Python | Python quickstart | Install/build, define nodes, route, stream, inspect metadata, and use common agent features |
| Move an existing graph workflow | Migration guide | Import changes, callback differences, reducer support, message state, and current compatibility limits |
| Understand why the runtime behaves this way | Runtime model | State patches, scheduler behavior, checkpoints, subgraph sessions, native context-graph ranking, intelligence records, knowledge-graph state, and external graph-store boundaries |
| Understand the ideas behind the design | Design lineage | Related systems, retrieval, graph, agent-memory, reactive-matching, interoperability, and observability work |
| Connect external tools and context | MCP integration | Mirror MCP tools, consume prompts/resources, expose AgentCore as an MCP server, and generate client config |
| Connect external graph data | Graph store integration | Hydrate native knowledge from in-memory or Neo4j stores and implement other graph-store backends |
| Export traces and metrics | OpenTelemetry integration | Opt-in run/node spans, metrics, and how to keep telemetry out of the default hot path |
| Embed the runtime from C++ | C++ quickstart | Native build, ExecutionEngine, state patches, and executable examples |
| Prove a change still works | Validation guide | Smoke tests, release builds, benchmarks, wheel checks, replay gates, and suggested validation lanes |
| Check performance claims | Benchmark notes | Current measured workloads, commands, environment details, and how to rerun the comparison |
For most Python users:
- Read the first two sections of the Python quickstart.
- Run the minimal counter graph.
- Skim Message State if you are building a chat-style agent.
- Skim Assemble Context For A Node if your nodes need prompt-ready context from messages, claims, evidence, memories, knowledge triples, and state.
- Skim Hydrate Knowledge From An External Graph Store if your graph facts live in Neo4j or another graph database.
- Skim Persistent Subgraph Sessions if your workflow has reusable specialist or child-agent state.
- Use the API reference only when you need exact signatures.
For runtime or platform engineers:
- Read Runtime Model.
- Skim Design Lineage And Related Work to see which ideas map to which implementation choices.
- Run the native validation path in Validation And Benchmarks.
- Inspect the public headers under
../agentcore/include/agentcore.
- Python quickstart: the main tutorial surface.
- API reference: exact Python and C++ surfaces.
- Runtime model: execution semantics and state behavior.
- Design lineage: related work and design credit.
- MCP integration: external tool, prompt, and resource interoperability.
- Graph store integration: external graph database hydration and adapter contract.
- OpenTelemetry integration: observability setup and emitted attributes.
- Migration guide: porting existing graph-builder code.
- Validation guide: confidence checks before publishing or merging.
The docs are backed by executable material in the repository. When in doubt, the tests are the most precise examples of current behavior.
- Python graph smoke:
../python/tests/state_graph_api_smoke.py - Agent workflow smoke:
../python/tests/agent_workflows_smoke.py - MCP smoke:
../python/tests/mcp_runtime_smoke.py - OpenTelemetry smoke:
../python/tests/opentelemetry_smoke.py - Graph-store pipeline:
../python/tests/graph_store_pipeline_test.py - Optional live Neo4j graph-store check:
../python/tests/neo4j_graph_store_integration_test.py - Native planner example:
../agentcore/examples/planner_executor_graph.cpp - Native knowledge-graph example:
../agentcore/examples/knowledge_graph_workflow.cpp - Proof/replay example:
../agentcore/examples/runtime_proof_suite.cpp
The README is the front door. The quickstarts are for getting something working. The concept docs explain behavior. The reference docs are for exact signatures. The operations docs are for proving changes and reproducing measurements.
That split is deliberate: AgentCore has advanced runtime features, but users should be able to approach them in layers instead of being dropped straight into engine internals.