Noeta

English

中文

English

中文

Appearance

NoetaA Python runtime + SDK for agents that have to keep running

Drive an agent in your own process today; run the same agent on a multi-worker, multi-host pool tomorrow — without touching the agent. Every capability is a plugin, every model vendor is one line of wiring, and every run is durable enough to survive kill -9 and replay afterwards.

Quickstart (5 min)
Benchmarks
GitHub

Server-ready, not just a loop you call

Client.start_workers(n) turns the same process into a resident worker pool; point the store at Postgres and several hosts share one database with lease-fenced writes. The Engine is stateless, so scaling out is a storage swap, not a rewrite — and there is no daemon to operate and no HTTP hop.

Every capability is a plugin — including ours

The kernel ships zero capabilities. File tools, web tools, memory, browser, MCP, sandboxes, storage backends, and every provider adapter are built-in plugins reaching the kernel through one doorway. Your plugin rides the identical path; there is no privileged internal API you are locked out of.

Sixteen extension surfaces, declared as inert data

A plugin is a package with a static manifest, so Noeta can list and collision-check everything it contributes before importing a line of its code. Tools, agents, policies, guards, observers, MCP servers, and sandbox providers are all contributions.

Kill the process mid-task; it resumes

State is never held in memory — it is fold(events), recomputed from an append-only log, with a heartbeat-renewed lease making exactly one writer per task. The next worker seals the interrupted attempt and carries on from the last durable point, exactly once.

Waiting is free and first class

A task suspends for a human answer, a timer, a subtask, or an external event, and costs nothing while it sleeps. The wake is durable, single-worker, and delivered exactly once — a month-long approval loop is the same machinery as a five-second tool call.

Any model, enforced — not promised

Anthropic, any OpenAI chat-completions gateway, and the OpenAI Responses API sit behind one internal protocol that never names a vendor. Swapping endpoints is wiring, not a rewrite — the kernel is barred from importing a provider package, and the build fails if it tries.

In the top band of the public leaderboard ​

BenchmarkScopenoeta-agent main (Claude Opus 4.8)Field
Terminal-Bench 2.140-task stratified sample82.5% (33/40)public board spans 58.7%–83.8%
SWE-bench Verified15-instance subset86.7% (13/15)top ~79%, mid-pack ~66–77%

Run through harbor, the official Terminal-Bench harness, on the official datasets, scored by each task's own verifier. The agent is noeta-agent's main preset, assembled entirely from this SDK's public surface. Both rows are samples, labelled as such — see Benchmarks for the full methodology, exclusions, and re-runnable commands.

60-second taste ​

bash
uv pip install noeta-sdk      # noeta-runtime comes along as a transitive dep

Zero credentials, no network — drive one turn with the offline FakeLLMProvider:

python
from noeta.sdk import Options, query, LLMResponse, TextBlock, Usage
from noeta.sdk.testing import FakeLLMProvider

provider = FakeLLMProvider(responses=[
    LLMResponse(stop_reason="end_turn",
                content=[TextBlock(text="Hello from Noeta.")],
                usage=Usage(uncached=1, output=1))
])

result = query(
    Options(system_prompt="You are concise.",
            allowed_tools=("Read",),
            permission_mode="bypassPermissions"),
    goal="Say hello.",
    provider=provider,
    model="stub-model",
)
assert result.answer() == "Hello from Noeta."

Point it at a real model by swapping the provider — see Configure a provider.

Find your way ​

New here? Read the Quickstart, then Your first agent. Everything else is below.

Tutorials — learn by doing ​

PageWhat you get
Quickstart (5 min)Install, run one turn offline, read the event log it produced.
Your first agentA real agent with a custom tool and a permission gate.
CI integrationRun agents deterministically in CI, no API key needed.

How-to — solve one problem ​

PageUse it when
Configure a providerYou want a real model: Anthropic, an OpenAI-compatible gateway, or Responses.
Build custom toolsYour agent needs to call your own code.
Spawn sub-agentsA task should delegate part of the work and wait for the result.
Connect MCPYou want tools from an existing MCP server.
Write a pluginYou want to package tools, agents, or policies for reuse.
Deploy a workerTasks should keep running outside the process that started them.
Deploy with DockerYou are shipping the worker as a container.
Use a sandboxTool calls must run isolated from the host.
Multi-tenant memorySeveral tenants share one deployment and must not see each other.
Swap providersAn existing agent has to move to a different endpoint.

Concepts — understand the model ​

PageThe idea
All conceptsThe reading order, plus one line per concept.
Event sourcingWhy state is fold(events) and what that buys you.
Task modelTask is the only primitive: states, attempts, subtasks.
Engine & executionWhat one step does: lease, fold, compose, decide, dispatch.
Fold & snapshotRebuilding state from the log, and the snapshot that keeps it fast.
Wake & resumeSuspending on a human, timer, or subtask — and waking exactly once.
Guard vs ObserverWho can block a tool call, and who may only watch.
Composer & cacheHow the prompt is assembled in three segments to hit the provider cache.
Provider neutralityOne internal protocol, three adapters, no vendor inside the kernel.

Architecture — how it is built ​

PageCovers
OverviewThe guided tour of the whole system.
Packages & import rulesnoeta-sdk over noeta-runtime, one namespace, the rules that keep them apart.
State & writersState slices, the single-writer invariant, the versioned fold.
Extension planesSixteen surfaces across three planes, and how built-ins ride them.

Reference — look things up ​

PageContains
SDK API mapEverything importable from noeta.sdk, with links into the detail pages.
query / ClientThe two entry points, their arguments, and what they return.
OptionsEvery Options field and the permission modes.
Types & testingEvents, content blocks, results, and the offline test doubles.
Plugins overviewWhat a plugin is and how it becomes active for an agent.
Plugin manifestThe manifest shape, loading, and version pinning.
Plugin surfacesAll sixteen extension surfaces, one section each.
ToolsThe built-in tool catalog.
PresetsThe preset agents and what each is wired with.
WorkerLoopWorker pool API, leases, polling behaviour.
ComparisonNoeta next to other agent frameworks.
GlossaryEvery term, grouped by domain, with an A–Z index.

Operations — run it in production ​

PageAnswers
TroubleshootingSymptom, cause, fix for the failures you will actually hit.
Known limitationsWhat Noeta does not do yet, stated plainly.
BenchmarksHow an agent built on Noeta scores on public benchmarks, and how that was measured.

Released under the Apache License 2.0.

Copyright © 2025–2026 Noeta Contributors