The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
harness
Product shell around the tinyagents tool loop. The model/tool iteration
itself runs in crate::agent::tinyagents (via
TurnSpec::run). This module owns sub-agent definitions, post-turn
memory/archival hooks, and oversized-tool-result handling. The channel/CLI
turn driver lives with channel runtime at
../../channels/runtime/turn_driver.rs.
Parent execution snapshots live with the sub-agent host in
../subagent_host/fork_context.rs.
Agent, its per-turn lifecycle, and transcript persistence live in
../session_host/, not here; this module supplies the definition/prompt data
that session host and ../subagent_host/ build turns from.
Cancellation is the tinyagents steering channel (SteeringCommand in
crate::agent::tinyagents); there is no in-house interrupt fence or
cancellation token owned here. The message queue that lets a caller steer or
follow up on an in-flight turn is tinyagents_harness::run_queue::RunQueue,
carried by the parent snapshot in ../subagent_host/fork_context.rs.
Responsibilities
- Define sub-agent archetypes, built-in and workspace TOML, and the
definition/prompt inputs consumed by
../session_host/(which owns theAgentstruct, turn lifecycle, and KV-cache prefix stability) and../subagent_host/, which implements the TinyAgents sub-agent lifecycle traits directly. This module does not export a compatibility runner of its own. - Offload oversized worker artifacts to the filesystem, and persist oversized
tool results as action-workspace artifacts (
artifact_offload/,tool_result_artifacts/).
Key sub-modules
| Module | Role |
|---|---|
artifact_offload/ |
The outputs/ / workspace/ convention under action_dir: prompt half (contract.rs) and host policy half (policy.rs); mechanics (thresholds, path resolution, pointer rendering, the writer) live in tinyagents_harness::artifacts and are re-exported here. |
tool_result_artifacts/ |
Wiring only: new_tool_result_store hands tinyagents_harness::artifacts::tool_results OpenHuman's redactor (SanitizingRedactor), file_read/use_skill names and FileReadTool::MAX_FILE_SIZE_BYTES. The store, [tool_result_preview] envelope, budgets and paged reads live in the crate. |
required_output.rs |
Pure validate/repair/synthesize primitives (issue #4117) that guarantee a required structured-output block (for example a thoughts JSON block) on every accepted turn. The orchestration that calls these lives on the session in ../session_host/turn/. |
credentials.rs |
scrub_credentials: regex scrubbing of credential-shaped text (key/value secrets, AWS access-key IDs, sk-... keys). Applied to every tool result by CredentialScrubMiddleware in agent/tinyagents/middleware/credential_scrub.rs, installed as the innermost tool wrap so nothing downstream sees the raw secret. |
Public surface
What harness/mod.rs actually re-exports:
AgentDefinition,AgentDefinitionRegistry,DefinitionSource,ModelSpec,PromptSource,SandboxMode,ToolScope: the sub-agent archetype data model. Sandbox policy lives on the explicit host operation context. Briefing task recency belongs to ``OpenHumanRunExt(agent/tinyagents/host/run_context.rs).artifact_offload::{...}: reached only via theartifact_offload::path (see Notes), never flattened intoharness::.
Adjacent public surface that lives in sibling modules, not here:
OpenHumanSessionHost/SessionHostBuilder/TurnOverrides and the Agent
turn lifecycle are in ../session_host/; OpenHumanSubagentHost,
SubagentRunOptions, and SubagentRunError are in ../subagent_host/;
LastTurnUsage/SubagentUsageEntry are in ../tinyagents/host/run_context.rs.
Dependencies
tinyagents_harness(vendored viavendor/tinyagents/): the tool loop itself (TurnSpec::run), therun_queueandartifactsprimitives this module wraps, and theInMemoryStoreused as the tool-result artifact index.tinytools_agent(also vendored): the tool-call parsers themselves (<tool_call>tags, fenced blocks, bare JSON,<invoke>XML, GLM grammar, p-format). This crate is a test-only dependency ofharness/; the parsers are not called from production code here.crate::agent_registry::agents: built-in agent archetype TOML/prompt bundles; custom bundles are loaded bytinyagents_definition.crate::security::SecurityPolicy: workspace containment policy plumbed intoartifact_offload::new_artifact_offload.tinymemory-api: provenance classification and untrusted-context wrapping.crate::memory: text sanitization (artifact_offload::SanitizingRedactorwrapsmemory::safety::sanitize_textfor both artifact stores).crate::config::AgentConfig,crate::skills::Workflow,crate::tools::{Tool, ToolSpec}: inputs consumed by the session and sub-agent hosts.
Used by
../session_host/and../subagent_host/build turns from the definitions and prompt data this module supplies; parent context types are owned by../subagent_host/.agent/bus.rsserves theagent.run_turnnative request throughrun_channel_turninchannels/runtime/turn_driver.rs; channels reach it through that bus.channels/runtime/dispatch/routing.rsconsultsAgentDefinitionRegistry/ToolScope.agent/tinyagents/middleware/credential_scrub.rscallsharness::credentials::scrub_credentialson every tool result.agent/orchestration/tools/*(spawn_subagent) call into../subagent_host/and take its parent context explicitly.
Tests
- Unit:
harness_tool_call_parsing_edge_case_tests.rs, plus*_tests.rsfiles beside each sub-module (tool_result_artifacts/mod_tests.rs,artifact_offload/artifact_offload_tests.rs). - Integration:
tests/in_process/agent_harness_public.rs,tests/agent_harness_e2e.rs.
Notes / gotchas
artifact_offload/mod.rsand../subagent_host/ops/runner.rscitedocs/specs/plan-agents.mdas the plan for moving durable state, the sub-agent graph, and offload mechanics onto TinyAgents primitives. That file is not checked into this repo, so the plan itself is not documented here, only the citations to it.artifact_offloaddeliberately has no flatArtifactKindre-export at theharnesslevel. It would shadowartifacts::ArtifactKindfor glob importers, so use theartifact_offload::path instead.- The
Agentstruct, its turn lifecycle, and transcript persistence used to live underharness/session/. That code has moved to../session_host/; this README describes only what remains inharness/today.
Related: docs/gitbooks/en/developing/architecture/agent-harness.md.