hero_agent

Rust-native AI agent for Hero OS. Drop-in replacement for hero_shrimp (Bun/TypeScript), following the same HeroRpcServer pattern as every other Hero service: Unix socket, OpenRPC, auto-MCP.

Status

Fully implemented — 3 crates, 56 built-in tools, SSE streaming, MCP integration, OSIS-backed memory and conversations.

Why Rust

• Native OSIS SDK integration — conversations, memories, user scoping without RPC bridge
• Native SSE streaming via tokio + axum
• One stack — same build, debug, deploy model as every other Hero service
• HeroRpcServer pattern: health, discovery, inspector dashboard — all built in
• LLM APIs are stable REST/SSE — no SDK needed, just reqwest + serde

Crate structure

crates/
├── hero_agent/          Core library — agent loop, LLM client, MCP, memory, tools
├── hero_agent_server/   Binary — HTTP server, SSE routes, admin dashboard
└── hero_agent_tools/    56 built-in tools — file ops, git, web, shell, planning

hero_shrimp naming

hero_agent intentionally uses hero_shrimp socket paths and naming conventions (e.g. hero_shrimp.sock) so it slots into the existing Hero ecosystem as a drop-in replacement without requiring changes to other services or the frontend.

When the decision is made to switch from hero_shrimp to hero_agent in production, a proper rename should be done across the ecosystem — updating socket paths, service names, and references in hero_services, hero_archipelagos, and other dependent repos.

Build and run

make build       # Build release binary
make run         # Run locally (TCP port for dev)
make test        # Run unit tests
make smoke-test  # Run integration smoke tests

Acknowledgment

hero_agent exists thanks to hero_shrimp. The architecture, tool design, agent loop, skill system, and SSE protocol were all pioneered by hero_shrimp in TypeScript. hero_agent is a Rust port — we followed the same design faithfully and hope it stays true to its origins.

Architecture

See docs/spec.md for the complete design and architecture specification.