agenarc

AgenArc

Philosophy

"Mechanism and Strategy Separation"

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

Node Types

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

.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)

{
  "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

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

License

MIT © Rycbartbad