Skip to main content

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)

Source distribution for agentgraph-core 0.1.0
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)

Table of built distributions (wheels) for agentgraph-core 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page