agenarc 0.7.1

Directed-graph Agent Orchestration Engine

AgenArc

Directed-Graph Agent Orchestration Engine

---

Philosophy

"Mechanism and Strategy Separation"

Layer	Role
Kernel	Ultra-stable scheduler — secure execution, resource validation, VFS sandbox
Self-repair	Built by users within the graph flow — evolve agents without touching the engine
Asset boundary	agrc:// virtual protocol — files, scripts, and prompts live in isolated bundles

---

Architecture

 ┌──────────────────────────────────────────────────────────┐
 │                      AgenArc v0.7                        │
 ├──────────────────────────────────────────────────────────┤
 │                                                           │
 │  ┌──────────┐    ┌──────────┐    ┌──────────────────┐    │
 │  │ Protocol │───▶│  Engine  │───▶│  Visualization   │    │
 │  │   (DSL)  │    │ (Runtime)│    │   (Web IDE)      │    │
 │  └──────────┘    └──────────┘    └──────────────────┘    │
 │        │               │                  │               │
 │  ┌─────▼─────┐  ┌──────▼──────┐  ┌───────▼────────┐     │
 │  │JSON Schema│  │  Scheduler  │  │  Graph Editor   │     │
 │  │+ Templates│  │  + Router   │  │  + Live Preview │     │
 │  │+ Conditions│ │  + Join     │  │  + Context Panel│     │
 │  └───────────┘  │  + Checkpoint│ │  + Status LEDs  │     │
 │                 │  + Plugins   │  └────────────────┘     │
 │                 └─────────────┘                          │
 └──────────────────────────────────────────────────────────┘

---

Features

Category	Highlights
Execution	Linear & parallel & async modes, Router (conditional branching), Join (branch sync), CheckpointManager
LLM	Streaming responses, multi-provider fallback, structured error classification
Scripting	Script_Node with AST-safe evaluator (3 trust levels), gas & memory limits
Packaging	.agrc self-contained bundles — JSON protocol + prompts + scripts + plugins in one ZIP
VFS	agrc:// virtual filesystem with rwx permissions, path-traversal protection
Plugins	Python / C++ / External loaders, hot-reload (file watching), event plugins
Visualization	Web IDE — graph editor, file tree editor, syntax highlighting, context panel, trace waterfall
SubGraph	Embed .agrc bundles as nodes — isolated context, auto port resolution, pack embedding
CLI	run / shell / serve / validate / info / pack / visualize / init

Node Types

Node	Description	Input → Output
SubGraph	Embed and execute a nested .agrc bundle as a sub-graph with isolated context	auto-resolved from child bundle: trigger outputs → inputs, terminal node outputs → outputs
Trigger	Entry point	payload → graph
Trigger	Entry point	payload → graph
LLM_Task	LLM inference (streaming + fallback)	messages → response, usage, error
Router	Conditional branching (all matches execute in parallel)	input → dynamic output ports
Join	Synchronize parallel branches (merge / concat / first)	dynamic → output
Memory_I/O	Persistent key-value storage (transactional + checkpoint)	key, value → value, success
Script_Node	Inline Python with AST safety (3 trust levels)	arbitrary → result
Prompt_Builder	Multi-turn conversation history management	user / assistant → messages
Log	Log and pass-through	message → message
Context_Set	Set global context values	key, value → success
Context_Get	Read global context values	key → value
Asset_Reader	Read files from bundle via VFS	path → content, success
Asset_Writer	Write files with atomic operations	path, content → success
Runtime_Reload	Hot reload scripts and plugins at runtime	target → success

---

Quick Start

pip install agenarc

# Run a chat agent
agenarc run examples/my_first_agent.agrc --input '{"payload":"Hello!"}'

# Interactive REPL
agenarc shell examples/my_first_agent.agrc

# Background service with plugins
agenarc serve examples/euchea.agrc

# Web-based graph editor
agenarc visualize examples/my_first_agent.agrc

Examples

Agent	Description
my_first_agent.agrc	Multi-turn chat — Trigger → Prompt_Builder → LLM_Task
qq_bot_agent.agrc	QQ bot with event plugin (serve mode)
euchea.agrc	PDF → C++ code generation via Alt+A hotkey (serve mode)

---

.agrc Bundle

my_agent.agrc/
├── manifest.json          # Metadata, permissions, hot_reload
├── flow.json              # Graph definition (nodes + edges)
├── prompts/
│   └── system.pt          # {{template}} prompt files
├── scripts/
│   └── tool.py            # Custom scripts (optional)
├── sub/                    # Embedded SubGraph bundles (auto-packed)
│   └── translator.agrc/
│       ├── flow.json
│       └── prompts/
├── plugins/                # Embedded plugins (auto-discovered)
│   └── my_plugin/
│       ├── agenarc.json
│       └── plugin.py
└── assets/                 # Static assets (optional)

Example flow.json

{
  "version": "1.0.0",
  "nodes": [
    { "id": "trigger_1", "type": "Trigger", "label": "Start" },
    {
      "id": "llm_1",
      "type": "LLM_Task",
      "label": "Chat",
      "config": {
        "model": "deepseek-chat",
        "system_prompt": "agrc://prompts/system.pt",
        "stream": true,
        "providers": ["deepseek", "openrouter"]
      }
    },
    { "id": "log_1", "type": "Log", "label": "Output" }
  ],
  "edges": [
    { "source": "trigger_1", "sourcePort": "payload", "target": "llm_1", "targetPort": "messages" },
    { "source": "llm_1", "sourcePort": "response", "target": "log_1", "targetPort": "message" }
  ]
}

---

SubGraph

An .agrc bundle can be embedded as a node in another graph:

{
  "id": "translator",
  "type": "SubGraph",
  "label": "翻译 Agent",
  "config": { "bundle": "translator.agrc" }
}

SubGraph 端口自动从子图 bundle 解析：

• 输入端口 = 子图 Trigger 节点的输出端口
• 输出端口 = 子图终端节点（无出边）的输出端口

Bundle 嵌入

引用 sub/ 目录下的子图会在 agenarc pack 时自动嵌入：

my_agent.agrc/
├── flow.json              # 引用 sub/translator.agrc
├── sub/
│   └── translator.agrc/   # 运行时打包时自动嵌入
│       ├── flow.json
│       └── prompts/

上下文隔离

子图拥有独立的 StateManager，不污染父图上下文。父图可以通过 config.inputs 注入值，通过边连接子图的输出端口获取结果。

---

Configuration

# ~/.agenarc/config.yaml

providers:
  deepseek:
    api_key: sk-your-key
    base_url: https://api.deepseek.com
    default_model: deepseek-chat
    temperature: 0.7

  openrouter:
    api_key: sk-your-key
    base_url: https://openrouter.ai/api/v1
    default_model: openrouter/free

agent:
  checkpoint_dir: ~/.agenarc

Provider	base_url
DeepSeek	https://api.deepseek.com
OpenAI	https://api.openai.com/v1
OpenRouter	https://openrouter.ai/api/v1
Ollama	http://localhost:11434/v1

Environment variables override config: AGENARC_OPENAI_API_KEY, AGENARC_OPENAI_BASE_URL, AGENARC_OPENAI_MODEL, AGENARC_ANTHROPIC_API_KEY, AGENARC_ANTHROPIC_MODEL, AGENARC_CHECKPOINT_DIR

---

Development

agenarc/
├── protocol/           # JSON Schema + protocol loader
├── engine/             # Executor, state manager, AST evaluator
├── operators/          # 13 built-in operators
├── vfs/                # agrc:// virtual filesystem
├── plugins/            # Plugin loader (Python/C++/External)
├── graph/              # Graph data structures + traversal
├── visualization/      # Web IDE server + static frontend
└── cli/                # Command-line interface

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/                          # All (742 passed)
pytest tests/ --cov=agenarc            # With coverage (~62%)
pytest tests/unit/test_builtin_operators.py -v  # Single file

# Lint & type check
ruff check agenarc/
ruff format --check agenarc/
mypy agenarc/

---

Documentation

Document	Description
CHANGELOG.md	Release history and change log
CONTRIBUTING.md	Development setup, PR process, commit style
docs/agents.md	User-facing agent creation guide (Chinese)
docs/plugins/README.md	Plugin development guide

---

License

MIT © Rycbartbad