Content
Agent Runtime Kit
AI Agent runtime framework for local automation tasks, supporting daemon persistent execution, typed IPC, real-time event streams, tool permission control, session memory, context compression, sub-agents, and MCP tool access.
English | [English](README.en.md)
[](https://github.com/zed123214/agent-runtime-kit/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://docs.pydantic.dev/)
[](https://textual.textualize.io/)
[](LICENSE)
## Project Positioning
Modern AI Agents should be more than just a single LLM API call wrapper. A usable local Agent runtime needs to have: long-running execution processes, typed IPC, observable event streams, secure local tool execution, persistent session memory, and a unified extension model for tool, Skills, sub-agents, and MCP Server integration.
Agent Runtime Kit uses Python to implement these fundamental Agent Runtime capabilities. The current provider implementation is based on the Anthropic model, but the system core is designed around the provider boundary: the project focuses on the periphery of the model, not the model itself, including daemon, communication protocols, tool calls, permission approval, session management, and event infrastructure.
## Supported Environments
This repository primarily targets Linux/macOS-like environments the current runbook, process control commands, and Shell tool behaviors rely on POSIX semantics, native Windows is not the.
On Windows machines is recommended to through WSL2 or Docker. The source code and documentation can still be read and reviewed directly on Windows.
## System Architecture
```mermaid
graph TD
User(( --> CLI["agentrt User --> TUI["agentrt-tui"]
CLI -->|JSON-RPC 2.0 over NDJSON TCP| Core["agentrt-core daemon"]
TUI -->|Subscribe / Replay Events| Core
subgraph Runtime["Agent Runtime"]
Core --> Session["SessionManager\nthread.jsonl"]
Core --> Runner["AgentRunner"]
Runner -->Loop\nPlanning-Execution-Observation"]
Loop -->LLM Provider\nStreaming Output + Usage"]
Loop --> Registry["ToolRegistry"]
Registry --> Permission["PermissionManager"]
Registry --> Builtins["Built-in Tools\nread/write/list/bash/task"]
Registry --> MCP["MCP Tools"]
Registry --> SubAgent["Subagents"]
Runner --> Compact["Compactor\nContext Budgeting"]
end
subgraph Observability["Observability"]
Loop --> EventBus["EventBus"]
Permission --> EventBus
SubAgent --> EventBus
EventBus -->events.jsonl"]
EventBus --> Broadcast["IPC Broadcaster"]
Broadcast --> TUI
end
```
## Core Capabilities
1. **Daemon + CLI/TUI Client Architecture**: Decouple long-running Agent execution processes from frontend lifecycles. CLI/TUI can disconnect, and the daemon continues to maintain the running state.
2. **Typed IPC**: Use Pydantic to model requests, responses, errors, and events, and expose inter-process communication protocols over JSON-RPC 2.0 and NDJSON TCP.
3. **Automatic Protocol Documentation**: `WIRE_PROTOCOL.md` is generated from the source code protocol model, reducing the risk of drifting between handwritten protocol documentation and code implementation.
4. **ReAct-style AgentLoop**: Uniformly handle LLM streaming output, `tool_use` parsing, tool parameter validation, tool execution, `tool_result` feedback, maximum step limit, cancellation semantics, and failure recovery at runtime.
5. **ToolRegistry + PermissionManager**: Built-in tools and MCP tools share schema validation, permission judgment, event publishing, and structured result return mechanisms.
6. **Session Memory**: Complete message history is saved to `thread.jsonl`, and organized long-term facts are saved to `notes.md`.
7. **Context Governance**: result truncation, context water, and compact summary replacement historical contexts.
8., Subagents, and Markdown Skills, isolated context sub, and MCP tools same tool registration, permission, event, and runner infrastructure.
##
| Resume Statement | Repository |
| --- | --- |
| Daemon +UI multi-process architecture | `src/agent_runtime/core/app.py`, `_runtime/cli//agent_runtime/tui `docs/architecture.md` JSON-RPC 2 over NDJSON TCP | `src/agent_runtime/core/bus/`, `src/agent_runtime/core/transport/`, `WIRE_PROTOCOL.md` |
| Type-safe protocol boundary | Pydantic protocol strict `mypy`, `WIRE_PROTOCOL.md` |
| Observable event streams | `EventBus`, `events.jsonl`, replayable client event subscription |
| Runtime-level tool permission control | `src/agent_runtime/core/permissions/`, `docs/tool-permissions.md`, `examples/permissions/` |
| LLM/tool execution closed loop | `src/agent_runtimeloop.py`, `src/core/runner.py`, unit tests, and integration tests |
memory and context governance | `_runtime/core/session/src/agent_runtime/core/ `docs/session-memory| Unified extension modelsrc/agent_runtime/core/skills `src/agent_runtime`, `src/core/mcp/`, `examples/` |
## Quick Start
### Environment Requirements
- Linux, WSL2, or Docker Python 3.12 [uv](docs.astral.sh/)
- Real LLM execution `ANTHROPIC### Installation
```bash
git clone https://github.com123214/agent-runtime
cd agent-runtime-kit sync
```
### Configuration
```bash
cp .env.example .env
```
Example:
```env
AGENTRT_HOST=127.0.0.1
AGENTRT_PORT=7437
AGENTRT_LOG_LEVEL=INFO
AGENTRT_LOG_FILE=~/.agentrt/logs/core.log
AGENTRT_LOG_FORMAT=text
# ANTHROPIC_API_KEY=sk-ant-your-key-here
# AGENTRT_LLM_DEFAULT_MODEL=claude-sonnet-6
# AGENTRT_MAX_STEPS=20
```
Do not submit real API Keys. Keep local keys in `.env` or shell environment variables.
### Running
```bash
uv run agent
uv run agentrt ping
uv run agentrt run "Inspect this repository and summarize the project structure"
uv run agentrt-tui
```
## Event Stream Example
```json
{"type":"run.started","run_id":"20260629-101500-a1b2c3","goal":"...","ts":"..."}
{"type":"llm.token","run_id":"20260629-101500-a1b2c3","token":"I","ts":"..."}
{"type":"tool.started_id":"20260629-101500-a1b2","tool_name":"list_dir","ts":"..."}
{"type":"permission.requested","run_id":"20260629-101500-a1b2c3","tool_name":"bash","ts":"..."}
{"type":"tool.finished","run_id":"20260629-101500-a1b2c3","tool_name":"list_dir","is_error":false,"ts":"..."}
{"type":"run.finished","run_id":"202606101500-a1b2c3","status":"success":"..."}
```
##
```text
/
|-- README.md
.en.md
|--.md
|-- WIRE
|-- docs/
| |-- architecture.md
|-loop.md
| |-- tool-permissions.md
|-- session-memory.md
|-- skills-subagents| `--lights.md
|-- examples/
| |-- basic_run/
|-- permissions/
| `-- trace_permission_flow| |-- skills/
| `-- mcp/
|-- scripts/
| |-- generate_wire_protocol.py
| `-- check_wire_protocol.py
|-- src/agent_runtime/
| |-- cli/
| |-- tui/
| `-- core/
| |-- app.py
| |-- runner.py
| |-- loop.py
| |-- bus/
| |-- transport/
| |-- tools/
| |-- permissions/
| |-- session/
| |-- compact/
| |-- skills/
| |-- subagent/
| |-- mcp/
| `-- trace/
`-- tests/
|-- unit/
`-- integration/
```
## Development and Checks
```bash
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run mypy src
uv run pytest testsv
uv run python_wire_protocol.py --```
On native Windows, `uv` script a trampoline path use the Python module run tools:
```bash
uv run python -ypy src
python -m pytest tests/ -v
```
After modifying under `src/agent_runtime/core/bus/ the protocol documentation:
```bash
uv run python scripts/g_protocol.py
```
## Documentation
- [Architecture](itecture.md)
- Loop](docs/agent-loop.md)
- [Tool Permissions](docs/tool-permissions.md)
- [Session Memory](docs/session-memory.md)
- [Skillsagents, and MCP](ills-subagents-m)
- [Project Highlights/project-highlights.md)
Runbook](RUNBOOK.md)
- [Wire Protocol](WIRE_PROTOCOL.md)
##
- `.env, session data, cache environment, and local not be submitted to the repository.
- Shell, file
Connection Info
You Might Also Like
No recommendations available