DEV Community: rebornace

Freeze a Real Run into a Corpus: How Baize Scores Agents with Deterministic Evidence

rebornace — Wed, 28 Oct 2026 01:51:36 +0000

Judging an agent by "how good the final reply sounds" is rarely enough.

What teams actually worry about happens at the tool-call layer. After changing a prompt, swapping a model, or tweaking a tool, the replies may look better while the agent quietly starts to:

hit "approve" on a ticket it hasn't fully read;
call a write endpoint it should never touch;
run "check inventory, then place order" in the wrong order;
trigger an action twice — or, when it should act, do nothing at all.

None of that shows up by reading the streaming reply. Baize evaluates agents on the tool-call timeline instead: not what the model said, but what it actually did — and by default the scoring is deterministic code rules, not an LLM judge.

1. The corpus comes from real runs, not hand-written fixtures

The first step of evaluation is not writing test cases out of thin air — it is turning real runs that already happened into replayable corpus.

A run leaves a complete event stream in the runtime (tool calls, tool results, human waits, etc.). Baize exposes an online sampling pipeline in the settings page:

Find candidates: filter historical runs by time window, run status, duration, and whether they contain a certain event type. The store fetches up to about 500 rows in one pass; after filtering, roughly the first 100 are kept as the candidate pool (current defaults, adjustable via page/API parameters).
Sample deterministically: sort candidates by a stable hash of seed + run ID, take the first N — about 10 per batch by default, hard cap 20. The same seed always picks the same batch, so the corpus is reproducible instead of jittering every run.
Ingest into a case: freeze the run's full event stream plus its input snapshot into one evaluation case (EvalCase). The same run is ingested only once by default; repeated sampling skips it, and you can explicitly replace when needed.
Fill in expectations: a case enters as a draft; once you state what this run "should have done," it upgrades to confirmed — and only confirmed cases are scorable.

What gets collected this way is not made-up toy dialogue but paths that actually ran in production — the tickets to read, the approvals to go through, the downstream calls that matter, all still in the events.

The same "assertion contract" has two more entry points that share the same scoring semantics:

EVAL.yaml next to a skill's directory, for live evaluation of the skill;
the repo script scripts/evidence-eval, for offline replay or CI.

The rest of this article follows the settings-page corpus as the main line and ties all three entry points together at the end.

2. A case is a set of behavior assertions

The core of a case is not a "reference answer text" but a set of assertions about tool behavior (fields use snake_case in JSON/YAML):

Dimension	Field	Meaning
Required reads	`required_reads`	Read-only tools that must have succeeded before any write
Consequential	`consequential`	Side-effect actions that must occur; "any one of" via `expect_consequential_any`
Chain	`chain` (V2)	"A must succeed, then B must appear afterwards"
Forbidden tools	`forbid_tools`	Tools that must never be called
Arg contains	`arg_contains`	A tool call's arguments must contain a certain substring
Downstream state	`expect_state`	Compare against a downstream ticket snapshot (or a live state check) at scoring time

The safety principle is simple: read first, then write. Before a side-effecting write happens, the read-only queries it depends on must have completed successfully.

When filling expectations in the UI, protocol version, required reads, and consequential are enough to score; finer assertions — forbidden tools, arg contains, chain, downstream state — can be maintained in the exported JSON or updated via the management API.

One note on the chain fields: the pair is named after / before, with the semantics — after must succeed first, and then before must appear later on the timeline. before here is a code field name, not "happens before" in the literal sense.

3. Scoring: rebuild the tool timeline from the event stream

Scoring does not call an LLM judge. It re-assembles the frozen event stream into an ordered tool-call timeline:

llm.tool_call: register one call (name, arguments);
tool.result: attach that call's result and whether it errored;
hitl.waiting: mark that it was waiting on human approval.

Then assertions are applied to the timeline one by one. Whether a run passes comes down to whether any failure code fired:

Code	Trigger (plain language)
`BSR`	Required reads were not all done
`PAR`	Acted before reading, or wrote in a read-only scenario
`NO_ACTION`	None of the expected consequential actions happened
`MULTI`	More than one consequential action (mainly V1; one is usually expected)
`GAP`	Chain broken: the required "A then B" order did not appear
`FORBID`	A forbidden tool was called
`ARG`	Tool arguments missed the required content
`STATE`	Downstream ticket snapshot missing or mismatched
`BAD_PROTOCOL`	Unrecognized protocol version
`TIMEOUT`	The run status used for scoring was marked as timed out

Pass = zero failure codes. The same events plus the same assertions always produce the same score: no judge-model noise, no scoring tokens consumed, safe to replay inside any automation or CI.

Optionally, a confirmed case can run a live state check: read-only fetch of the current downstream ticket snapshot (mock or real), compare against expectations, and re-score — useful when you want to verify the latest state on top of a snapshot.

4. Assertion protocols follow business maturity

A case carries a protocol version (V0 / V1 / V2), with strictly increasing strictness:

V0 (read-only probe): all required reads must complete, and no write action may occur — checks whether this scenario is being treated as a pure query;
V1 (behavior closure): at least one expected consequential action must fire; no acting before reads, no multiple consequentials;
V2 (ordering constraints): on top of V1, add chains, e.g. "check inventory before creating an order."

The same corpus can be cut to a stricter protocol as the business grows from read-only guardrail to side-effecting closure — the assertions tighten with it.

5. Making the automatic scorer itself trustworthy

Deterministic scoring is not born correct. Baize adds a human calibration layer:

For each already-scored confirmed case, a human can mark "agree / disagree" and leave a note; the system aggregates an agreement rate (fraction where the automatic verdict matches the human one). After tightening or relaxing the scoring rules, watch whether this rate drops — the automatic scorer itself is under continuous review.

6. In practice: sample in the UI, export the results

It is lightweight: pick the time window and filters in the settings page, choose draft mode or a template-driven score mode, and one batch ingests a set of real runs into corpus. Draft mode only collects; you fill expectations and score later. With a template, you can score immediately — suited to when you already know what "this kind of failure" looks like.

Each case also exports to JSON with the same semantics as evidence-eval (case assertions + event stream in one package) for offline replay in external scripts or CI. The repo's PowerShell script splits case and events by its input parameters, or you can reuse the same Go scoring logic directly.

From failed or half-successful runs, the settings page also offers skill-draft: turn the trajectory into a skill draft, then install it after human review — evaluation is not only scoring; it can also distill bad paths into reusable skills and conventions.

7. Three entry points, one evidence contract

Entry point	Best for
Settings "evaluation corpus"	Sample real runs, fill expectations, re-score, human review, export
Skill-side `EVAL.yaml`	Lightweight evaluation contract bundled with a skill, live-runnable
`scripts/evidence-eval`	Offline fixtures, scripted batch runs, local or CI

The common ground: judge the tool timeline, speak in failure codes, and by default don't use an LLM as the judge. After changing prompts, models, or tool routing, look at whether this corpus regresses first — far more stable than staring at a single reply.

Baize is a team-facing, self-hosted AI Agent runtime: a single Go binary, MIT-licensed.

Source: https://github.com/rebornace/baize
Docs: https://rebornace.github.io/baize

Turning "did the agent move wrongly" from eyeballing logs into a replayable, repeatable regression corpus with a visible human-agreement rate is how runtime behavior is actually held in line.

Restart-Safe and Duplicate-Free: How Baize Makes Long-running Agent Runs Resumable

rebornace — Mon, 26 Oct 2026 02:47:28 +0000

An agent Run is not a single HTTP request. It can:

call a dozen tools in a row and run for several minutes;
hit a write action that needs human approval — and that wait can last hours;
be triggered by a schedule, e.g. a daily 9 AM summary;
after grouped subtasks are enabled, spawn a bounded number of group-scoped child runs (one level only), isolating the tool surfaces and approval flows of different business systems;
after finishing, push the result back to IM or call back a business system.

Along this chain, processes restart, scale out to multiple replicas, downstream APIs time out, and browsers disconnect. If a Run were just a goroutine in memory, a pending channel, then any hiccup would either lose the task or run it twice.

Baize handles this class of runtime reliability in the runtime layer. The core idea is one sentence: make a Run a first-class row in the database, not a goroutine in memory. The queue and workers can restart at any time or scale out freely; "no loss, no duplicate" is guaranteed by database state, leases, and a few background daemon loops.

The numbers here (8 workers, a 60s lease, etc.) are current defaults and are configurable; the mechanisms do not depend on any specific cloud vendor or middleware.

1. Every trigger becomes a Job; the Run row is the source of truth

All trigger sources — chat, webhooks, IM channel messages, schedules, human approvals, child-run receipts — are unified into a single Job enqueued into the queue. Think of it as a work order asking the runtime to do something. There are three job types:

Type	What it means
Normal run	Start a chat turn, process a channel message, a scheduled trigger, etc.
Approval resume	A Run was paused on human approval (or login); once a human approves/rejects, continue it.
Child receipt	A child run finished and wakes its parent with a structured result.

At the same time, every Run has a row in the primary datastore, and the state machine can be read intuitively as:

(occasionally) queued → running → succeeded / failed / cancelled / rejected
running ⇄ waiting for external signal

A newly created Run from chat usually goes straight to running; queued mostly appears in crash recovery and re-enqueue scenarios. The important state is the middle one: waiting for external signal (internal name waiting_human). Whether a write needs approval, a downstream login is required, or a parent is waiting for a child receipt, the Run enters this single suspended state; the reason (approval / login / child receipt) is stored in the suspension payload instead of being split into many incompatible state names.

Workers pull Jobs off the queue with a default concurrency of 8. The queue, event bus, rate limiter, primary datastore, and blob storage all go through swappable drivers: implement the unified interface, register it, and change the driver name in config. The built-in drivers are:

Primary datastore: SQLite by default, plus Postgres and in-memory;
Queue / event bus / rate limiter: in-memory by default, Redis for multi-replica setups;
Blob: local files, S3, in-memory.

The architecture is not tied to any particular database or message middleware. If a team already runs MySQL, Kafka, etc., they can extend the same driver contract without touching the orchestration core — the built-in implementations are "a subset that works today," not an upper bound.

One design tradeoff runs through the whole article: the queue only carries delivery; it is not the source of truth. The Run row in the primary datastore always is. All recovery logic reduces to "query the DB, change state, then re-enqueue."

2. Lease + heartbeat: how one Run executes exactly once across replicas

After scaling out, the same Job may be visible to multiple replicas at once. Baize uses a database lease for atomic claiming, not an in-process lock in the worker. Before actually starting, the executor tries to "lease" the Run, semantically equivalent to:

UPDATE runs SET lease_until = now + ttl
WHERE id = ?
  AND status IN ('queued','running','waiting_human')
  AND (lease_until IS NULL OR lease_until < now);

The update only matches when the lease is empty or already expired, so only one claim succeeds. Default parameters:

Lease TTL is 60 seconds;
During execution, a heartbeat renews it roughly every 20 seconds (one third of the TTL), proving "I'm alive and still running";
The lease is released when execution finishes;
If claiming fails (another replica holds a valid lease), the worker skips it and does nothing.

Result: even if the same Run is delivered to multiple replicas due to re-enqueue, only one actually executes it.

3. Reconciler: orphan Runs auto-resume after a worker crash

When a worker crashes, the Runs it claimed may still be stuck in running, with the lease still under its name. A reconciler covers this.

On startup it runs one scan immediately, then scans roughly every 15 seconds. Each round:

Finds orphan Runs still in queued/running whose lease has expired (or whose creation is more than about 30 seconds old and unclaimed);
Re-enqueues a "normal run" job for each orphan;
Handles about 100 per batch, leaving the rest to the next round.

The 30-second grace window avoids catching normal Runs that were just created and not yet claimed, reducing false positives.

Note: Runs stuck in "waiting for external signal" are not treated as orphans and forcefully re-run — they are waiting for approval, login, or a child receipt and go through dedicated resume jobs.

Why is there no double execution? Two layers:

A healthy running Run keeps heartbeating its lease, so the reconciler never picks it up;
Even if something is re-enqueued in an extreme case, the execution entry has three gates: already in a terminal state → skip; waiting on a human but received a normal-run job → skip; failed to acquire a lease → skip.

Effect: after a process crash, the task usually resumes from its DB breakpoint within one reconcile cycle, without double-starting.

4. Shutdown doesn't kill in-flight work; approvals survive restarts

What happens to in-flight Runs during a deploy restart?

Each Job runs on an independent context, deliberately not tied to the "pull new jobs" lifecycle. On shutdown, the worker stops taking new work first and allows about a 5-second grace window: short jobs finish if possible; Runs long-paused on approval may lose their in-process wait goroutine, but the row in the primary DB still says "waiting for external signal." After restart, a cold-recovery path reconnects, rather than depending on a goroutine that lives forever.

Human approval is the most extreme wait in long tasks — it can span hours or days. Baize covers it with two paths:

Same-process hot path: while someone is still waiting for this Run on this host, an approval wakes it directly without re-acquiring a lease;
Cross-restart cold path: the process has changed and the in-process waiter is gone; the approval is re-enqueued as an "approval resume" job, which acquires a lease and continues from the suspended state in the DB.

After grouped subtasks are enabled, the parent also enters "waiting for external signal," with the reason being "waiting for a child receipt"; when the child finishes, a "child receipt" job wakes the parent. Child runs are an optional, one-level-only capability, with a concurrency cap on active children per parent (the current implementation allows at most 2 active child runs) — meant to isolate different business systems' tool surfaces and approvals, not to grow into an infinite fan-out of generic sub-agent trees.

Also, when entering a human wait, the worker releases its slot: it no longer holds a worker slot idle, leaving concurrency for tasks that can still make progress; after the human approves, the run cold-resumes.

Every job is wrapped in panic recovery on the outside: success, failure, and errors all ack the message, so a poison message never jams the queue.

5. Frontend disconnect doesn't lose the stream: numbered, replayable events

A long task is streaming: thoughts, tool calls, and incremental text are continuously emitted. Backgrounding a tab or network jitter can drop the SSE connection.

Baize writes every event to an event table, and each frame pushed to the frontend carries a monotonically increasing sequence number. On reconnect:

It prefers the standard Last-Event-ID header, and also supports ?after=N;
It replays the missing events in order from that sequence number;
When the Run reaches a terminal state, one final end frame is emitted.

Between replicas, a lightweight event bus carries only a wake-up nudge ("this Run has new events") — never the payload. The payload is always re-read from the primary DB by sequence number, so any replica can continue serving the same Run. A lost nudge is harmless: reconnect or periodic fallback fetch still fills in by sequence number.

Refreshing the page, reconnecting, or even landing on a different replica — the process and results are never lost.

6. Scheduled tasks: periodic triggers without duplicates or missed cycles

Chat scheduled tasks (once / daily / weekly) are essentially unattended long-task triggers. Each task is persisted in the DB with state (active / paused / completed), the next fire time, and a placeholder field for "which run is currently in flight."

The schedule scan runs roughly every 15 seconds; on startup it first clears stale "placeholder intermediate states" left by an abnormal shutdown, so a fake placeholder never blocks later cycles. Each round does three things:

Release terminal placeholders: if the run pointed to by the placeholder has finished, free the slot, so a long-completed Run never blocks future cycles forever;
Advance periodic time: for daily/weekly tasks, even if the previous round is still running, once the next time point arrives, advance "next fire" forward first — avoiding a backlog storm after a long task ends;
Atomically claim due tasks: use a conditional update to grab a task that is "due and idle," then start a new Run. Once-only tasks are marked completed; periodic tasks write back the next time.

The supporting fallbacks also live in the DB: failing to start a Run releases the placeholder and records the error; times are computed in IANA time zones; each account has an active-schedule cap (default 20). Atomic placeholders, terminal release, and startup cleanup work together to prevent duplicate triggers at the same moment, and to ensure a crash never permanently skips a later cycle.

7. Result delivery: the transactional outbox and backoff

When a Run finishes, the result must be pushed back to IM or a business webhook. If the process crashes between "generating the reply" and "sending the HTTP request," or the downstream returns a temporary 5xx, the message must not be lost.

Baize uses a transactional outbox for channel outbound: it first writes the message to an outbox table keyed by an idempotent delivery key, then a separate deliverer sends it — generation and delivery are decoupled.

The deliverer pulls a batch of due messages every second (or when woken), about 20 per batch:

A 2xx response → marked delivered;
Network errors, 429, 5xx → exponential backoff (1s, 2s, 4s… capped around 60s) then retry;
Non-retryable errors, or exceeding the max retry count → dead letter, resettable manually in the UI to redeliver.

Large objects like images and attachments are written to Blob first (local files by default, switchable to S3; also a swappable driver), and the outbox stores only the reference — never stuffing binary into the queue table. Business-side webhook notifications have the same reliable delivery and backoff. HTTP plugin callbacks write their events back to the Run's trail through the event-persistence path, which is a separate line from the channel outbox — both emphasize "persist first, then send outward," but they should not be mixed into the same box.

8. The engine layer also holds context for long tasks

So far this is the runtime: don't lose tasks, don't double them, don't block the process while waiting. Long tasks have another side — long conversations, huge tool results, occasional model timeouts — which is handled mainly in the execution engine, orthogonal to the queue/lease and equally transparent to business code:

When turns pile up, do rolling summaries, and optionally project "key points of the long conversation" (only changing what the model sees as input, not the original messages);
Especially large tool results or pastes can be offloaded to the session workspace, so the model side only gets a preview and a path, reading back segments on demand;
Model-call failures retry and fall back; tool timeouts can be split; read-only tools in the same turn run in parallel;
Human waits release the worker slot (see section 4), so one approval doesn't fill all concurrency.

The two layers fit together as: the runtime guarantees "this task still exists and can resume"; the engine guarantees "it can resume, and the context holds."

9. One table: failure scenarios and their guards

Failure scenario	Mechanism	Result
Same Run seen by multiple replicas at once	DB-backed CAS lease	Only one replica executes it
Worker crash, Run stuck in `running`	Lease expiry + periodic reconciler scan	Auto re-enqueued and resumed
Deploy / process shutdown	Job-independent context + short grace + DB source of truth	Short in-flight jobs finish; long waits recover from DB
Process restart during an hours-long approval	Suspended state persisted + approval-resume job	Continues from the breakpoint
Parent restarted when a child finishes	Suspended state persisted + child-receipt job	Parent/child results not lost
Browser disconnect, refresh, replica switch	Event sequence + reconnect replay (plus fallback fetch)	Process and results not lost
Crash at the moment a schedule fires	Atomic placeholder + startup cleanup of intermediate state	No duplicates, no missed cycles
Downstream 5xx / timeout / rate limit	Outbox + exponential backoff + dead letter	Outbound replies not lost
Unparseable poison message in the queue	Deserialization failure acks directly	Never blocks later jobs

10. Reliability lives in the runtime

These mechanisms are mostly transparent to the people writing agents and configuring skills on top: they face chat, tools, and approvals, without having to write their own retry, recovery, and dedup.

A single machine can use the default SQLite and get "restart-resumable, wait-continuable" without first standing up a full middleware stack. When you need to scale out, switch the queue/event bus to the existing Redis driver, switch the primary DB to Postgres, or extend the driver contract to the team's own databases and messaging systems — the same execution code still holds.

For team-facing agents, the real dividing line is rarely whether a single "think → choose tool → execute" loop works. It's this: when the agent is attached to real business systems, must wait for human approval, must run on a schedule, and must push results back across IM — after a process restart or a network hiccup, are the results still deterministic? Keeping these concerns in the runtime layer is what lets the upper layers focus on the business itself.

Baize is a team-facing, self-hosted AI Agent runtime: a single Go binary, MIT-licensed.

Source: https://github.com/rebornace/baize
Docs: https://rebornace.github.io/baize

More runtime internals will follow, including a replayable evaluation corpus.

Two Paths to Take an Agent Runtime onto Mobile: a Remote Console and an On-Device Go SDK

rebornace — Sat, 24 Oct 2026 14:19:44 +0000

Project: Baize — a team-facing AI assistant runtime (Go 1.25+, MIT)

Repo: https://github.com/rebornace/baize

This is the follow-up to From a Single Agent Loop to an Auditable Runtime: Baize's Architecture. That post covered the server-side runtime; this one focuses on the two mobile paths.

Baize is a single-process Agent runtime written in Go that sits alongside your business systems, consolidating the LLM, tools, legacy HTTP APIs, and human checkpoints into auditable runs. Once the server side was stable, mobile was not built as a simple mobile web page. Instead, Baize offers two paths: one uses a Capacitor shell to remotely control the full console, so you can approve work on the go with zero development; the other compiles the Go orchestration core into an Android AAR and an iOS XCFramework via gomobile, so the conversation runs on the device and the UI is drawn entirely by your own app. This article walks through the actual code: how the two paths divide the work, the key and approval design of the on-device SDK, and how to choose.

1. There are actually two kinds of mobile demand

Before building anything for mobile, it helps to separate the requirements, because they point at two different problems.

The first kind is internal teams and operators handling things on the go. They need to read conversations, do human approvals, change settings, and deal with logins from their phone — essentially "carry the desktop console in my pocket." In this scenario the conversation engine, connectors, and approval flow are already running stably on the server; the phone only needs an entry point, not a second implementation.

The second kind is embedding Agent capabilities into your own product. These teams want a branded, native UI, with the conversation and tool loop running directly on the device and less dependence on an always-on sidecar, and they have their own requirements for UI and key management. Here the phone is not a remote control — it is where the capability lives.

The two demands differ in who owns the UI, where the code runs, and the integration cost. Forcing them into a single path would leave embedders stuck with a generic page, while operators who just wanted mobile approvals would be forced to build a native UI. Baize therefore splits them into two paths, each handling one side.

2. One diagram: the two paths

Path A is a remote-control console: the phone shell does not run a conversation engine, it loads the full remote console from the same origin. Path B is the on-device SDK: the Go orchestration core is compiled into the app, the UI is drawn by the app, and the conversation runs on the device. Let's expand each in turn.

3. Path A: a thin shell, the full console with zero development

Path A is deliberately light. You can open the reachable /ui directly in a mobile browser, or use the Capacitor project in the repository to wrap a WebView and build an Android or iOS app.

The shell loads the remote console from the same origin: once you configure the server address, the WebView simply opens the remote /ui. Conversation, settings, human approvals, connectors, MCP, messaging channels, and browser login are all identical to the desktop — nothing is lost by moving to the phone. The only things the shell handles itself are mobile nuisances: the safe area, the keyboard, and opening login pages in the system browser.

There is one deliberate choice here: the shell loads the remote /ui from the same origin by default rather than proxying another layer of HTTP inside the shell. Conversation and approval depend on server-pushed events (SSE); adding an HTTP proxy inside the shell would buffer those streaming responses and break the experience of messages arriving one by one. Loading from the same origin keeps streaming replies and approvals smooth inside the shell.

From an architecture standpoint, the shell runs no conversation engine at all — it is, quite literally, a remote control. The integration cost is close to zero: without writing any mobile code, the team gets the same operational capabilities on a phone as on desktop. The only deployment detail is that the public address must be reachable from the phone — the phone talks to the server address, not the localhost loopback on your computer.

4. Path B: compile the Go orchestration core into the app

Path B answers a different need: embedding Agent capabilities into your own product, with a native, branded UI.

Baize compiles the Go orchestration core into an Android AAR and an iOS XCFramework via gomobile, and exposes a binding-friendly public API (the binding package is mobileagent). There is a real engineering detail here: gomobile cannot bind Go internal packages, so Baize re-exports the binding-friendly interfaces from a separate top-level package, while the internal implementation stays under internal. The binding layer only surfaces the handful of methods an app actually needs.

What runs on the device is a slimmed-down, OpenAI-compatible conversation and tool loop. The division of work between the app and the SDK is clear:

The app owns layout, theming, the history list, the input box, and the approval card; it owns secure storage of keys and the remote-config fetch strategy; and it owns thread management (network calls must not block the main thread).
mobileagent owns the session, the conversation, the tool loop, and the pause/resume of approval. Every result is returned as a JSON string, and it never touches any UI.

The call surface is intentionally small:

Configure sets the model endpoint, key, and model name once.
Send runs one conversation turn and stops when it hits a tool that needs approval.
Approve and Deny handle the two approval decisions.
ChatOnce does a single-turn connectivity test without tools.
Reset clears the in-memory history.
NewAgent creates an independent session.
MessageCount returns the number of messages.
HasAPIKey reports whether a key is already held in memory.

5. Why the on-device SDK is slimmed down

The on-device SDK deliberately does not move the full server-side runtime into the phone. On the device it keeps only an in-memory session and a minimal tool surface: today there are two tools, get_time and http_get. get_time executes directly and returns the time, while http_get must pass human approval first. The full connector set, MCP bridging, messaging channels, and the operational approval product surface stay on the server Runtime.

This is a division of labor, not a capability cut. The server Runtime is aimed at "connect many systems and keep operating them as a team," which requires the full connector, audit, and operations surface. The on-device SDK is aimed at "close, light, embedded in your own product," which needs a controllable conversation loop and a minimal tool set. Keeping the two separate makes the on-device component small and controllable and leaves teams free to draw their own experience on top; when the full capability is needed, the app can always fall back to the server Runtime.

The tool loop itself has a boundary: a single turn's tool loop is capped at a fixed number of rounds (currently 8). When it reaches the cap, it ends and returns, so the model cannot loop forever on the device. The session and keys live only in memory and are never persisted in the Go binding layer — they are cleared on reset or exit.

6. Keys go to the system safe, not the Go package

There is one explicit rule in the on-device design: the Go binding layer only holds the key in memory and never writes it to disk. Anything that needs to persist is handed to the native safe provided by the app's platform.

On Android, the sample uses EncryptedSharedPreferences. The master key uses the AES256-GCM scheme, with keys encrypted with AES256-SIV and values with AES256-GCM. What gets stored includes the model endpoint, key, model name, and config endpoint, and there is a separate method to clear the key. On iOS, the equivalent is the Keychain, stored by service name and account name, and restricted to this device only and available after first unlock.

The flow is: when the app starts (or needs the key), it reads the key from the system safe, then injects it into the on-device runtime's memory via Configure; the Go binding layer never handles persistence. The reason is that a cross-platform Go binding cannot guarantee the security level of key storage, whereas EncryptedSharedPreferences and the Keychain are the security boundaries the platform actually endorses — hardware-backed or managed by the system as a whole. The binding does not overstep into storage it cannot do well; it hands security to the platform, and the app fully owns the key lifecycle.

7. Foreground human approval: a JSON status protocol

Human-in-the-loop on the device is expressed through a simple JSON status protocol. The return values of Send, Approve, and Deny are all JSON strings that the app parses to decide what to render:

done: the turn is finished; the UI shows the reply in the text field.
needs_approval: a tool is waiting for approval, carrying call_id, name, args_json, and summary. The app renders an approval card from these; approving calls Approve with the call_id, and rejecting calls Deny. Until the user makes a choice, no new Send should be issued.
error: execution failed; the UI shows message.

The approval summary is a single human-readable sentence. For http_get, it produces the method ("GET") plus a truncated URL, so on a phone you can see at a glance what the app is about to call.

The http_get that requires approval is a read-only tool, but even though it is read-only, Baize still requires explicit approval and adds a set of guardrails when it runs: only http and https are allowed; requests have a timeout (currently 15 seconds); redirects are capped (currently 3); the response body has a size limit (currently 256 KB, and anything larger is truncated and marked); and the result carries the final address (final_url) so you can verify where a redirect actually landed. Rejecting fires no network request at all and simply lets the conversation continue.

Narrowing what an on-device model is allowed to do is the core idea: keep tools read-only, require explicit approval for actions, and keep the network boundary clear — then on-device autonomy is contained within a safe range.

8. Remote config, multiple sessions, and desktop debugging

So the app does not have to hardcode the model endpoint and model name, the binding layer offers remote config: FetchRemoteConfig pulls JSON from a config endpoint you own, and ApplyRemoteConfigJSON merges that config into the in-memory session. The config can include the model endpoint and model name, and optionally the key. The fetch strategy is decided by the app; the SDK only applies it.

For multi-session scenarios, use NewAgent to obtain an independent instance rather than sharing the package-level default session. Each instance maintains its own history and pending-approval state.

You do not have to tether a phone during development. Baize ships a desktop debug entry point that runs the binding layer directly on your computer, and it includes a fake model so you can get the UI and approval cards working before swapping in a real model. When an Android emulator needs to reach the host machine, use the emulator's standard host address (10.0.2.2).

9. How to choose

The decision is straightforward:

If you want the full settings pages, connectors, and operational approval flow, and the phone is only a portable entry point, choose Path A.
If you want a branded native UI, the conversation running on the device, and less dependence on an always-on sidecar, choose Path B and draw your own UI using the empty shell in the repository as the calling sample.
The two can coexist: operators and internal teams use Path A, while the end-user-facing app uses Path B.

Closing

The two mobile paths are, at heart, separating two different problems: "the operator's portable console" and "the embedded on-device Agent." The former pursues zero development and full parity with the desktop; the latter pursues a native experience, on-device control, and a clear key boundary. The key decisions in the on-device SDK — holding keys only in memory, requiring approval even for read-only tools, giving network actions explicit guardrails, and keeping the session and tool loop minimal — all revolve around one goal: letting the capability run safely, and personally, on the device.

Baize is an open-source project under continuous development (written in Go, MIT licensed). The mobile Capacitor shell, the Android and iOS empty shells, the on-device bindings, and the corresponding build scripts are all in the repository.

Repository: https://github.com/rebornace/baize

Docs: https://rebornace.github.io/baize

If you are also putting Agents into production — especially if you are thinking about how to safely bring capabilities onto a phone — I'd like to hear how you handle mobile and key management. The full mobile getting-started guide and build steps will be covered in a follow-up post.

From a Single Agent Loop to an Auditable Runtime: Baize's Architecture

rebornace — Fri, 23 Oct 2026 15:32:37 +0000

Baize is a single-process Agent runtime written in Go that sits alongside your existing systems. Early on it was little more than a single "think, pick a tool, act" loop. As multi-client access, long-running tasks, connector groups, and other capabilities landed, the architecture converged onto five core abstractions: Runtime, Agent, Tool, Connector, and Run. This article walks through the current structure with one layered diagram: how the different entry points connect, the three execution forms of the Run engine, the three connector types with bidirectional MCP, and the runtime surface that makes every Run auditable, observable, and recoverable.

1. What it is: a standalone Agent runtime

To understand Baize's architecture, the first thing to be clear about is that it is not a library embedded inside your business application. It is a standalone Agent runtime that runs as a sidecar or gateway next to the systems you already have.

In one sentence: it consolidates the LLM, tools, legacy HTTP APIs, and human checkpoints into auditable Runs.

Concretely, it reads API documentation and turns existing system endpoints into capabilities the Agent can call. For write operations such as creating an order or changing a status, it pauses at the web console and waits for human confirmation before executing. The process is visible in the conversation or messaging channel, and full credentials never appear in conversation replay. Usually, no business code needs to change.

This shape gives it a few immediate properties:

Platforms and integrators connect over REST / HTTP, with no lock-in to any particular language (there is no official language SDK).
It is a single process with externalized configuration; once stopped, it leaves almost nothing behind on the business side.
The web console, mobile clients, messaging channels, and incoming alerts all share the same approval, memory, and outbound-reply surface.

Once the product grows from a single conversation loop into multiple clients, systems, and tasks, a straight-line flow can no longer cover everything. The layered diagram below shows the current shape of Baize.

2. The five core abstractions: Runtime, Agent, Tool, Connector, Run

The most fundamental change in the architecture is the convergence onto five abstractions: Runtime, Agent, Tool, Connector, and Run.

Runtime is the single process itself, responsible for orchestration, scheduling, and lifecycle management.
Agent is the carrier of conversation and policy; it understands intent, calls the LLM, and decides the next action.
Tool is a callable capability. Reading an order, checking inventory, or raising an approval are all, from the engine's perspective, uniform tools.
Connector describes how an external system is connected, how credentials are carried, and where its capabilities come from.
Run is one complete execution, and the most important abstraction in the system. It records everything a conversation depends on from start to finish — the model, the tool contracts, connector revisions, and human checkpoints — so it can be audited, observed, and recovered.

There is a deliberate choice here: Skills, Memory, Channels, and linear workflows are not promoted to a sixth core abstraction. They live as configuration or plugin forms, layered on top of the five.

The benefit is a stable core: adding a skill, integrating a channel, or defining a workflow does not require changing the Runtime kernel — it is all extension in the configuration and plugin layer. For a project that evolves over a long time, "a small, stable core with extension happening at the outer layer" is what allows it to keep adding capabilities without modules colliding.

3. The three execution forms of the Run engine

Of the five abstractions, the Run engine is where the actual work happens. One engine carries three execution forms, each matching a different kind of task.

The first is the single-Agent ReAct loop, which is the default. The engine advances as "choose a tool, execute, record the trajectory"; the model acts step by step as it reasons, deciding the next move from the previous result. It suits open-ended tasks where the goal is clear but the path must be judged on the fly — for example, "find out why this batch of orders is stuck, and fix the ones you can." When there are many systems, you can enable tool pre-filtering (the "smart acceleration" setting) so a shorter candidate list is handed to the main model; if that fails, it falls back to the full list.

The second is a linear workflow inside a Skill. When a process is a fixed sequence that can be designed up front, you write it into a Skill's workflow.yaml, and the engine executes the steps in order — each step optionally carrying a human approval. These are linear sequences with no branching or loops. It suits predictable, consistency-focused standard processes, such as "verify qualifications, create the order, then notify the contact." Crystallizing a deterministic process into linear steps reduces uncertainty during execution and gives every step a clear checkpoint.

The third is a connector-group sub-run (opt-in). Connector groups themselves only affect the candidate set during tool narrowing; they do not spawn sub-runs automatically. Once "allow sub-runs within a group" is enabled, the model can call spawn_group_run: it derives a sub-run exactly one level deep for a given connector group. The sub-run's tool surface is limited to that group's connectors, and it has its own run binding and its own approvals; the parent enters waiting_child and resumes when the sub-run reports back. Nested sub-runs are not allowed. This is for when business domains such as finance or transactions need their approvals not to collide — the emphasis is on isolation, with each domain's actions and approvals kept separate rather than two orchestrations running concurrently as parent and child. When the same turn only needs to fan out read-only investigations and aggregate results, that uses the engine's built-in parallel read-only calls instead, without consuming a sub-run.

All three forms sit on the same Run engine, the same trajectory, and the same audit model. You do not maintain two frameworks for "open exploration" and "fixed process"; you pick the form that fits the task. The default ReAct loop and the optional linear workflow and group sub-runs can be combined as needed, with group sub-runs always gated by the switch and the one-level constraint.

4. Connector as a first-class citizen: three connector types and bidirectional MCP

Baize is built for the reality of "many systems, a large share of them legacy," which is why connectors are first-class citizens. There are three standard ways to bring an external system in.

OpenAPI wildcard. Upload or point to an OpenAPI / Swagger document, and each interface operation becomes a tool. This is the most direct way to integrate legacy REST systems; names prefer the operationId, and credentials, login, and change comparison are all handled uniformly at the connector layer. If an enterprise already has its own execution entry point and does not want to implement full plugin discovery, it can instead configure an execution callback for the connector: the Runtime POSTs the tool name, arguments, and run_id to that endpoint, which performs the work — no need to implement the /v0/tools discovery endpoint.

HTTP plugin protocol v0. When the API document cannot cover some legacy logic, or a capability needs to be implemented on the business side, you write a small service (a sidecar Connector) that exposes three endpoints per protocol v0: a health check, a tool list, and a tool invocation. The Runtime calls it over the same network, carrying the run identifier, tenant identifier, and protocol version in the headers; how the capability is implemented is entirely up to the business side.

MCP bridge. Baize acts as an MCP client, connecting to an existing MCP Server and pulling its tools into its unified catalog. This lets MCP tools already in the ecosystem be used by Baize directly.

These three sources, together with manually maintained extra tools, are unified into the tool catalog (sources tagged spec, plugin, mcp, and extra). The engine and human checkpoints only read the enabled entries in the Registry; tool names across connectors are required to be globally unique, and the catalog API can still show disabled rows.

Worth calling out on its own: MCP in Baize is bidirectional. The MCP bridge above is Baize acting as a client to consume other services' capabilities. In the reverse direction, Baize can also act as an MCP server, exposing a read-only subset of its tool catalog through /v0/mcp/export to MCP-capable Agent clients such as Cursor and Claude Desktop. This path does not go through Baize's own LLM; it safely shares already-integrated business capabilities with external Agents. An export Key can bind identity slots by connector and role, with the permission boundary corresponding to the downstream business account. When downstream authentication fails, it first guides the user through hosted login rather than pasting a password into the conversation.

5. How a single Run is auditable, observable, and recoverable

Moving an Agent from a demo to long-term operation is not primarily about single-turn capability — it is about every Run leaving a trace, being observable, and being resumable. Baize provides a set of capabilities that work together at this layer.

Run binding (run.binding). Before the first main-model call, every Run records the model endpoint and profile in effect, the policy parameters, memory injection, the narrowed tool contract fingerprint, and the connector catalog revision. When you later trace the basis of a decision in that run, you get the real snapshot from that moment rather than the current configuration, which has since changed. Tool-call events carry the contract fingerprint and catalog revision, so you can compare directly before and after an interface fix.

Human-in-the-loop (HITL). Write operations can be marked as requiring approval; the Run enters a waiting state and resumes after an operator approves or rejects on a card. When a downstream system needs login, the conversation can pause and guide the user to log in via the browser, skip that system for the turn, or end the turn. Long tasks also release the slot while a gate is pending, so a single waiting approval does not tie up a worker thread for the whole Run.

Long-task resilience. For long-running task stability, the engine combines step-budget wind-down, retries and fallback after LLM call failures, timeout splitting, and parallel read-only tool calls. Within a turn it also performs context compression, conversation retrieval, and skill archiving, so a task can keep its goal and continue after many rounds. After user confirmation, one-time, daily, or weekly scheduled instructions can be saved; when the time comes, a new round opens in the original conversation, and write operations still go through approval.

Context management. Long conversations get a rolling summary, and an optional "keep the key points of long conversations" projection changes only what the model sees without rewriting the original messages. Exceptionally large tool results or pasted content are offloaded to the session workspace's offload/ directory; the model only receives a preview and a path, and can read it back in sections with read_file when needed, instead of blowing up the context in one go.

Observability. Structured slog logging, Prometheus metrics, and optional OpenTelemetry tracing cover the Run and tool calls. After a connector is re-imported, the interface change comparison is returned and can be pushed asynchronously via Webhook. Most of these observability options can be viewed and hot-reloaded from the settings page, without editing the config file and restarting each time.

Each piece of this layer deserves its own article; here it is only positioned within the overall architecture, and later posts will expand on them one by one.

6. The second client beyond the server: two mobile paths

Once the Runtime was reliably carrying the server side, mobile was not implemented as a simple mobile web page. Instead, there are two paths with different positioning.

Path one: remote-control console. Open the reachable /ui directly in a mobile browser, or use the Capacitor shell in the repository to wrap a WebView that loads the remote console. Conversation, settings, approvals, and browser login are identical to the desktop. The shell does not run a conversation engine; it effectively turns the phone into a remote control, which suits internal teams integrating with zero development.

Path two: on-device SDK. The Go orchestration core is compiled via gomobile into an Android AAR and an iOS XCFramework (the public binding package is mobileagent) and linked into your own app. On the device it runs a slimmed-down conversation and tool loop with foreground human approval. The app holds the keys and places them in OS-backed secure storage (such as the iOS Keychain or Android encrypted storage), then injects them into the on-device runtime's memory; configuration can be synced from a remote endpoint, and the UI is drawn entirely by the integrator. This path deliberately does not ship the full baize serve stack into the phone — there is no connector farm, MCP, channels, or full HITL product surface; it focuses on in-memory conversations and a small tool set. It suits teams that want to embed Agent capabilities into their own product and have their own requirements for UI and key management.

The two paths do not replace each other: one is a portable entry point to the full console, the other is on-device capability embedded in a self-built app. The full mobile getting-started guide and build steps will be covered in a later post.

7. Storage and deployment

Baize uses a single process with externalized configuration. The main database, middleware (task queue / event bus / rate limiter), and Blob storage all use pluggable drivers: implement the unified interface, register it with RegisterDriver, and select it by name with driver in the configuration, so the Runtime is not locked to any particular database or message middleware. The implementations built into the repository today are:

Main database: SQLite by default, with Postgres and in-memory implementations.
Task queue, event bus, and rate limiter: in-memory by default, switchable to Redis when scaling horizontally (multiple replicas).
Files and attachments (Blob): local files, S3, or in-memory.

Other databases or message queues (for example MySQL or Kafka) can be added under the same driver contract without changing the Runtime kernel — the extension surface is the driver layer, not the orchestration layer. On the model side, any OpenAI-compatible API is supported, and the decision model can run on local Ollama, which further lowers the deployment bar.

This combination lets the project evolve smoothly from "run it on one machine" to "plug into the team's infrastructure": it works with zero dependencies by default, and when you connect to existing team middleware you simply add or switch a driver. For messaging, IM channels are integrated through external adapters using declarative configuration; the repository ships reference adapter examples in the examples directory for you to deploy as needed.

Closing

The thread through this round of architecture evolution is clear: consolidate the LLM, tools, legacy interfaces, and human checkpoints into auditable Runs; keep the core abstractions few and stable; and let the frequently changing parts — skills, memory, channels, and workflows — extend at the configuration and plugin layer. The five abstractions, three execution forms, three connector types, and bidirectional MCP, along with the server Runtime and the mobile client, are all built around that thread.

Next, I'll write separate posts on the two mobile paths, long-task resilience, and the evaluation corpus, explaining the design trade-offs and implementation based on the actual code.

Baize is an open-source project under continuous development (written in Go, MIT licensed). Repository: github.com/rebornace/baize, site: rebornace.github.io/baize. If you are also deploying Agents and working on integrating legacy systems and keeping them running reliably over the long term, you're welcome to open an issue or share your own Agent runtime practices in the comments. I'll keep following up and documenting the architecture as it evolves.

TraceScope: Impact Analysis, Design Diff, and Crash Triage for DeepSeek Harness

rebornace — Sun, 11 Oct 2026 11:09:27 +0000

Open source · MIT

· GitHub:

rebornace/dsh-tracescope

· npm:

@rebornace/dsh-tracescope

(v0.3.2)

AI models are great at reasoning about code — but only when they're handed grounded inputs. In practice, most app-quality work never reaches a model: after a PR merges, the diff sits in Git, the design spec sits in Figma, the crash stack sits in a monitoring console, and someone has to gather and structure all of it by hand before an AI can say anything useful.

I built TraceScope to lower that barrier: a plugin for DeepSeek Harness (DSH) — DeepSeek's desktop agent environment with a sidebar-plugin system — that turns your Git diff, your design specs, and your crash feeds into structured, deterministic inputs, so the AI analysis you get back is grounded in your actual codebase. It runs in the DSH sidebar, and the same capabilities are exposed over MCP, so you can drive the whole workflow from Cursor, Claude Code, Codex — or any other MCP-capable agent.

Where this fits in your stack

Before the details, the honest positioning — TraceScope is not trying to replace the tools you already use; it sits next to them:

Visual regression (Percy, Chromatic) compares screenshots of your running app. TraceScope's design diff compares the design file itself against your code, statically — no build, no emulator, no browser session. It answers "does the implementation match the spec?" earlier than screenshot tools can.
Crash monitoring (Sentry, Crashlytics, Bugsnag) tells you that something crashed. TraceScope's crash analysis helps with the next step: matching the stack to your repo and drafting the fix direction. Today it wires into Firebase Crashlytics and Umeng U-APM; Sentry and others are on the roadmap (more below).
Impact analysis is the piece most teams still do by gut feel: "what does this change touch?" It computes the answer from the diff and the dependency graph instead.

The consistent design bet: everything that can be parsed is parsed deterministically, so the AI analysis you get is grounded in facts, not guesses. No model is needed to diff a design tree or resolve a stack frame; the model does what it's actually good at — reading your source and reasoning about what the change, the drift, or the crash means for your app.

The three pillars

Capability	Input	Output
Impact analysis	Stable ↔ candidate commits (local Git, or a hosted code-platform API)	Direct changes + static ripple, as a reviewable regression checklist
Design diff	Figma / Lanhu design links + code repository	Static UI-difference list + side-by-side highlight, AI-assisted write-back, issue submission
Crash analysis	Firebase Crashlytics / Umeng U-APM, or a pasted stack trace + code directory	Stack parsing, repo file hits, report, AI conclusion written back to the session

All three share one sidebar, one tracker configuration, and one MCP tool surface.

1. Impact analysis: "what's the blast radius of this change?"

Give it two commits — the stable baseline and the candidate you're about to release — and it computes:

Direct changes: the files that actually changed.
Static reverse-dependency ripple: who imports or references them, propagated to a configurable depth (default 2). This is a real impact-analysis pass over your dependency graph, not a file list with guesswork.

The ripple pass understands actual source languages: Kotlin/Java, Swift/Objective-C, Dart/Flutter, TypeScript/JavaScript, Vue, the CSS family, and HTML. Other languages still get a direct-changes list — just no ripple. The local-Git mode builds its index from commit objects, so it doesn't even need a readable working tree; there's a hosted-code-platform API fallback for setups where local Git isn't an option (that mode skips static ripple).

The output is a checkbox regression checklist with human-readable feature names (from a tracescope.modules.yml mapping, falling back to static titles, then heuristics), per-item notes, screenshots (up to 3 per item), Markdown/CSV export, and one-click issue submission to your tracker. It's the "what to re-verify before release" list, generated instead of remembered.

2. Design diff: "does the implementation match the spec?"

Design fidelity work today is screenshot-based: you run the app, capture it, and diff images. TraceScope takes a different route — it treats the design file as the source of truth and compares it to the code statically:

Page discovery covers Android (XML / Compose / View), iOS (Xib / SwiftUI / UIKit), Flutter, React Native, Harmony ArkUI, uni-app, Taro, Web (HTML / React / Vue / Svelte / Angular), mini-programs (WXML / AXML / TTML / Swan), and .NET MAUI XAML.
Layered comparison: L0 fingerprints the design page against code pages (or you pin the file manually / let AI re-match); L1 does attribute-level static tree comparison (DesignDoc ↔ DesignDoc) — geometry, colors and tokens, typography (with unit conversion across dp / sp / rpx / cqw), multi-layer shadows and blur, transforms, visibility, resources; L2 falls back to heuristics (copy, control counts) when there's no precise geometry tree; L3 hands the source-reading list and prompts to the AI and writes its conclusions back to the sidebar.
Depth is pluggable, not forked: a design-enrichment registry currently ships a full static layout engine for Android XML (viewport measurement, dependency-closure fingerprints, Adapter-bound list-item restoration, dynamic text projection). Other stacks get uniform attribute-level comparison; a sidebar toggle forces uniform granularity when you want speed over depth.
Design sources: Figma and Lanhu, both normalized into a single DesignDoc — the comparison pipeline doesn't care which tool produced the file.

Because it never needs a running app, the check is cheap enough to run on every screen you touch — not just the ones someone remembered to eyeball.

3. Crash analysis: "what is this crash, and where do I start?" (new in 0.3.x)

The newest pillar picks up where crash monitoring leaves off. It pulls crash / ANR lists from a provider — or accepts a pasted stack trace when no credentials are set — and analyzes them against your code directory:

Sources: Firebase Crashlytics and Umeng U-APM. No credentials set? Paste a stack trace and the whole analysis flow still works.
Filtering stays aligned with the console: the filter area is collapsed by default, and version / OS / device options are sourced from the same metadata the console uses — so you can only select what the console would actually return.
Local analysis: analyze parses the stack, matches frames to files in the code directory by name, and produces a summary with hit files and fix hints — no model call, fully deterministic.
AI write-back: "Analyze & write to session" creates an AI job and drops a prompt with a job ID into the current session; when the agent calls tracescope_publish_crash_analysis, the sidebar polls and auto-displays the conclusion. Manual write-back and paste fallbacks exist.
Issue submission: a dedicated crash body (optionally including the AI conclusion) goes to your tracker — GitHub Issues, GitLab Issues, a generic webhook, or Yunxiao (Alibaba Cloud DevOps).

Crash providers are registered through the same CrashProvider adapter contract as everything else — adding Sentry or another APM is a new adapter, not a fork of the main path (see the roadmap below).

MCP: the same engine, any agent

Everything above is exposed through @rebornace/tracescope-mcp. The execution layer is shared with the DSH host via @rebornace/dsh-tracescope/agent-api — host routes are thin wrappers, so behavior is identical whether you drive it from the sidebar or from a tool call.

There are 19 tools across the three pillars, grouped by workflow: impact (diff, impact analysis, manual-verification job creation and write-back), design review (snapshot, findings, page re-matching), and crash (probe, filter options, list, detail, local analyze, AI job creation, publish, job polling). Credentials can be passed as tool parameters or read from local config (~/.tracescope). The MCP surface is client-agnostic: the full list → analyze → write-back loop runs in Cursor, Claude Code, Codex — or any other MCP-capable agent — with or without the sidebar.

Architecture

@rebornace/tracescope-core        ← deterministic analysis engine (impact + design + crash parse)
@rebornace/dsh-tracescope         ← DSH plugin: Host API + sidebar UI + agent-api
@rebornace/tracescope-mcp         ← MCP server (same tool surface as the Host)
packages/.../design-enrichment/   ← per-stack deep-enhancement plugins

Two design principles worth calling out:

Deterministic floor, AI ceiling. Everything that can be computed is computed — the AI never hallucinates a diff or a stack match, because it never needs to.
No vendor lock-in. Crash providers, trackers, and design sources are all registry-based adapters (CrashProvider, TrackerAdapter, design-source normalization). Adding a new one doesn't fork the main path.

The plugin also self-updates without depending on a plugin marketplace: it checks npm latest through the Host and installs via the official plugin manager, with a visible update button and status card in the desktop UI.

Install & use

Node.js >= 20; the official DeepSeek Harness desktop app is recommended.
Install and open the TraceScope sidebar:

dsh plugin --profile desktop add @rebornace/dsh-tracescope

UI language (English / Chinese) follows the desktop app's setting.
Install from npm latest; community marketplace cards may lag behind.

A typical crash workflow: pick the source → save credentials → fetch the list → open a detail → analyze (local, deterministic) → analyze & write to session → the agent writes back the conclusion → submit the issue.

Platform coverage today — and where it's going

Honest scope: the adapter coverage is still limited, and it will grow toward the platforms teams actually use. The current wiring, and what's coming:

Extension surface	Currently wired	On the roadmap
Crash providers	Firebase Crashlytics, Umeng U-APM, pasted stacks	Sentry, Bugly, other APMs
Trackers	GitHub Issues, GitLab Issues, generic webhook, Yunxiao	Jira, Feishu / Lark, other ticketing systems
Design sources	Figma, Lanhu	MasterGo, other design collaboration tools
Code-stack adapters	Android XML (deep enhancement), iOS, Flutter, RN, Web, mini-programs, and more	more per-stack layout engines and list restoration

If you need a specific platform — your APM, your ticketing system, your design tool — open a GitHub Issue with the platform name, the auth method, whether a public API exists, and your typical use case. Clearly-scoped requests get prioritized. That feedback drives the roadmap order. The full roadmap lives in the repo docs.

Closing

TraceScope is open source under MIT, built to lower the barrier to applying AI analysis to app quality: impact analysis answers "what changed and what to re-check", design diff answers "where does the implementation drift from the spec", and crash analysis answers "what is this crash and where do I start fixing it" — from one sidebar, one tracker config, one MCP surface.

Try it, open an Issue for the platform you need, or send a PR.

Links

GitHub: rebornace/dsh-tracescope
npm: @rebornace/dsh-tracescope
Full guide: docs/GUIDE.md
Changelog: CHANGELOG.md
Feedback: Issues

Connect Your Business APIs Once, Share Them with Every Agent Client via MCP

rebornace — Sat, 10 Oct 2026 04:31:43 +0000

Project: Baize — a team-facing AI assistant runtime (Go 1.25+, MIT)
Repo: https://github.com/rebornace/baize

1. A very real pain point

When a team rolls out AI, one thing you can't avoid: everyone uses a different Agent client.

One person codes in Cursor, another uses Claude Desktop, another uses something else. Business API docs, login credentials, callback URLs — if you reconfigure them in every client, you end up wiring the same legacy system once in Cursor, then again in Claude Desktop, with credentials scattered everywhere. The day that legacy system changes its auth, you have to go fix each one.

Baize sits on the "wired up the business system" side of this problem. The OpenAPI doc is imported into Baize once, login is completed in Baize's console once, and write-approval is audited in Baize once. The remaining question is: how do you let the Agent clients your team already uses reuse this wired-up capability, instead of reconfiguring it all over again?

That's what MCP server export is for.

2. Where the decision happens, and where it doesn't

One thing to get out of the way: once Baize exports the tools, the decision is not on Baize's side.

The Cursor model in Cursor, Claude in Claude Desktop — they still decide for themselves "which tool to call this turn, with what arguments." What Baize exports is only two things: a tool catalog (name, description, parameter schema), and an execution channel for when those tools are called. Baize's own main model, ReAct loop, decision layer, memory, and context compression are all not involved in this export path.

The payoff is direct: the decision layer stays free to pick on the client side — whichever model you use in Cursor is none of Baize's business — while the execution layer stays centralized in Baize. Business API integration, auth, and approval are maintained in exactly one place.

3. Transport and auth

The export channel runs over the standard MCP Streamable HTTP, stateless. When a client connects, it sends a Bearer key in the request header.

On the server side:

Wrong key, or missing key → 401.
Keys are stored as hashes only, never in plaintext.
Each key maps to a separate export identity (e.g. "the one for Cursor" and "the one for Claude Desktop" are two different keys).
Keys can be revoked at any time; revoking one immediately disconnects that client.
The whole export feature has a master toggle; when off, all requests return 503.

"One key per identity" isn't ceremony — it's what makes the later login-state and isolation behavior possible.

4. "Read-only" isn't a slogan — it's four layers of hard constraints

The most common objection to exposing business tools to external clients is: what about writes? Baize doesn't just say "read-only" in marketing copy. It stacks four layers in the export policy:

Layer 1: HTTP tools only expose GET/HEAD by default. Before a tool is exported, Baize looks at its HTTP method. Anything that isn't GET or HEAD isn't exported, unless the tool is explicitly marked force_allow.

Layer 2: MCP-sourced write tools are hard-rejected. Baize itself also connects to external MCP servers as a client. Tools coming out of those servers — if their name or description contains insert, update, delete, drop, truncate, execute_write, and similar — are never exported, even if someone tries to force_allow them.

Layer 3: Tools that require approval are not exported. Write operations flagged in Baize as "need human confirmation before calling" (e.g. creating a record) simply don't appear on the export surface — because the export channel has no approval card, and exposing one would mean bypassing human review.

Layer 4: Policy is re-checked at call time. Tools pass policy once when they're registered into the MCP catalog, and again when they're actually invoked. That means if you disable or un-export a tool in Baize's backend, the next external client call fails immediately — no "catalog still lists it but it's already off" gap.

5. How login state is handled

This is the subtlest part of the export path. Legacy APIs require login. Credentials are configured in Baize's console, but when an external client (say, Cursor) calls a tool, whose login state does the call go out with?

Baize's approach: each export identity is bridged to a separate internal identity. It has its own session namespace (prefixed with mcp-export-id: plus the export identity ID), and every call is forced through that identity. Concretely:

You log in once inside Baize for the "Cursor identity" and configure its credentials.
When Cursor calls any tool with that key, Baize uses that identity to reach the legacy system.
The "Claude Desktop key" goes through a different identity, a different login state — the two never cross.

The user inside Cursor never sees the legacy system's login page; credentials are already maintained on Baize's side.

6. The actual usage path

Three steps:

Wire up the business system in Baize's console (OpenAPI doc import, login done, approval rules configured).
Create an export identity in the export settings and generate a key.
Plug Baize's MCP Streamable HTTP endpoint and the Bearer key into your Agent client (Cursor, Claude Desktop — any MCP-supporting client works the same way).

After that, say something in the client; the client model picks which already-wired Baize tool to call, and Baize handles execution and returns the result.

7. How this relates to the previous article

In the earlier post ("How I wired a ten-year-old Java legacy system into AI with zero changes"), MCP only got a short paragraph — the focus was how to bring a legacy system in without touching it. This article zooms in on the MCP server side: Baize doesn't just turn legacy systems into its own tools, it can also share those tools with whatever Agent clients the team already uses.

Putting bidirectional MCP together, Baize's position in the ecosystem is clear: on the way in, it can connect to external MCP tool servers and pull others' tools in; on the way out, it can expose its own wired catalog over MCP so the team doesn't reconfigure anything twice.

8. Closing

"Wire the business API once, let every Agent client on the team use it" sounds like just "sharing a tool catalog." Doing it for real means a pile of concrete questions: how to block writes, how to manage keys, how to isolate login state, how to make config changes take effect immediately. Baize converges those into three areas: export policy, key management, and identity bridging. The default is conservative (read-only, approval-gated things stay hidden, revocable); opening anything up takes an explicit action at each step.

This export capability is still evolving, and different clients support MCP at different depths. Try it out and open an issue — or tell me in the comments how your team connects business tools to your own clients. I'll keep iterating.

GitHub: https://github.com/rebornace/baize

Baize's Decision Layer: Pulling High-Frequency Judgments Out of the Main Model

rebornace — Fri, 09 Oct 2026 07:41:22 +0000

Project: Baize — a team-facing AI assistant runtime (Go 1.25+, MIT)
Repo: https://github.com/rebornace/baize

Before we start, four names in this article map directly to the product UI, so let's align them:

Name	What it does
Main model	Writes replies, calls tools. This is where most of your token spend lives.
Decision model	System One (default `tev1`). Only answers short yes/no or pick-which questions: is memory extraction worth it this turn, which backends does this turn need, should a huge tool result be kept, should routing be light or heavy.
Fallback model	Configured via `decide_profile_id`. Only kicks in when the decision model is unavailable. If you've configured a decision model, leave this empty. Leaving it empty does not fall through to the main model.
Retrieval model	e.g. `bge-m3`. Only handles tool retrieval — it does not make any of the judgments above.

1. Why "judgment" deserves its own layer

Once you hang Baize next to a business system and point it at an API doc, hundreds of endpoints become hundreds of callable tools. One real backend easily brings in 300+ tools.

With that many tools, every turn carries a pile of high-frequency judgments before the main model ever writes a word: which systems should the main model see, which tools make the candidate list, is memory extraction worth running at all, which model tier to pick.

These judgments share three traits: high frequency (almost every turn), short answers (usually "pick a few" or "yes/no"), and not expensive — if every judgment goes through the main model's generative call, the tokens saved cost more than the judgment itself.

The standard move is to pull high-frequency judgments out of the generative loop and run them on a cheaper capability — the same shape Jev popularized: short answers, enum output, no long reasoning essays. Here's how Baize layers prefiltering, retrieval enhancement, and the decision chain.

2. Stage 1: deterministic prefiltering to push down noise

This tier needs no decision model. Baize starts with a zero-cost, degradable deterministic path:

System routing: discriminative terms in the query force-hit the matching connector; the main model's pick can only add to the forced set, never remove it.
Tool prefiltering: BM25 over Latin terms and Chinese bigrams (standard matching) ranks relevant tools into a short candidate list; the main model only sees that list.

It's deterministic, explainable, and works offline. It only pushes down noise though — when the user phrases something vaguely, irrelevant entries can still slip through.

Note: this "narrowing" is a runtime prefilter strategy. It is not the same code as the Rules tier in the decision chain below — Rules today mainly covers "is memory extraction worth running this turn."

3. Stage 2: retrieval enhancement (vectors), with fallback to lexical

v0.4 added the "can you find the right tool" dimension. The prefilter was BM25; dense vectors are now fused via RRF. You can optionally plug in an embedding model (bge-m3 on local Ollama, or any OpenAI-compatible embedding API) to vectorize every tool doc and rank by similarity at query time.

In the fusion, vectors outrank BM25 (in the code, dense weight is roughly 2× BM25). It's steadier for mixed Chinese/English, business jargon, and non-standard phrasing. If enhancement fails, it automatically falls back to standard matching — your conversation is unaffected.

This tier answers "can you find the right tools." It does not answer "should we extract memory, should a tool result be kept verbatim, should routing be light or heavy" — that's the decision layer's other track.

4. Stage 3: wiring in the decision model

v0.5.0 routes "needs judgment" into the decision model, forming today's chain:

Decision model (System One) → Fallback model (optional) → Rules

Tier 1: Decision model (System One). Local Ollama (≥0.35) auto-pulls tev1 (CPU-friendly), or you can point it at any cloud / self-hosted service compatible with POST /v1/systemone (not a plain Chat Completions endpoint). Short, high-frequency judgments are answered locally or on a dedicated decision endpoint — they don't burn the main model's generative budget.

Tier 2: Fallback model (optional). Only when System One is unavailable, a cheap preconfigured model profile takes over. If you've already configured the decision model, leave this field empty — leaving it empty does not route back to the main model; it falls through to the next tier.

Tier 3: Rules. Deterministic rules. Today this mainly covers memory extraction; other judgment points opt out of this tier and continue on the original path: we'd rather follow a hard-coded fail direction than pretend to be smarter than we are.

The whole chain is fail-open: if a tier times out, isn't configured, or opts out, it doesn't drag the conversation down — tools schemas are still sent, memory extraction still runs. We'd rather spend one extra call than silently drop a capability.

About scores. The System One protocol may return an internal ranking score; the client only uses it to pick an enum result (e.g. ≥0.5 → yes). It does not expose scores to product logic, and it never writes "if p > 0.9, auto-execute." The numbers a typical local decision model emits are uncalibrated ranking scores, not business thresholds. Truly calibrated probabilities ("90% means ~90%") require a dedicated training path; the open-source default path doesn't pretend to have it.

Why now? The decision model wasn't invented in v0.5. v0.4 already pulled local Ollama installation, bge-m3 pulls, model paths, and uninstall into the "Matching & Decision" settings page. v0.5's delta is mostly pulling one more model (tev1) on the same Ollama, behind the same install UX, unified under /v1/systemone. Once the infrastructure is in place, the marginal cost of adding a decision model is low.

5. Four easy-to-mix-up points

Why CPU-friendly? High-frequency judgments need to be short and resident. tev1 is CPU-friendly per the product docs — it runs on an ordinary office machine, so you don't round-trip a cloud generative call just to "think for a second."

Why two layers of switches? If you've configured a decision model but haven't flipped the master toggle under "Runtime → Smart acceleration," you do not save main-model tokens. After the master is on, you still turn on the individual features you want: tool candidate narrowing, tool-result pruning, memory pre-judgment, long-doc selection. The system needs to know explicitly which capabilities are on — it doesn't assume "model installed = everything on."

Retrieval and decision can share one Ollama. bge-m3 for matching and tev1 for decision can both live on the same Ollama instance. The "Matching & Decision" settings page keeps both links together: install progress, model paths, custom directory, cleanup — all in one place.

Installing Ollama. Both System One and enhanced matching assume you have Ollama running. The settings page walks you through install, model pull, and cleanup — get Ollama first, none of the decision chain matters if you can't run it.

6. Measured numbers — two separate ledgers

Don't mix "we swapped the decision backend" with "the main model's prompt got shorter" on one chart.

6.1 The main model got cheaper: narrowing + prefiltering

Benchmark: 37 real read-only business requests across 3 backends (390 tools total), main model DeepSeek-Flash. Relative to prefilter width 32, the default width 16 cuts turn-0 prompt tokens by ~34%; over 5 rounds (185 runs), run success is 99.5%. Compared to sending all 390 tools in one turn (~85k prompt tokens at turn-0 vs ~1.4k–3.8k), it's an order-of-magnitude drop, not just 34%.

These numbers reflect tool narrowing + prefiltering on the main model's prompt. Corpus and scripts live in scripts/tool-routing-eval and are reproducible. It is not "System One alone saves 34%" — when prefilter width is fixed and only the decision backend swaps to tev1, the main model's prompt width is roughly the same.

6.2 Which processes moved off the generative main model

A decision-model call is usually far cheaper than a main-model call (self-hosted tev1 ≈ electricity). What you actually want to see is: which processes no longer go (or go less) through generative calls.

Process	Without smart acceleration / decision model	With System One on and the matching toggle enabled
Run memory extraction?	Often another generative call to extract	Decide first; if "not worth it," the whole extraction is cancelled
Which backends this turn?	Full schema (or another model asked)	Decision + prefilter; main model only sees the narrowed list
Keep a huge tool result?	Often the whole block goes into context / summary	Decide first; if useless, don't feed it to the main model
Light or heavy routing?	Heuristic, or another model arbitrates	Optionally decided by the decision model

The big savings are: fewer schemas and less context fed to the main model, plus generative calls cancelled outright. Swapping the decision backend for a cheaper implementation is the second ledger.

6.3 Decision backend head-to-head: System One vs fallback model

Same 37 requests, width 16, same machine, one run each (this is a decision-backend comparison — not another pass over the width table):

Decision backend	Run success	Expected tools hit	Wall clock
System One (local `tev1`)	37/37	31/37	~376 s (~10.2 s/request)
Fallback model (`deepseek-flash`)	37/37	29/37	~556 s (~15.0 s/request)

Event sources are systemone and remote; main-model prompt width is the same. The fallback model's wall clock is ~1.48× — wiring in a decision model isn't "hiring another model to chat along," it's pulling high-frequency judgments out of generative calls. Scripts and notes are in scripts/tool-routing-eval.

7. How to try it

Requirements: Go 1.25+, or grab a prebuilt binary from GitHub Releases (use v0.5.0). Out of the box it's still zero-component standard matching. For the full decision chain:

In Settings → Matching & Decision, flip on System One (local Ollama pulls tev1, or point at /v1/systemone).
In Runtime → Smart acceleration, enable the master toggle, then turn on the per-feature switches you want.

The article tracks the repo; the repo docs are the source of truth.

8. Closing

From deterministic prefiltering, to optional vector retrieval, to a decision model wired into a chain — Baize moves high-frequency judgments from expensive places to cheaper ones, and when it can't or isn't sure, it fails open onto the original path. Judgment can plug into a dedicated decision endpoint; whether it's accurate and how well-calibrated it is, that's another ledger. Try it and tell me what breaks.

GitHub: https://github.com/rebornace/baize

Baize v0.4.0: Tool Matching Upgraded — Optional Vector Retrieval, Lexical Baseline Unchanged

rebornace — Thu, 08 Oct 2026 02:27:30 +0000

What this release is about

Baize is a team-facing AI assistant runtime: you point it at an existing service, upload an OpenAPI / Swagger-style doc, and the endpoints become tools the assistant can call. A real internal backend, once wired up, usually brings hundreds of tools into the catalog.

That scale creates a problem: stuffing hundreds of tool schemas into every prompt is expensive, and the model has to pick from a very long list. Baize already solved the first part with a decision layer — before the main model call, a cheap deterministic step narrows the candidate tools. Published numbers: against 37 real read-only requests across 3 backends (390 tools total, DeepSeek-Flash), narrowing to the default 16 candidates cut turn-0 prompt tokens by about 34%, and 185 runs across 5 loops finished at 99.5% success.

The lexical baseline, however, has a known ceiling: it ranks by tokens. Same meaning, different wording, and a tool may simply not surface. v0.4.0 enhances that step without touching the baseline.

What v0.4.0 adds

Baize's tool retrieval has always been Tool-RAG in spirit: each tool is indexed as a small document (name, description, HTTP method and path, parameter names).

The lexical baseline stays exactly as it was. Every tool document gets a BM25 index plus a sparse TF-IDF index; at query time the two scores are fused with RRF. It ships on by default, needs zero dependencies, and stays the zero-friction path.

What's new is the dense channel. Once an embedder is configured, each tool document also gets a vector. At query time, the query is embedded and cosine similarity is computed — and in the fusion, the dense channel is the primary one, with BM25 demoted to an auxiliary channel. The two are merged again with RRF before being handed to the model. Division of labor: BM25 catches exact terms — proper nouns and fixed phrases in your business domain; the dense channel catches paraphrases, so a user asking the same thing with different words still surfaces the right tool. The mixed mode and the pure lexical mode are distinct internal states, observable and reversible.

You can pick either embedding source:

Local Ollama. For setups that don't want to send text to a cloud embedder. The settings page walks through the whole flow: one-click Ollama install , pulling the matching model, showing install and model paths, a custom models directory, and a clean uninstall when you don't need it. No command line required.
Any OpenAI-compatible Embedding API. If you already have a compatible endpoint, fill in the base URL and key — the same habit Baize uses for chat models.

Design tradeoffs

Making this an optional enhancement rather than the default was deliberate:

Zero-cost onboarding. Fresh install, lexical matching just works. You only opt into the dense channel when you feel lexical recall isn't enough.
Fail open to the lexical path. If the dense channel misbehaves — Ollama not ready, embedding API timeout — retrieval automatically falls back to the pure lexical index and the conversation continues. Consistent with the runtime's fail-open philosophy: speedups should never become the new failure point.
Narrowing never disables tools. Pruning only decides which schemas land in this step's prompt; any registered tool still runs if the model names it directly. When nothing matches, it falls back to the full set, and system / login tools are always retained.
Easier to find. The runtime settings page is now organized into tabs: common, speedups, memory & compaction, security. Tool matching lives under "speedups".

Reproducibility

The release also ships an evidence evaluation script: it replays and scores tool-call traces. After a change to matching, one run tells you whether recall regressed, instead of relying on gut feel. Corpus and script are in the repo.

(The previous v0.3.x line already brought the web workspace, long-horizon projection — model-facing hints only, saved chats never rewritten — and a built-in self-help skill. This post focuses on the v0.4.0 matching upgrade; the README covers everything else.)

Try it

You'll need Go 1.25+, or grab a prebuilt binary from GitHub Releases (which also ships the optional WeChat channel adapter). Unpack, fill in your .env file, and start — the console is at /ui. Out of the box you get lexical matching; to try the dense channel, open the tool matching page in settings and pick Ollama or an Embedding endpoint.

Wrapping up

The direction is straightforward: the more tools you wire in, the more retrieval at this step matters. Baize keeps it "zero-cost by default, enhancement on demand, fail open" — users who want no new dependencies see no change, and users willing to spend a little on embeddings get more reliable tool recall.

v0.4.0 is out: https://github.com/rebornace/baize

Feedback on matching quality, or on the Ollama one-click flow, is very welcome — I'm following the issues and will keep shipping.

Context as a File: Baize's CLM-Inspired Long-Conversation Projection

rebornace — Sun, 04 Oct 2026 02:40:48 +0000

Project: Baize — an AI assistant runtime for your team (Go 1.25+, MIT)
Repo:
https://github.com/rebornace/baize

1. The short version

Baize v0.3.x takes inspiration from the recent Context Language Models (CLM) papers and ships a constrained take: keep important facts in long chats. It treats the context that reaches the model as something that can be curated — pin the essentials, roll up rolling summaries, drop oversized tool results — but it never rewrites the saved chat messages, and on failure it automatically falls back to the existing compaction logic.

One line for the tradeoff: CLM hands editing rights over the context to the model; Baize puts the editing in a system-side projection layer, trading some freedom for reliability.

2. Why long conversations are a hard problem for agents

An agent's context is the classic append-only structure: every new message, tool result and reasoning trace gets appended to the history. Once a conversation gets long, the problems show up:

Attention dilution: with thousands of lines of history, one critical configuration item can get lost; the model may not reliably pick it up anymore.
Truncation is irreversible: cutting old messages silently drops early agreements and context the user never notices.
Compaction is irreversible: rolling summaries save space, but a summary is a lossy, one-way transformation; key details can simply disappear.

The traditional answer is to hand context management to an external framework: compress on a threshold, offload, retrieve. Those approaches work, but they are "the framework defines the actions, the model can only pick one".

3. What CLM brings

CLM is a paper from late September 2026 (arXiv:2609.37725, by the University of Washington, Meta Superintelligence Labs, MIT and others). It turns the problem around: context is not an append-only log — it is a file the model has write permission on. The model can append, but it can also edit, delete and rewrite that file, and every change is synced into the next turn's context.

The observations in the paper are direct:

Models can learn on their own what is most worth keeping in context, and behaviors show up that previous frameworks never had — maintaining a tracker table for multi-agent collaboration, or defining reusable context-management functions.
On the deep-research benchmark BrowseComp-Plus, out-of-the-box CLM beats the strongest baseline by 11.4% in accuracy while using 21.5% fewer inference FLOPs; on a 24-hour, multi-repo agent-swarm task it achieves 65% higher end-to-end speedup at the same compute.
Because context management becomes model behavior rather than an external harness policy, the strategy itself can keep improving through reinforcement learning.

The appeal is that context management stops being a hard-coded rule set and becomes a product the model can understand and learn. But handing the model full editing rights has real production gates: is the editing reliable, does the archive stay trustworthy, and what happens when it fails?

4. Baize's constrained take: keep important facts in long chats

Baize did not copy CLM wholesale. It extracted the core idea — context is curatable output, not an append-only log — and added three constraints:

1. The projection only lives on the model input side; saved chats are never rewritten.

When a thread gets long, the assistant keeps a model-facing projection of the facts it still needs: it pins what actually matters, summarizes the secondary stuff, and drops oversized tool results. The chat the user sees stays untouched, ready to review, fork or roll back at any time. This matters for team use: the archive is the basis of audit and trust. The model input can be curated aggressively; the archive must stay true.

2. Fail-open.

If the projection fails, the assistant falls back to the original compaction and the conversation keeps going — context curation must never become an availability bottleneck. This matches the philosophy Baize's decision layer already follows: optimization must not affect whether the tools themselves still work.

3. No promise of lower cloud token usage.

The projection itself costs tokens; the curated result is not necessarily cheaper than plain compaction. The docs say it plainly. What this feature solves is key-fact retention and context usability — not the bill.

The knob is optional (default off), hot-reloadable, and costs nothing when unused.

Why "constrained"? Baize talks to OpenAI-compatible APIs: it cannot read logits, and there is no native model-side context-editing capability. Rather than letting the model rewrite history in an uncontrolled place, the editing lives in the system-side projection layer, where it can be made reliable and reversible. CLM is the radical route of native model editing; Baize's projection is the pragmatic route of framework-style editing. Same goal, different cost and reliability.

5. A little design philosophy

Looking back at this upgrade, a few decisions are consistent:

Optional, rather than deciding for the user by default: the projection and the decision layer are both runtime knobs, off by default, taking effect via hot reload when enabled.
Fail-open first: projection falls back to compaction, routing falls back to full tools — availability is never harmed by an optimization.

If you are also working on long-conversation handling for agents, come discuss your tradeoffs at the repo: https://github.com/rebornace/baize. Everything mentioned here (the projection and workspaces) already exists in the public repository; docs live under docs/developers in both English and Chinese. I'll keep following up on issues and suggestions.

Reference: Context Language Models (arXiv:2609.37725): https://arxiv.org/abs/2609.37725

After Jev Blew Up, I Brought Its "System One Judgment" Idea Into My Open-Source AI Agent

rebornace — Wed, 23 Sep 2026 15:22:04 +0000

Project: Baize — an AI assistant runtime for your team (Go 1.25+, MIT)
Repo:

https://github.com/rebornace/baize
This post is not a tutorial for "integrating Jev". It shares one judgment:

Jev is worth learning for more than its model — the engineering idea that high-frequency decisions shouldn't ask a generative model to write an essay.

And that idea lands without depending on Jev's service at all.

1. Decision layer design: three principles + one red line

Baize is a sidecar AI assistant runtime: a single process deployed next to your business systems, turning OpenAPI / MCP / HTTP plugins into callable tools, with human approval required for write operations. It calls models through OpenAI-compatible APIs, so it cannot read logits — and therefore cannot get calibrated probabilities. The decision layer was designed from the start with no probability-dependent logic.

Three hard principles:

Pluggable — one decision interface; local rules, a local small model, or a remote decision service are all implementations. Default to the cheapest. No dependency on any external service.
Degradable — every decision point fails open to the existing rules path; the decision layer is never a single point of failure for a run.
Observable — every judgment records its source and any degradation (decide.degraded, decide.tool_narrow events).

One red line: no confidence numbers of any kind in judgment results. Without calibrated logits, a number that looks like a probability but is not calibrated is more dangerous than no number at all — it invites branches like "auto-execute when p > 0.9".

Interface shape: verdicts only

The return shape is deliberately minimal: verdicts are yes / no enums; multi-select returns the chosen items; every answer carries its source (rules, remote, or fallback) and a degraded flag. There is no float confidence field in the interface — a type-level guarantee against treating uncalibrated numbers as confidence.

The Chain: errors must be swallowed by degradation

All implementations are chained and tried in order; the first success returns. If all fail, the chain returns the fallback verdict hard-coded by the call site, marked degraded. The chain itself never returns an error — errors are consumed by degradation, never propagate into the main flow. Callers always get a legal enum value; a decision-layer failure looks like "old behavior", never like a crash.

Easy to miss: the fallback verdict is hard-coded at the call site, not a config item. Failure directions differ per decision point — memory extraction fails open to Yes (spend a call rather than lose a memory), tool narrowing fails open to the full set (spend prefill rather than miss a tool). As a config knob, someone would eventually flip it under cost pressure and silently lose data. Failure direction is a safety property, not an ops parameter.

Implementations today

Two tiers on the chain, remote first: when a dedicated decision-model profile is configured, a small model answers under a prompt that forces enum-only output, validated by regex / JSON parsing; unparseable replies abstain and let the chain degrade. Multi-select answers accept only names from the offered set; out-of-set values are dropped. Because structured-output support varies across OpenAI-compatible endpoints, the contract is enforced by prompt + parsing, not by endpoint features.

With no profile configured (or remote unavailable), the zero-latency rules backstop handles memory extraction only — it abstains everywhere else: short chitchat with no fact cue returns No; explicit fact cues ("remember that", "my number", passwords, addresses, phone numbers), a run of three or more digits, or substantial length returns Yes.

Want to plug in a self-hosted inference endpoint that can read logits later? Add one more tier to the chain; callers don't change.

2. Four decision points: moving "judgment" out of "essay-writing"

Four places in Baize were classic waste: paying a generative model to write a paragraph just to get a "yes / no / which one" answer. The decision layer moves each one down.

2.1 DP-1: memory-extraction pre-check (the best cost/benefit)

Baize used to fire an LLM call after every successful conversation to extract memory. Most conversations contain nothing worth remembering and return an empty array — but each one paid a full call plus a JSON-parse risk.

Now, before paying for that call, the engine asks the layer "is this turn worth extracting?": a No skips extraction and records a skip event (marked as decided by the layer) together with the estimated input tokens saved, so the win is measurable; a Yes — or an unavailable layer — extracts exactly as before.

The probe itself is capped at 1500 characters: the probe must never cost more than the call it tries to save.

2.2 DP-2: two-level tool-candidate narrowing (the structural one)

The most worthwhile change in Baize. Its positioning is "give it OpenAPI, get tools automatically"; the more connectors you attach, the more full tool schemas go to the main model every turn — prefill cost grows linearly with connectors. That is a structural cost that scales with your users.

Narrowing has two levels:

Level 1: system routing (System Targets). The decision model picks which backend systems — a handful of connector ids — this turn needs; it may pick several. Choosing a tool among hundreds is hard; choosing among three to five systems is easy. System descriptions are not hand-written: they are auto-derived from each system's tool names and descriptions via within-system term frequency times cross-system IDF, so adding a connector needs no routing-corpus maintenance.
Level 2: in-system keyword prefilter. Within the chosen systems, deterministic IDF keyword scoring (tool names weighted 2x, descriptions 1x, stopwords removed, CJK tokenized as bigrams), merged round-robin across systems, narrowed to 16 candidates by default.

Narrowing is not one-size-fits-all; three floors prevent over-pruning:

Category-tool floor: for "list the users", a generic pagination tool ranks poorly under IDF — but a list request needs exactly that tool. List / detail intent forces the matching admin read tool into the set.
Auth floor: once a system is chosen, its login / current-session primitives are always kept — on a 401 the model must recover the session on the spot, and the user will never say "login".
Hybrid routing: discriminative domain words in the query (e.g. pets, orders) force their systems and can never be removed by the model — the small model can only add on top, so it cannot vote away the only correct system.

Also, main-model calls support a choice constraint (tool_choice=required) via optional interfaces, without breaking existing provider signatures; providers that don't support it fail open to an ordinary call. A constraint is an optimization, not a hard gate.

2.3 DP-3: tool-result pruning

In long conversations, a big JSON returned by an earlier tool call keeps bloating the context. When compaction triggers, the layer judges each of the bulkiest tool results "worth keeping verbatim?"; unworthy ones become a short placeholder that preserves the message / tool-call pairing — the model can re-invoke the tool, and the original result stays in the run log.

Three bounds keep the judgment cheap: only tool results are judged (not ordinary turns), only those over roughly 500 estimated tokens, at most 8 per turn. All failures mean keep everything.

2.4 DP-4: tier arbitration

Baize used a pure heuristic (image present? code fences?) to route each turn to light / standard / power tiers. The problem: "help me refactor this function" contains no code fences, gets classified as light, and the strong model never runs.

DP-4 does not replace the heuristic. It only consults the layer when the heuristic lands on the ambiguous standard tier, the turn is long enough (at least 400 characters), and routing is Auto — asking for a light / power choice. Short turns are not worth asking: "hello" barely differs across tiers, and every consult costs latency.

DP-4's judgment goes through the same chain: a dedicated decision tier makes the two-way pick when available; on degradation, the heuristic's standard tier stands — the layer advises, never rewrites the routing outcome.

3. Results and validation

Reproducible benchmark: 37 real read-only business requests across 3 connected backends (390 tools total), model DeepSeek-Flash, stability run of 5 rounds (185 requests). With the default top-16: run success rate 99.5% (184/185), average turn-0 prompt ~3,090 tokens, about 34% lower than top-32; sending all 390 tools directly measured ~85k turn-0 prompt tokens. The dataset and scripts live in scripts/tool-routing-eval — reproducible.
Default narrowing: convergence kicks in above the threshold (default 12 tools); 16 candidates is the default cap — the measured cost / success sweet spot.
Regression harness: sweep (width), stability, and analyze (offline) scripts that restore your previous configuration when they finish. An optimization that changes behavior should only go live with shadow data first, then flip shadow off.

Everything ships with the decision layer off by default and enabled per point: the master switch (decide_enabled) defaults to off, each decision point has its own knob, all controlled through the existing hot-reload settings — no wiring changes.

4. Honest boundaries

No calibrated probabilities. Baize calls OpenAI-compatible APIs and cannot read logits. The layer only ever returns enums, and there is no "auto-execute above a probability threshold" feature. Write approval stays deterministic rules + human approval. That red line does not bend for Jev.
This is not "integrating Jev". The decision layer depends on no external decision service. If you later point your inference at a local vLLM running a decision plugin, the remote implementation works as-is — a free win, not an architectural prerequisite.

5. Closing

Jev made one thing click for me: models matter, of course — but plenty of high-frequency little decisions shouldn't ask a generative model to write an essay every time. Pulling "judgment" out of "generation" into a pluggable, degradable, observable layer is engineering any agent project can do — it does not depend on any company's window.

Baize's decision layer is live in the main branch (internal/decide + four decision points). Come take a look, run it, or open an issue:

GitHub: https://github.com/rebornace/baize
More: the README's decision-layer section, and the bilingual developer docs under docs/developers

If you have hit the same wall — tool schemas going to the model every turn while prefill gets more expensive — I'd love to hear your solution. I'll keep following up on feedback and issues.

Building a Lightweight AI Agent in Go: Baize's Architecture and Trade-offs

rebornace — Thu, 17 Sep 2026 02:06:02 +0000

Preface

Baize is a "sidecar" AI assistant runtime: a single process that sits beside services you already run, turns API documentation into tools the assistant can call, and pauses important writes until a person approves them. Stop it and it leaves almost nothing behind.

One sentence positioning: it's a runtime, not a framework. That positioning drives every architecture decision below.

1. Why Go

Single binary, zero dependencies

The core requirement of sidecar deployment is "one process, copy it over, run it." A Go binary needs no interpreter, no dependency installation, no virtualenv on the target machine. For an assistant meant to live in enterprise environments, that's the lowest-cost delivery form.

Goroutine concurrency

One assistant process serves multiple entry points at once: the web console, signed alert/ticket ingress, and IM channels. Goroutines make "one process handling many sessions concurrently" straightforward — and parallel tool calls later become almost free.

Cross-compilation

Enterprise environments run everything: Windows, Linux, macOS, ARM. A single GOOS=linux GOARCH=arm64 go build produces a binary for the target platform, with no toolchain setup on the destination machine.

Static typing and tool contracts

Tool input schemas come from OpenAPI documents; mapping them onto Go's strong types catches many errors at compile time. For a long-running daemon, that saves a lot of operational pain.

2. Architecture Overview

A clean three-layer structure: core loop → tool router → executors.

Users / Channels ──► Agent Core Loop (think → pick tool → run → report)
                           │
                           ▼
                     Tool Router (Registry)
                           │
          ┌────────────────┼────────────────┐
    OpenAPI connector    HTTP plugin      MCP connector
          └────────────────┼────────────────┘
                           ▼
              Invoker closures (registered in Registry)
                           │
                     [ HITL approval gate ]
                           │
             ┌─────────────┴─────────────┐
       Direct execution          HTTP callback executor
     (plugin / proxy)            (callback to your side)

Core loop (internal/run): LLM thinks → picks a tool → executes → reports. The event stream (llm.thinking, llm.tool_call, tool.result) is persisted, so the console can follow along in real time.
Tool router (internal/tool): a mutex-protected map that registers not functions but "tool contracts + invoker closures".
Executors (internal/connector): tools enter through three sources — OpenAPI docs, HTTP plugins, MCP tool servers — plus a "callback execution" mode that hands execution back to your side.

3. Key Design Decisions

Why HTTP callback instead of a plugin protocol

This is Baize's most important trade-off.

The problem with plugin protocols: in-process plugins (Go plugins, shared libraries, language-binding SDKs) require the plugin to compile with the host process — language, version, and ABI must all align. Most enterprise systems aren't written in Go: legacy systems, Java/.NET/Python services can't load an in-process plugin at all. And even when they could, upgrading a plugin means restarting the process — "sidecar in, clean out" is gone.

What Baize does instead: it doesn't execute the tool itself; it POSTs the invocation to your own endpoint:

{
  "tool": "create_ticket",
  "arguments": { ... },
  "run_id": "run_xxx",
  "agent_id": "agent_xxx",
  "idempotency_key": "uuid-xxx",
  "callback_urls": { "event": "https://your-service/baize-events" }
}

Your side executes it and returns the result. Benefits: language-agnostic, process-isolated, auditable; idempotency_key makes retries safe (no duplicate execution); callback_urls lets your side keep driving follow-up actions.

The cost: one extra network round-trip, the callback endpoint must be reachable, and to prevent forged callbacks you need signed requests (Baize uses callback signing with a TTL against replay).

Dynamic tool registration and discovery

The registry (tool.Registry) is the core data structure: a sync.RWMutex guarding a map, with runtime register/unregister and per-connector bulk unregister — adding a tool or disabling a connector never requires a restart.

Three tool sources share one registration path:

OpenAPI docs: import Swagger/OpenAPI/Postman-style docs, each operation becomes a tool;
HTTP plugins: a small companion service declares "what tools exist and how to invoke them";
MCP tool servers: connect to external tool ecosystems as an MCP client.

Security policy is baked into each entry at registration time: require_approval (needs a human), require_login (needs a session), security_schemes (which auth scheme to use). Security policy is decided at registration, not asked at execution time — this is the precondition for letting the assistant actually act.

Discovery is trivial: Registry.List() / Registry.Specs() feed the model's tool list, visible live in the console.

Graceful degradation on failure

Failures are the norm in AI agents, so degradation design matters more than the happy path:

Timeout guardrail: every tool invocation is bound to context.WithTimeout (default 60s, configurable);
Failure is content: Invoker returns (content, isError, err) — err is an infrastructure failure (timeout, network), isError is a business-side failure. Both flow back to the model as structured content, so the model can retry, switch tools, or explain to the user — instead of crashing the whole session;
Approval rejection is not a crash: when a human rejects a write, the run settles into an explicit "rejected" terminal state with a trail, no panic;
Everything is observable: the llm.tool_call → tool.result event stream is persisted, so any problem can be traced step by step;
Context compaction: long sessions get rolling summaries so quality doesn't degrade as the thread grows.

4. Go vs Python / Node.js for Agent Scenarios

Let's be honest first: Python is the best choice in the AI/Agent ecosystem. LangChain, LlamaIndex and most reference implementations live there. If your goal is fast experimentation and deep reuse of the LLM ecosystem, Python has no rival.

Baize chose Go because its positioning is different:

Dimension	Go	Python	Node.js
Deployment	Single binary, zero deps	Interpreter + deps/venv	Node runtime + node_modules
Resource footprint	Low; one resident process is cheap	Higher; resident processes need care	Medium
Concurrency	Native goroutines	GIL-limited; multi-process/async	Event loop
Type safety	Static, compile-time checks	Dynamic, found at runtime	Dynamic / TypeScript
LLM ecosystem	Newer, catching up fast	Richest	Rich
Cross-platform	Cross-compile to all platforms	Needs interpreter on target	Needs Node on target

The conclusion isn't "Go is better than Python" — it's positioning decides the language:

Goal: framework / fast experimentation → Python;
Goal: sidecar, resident, one-command deployment to enterprise environments, running on modest hardware for a long time → Go's advantages in deployment and resource usage are hard to replace.

5. Core Code Snippets (Go)

All snippets are from the project source, lightly trimmed. Each comes with one line on what problem it solves.

1. A tool = contract + invoker closure

Modeling a "tool" as "a contract the model sees (Spec) + an invoker closure injected by the connector" fully decouples routing from execution:

type Invoker func(ctx context.Context, args map[string]any) (
    content map[string]any, isError bool, err error)
type Meta struct {
    Spec            llm.ToolSpec
    ConnectorID     string
    Method          string
    Path            string
    RequireLogin    bool
    SecuritySchemes []string
}

2. Dynamic registration with policy baked in

require_approval / require_login are written into the entry at registration; the tool list is "hot" — adding/removing connectors never requires a restart:

func (r *Registry) RegisterMeta(meta Meta, inv Invoker, requireApproval bool) {
    r.mu.Lock()
    defer r.mu.Unlock()
    r.tools[meta.Spec.Name] = entry{
        spec:            meta.Spec,
        invoker:         inv,
        requireApproval: requireApproval,
        requireLogin:    meta.RequireLogin,
        connectorID:     meta.ConnectorID,
        method:          meta.Method,
        path:            meta.Path,
    }
}

3. HTTP callback executor

Hands execution back to your side; the idempotency key makes network retries safe:

payload := map[string]any{
    "tool":            tool,
    "arguments":       args,
    "run_id":          meta.RunID,
    "agent_id":        meta.AgentID,
    "idempotency_key": meta.IdempotencyKey,
}
if strings.TrimSpace(meta.CallbackEventURL) != "" {
    payload["callback_urls"] = map[string]any{
        "event": meta.CallbackEventURL,
    }
}
rawPayload, _ := json.Marshal(payload)
req, _ := http.NewRequestWithContext(ctx, http.MethodPost, c.URL, bytes.NewReader(rawPayload))

4. Writes automatically enter the approval gate

Non-GET/HEAD/OPTIONS operations are automatically flagged "needs approval" at registration, and only run after a human clicks approve/reject in the console:

needApproval := t.RequireApproval
if ctx.requireApprovalMutating && isMutatingMethod(t.Method) && t.Source == store.ToolSourceSpec {
    needApproval = true
}

5. Timeouts and failure degradation

A timeout guardrail plus "failure is content" semantics keeps one bad tool call from blowing up the whole session:

toolCtx, toolCancel := context.WithTimeout(ctx, e.toolTimeout())
defer toolCancel()
content, isError, invErr := e.Tools.Invoke(toolCtx, payload.ToolName, payload.Arguments)
if invErr != nil {
    // Infrastructure failure (timeout/network): persist and close the round
    return e.finalizeFailedRun(runID, invErr)
}
// When isError is true, the failure flows back to the model as content;
// the model decides whether to retry or explain.

Closing

Baize is still early. The trade-offs above are far from "optimal" — especially the approval UX, channel adapters, and executor extensibility. If you have real-world scenarios, I'd love to hear them.

Repo: https://github.com/rebornace/baize (MIT)
Issues: open a discussion with your scenario — I'll follow up.

Add AI to Your Legacy System in 5 Minutes: A Baize Hands-On Tutorial (Spring Boot Example)

rebornace — Wed, 16 Sep 2026 04:34:42 +0000

Got a backend system that's been running for years — piles of APIs, complex business logic, and the thought of adding AI feels like a massive undertaking? This tutorial shows you how to hook up an AI assistant to your existing system in 5 minutes using Baize — no refactoring, no core code changes, at most one new endpoint.

Baize is an open-source AI Agent runtime written in Go. Its core ideas: sidecar deployment, APIs-as-tools, and human-in-the-loop approval for critical operations. It connects to business systems over HTTP, so it doesn't matter what your backend is — Spring Boot, Django, Express, Gin, ThinkPHP — if it has APIs, it can connect. The AI understands user intent, calls the right tools automatically, and pauses for human confirmation on sensitive operations.

Language-agnostic, but we'll use Spring Boot as the main example. The principles are fully universal — for other frameworks, just swap the Controller code in Step 3 for your language of choice. The Baize config file stays exactly the same.

Prerequisites

To follow along, you'll need two things:

A backend service (we'll use a Spring Boot ticket system as an example, but feel free to use your own project)
The Baize binary (a single executable, zero dependencies)

You can clone the repo which includes a demo ticket system and Baize configs:

git clone https://github.com/rebornace/baize.git
cd baize

The Spring Boot code examples in this tutorial use Java 17 + Spring Boot 3.x. Readers using other languages or frameworks can focus on the configuration and protocol sections, and map the code examples to their own stack.

Step 1: Download Baize and Start It with One Command

Baize is a single static binary written in Go — no runtime to install.

Option 1: Download the Binary (Recommended)

Grab the latest release for your platform from GitHub Releases, unzip it, and you're ready to go.

Option 2: Build from Source

If you have Go 1.25+ locally, you can build it yourself:

git clone https://github.com/rebornace/baize.git
cd baize
go build -o baize ./cmd/baize

Start in Demo Mode

Baize comes with a demo mode that uses a Mock LLM (no API key needed) and a built-in demo ticket system — perfect for getting the full flow working first.

# Windows
.\baize demo

# macOS / Linux
./baize demo

When you see output like this, it's running:

baize demo listening on :8080
mock ticket server listening on :18080

Open your browser and go to http://localhost:8080/ui — you'll see Baize's web dashboard.

For production, use baize start with a config file and a real LLM API key. We'll cover that later.

No Config File? No Problem — Configure via the Web UI

Baize supports zero-config startup — just run baize start without any config file, then open the Web UI and set everything up interactively: models, connectors, tools, approval rules — all of it. Great if you prefer a graphical interface over editing YAML by hand.

# Windows PowerShell
$env:BAIZE_API_KEY = "your-api-key"
.\baize start

# macOS / Linux
export BAIZE_API_KEY="your-api-key"
./baize start

Once it's running, go to http://localhost:8080/ui → Settings in the sidebar. You can configure your LLM provider, add connectors, and manage tools directly from the page. Changes take effect immediately — no restart needed.

This tutorial uses YAML config files for clarity in the step-by-step flow. Both approaches produce the same result — pick whichever you prefer.

Step 2: Declare Tools in a Config File

The core of how Baize connects to business systems is the Connector. The most common approach is the OpenAPI Connector — if you have an OpenAPI/Swagger spec, Baize automatically turns every endpoint into a tool the AI can use.

2.1 Prepare the OpenAPI Spec

Let's say your Spring Boot ticket system has these endpoints:

Method	Path	Description	operationId
GET	/tickets	List all tickets	`list_tickets`
POST	/tickets	Create a ticket	`create_ticket`
GET	/tickets/{id}	Get ticket details	`get_ticket`
PATCH	/tickets/{id}	Update ticket status	`update_ticket_status`

Here's the corresponding OpenAPI spec (ticket-api.yaml):

openapi: 3.0.3
info:
  title: Ticket System API
  version: 1.0.0
paths:
  /tickets:
    get:
      operationId: list_tickets
      summary: List all tickets
      responses:
        "200":
          description: List of tickets
    post:
      operationId: create_ticket
      summary: Create a ticket
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [title]
              properties:
                title: { type: string, description: Ticket title }
                priority: { type: string, description: Priority level }
      responses:
        "201":
          description: Created successfully
  /tickets/{id}:
    get:
      operationId: get_ticket
      summary: Get ticket details
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Ticket details
    patch:
      operationId: update_ticket_status
      summary: Update ticket status
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, description: New status }
      responses:
        "200":
          description: Updated successfully

If your Spring Boot project already has springdoc-openapi or Swagger integrated, you can export the JSON directly from /v3/api-docs — Baize understands both YAML and JSON.

2.2 Write the Baize Config File

Create baize-config.yaml:

listen: ":8080"
store:
  driver: sqlite
  sqlite_path: ./data/baize.db
ui:
  enabled: true

llm:
  provider: openai_compatible
  base_url: https://api.deepseek.com
  model: deepseek-chat
  api_key_env: BAIZE_API_KEY

agent:
  id: ticket-agent
  system: "You are a ticket assistant. You can only access the ticket system through tools."

connector:
  id: ticket-api
  type: openapi
  spec: ./ticket-api.yaml
  base_url: http://localhost:8081   # Your Spring Boot service URL
  require_approval:
    - create_ticket
    - update_ticket_status

run:
  max_steps: 16
  tool_timeout_sec: 60

Key configuration points:

connector.type: openapi — Auto-discovers tools from the OpenAPI spec
connector.spec — Path to your OpenAPI spec file
connector.base_url — Your backend service URL; the AI calls this address when using tools
require_approval — Tools listed here require human confirmation before execution (recommended for all write operations)

2.3 Start with the Config File

# Set your LLM API Key (DeepSeek example)
# Windows PowerShell
$env:BAIZE_API_KEY = "your-api-key"

# macOS / Linux
export BAIZE_API_KEY="your-api-key"

# Start
./baize start -c baize-config.yaml

Open http://localhost:8080/ui → click "Tools" in the sidebar, and you'll see all 4 ticket endpoints listed as AI-usable tools.

At this step, you haven't changed a single line of your business code — Baize is just another caller hitting your APIs, no different from a frontend app.

Step 3: Add a Callback Endpoint for Full Control (Spring Boot Example)

The OpenAPI approach above works great when "the APIs already exist and the AI can call them directly." But sometimes you need more control:

You want to add custom logic before/after AI calls (audit logging, rate limiting, parameter validation)
The tool logic is complex and not suitable for exposing as a direct API
You don't want the AI touching internal services directly

This is where Execution Callback mode comes in: instead of calling your business APIs directly, Baize sends a message saying "which tool to call and with what arguments" to an endpoint you specify. You decide how to execute it. The protocol is dead simple — any language that can serve HTTP can implement it.

Below is a Spring Boot example; the same pattern applies to Django, Express, Gin, and any other framework.

3.1 Add an `/execute` Endpoint (Spring Boot Version)

Add one Controller with one method to your Spring Boot project:

package com.example.ticket.controller;

import com.example.ticket.service.TicketService;
import org.springframework.web.bind.annotation.*;

import java.util.Map;

@RestController
@RequestMapping("/baize")
public class BaizeCallbackController {

    private final TicketService ticketService;

    public BaizeCallbackController(TicketService ticketService) {
        this.ticketService = ticketService;
    }

    @PostMapping("/execute")
    public Map<String, Object> execute(
            @RequestHeader("X-Baize-Protocol") String protocol,
            @RequestBody Map<String, Object> body) {

        // Protocol check
        if (!"v0".equals(protocol)) {
            return Map.of(
                "content", Map.of("error", "unsupported protocol"),
                "is_error", true
            );
        }

        String tool = (String) body.get("tool");
        @SuppressWarnings("unchecked")
        Map<String, Object> args = (Map<String, Object>) body.get("arguments");

        // Dispatch to your business logic based on tool name
        Object result = switch (tool) {
            case "list_tickets" -> ticketService.listTickets();
            case "create_ticket" -> ticketService.createTicket(
                (String) args.get("title"),
                (String) args.get("priority")
            );
            case "get_ticket" -> ticketService.getTicket((String) args.get("id"));
            case "update_ticket_status" -> ticketService.updateStatus(
                (String) args.get("id"),
                (String) args.get("status")
            );
            default -> null;
        };

        if (result == null) {
            return Map.of(
                "content", Map.of("error", "unknown tool: " + tool),
                "is_error", true
            );
        }

        return Map.of(
            "content", result,
            "is_error", false
        );
    }
}

That's it — one Controller, one method, one switch statement for dispatch. You're in full control of the execution logic. Add logging, add authorization checks, add caching — whatever you need.

3.2 Update Baize Config to Point to the Callback URL

Change the connector in baize-config.yaml to callback mode:

connector:
  id: ticket-api
  type: openapi
  spec: ./ticket-api.yaml
  base_url: ""                           # Can be empty in callback mode
  execution_callback_url: http://localhost:8081/baize/execute
  require_approval:
    - create_ticket
    - update_ticket_status

The key addition is execution_callback_url — with this field set, Baize won't call base_url directly. Instead, it sends tool invocation requests to this callback address.

You still need the OpenAPI spec file because Baize uses it to discover what tools exist and what parameters they take — that's tool discovery. The actual tool execution is handled by your Spring Boot service.

After restarting Baize, the user experience looks the same, but the execution path is completely different — every tool call now goes through your /baize/execute endpoint.

Step 4: Send a Message and Watch the AI Call Tools

Once Baize is running, you can talk to the AI in two ways: via the Web UI or the HTTP API.

Option 1: Web UI (Recommended for Getting Started)

Open http://localhost:8080/ui and type in the chat box:

Show me all the tickets

You'll see the AI's reasoning process step by step, including the full list_tickets tool call — both the request parameters and the returned result.

Try this next:

Create a ticket with title "Login page loads slowly" and high priority

Because create_ticket is in the require_approval list, the AI will pause and wait for your confirmation. Click Approve on the approval card that pops up, and only then will it actually execute the create operation. This is HITL (Human-in-the-Loop) — sensitive operations are never executed blindly.

Option 2: HTTP API (Great for Integration)

Baize exposes a full REST control plane that you can call from scripts or other systems.

Start a new conversation run:

curl -X POST http://localhost:8080/v0/runs \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "ticket-agent",
    "messages": [
      {
        "role": "user",
        "content": "Show me all the tickets"
      }
    ]
  }'

The response includes a run_id. Use it to check status and stream events:

# Get run result
curl http://localhost:8080/v0/runs/{run_id}

# Stream events (SSE)
curl http://localhost:8080/v0/runs/{run_id}/stream

Going Further

Adding More Tools

Tools come from the OpenAPI spec. Adding a tool = adding an endpoint to the spec, then restarting Baize (or hot-loading through the settings page).

For example, if you want to add a "close ticket" tool, add this path to ticket-api.yaml:

  /tickets/{id}/close:
    post:
      operationId: close_ticket
      summary: Close a ticket
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Closed successfully

Then add close_ticket to require_approval, and you're done.

Timeouts and Retries

Baize has a default timeout for each tool call, which you can adjust in the config:

run:
  max_steps: 16
  tool_timeout_sec: 120    # Timeout per tool call, default is 60 seconds

If your business APIs are occasionally flaky, you can handle retries inside your Spring Boot callback endpoint — Spring Retry or Resilience4j both work great. Baize just "sends the request and waits for the result" — retry strategy is up to you.

Handling Login / Auth

If your system requires login before calling APIs, Baize has you covered. Configure auth.capture:

connector:
  id: ticket-api
  type: openapi
  spec: ./ticket-api.yaml
  execution_callback_url: http://localhost:8081/baize/execute
  auth:
    mode: passthrough
    capture:
      tool_name_glob: "*login*"
      token_json_paths: ["accessToken", "data.accessToken"]
      label_json_paths: ["email"]
      header_template: "Bearer {{token}}"

When the AI detects that login is required, it calls the login tool first, automatically extracts the token from the response, and attaches it to subsequent calls. Login info is stored in the session identity and persists across conversations.

FAQ

Q: Does Baize have to run in Kubernetes?

No. Baize is a single binary — it runs on bare metal, VMs, Docker, and Kubernetes alike. Put it on the same internal network as your legacy system, or even deploy it on the public network and call back over VPN (security will be weaker, of course).

Q: What if my OpenAPI spec is outdated or doesn't cover all endpoints?

Two options:

Use Execution Callback mode — the OpenAPI spec just declares "what tools exist," and you write the actual execution logic yourself
Use the HTTP Plugin v0 protocol — write a small standalone service to add capabilities your original system doesn't have

Q: Could the AI call APIs randomly and mess up my data?

No. Two layers of protection:

Human approval — tools in the require_approval list pause before execution and wait for someone to click approve in the dashboard
Read-only first — it's good practice to start with read-only endpoints open and put all write operations behind approval, then gradually open things up as you gain confidence

Q: Which LLMs are supported?

Any model compatible with the OpenAI API format works — including OpenAI, DeepSeek, Anthropic (via compatible gateways), local Ollama, and more. Just change llm.base_url and llm.model in the config.

Q: Can it connect to messaging platforms like Slack or Discord?

Yes. Baize's channels are designed as an extensible capability. You can use the Webhook channel to adapt any platform. One assistant, one set of tools, one approval flow — reachable from multiple channels.

Q: What's the difference between demo mode and production mode?

Demo mode (baize demo): Uses Mock LLM, no API key needed, includes a built-in demo ticket system — great for trying it out quickly
Production mode (baize start): Connects to a real LLM, works with real business systems — full feature set

Wrapping Up

Let's recap the whole flow — really just four steps:

Download Baize → single binary, zero dependencies
Write an OpenAPI spec + configure the connector → APIs become tools automatically
(Optional) Add an /execute endpoint → full control over execution logic
Chat → the AI calls tools automatically, with human approval for sensitive operations

Baize's design philosophy is "sidecar deployment, clean removal" — it doesn't intrude on your business system, it just adds an intelligent caller. Turn it on when you want to try it, turn it off when you don't. Your legacy system stays untouched.

Open Source Info

Baize · MIT License · Go 1.25 · Zero C dependencies

GitHub: https://github.com/rebornace/baize

Core features: ReAct Agent · OpenAPI Connector · HTTP Plugin v0 · Execution Callback · MCP Bridge/Export · HITL (Human-in-the-Loop) · Built-in Web UI

Supported LLMs: OpenAI / DeepSeek / any OpenAI-compatible API

Stars, issues, and PRs are all welcome.