atomr-agents-quickstart
/atomr-agents-quickstart
Use when standing up the first atomr-agents project, picking feature flags for the `atomr-agents` umbrella, building a first `Agent`, or running an end-to-end agent turn against `MockRunner`. Triggers on adding `atomr-agents = ...` to Cargo.toml, writing the first `Agent { ... }` literal, wiring an `InferenceClient`, or asking "how do I get atomr-agents running".
- Author
- rustakka ↗
- Repository
- atomr-agents ↗
- Licence
- Apache-2.0
- Last repository change
- 08.06.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 8
No signals detected. Repository changed on 08.06.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Use when standing up the first atomr-agents project, picking feature flags for the `atomr-agents` umbrella, building a first `Agent`, or running an end-to-end agent turn against `MockRunner`. Triggers on adding `atomr-agents = ...` to Cargo.toml, writing the first `Agent { ... }` literal, wiring an `InferenceClient`, or asking "how do I get atomr-agents running".
Triggers from the description
Original author description
Use when standing up the first atomr-agents project, picking feature flags for the `atomr-agents` umbrella, building a first `Agent`, or running an end-to-end agent turn against `MockRunner`. Triggers on adding `atomr-agents = ...` to Cargo.toml, writing the first `Agent { ... }` literal, wiring an `InferenceClient`, or asking "how do I get atomr-agents running".
How it works
- The 30-second mental model
- The minimal consumer Cargo.toml
- Building an agent
- Composing prompt → model → parser
- When to reach beyond the agent
- Canonical references
- Common mistakes
SKILL.md preview
---
name: atomr-agents-quickstart
description: Use when standing up the first atomr-agents project, picking feature flags for the `atomr-agents` umbrella, building a first `Agent`, or running an end-to-end agent turn against `MockRunner`. Triggers on adding `atomr-agents = ...` to Cargo.toml, writing the first `Agent { ... }` literal, wiring an `InferenceClient`, or asking "how do I get atomr-agents running".
---
# atomr-agents quickstart
A composable agentic framework on the [atomr](https://github.com/rustakka/atomr)
actor runtime. Pluggable strategies, channelled state, durable
checkpointing, parallel tool dispatch, retriever zoo — the LangGraph
+ LangChain feature surface in atomr's actor idiom.
## The 30-second mental model
- **Composition is the unit of work.** Every executable unit
(prompt, model, parser, tool, retriever, sub-agent, workflow,
harness) implements `Callable`. `Pipeline` chains them. Decorators
(`with_retry`, `with_fallbacks`, `with_config`, `with_timeout`)
layer policies orthogonally.
- **State is channelled.** `StateSchema` declares one channel per
state key. Each channel carries a reducer
(`AppendMessages`, `MergeMap`, `LastWriteWins`, `AppendList`,
`MaxByTimestamp`). `Checkpointer` persists per-super-step
snapshots; `fork(checkpoint, edits)` creates a divergent run.
- **Strategies are the extension surface.** `InstructionStrategy`,
`ToolStrategy`, `MemoryStrategy`, `SkillStrategy`, `LoopStrategy`,
`TerminationStrategy` — generic so the agent's hot path
monomorphizes; `Box<dyn>` opt-in for runtime config.
- **Tools are parallel and provider-agnostic.** Multiple tool calls
in one assistant turn dispatch concurrently via `tokio::JoinSet`.
Streaming `tool_call_delta` parses OpenAI and Anthropic deltas
natively.
## The minimal consumer Cargo.toml
```toml
[dependencies]
# Defaults: agent + tool + skill + memory + persona + instruction
atomr-agents = "0.2"
atomr-infer = { version = "0.6", features = ["openai"] } # or any provider
# Add features as needed:
# atomr-agents = { version = "0.2", features = ["harness", "eval", "embed"] }
# Or pull a provider runtime through the umbrella (skips the explicit
# atomr-infer dep — runner is re-exported under agent::providers::*):
# atomr-agents = { version = "0.2", features = ["agent", "provider-anthropic"] }
# atomr-agents = { version = "0.2", features = ["agent", "provider-openai"] }
# atomr-agents = { version = "0.2", features = ["agent", "provider-gemini"] }
# RAG-flavored:
# atomr-agents-retriever = "0.2"
# atomr-agents-ingest = "0.2"
# Test scaffolding:
# atomr-agents = { version = "0.2", features = ["testkit"] }
```
See [`docs/feature-matrix.md`](https://github.com/rustakka/atomr-agents/blob/main/docs/feature-matrix.md)
for every feature flag and the canonical "shapes" (minimal agent /
RAG / production harness / multi-agent / kitchen-sink).
## Building an agent
```rust
use std::sync::Arc;
use atomr_agents::prelude::*;
use atomr_agents::agent::{Agent, AgentBudgets, InferenceClient, LocalRunnerClient, Provider};
use atomr_agents::tool::{StaticToolStrategy, DynTool};
use atomr_agents::memory::{InMemoryStore, RecencyMemoryStrategy};
use atomr_agents::skill::StaticSkillStrategy;
use atomr_agents::persona::StaticPersonaStrategy;
use atomr_agents::instruction::{
ComposedInstructionStrategy, StaticBehaviorStrategy, StaticTaskStrategy,
};
use atomr_agents::observability::EventBus;
use atomr_infer_testkit::{MockRunner, MockScript};
let runner = MockRunner::new(MockScript::from_text(["the answer is ", "42"]));
let inference: Arc<dyn InferenceClient> =
Arc::new(LocalRunnerClient::new(runner, Provider::OpenAi));
let agent = Agent {
id: AgentId::from("a-1"),
model: "gpt-4o-mini".into(),
instructions: ComposedInstructionStrategy::new(
StaticPersonaStrategy::new("You are a helpful assistant."),
StaticTaskStrategy("Answer concisely.".into()),
StaticBehaviorStrategy("Always cite sources.".into()),
),
tools: StaticToolStrategy::new(Vec::<DynTool>::new()),
memory: RecencyMemoryStrategy::new(Arc::new(InMemoryStore::new()), 8, 40),
skills: StaticSkillStrategy::new(vec![]),
inference,
bus: EventBus::new(),
max_tool_iterations: 5,
};
let r = agent.run_turn("hi".into(), AgentBudgets::default()).await?;
println!("{}", r.text);
```
Swap `MockRunner` for any atomr-infer `ModelRunner` (OpenAI,
Anthropic, vLLM, Candle, …) and the same code runs unchanged. The
`Provider` enum tells the streaming tool-call parser which delta
format to expect.
## Composing prompt → model → parser
```rust
use atomr_agents::callable::{Pipeline, with_retry, RetryPolicy};
let pipeline = Pipeline::from(prompt_handle)
.then(model_handle)
.then(parser_handle)
.build();
// Add retries on the model stage:
let resilient_model = with_retry(model_handle, RetryPolicy::default());
let pipeline = Pipeline::from(prompt_handle)
.then(resilient_model)
.then(parser_handle)
.build();
let output = pipeline.call(input, ctx).await?;
```
This is the LCEL `prompt | model | parser` shape.
## When to reach beyond the agent
| You need… | Reach for… |
|---|---|
| Channelled state + checkpointing | `atomr-agents-state` — see `atomr-agents-state` skill |
| Pause/resume / approval flows | `atomr-agents-workflow::Interruptible` — see `atomr-agents-hitl` skill |
| RAG | `atomr-agents-retriever` + `atomr-agents-ingest` — see `atomr-agents-rag` skill |
| Multi-agent topology | `atomr-agents-org` — see `atomr-agents-multi-agent` skill |
| Eval gates in CI | `atomr-agents-eval` + `atomr-agents-registry` — see `atomr-agents-eval` skill |
| Tracing into LangSmith | `atomr-agents-observability` — see `atomr-agents-observability` skill |
## Canonical references
- [`docs/index.md`](https://github.com/rustakka/atomr-agents/blob/main/docs/index.md) — documentation hub
- [`docs/architecture.md`](https://github.com/rustakka/atomr-agents/blob/main/docs/architecture.md) — runtime layout
- [`docs/agent-pipeline.md`](https://github.com/rustakka/atomr-agents/blob/main/docs/agent-pipeline.md) — per-turn pipeline + tool-call loop
- [`docs/feature-matrix.md`](https://github.com/rustakka/atomr-agents/blob/main/docs/feature-matrix.md) — every feature flag
- [`crates/agent/src/pipeline.rs`](https://github.com/rustakka/atomr-agents/blob/main/crates/agent/src/pipeline.rs) — agent implementation
- [`crates/harness/examples/research_harness.rs`](https://github.com/rustakka/atomr-agents/blob/main/crates/harness/examples/research_harness.rs) — sub-harness composition example
## Common mistakes
- **Forgetting to set `Provider`.** The wrong provider parses
`tool_call_delta` for the wrong format and tools never fire.
- **Empty `tools` with `max_tool_iterations > 1`.** Wastes inference
budget; if you have no tools, set `max_tool_iterations = 1`.
- **Using `MockRunner` in production.** It returns canned chunks; the
agent will appear to work but never actually consult a model.
- **Holding the `Agent` across `.await` while sharing it.** `Agent`
isn't `Sync` — wrap in `Arc<RwLock<>>` if multiple callers need it.
- **Pulling `cudarc` into a remote-only build.** Add atomr-infer's
`remote-only` feature to keep GPU deps out of the dep graph.
Versions
The database has no other skills named atomr-agents-quickstart.
Database snapshot: 13.11.2026 · package version 1455c80fb787 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100atomr-agents-meetings-harness
Use when turning a diarized STT transcript into structured meeting artifacts in atomr-agents — building a `MeetingsHarness`, accumulating a `MeetingAnalysis` (attendees, notes, actions-with-owners, tiered summaries), picking batch vs live mode, persisting via the configured… - 100atomr-agents-tools
Use when authoring or modifying a `Tool` / `RichTool`, designing a tool's `ToolDescriptor` schema, returning a `ToolReturn::Command`, wiring tools into an `Agent`'s `ToolStrategy`, or using built-in tools (`HandoffTool`, `WriteMemoryTool`, `RecallMemoryTool`). Triggers on `impl… - 100atomr-persistence
Use when adding event sourcing to an actor in a project that depends on atomr. Covers the Eventsourced trait, journals, snapshots, recovery, RecoveryPermitter, AsyncSnapshotter, and choosing a storage adapter (sql / redis / mongodb / cassandra / aws / azure). Triggers when… - 100atomr-testing
Use when writing tests against atomr actors using atomr-testkit. Covers TestKit, TestProbe (expect_msg / receive_n / expect_no_msg / expect_msg_pf), and the virtual-time TestScheduler. Triggers when authoring `#[tokio::test]` cases that exercise actors, mailboxes, or scheduled timers. - 100agenticx-quickstart
AgenticX zero-to-hero quickstart guide. Use when the user wants to get started with AgenticX, create their first project, build their first agent, or run their first workflow. Covers installation, project scaffolding, agent creation, task execution, and CLI basics. - 100agent-workflow
Complete workflow for building, implementing, and testing goal-driven agents. Orchestrates building-agents-* and testing-agent skills. Use when starting a new agent project, unsure which skill to use, or need end-to-end guidance.