A LangGraph-based agent runtime with MCP integration, shell tooling, configurable tool approval modes, optional embedding-based retrieval, and a prompt manager.

• Agent
  • 1. Table of Contents
  • 2. What This Project Provides
  • 3. Quick Start
    • 3.1. Environment Variables
    • 3.2. Prerequisites
    • 3.3. Clone and Initialize
    • 3.4. Run on Host
    • 3.5. Run in Docker
    • 3.6. Common Startup Overrides
    • 3.7. Interactive CLI commands
  • 4. Configuration
    • 4.1. Optional Environment Variables
    • 4.2. Hydra Config Map
    • 4.3. MCP Runtime Model
  • 5. Auto Mode Reference
  • 6. Tooling Model
    • 6.1. Local Built-In Tools
    • 6.2. MCP-Discovered Tools
    • 6.3. Add a New Local Tool
  • 7. Further Documentation

• Stateful agent runtime: Uses LangGraph with in-memory conversation state and streaming output.
• 5-level tool approval policy: Ranges from fully manual to fully automatic (work.auto_mode).
• MCP tool federation: Loads tools from configured MCP servers; unavailable servers are skipped.
• Shell command tool: Executes commands with configurable timeout and working directory.
• Embedding Knowledge Base (EKB): Supports semantic retrieval over indexed files.
• Prompt manager (prompt_manager/): Builds lorebook JSON from prompts/lorebooks/*/entries/*.md (or loads existing JSON), then each turn runs match → filter → expand → sort → budgeted inject, and splices the result into the preset skeleton (core, character, persona, and optional depth anchors). See doc/prompt_manager.md.
• Hydra-based configuration: Hierarchical YAML composition with command-line overrides.
• Container support: Includes Docker scripts for build and startup.

Set these variables before starting the agent.

Required for LLM requests:

Example:

export OPENAI_API_KEY="your_api_key"
export OPENAI_API_BASE="https://your-provider.example/v1"

• Install uv.
• Ensure required ports for MCP servers are available (default: 8000, 8001, 8002).

git clone git@github.com:zeroDtree/agent.git
cd agent
git submodule update --init --recursive

The mcp submodule contains MCP server implementations used by the startup scripts.

bash shell_scripts/start.sh [hydra overrides...]

This command starts MCP servers defined in mcp/config.yaml, waits for ports to become ready, then launches the agent. MCP servers are stopped when the process exits.

bash shell_scripts/build_docker.sh
bash shell_scripts/start.docker.sh [hydra overrides...]

The container mounts:

• Project directory: /tmp/proj_dir
• Writable working directory: /tmp/work_dir
• shell_scripts/start.sh auto-creates /tmp/work_dir/.venv when ++work.working_directory=/tmp/work_dir is set.

In Docker, use this split as a best practice:

• Read source files from /tmp/proj_dir (mounted project root).
• Write generated artifacts to /tmp/work_dir (mounted writable workspace).
• Keep task-level Python dependencies in /tmp/work_dir/.venv.

Use Hydra override syntax to customize runtime behavior at launch:

bash shell_scripts/start.sh \
  ++work.auto_mode=whitelist_accept \
  ++work.working_directory=/tmp/work_dir

When ++work.working_directory is set to a non-. path, startup initializes a dedicated .venv under that directory once. This task-level environment is separate from UV_PROJECT (the runtime environment used to launch main.py).

After bash shell_scripts/start.sh (or bash shell_scripts/start.docker.sh in Docker), the CLI prompt accepts the following. Any other line is sent to the model as a normal user turn; each turn may print lorebook entries that matched for that message.

Optional variables for the knowledge_graph MCP server (Neo4j):

Agent configuration is composed from files under config/:

MCP runtime behavior comes from two sources:

• mcp/config.yaml: MCP server process launch settings (transport, host, port, enabled)
• config/mcp/default.yaml: Agent-side MCP endpoints for tool discovery

Default configured MCP servers:

Configure approval behavior with work.auto_mode:

Safe and dangerous lists are defined in config/tool/default.yaml.

This project exposes both local Python tools and MCP-discovered remote tools.

MCP tools are loaded dynamically from endpoints defined in config/mcp/default.yaml. Available tool sets depend on enabled servers in mcp/config.yaml (for example math, code_lint, knowledge_graph).

1. Implement the tool under tools/.
2. Register it in tools.get_all_tools().

No change in main.py is required for local tool registration.

• EKB usage and commands: doc/embedding_knowledge_base.md
• Prompt manager (pipeline, types, build vs runtime): doc/prompt_manager.md