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.
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
@agentrail/runtime-core: agent definition, execution loop, tool contracts, provider abstractions@agentrail/host: hosted request primitives for chat and stream lifecycles@agentrail/host/defaults: recommended hosted SDK and default capability builders@agentrail/prompts: prompt fragments, bundles, rendering, and file loading@agentrail/orchestration: managed sub-agents, mailboxing, waits, and recovery@agentrail/memo: session storage, message history, and compaction@agentrail/knowledge: knowledge-base indexing and reading tools@agentrail/skills: skill discovery and skill tool execution@agentrail/sandbox: sandbox lifecycle and execution/browser tools@agentrail/tools: general-purpose tools such as ask-user and todo writing@agentrail/events: shared event contracts@agentrail/config: typed YAML config loading, defaults, and validation for Agentrail apps@agentrail/plugin-user-memory: plugin for persistent user memory across sessions@agentrail/slash-commands: slash command parsing and dispatch@agentrail/deep-research: deep research workflow built on top of Agentrail@agentrail/create-agentrail-app: scaffolding CLI for new Agentrail projects
examples/playground-server: full hosted reference serverexamples/playground-ui: companion UI for the playground serverexamples/deep-research: dedicated workflow example built on top of Agentrail
pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm dev:playground-server
pnpm dev:playground-ui
pnpm dev:deep-researchFor contributor workflow details, see CONTRIBUTING.md.
Useful verification commands while working on the framework:
pnpm --filter @agentrail/host test
pnpm --filter @agentrail/prompts test
pnpm --filter @agentrail/playground-server typecheckThe 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.
- 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
Agentrail is licensed under Apache-2.0.