Build, host, and orchestrate tool-using AI agents.

Website & Docs → agentrail.run

---

Agentrail is an open-source agent harness framework for building, hosting, and orchestrating tool-using AI agents.

It provides a composable runtime core, a hosted server layer, a prompt SDK, multi-agent orchestration, filesystem-backed memory, sandboxed execution, and optional plugins and workflows.

Note

Agentrail is in pre-GA development. Public APIs and package boundaries may change before the first stable release. See ROADMAP.md for current status and planned milestones.

Why Agentrail

Agentrail grew out of patterns developed in a production AI agent system, distilled into a composable open-source framework.

It is designed for developers who want more structure than ad hoc agent scripts, but less product lock-in than a hosted platform.

• Production-proven — built from real-world agent infrastructure, not a proof-of-concept
• Code-first, no platform lock-in — define everything in code, no hosted platform or GUI required
• Complete host layer — goes beyond an agent loop with a full chat and streaming request lifecycle
• Pluggable LLM providers — unified abstraction over Anthropic, OpenAI, and others; swap without rewriting agent logic
• Multi-agent orchestration — delegate work to sub-agents with mailboxing, structured waits, and failure recovery
• Profile and plugin extension model — package agent behavior in profiles, extend the runtime through plugins with clear boundaries
• Session memory and knowledge — built-in message history compaction, knowledge-base indexing, and retrieval
• Docker sandbox isolation — run LLM-generated code safely, fully isolated from the host environment

Packages

• @agentrail/core: agent definition, execution loop, tool contracts, prompt SDK, session types, LLM providers
• @agentrail/capabilities: sandbox, knowledge, skills, orchestration, browser automation, and built-in tools
• @agentrail/app: hosted request lifecycle (createAgentApp), profiles (defineProfile), session management, plugins, config, events
• @agentrail/deep-research: deep research workflow (standalone addon)
• @agentrail/create-agentrail-app: scaffolding CLI for new Agentrail projects

Examples

• examples/playground-server: full hosted reference server
• examples/playground-ui: companion UI for the playground server
• examples/deep-research: dedicated workflow example built on top of Agentrail

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm dev:playground-server
pnpm dev:playground-ui
pnpm dev:deep-research

For contributor workflow details, see CONTRIBUTING.md.

Useful verification commands while working on the framework:

pnpm --filter @agentrail/core test
pnpm --filter @agentrail/app test
pnpm --filter @agentrail/playground-server typecheck

Quick Start

The fastest way to get started is the Quickstart guide on the documentation site.

For a full local reference setup, see the examples/playground-server and examples/playground-ui packages.

Community

• GitHub Discussions — questions, ideas, and show and tell
• Bug reports — use the issue tracker for confirmed bugs
• Feature requests
• Security vulnerabilities — please do not open public issues

License

Agentrail is licensed under Apache-2.0.