AgentGraph Core
AgentGraph Core is a small Python runtime foundation for building observable, human-in-the-loop agent systems.
It provides shared backend primitives for projects that need transparent agent execution, tool auditing, scheduled runs, human review, artifact tracking, and evidence-based knowledge promotion.
Core idea
application UI / API adapter
-> agentgraph-core
-> agent profile
-> graph definition
-> tool registry
-> run lifecycle
-> event stream
-> artifact index
-> human gate
-> schedule
-> knowledge ledger
-> application-specific tools and state authority
Applications keep their own product shape, domain models, and storage authority. AgentGraph Core provides the common runtime contract.
Included
AgentProfile: agent identity, responsibility, model, and knowledge boundary.GraphDefinition: product-visible nodes, edges, and conditional routing contract.ToolDefinition/ToolExecution: tool registry, enable/disable, risk, approval, and execution status.AgentRun: lifecycle, current node, heartbeat, retry, and failure metadata.AgentEvent: frontend-visible event stream.RunArtifact: index for generated artifacts without forcing large payloads into SQLite.HumanGateReview: approve / reject / edit / score / need-more-data gate.KnowledgeRecord/KnowledgeEvidence: candidate -> stable -> rejected ledger.ScheduledJob: manual / cron / event trigger model.SQLiteStore: small deployable persistence layer.build_runtime_graph(...): LangGraph adapter for registered graph definitions.
Excluded
- No frontend.
- No product-specific domain models.
- No product-specific terminology.
- No requirement to replace an application's existing file authority or database.
Install for development
python -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
pytest -q
Minimal graph
from agentgraph_core import AgentRun, GraphRuntimeSpec, RunStatus, build_runtime_graph, default_entry_node
from examples.catalog.demo_catalog import GRAPH
from examples.demo_runtime import NODE_HANDLERS, ROUTE_HANDLERS
spec = GraphRuntimeSpec(
definition=GRAPH,
entry_node_id=default_entry_node(GRAPH),
node_handlers=NODE_HANDLERS,
route_handlers=ROUTE_HANDLERS,
)
compiled = build_runtime_graph(spec)
result = compiled.invoke({
"payload": {
"run": AgentRun(agent_id="content-operator", graph_id=GRAPH.id, status=RunStatus.running),
"topic": "demo",
"sources": ["demo://source"],
"auto_approve": True,
}
})
Tool registry example
from agentgraph_core import ToolRegistry
from agentgraph_core.models import ToolDefinition, ToolRisk, ToolExecutionRequest
registry = ToolRegistry(
tools=[ToolDefinition(id="echo", name="Echo", description="Echo input", risk=ToolRisk.read)],
handlers={"echo": lambda payload: {"echo": payload}},
)
execution = registry.create_execution(ToolExecutionRequest(tool_id="echo", input={"hello": "world"}))
assert execution.status == "succeeded"
Persistence
Default SQLite path:
data/agentgraph.sqlite3
Override:
AGENTGRAPH_DB_PATH=/path/to/agentgraph.sqlite3
SQLiteStore stores the full run JSON snapshot and mirrors events, artifacts, human decisions, tool executions, knowledge, schedules, and registry definitions into queryable tables.
Application integration pattern
application UI
-> application API adapter
-> agentgraph-core run/event/artifact/human-gate/knowledge layer
-> application-specific tools
-> application-specific state authority
Typical integrations keep large generated content, domain state, or external records in their existing storage system, while using AgentGraph Core for operational visibility and control-plane state.
Development checks
pytest -q
python -m compileall agentgraph_core examples tests
Metadata
Release files for agentgraph-core 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentgraph_core-0.1.0.tar.gz | 18.0 kB | Without provenance | Details for agentgraph_core-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentgraph_core-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agentgraph_core-0.1.0-py3-none-any.whl |
Total release size: 34.5 kB
Release files / agentgraph_core-0.1.0.tar.gz
| Download URL | agentgraph_core-0.1.0.tar.gz |
|---|---|
| Size | 18.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a4f036e6018d81bbfc9a1a6026a841c541674bdd0355538ec776d3e4f9df513a
|
|
BLAKE2b-256 checksum How to use checksums |
fcdd3440b3640d770966a57bb9ad55f3b6d197a6d3d93e9660016ac92d96c0b0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Release files / agentgraph_core-0.1.0-py3-none-any.whl
| Download URL | agentgraph_core-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
613a61965c3549c10dceac8f0a393e214bfd4f6dbae4aa55cffeebdf8f4d2fc4
|
|
BLAKE2b-256 checksum How to use checksums |
a0aa3229eb2e23a521d4c53beddb64461b2dd896108c7fb07e4309f388218202
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.2
|
Security for agentgraph-core 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.