# AgenticGraph

> AgenticGraph gives Laravel a native graph execution model for AI work. Nodes do the work, edges decide where execution goes, and shared state carries the run forward. Packages: core (agenticgraph/agenticgraph), the stream client (npm), and vector (agenticgraph/vector).

## Core

- [Overview](https://agenticgraph.dev/docs/overview.md): AgenticGraph gives Laravel a native graph execution model for AI work: nodes do the work, edges route it, and shared state carries the run.
- [Getting Started](https://agenticgraph.dev/docs/getting-started.md): Install agenticgraph/agenticgraph, publish config and migrations, migrate, set the env basics, and run your first graph with AgenticGraph::run.
- [Graphs](https://agenticgraph.dev/docs/graph.md): Connect nodes, edges, and state into a graph you can route, loop, pause, and execute in Laravel.
- [Execution](https://agenticgraph.dev/docs/execution.md): Follow the coordinator as it moves through nodes, carries state, handles interrupts, and runs sync, async, or streaming executions.
- [State](https://agenticgraph.dev/docs/state.md): Learn how AgenticGraph State carries immutable data between nodes, accumulates writes, and becomes a durable checkpoint snapshot.
- [Nodes](https://agenticgraph.dev/docs/nodes.md): A node is one job: state in, work, new state out. It does not pick the next hop. AbstractNode is PHP. PrismNode is language.
- [Prompt templates](https://agenticgraph.dev/docs/prompts.md): Prompt templates fill {word} placeholders through one interpolator. llm()->prompt() takes a string or a template; inline content is never interpolated.
- [MCP](https://agenticgraph.dev/docs/mcp.md): mcp() asks Relay for an MCP server's tools and adds them to the same request path as tools(). run() returns the text, tool calls and results.
- [Edges](https://agenticgraph.dev/docs/edges.md): An edge is a hop: after this node, go there. Direct, a decision, several later, or fan-out and join. Nodes do not pick the next name.
- [Cyclic graphs](https://agenticgraph.dev/docs/cyclic.md): A cycle is an edge to a node that already ran. Declare nothing special, but give it a real exit: a count in the router, with a runtime backstop.
- [Routing](https://agenticgraph.dev/docs/routing.md): A router reads state and returns a node name, or several to run together. Use PHP when you can name the hop, PrismRouter when the hop is language.
- [Parallel execution](https://agenticgraph.dev/docs/parallel.md): A router can return several node ids. Each branch starts from the same snapshot and writes its own keys; addJoin waits and merges them.
- [Interruptions](https://agenticgraph.dev/docs/interrupts.md): A PrismNode can ask the coordinator to wait before it runs. The handle comes back interrupted. Resume writes the human input and continues from the checkpoint.
- [Streaming](https://agenticgraph.dev/docs/streaming.md): Streaming is the execute loop with events leaving as nodes run: stream() is async SSE, broadcast() is a websocket, and prompt() emits text_delta.
- [Tracing](https://agenticgraph.dev/docs/tracing.md): Turn tracing on, pick a driver (AgenticPulse, log, file, OTLP), and read the span tree for a run. Traces are sent synchronously; no queue worker needed.
- [Checkpoints](https://agenticgraph.dev/docs/checkpoints.md): Checkpoints snapshot the node and state after each node and before an interrupt gate, so a run can resume from the same store after a deploy.

## Core › API reference

- [Graph](https://agenticgraph.dev/docs/api/graph.md): API reference for GraphBuilder, Graph, and AgenticGraph registry methods. Assemble, validate, and look up a graph.
- [Execution](https://agenticgraph.dev/docs/api/execution.md): API reference for AgenticGraph::execute, ExecutionOptions, and ExecutionHandle. Start a run, wait, resume, or replay a stream.
- [State](https://agenticgraph.dev/docs/api/state.md): API reference for Shahzad\AgenticGraph\State\State. Final immutable StateContract: get, set, merge, toStoragePayload, and interrupt helpers.
- [Nodes](https://agenticgraph.dev/docs/api/nodes.md): API reference for NodeInterface, AbstractNode, and PrismNode. Execute, retries, hooks, and Prism helpers.
- [Prompts](https://agenticgraph.dev/docs/api/prompts.md): API reference for PromptTemplate, ChatPromptTemplate, prompt files (Prompts::get), TemplateInterpolator, and PrismNode prompt helpers.
- [MCP](https://agenticgraph.dev/docs/api/mcp.md): API reference for mcp() on the LLM request: Relay server names, tool choice, maxSteps, and the LlmResponse it returns.
- [Streaming](https://agenticgraph.dev/docs/api/streaming.md): API reference for AgenticGraph stream and broadcast, StreamDescriptor, StreamEvent, the frozen wire envelope, and the SSE store route.
- [Tracing](https://agenticgraph.dev/docs/api/tracing.md): API reference for Trace::span, TraceContext accessors, and tracing config. AgenticPulse, log, file, and OTLP/HTTP JSON exporters, capture depth.

## Core › Guides

- [Testing](https://agenticgraph.dev/docs/guide-testing.md): Test nodes with State. Fake the model with Llm::fake(). Run graphs with AgenticGraph::run(). stream() returns a descriptor. The iterator is inline.
- [Middleware](https://agenticgraph.dev/docs/guide-middleware.md): Node middleware is a config onion around execute: handle($state, $node, $next). The default stack is logging, timing and validation; retries sit inside.
- [Lifecycle events](https://agenticgraph.dev/docs/guide-events.md): Laravel lifecycle events are not stream events or traces. Listen with Event::listen for GraphExecutionFailed, TokensUsed and InterruptPending.
- [Prompt files](https://agenticgraph.dev/docs/guide-prompt-files.md): Prompt files are Markdown with front matter in resources/prompts. Prompts::get('name') returns a ChatPromptTemplate; agenticgraph:prompts validates every file.
- [CLI](https://agenticgraph.dev/docs/guide-cli.md): php artisan agenticgraph:execute runs a graph synchronously and prints State JSON. Visualize outputs Mermaid only; there is no agenticgraph:install.
- [Troubleshooting](https://agenticgraph.dev/docs/guide-troubleshooting.md): Common failure symptoms, likely causes and concrete fixes for state, execution, checkpoints, parallel branches and tracing in AgenticGraph.

## Stream

- [Getting started](https://agenticgraph.dev/docs/stream-getting-started.md): Install the AgenticGraph JS/TS stream client, pick Echo or SSE, connect, and consume events.
- [Core](https://agenticgraph.dev/docs/stream-core.md): AgenticStream, transports, event consumption, status, interrupts, and selectors.
- [React](https://agenticgraph.dev/docs/stream-react.md): useAgenticStream, useStreamSelector, and the HITL flow in React.
- [Vue](https://agenticgraph.dev/docs/stream-vue.md): useAgenticStream composable, useStreamSelector, and the HITL flow in Vue 3.
- [Transports](https://agenticgraph.dev/docs/stream-transports.md): Broadcast vs SSE delivery, infrastructure requirements, and when to use each.
- [Limitations](https://agenticgraph.dev/docs/stream-limitations.md): Connection lifecycle, replay, reconnect, rendering cadence, and security constraints.

## Vector

- [Overview](https://agenticgraph.dev/docs/vector-overview.md): agenticgraph-vector stores documents, embeds text, and returns similar hits. It does not generate answers or build prompts.
- [Installation](https://agenticgraph.dev/docs/vector-installation.md): Install agenticgraph/vector, enable pgvector on a dedicated Postgres connection, set VECTOR_DB_CONNECTION, then healthCheck().
- [Quick start](https://agenticgraph.dev/docs/vector-quick-start.md): Create a collection, upsert documents (auto-embed), similarTo → take → get, then toContext(). Filter, minScore, and usingVector are optional.
- [Configuration](https://agenticgraph.dev/docs/vector-configuration.md): vector.stores.pgvector.connection is VECTOR_DB_CONNECTION. Embeddings use Prism with the provider and model you set (no default). Events are not trace spans.
- [Limitations](https://agenticgraph.dev/docs/vector-limitations.md): The first resolved store is kept per request, pgvector must be installed, and dimensions, metric and index cannot be altered. fetch() scores are always 1.0.

## Vector › Guides

- [Building RAG](https://agenticgraph.dev/docs/vector-guide-building-rag.md): Retrieve with similarTo, pass the hits to a PrismNode with context(), generate, and cite the sources. RAG is your pattern; the package only retrieves.
- [Batch ingestion](https://agenticgraph.dev/docs/vector-guide-batch-ingestion.md): Chunk upserts with batchSize, report onProgress after each chunk, attach a precomputed vector to skip embed, or call embedBatch yourself.
- [Queued ingest](https://agenticgraph.dev/docs/vector-guide-queued-ingest.md): Ingest thousands of documents in the background with ->queue()->upsert(): one job per batch, retries with backoff, events and vector:ingest:resume.
- [Chunking long documents](https://agenticgraph.dev/docs/vector-guide-chunking.md): Split long documents with TextSplitter, store the chunks with upsertChunks(), search with collapse('parent_id') for one hit per document, and cite the parent.
- [Score ergonomics](https://agenticgraph.dev/docs/vector-guide-score-ergonomics.md): Cosine scores are 1 - distance, on [-1, 1]. There is no universal minScore: calibrate one on a small golden set with a threshold sweep.
- [Tracing integration](https://agenticgraph.dev/docs/vector-guide-tracing-integration.md): Package events always fire when enabled. A vector.search span exists only inside a traced graph node, and its attributes are counts, not query text.
- [Changing the embedding model](https://agenticgraph.dev/docs/vector-guide-changing-embedding-model.md): Add a second embedding provider, dry-run, then run vector:migrate. Documents are re-embedded into a new collection and the alias switches in one transaction.
- [Hybrid search](https://agenticgraph.dev/docs/vector-guide-hybrid-search.md): Enable keyword search on a collection, then ->hybrid() fuses vector and full text results. Vector search plus a reranker is the recommended pipeline.
- [Reranking](https://agenticgraph.dev/docs/vector-guide-reranking.md): Rerank results with a rerank API (Cohere, Voyage), an LLM through Prism, or your own driver. ->rerank() fetches extra candidates and take() keeps the best.
- [Capability discovery](https://agenticgraph.dev/docs/vector-guide-capability-discovery.md): capabilities() on the store returns StoreCapabilities; supports(StoreCapability::...) tells you whether a feature works. healthCheck tests connectivity only.

## Vector › Reference

- [Facades & builder](https://agenticgraph.dev/docs/vector-reference-facades-and-builder.md): Search, rerank, ingest, filter, list ids, update metadata, delete, and manage collections with the Vector and Embeddings facades.
- [Value objects](https://agenticgraph.dev/docs/vector-reference-value-objects.md): Document, SearchResult, CollectionDefinition, IdPage, UpdateMetadataResult, StoreCapabilities, and the other types you pass in and get back.
- [Exceptions](https://agenticgraph.dev/docs/vector-reference-exceptions.md): Typed Vector exceptions, what causes them, and how to fix each one.

## Tutorials

- [Your first AI agent in Laravel: a streaming FAQ bot](https://agenticgraph.dev/tutorials/faq-bot.md): Build a Laravel page where a one-node AgenticGraph agent answers questions about a product and streams the answer word by word. Runs locally with Ollama.

## Optional

- [Full documentation](https://agenticgraph.dev/llms-full.txt): every page above as one Markdown file