yggdrasil-lm 0.1.3

Yggdrasil: a Python framework for graph-native agent orchestration

Yggdrasil - Observable and Explainable Agent-as-Graph library

Build agent systems as graphs, where agents, tools, context, and workflow state live in one runtime.

yggdrasil is a Python framework for graph-native orchestration. The core idea is simple:

• store agents, tools, prompts, and context as graph nodes
• connect them with typed edges
• let the runtime compose and execute that graph at query time

The strongest use case is not just "build an agent." It is:

• build an agent system that changes over time
• manage that system as graph data
• explain why it behaved the way it did

The intended workflow is:

1. define agents, tools, and context as graph nodes
2. connect them with typed edges
3. run queries through the graph
4. inspect behavior with structured traces and explain_run

Illustration

Yggdrasil is named after the world tree because the project is meant to connect distinct realms of work in one traversable system:

• data and memory
• humans and approvals
• deterministic business logic
• probabilistic reasoning with LLMs
• durable workflow state across all of them

Start Here

If you are new to the project, use this order:

1. Start Here
2. Your First Graph
3. Choose a Backend
4. Control Plane Thesis
5. Explainable Agent Systems
6. Flagship Workflow
7. Observability
8. Visualizer Web UI

Skip these until later:

• Advanced configuration
• Batch execution
• Long-running workflows
• API reference

Install

Requirements: Python 3.11+

Install directly from Git without cloning:

pip install "yggdrasil @ git+https://github.com/hoangdao1/yggdrasil.git"

Add extras the same way:

pip install "yggdrasil[anthropic] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[openai] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[embeddings] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[observe] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[neo4j] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[claude-code] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[viz] @ git+https://github.com/hoangdao1/yggdrasil.git"
pip install "yggdrasil[dev] @ git+https://github.com/hoangdao1/yggdrasil.git"

Or clone the repo for local development:

git clone https://github.com/hoangdao1/yggdrasil.git
cd yggdrasil
pip install -e .

Add the extras you need:

pip install -e ".[anthropic]"    # default Anthropic backend
pip install -e ".[openai]"       # OpenAI-compatible backend
pip install -e ".[embeddings]"   # semantic retrieval
pip install -e ".[observe]"      # OpenTelemetry export
pip install -e ".[neo4j]"        # Neo4j graph store
pip install -e ".[claude-code]"  # Claude Code sub-agent backend
pip install -e ".[viz]"          # browser trace visualizer
pip install -e ".[dev]"          # tests + rich trace UI

Fastest Working Example

90% of use cases fit in five lines. The beginner-friendly path uses GraphApp, which wires up the store, executor, and backend automatically.

import asyncio
from yggdrasil_lm.app import GraphApp


async def main() -> None:
    app = GraphApp()
    agent = await app.add_agent("Bot", system_prompt="You are a helpful assistant.")
    ctx = await app.run(agent, "What is Python 3.13?")
    print(ctx.outputs[agent.node_id]["text"])


asyncio.run(main())

Need tools? Attach the built-ins and go:

import asyncio
from yggdrasil_lm.app import GraphApp


async def main() -> None:
    app = GraphApp()

    agent = await app.add_agent(
        "Researcher",
        system_prompt="You are a technical researcher.",
        model="claude-sonnet-4-6",
    )
    app.use_default_tools()  # registers built-in web_search, echo, run_python

    ctx = await app.run(agent, "What changed in Python 3.13?")
    print(ctx.outputs[agent.node_id]["text"])


asyncio.run(main())

Want local Claude Code sub-agents instead of a hosted API backend?

from yggdrasil_lm.app import GraphApp

app = GraphApp(
    provider="claude-code",
    cwd="/path/to/project",
    permission_mode="acceptEdits",
)

This uses your Claude Code executor setup and can bridge graph ToolNodes into the sub-agent as in-process MCP tools.

See API reference §2 Builder API for the full GraphApp surface, including add_tool(fn=..., attach=True, agent=...), add_context, add_prompt, and delegate.

Why This Project Exists

Many agent systems start as prompt-and-tool loops, then become operational systems:

• new policies appear
• review steps are added
• context sources change
• capabilities vary by tenant or environment
• operators need to explain decisions

yggdrasil is designed for that phase.

It treats the agent system as something that should be:

• versioned
• diffed
• migrated
• inspected
• explained

Core Mental Model

Keep these four ideas in mind:

1. Composition is traversal. Agents discover tools, prompts, and context by following graph edges.

2. Execution is traversal. Running a query is a walk through the graph.

3. Routing is explicit. Multi-agent handoff is represented in the graph and resolved by the executor.

4. Outputs can become graph state. Runs produce traces and can materialize runtime context.

API Layers

There are two ways to use the project.

Beginner API

Use this first. Import from yggdrasil.app:

• GraphApp
• create_agent()
• create_tool()
• create_context()
• create_prompt()
• create_executor()

Low-Level Runtime API

Use this when you need direct control:

• AgentNode, ToolNode, ContextNode, PromptNode
• Edge
• NetworkXGraphStore
• GraphExecutor

What The Project Already Does Well

• dynamic tool and context composition from graph edges
• multi-agent routing
• sequential, fan-out, and DAG execution strategies
• batch execution with concurrency, checkpointing, and resume
• structured traces with terminal and browser views
• typed run explanations with hop summaries, routing decisions, and tool call details
• workflow runtime features such as pause/resume, approvals, and checkpoints

For the browser trace viewer specifically, see Visualizer Web UI.

Recommended Learning Path

Learn the runtime

• Your First Graph
• Workflow Patterns
• Observability
• Explainable Agent Systems
• Why behavior changed
• Flagship Workflow

Run practical local examples

• examples/builder_echo.py
• examples/deterministic_routing.py
• examples/approval_workflow.py
• examples/parallel_workers.py
• examples/research_pipeline.py

Learn provider setup

• Choose a Backend
• Advanced configuration

Learn the platform layer

• Control Plane Thesis
• Architecture
• Repo map

Contributor Docs

• Contributing
• Architecture
• Repo map

Reference Docs

• API reference

Project Status

This repo now has a clearer split:

• README.md: first-run path
• docs/: tutorials, architecture, and operations
• API_REFERENCE.md: exhaustive reference
• yggdrasil/app.py: beginner-facing builder API
• yggdrasil/core/: low-level runtime