Mental model
Understand the seven pieces of a Noir agent and which parts belong to your application.
Noir is the reliability boundary around an agent, not the intelligence provider inside it. Your code supplies behavior and providers. Noir supplies common execution semantics for messages, effects, approvals, retries, and delivery.
The one-file shape
noir({
model,
channels,
connectors,
database,
memory,
sandbox,
plugins,
})Each field answers one question:
| Field | Responsibility | Owned by |
|---|---|---|
model | generate decisions and tool calls | your model provider |
channels | receive and deliver messages | your provider accounts |
connectors | expose named external systems | your clients and credentials |
database | persist the runtime inbox, history, approvals, checkpoints, and outbox | your database |
memory | recall and store long-term facts | your adapter and memory vendor |
sandbox | provide an owned working environment | your driver or local process |
plugins | add tools, policy, hooks, routes, and lifecycle | your selected modules |
All except model and channels are optional in the provider-native authoring mode. In handler mode, the model is optional too because your existing framework can own the loop.
The execution boundary
An inbound provider event becomes a normalized InboundEvent. Noir deduplicates it, derives a conversation key, serializes work for that conversation, and gives the turn a stable execution ID. Successful tool steps can be checkpointed. Outbound messages enter an outbox before the channel sends them.
That boundary provides an answer to the hard failure case: the process may stop after an external provider accepts a request but before local state records success. Noir can replay its own work, but an external write must also receive the stable idempotency key available in ToolContext or noir.executionId.
Connectors, resources, and plugins
These concepts are deliberately distinct:
- A connector is a named external system. Its tools become
name.tool, and it may expose a client, health check, or close hook. - Memory and sandbox are first-class resources because they shape nearly every turn and have ownership scopes.
- A plugin adds an optional behavior bundle: tools, policy, prompts, services, routes, hooks, health, and lifecycle.
- A standalone tool is the escape hatch for one function that does not justify a connector or plugin.
The ownership rule
You own the source, provider accounts, credentials, data, deployment, prompts, model selection, tools, and policies. Noir owns the semantics it promises inside your process: event identity, leases, retries, approval binding, checkpoint reuse, output bounds, and delivery settlement.
The result is self-hosted in the literal sense. Removing Noir leaves ordinary TypeScript adapters and provider clients in your repository; there is no remote project to export.