examples/

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

Links

Open Source Insights

README ¶

Examples

Runnable programs that exercise Bide end to end. Each is a main.go in its own directory with a header comment giving a one-line description and its run command.

Model-centric examples call an OpenAI-compatible endpoint (here OpenRouter) and read an API key from the environment; set OPENROUTER_API_KEY before running them. Examples marked "offline" need no key and no network.

Most examples are packages of the root module: run them from the repository root with go run ./examples/<name>. Eight are their own modules because they import an adapter module with its own dependencies, or drive containers (approval, plan, mcp, observability, stripe-refund, hsm-signing, sso-certs, and the govern examples); cd into the directory and run go run ., or go run ./<name> for a govern example (the go.work at the root resolves the local modules; with GOWORK=off each module's replace directives do the same).

Authoring basics

Start here to learn the core authoring surface: the agent loop, typed results, streaming, sessions, sub-agents, parallel steps, and retrieval.

Example	What it shows	Run
`smoke`	The agent loop end to end against a live model, with tool calling.	`OPENROUTER_API_KEY=sk-... go run ./examples/smoke`
`typed`	`RunTyped[T]`: do work with tools, return a strongly-typed struct (note `WithOutputMode(OutputNative)` for provider-native structured output).	`OPENROUTER_API_KEY=sk-... go run ./examples/typed`
`streaming`	`Agent.Stream`: range lifecycle Events for token deltas and tool start/finish, then `Result` for the answer.	`OPENROUTER_API_KEY=sk-... go run ./examples/streaming`
`session`	Durable multi-turn `Session.Send`, then rebuilding the transcript from the store.	`OPENROUTER_API_KEY=sk-... go run ./examples/session`
`subagent`	A parent agent delegating to a `SubAgent` exposed as a tool, sharing one store.	`OPENROUTER_API_KEY=sk-... go run ./examples/subagent`
`parallel`	`agent.Journal.Parallel` over several `Task[T]`: durable, auditable fan-out/fan-in (offline).	`go run ./examples/parallel`
`rag`	A trivial in-memory `Retriever` wired via `WithRetrieval` (classic) and `RetrievalTool` (agentic).	`OPENROUTER_API_KEY=sk-... go run ./examples/rag`

Accountability, durability & integration

The accountability layer: governance, delegation and authority, proofs, crash-safety, evaluation, and integration seams.

Example	What it shows	Run
`authority`	Authority-as-governed-state: a principal's delegated limit is a state variable, seeded from identity (offline).	`cd examples/govern && go run ./authority`
`delegation`	A non-repudiable delegation chain across sub-agents, each hop signed and never widened (offline).	`cd examples/govern && go run ./delegation`
`earned-authority`	Authority earned from a provable track record: widens on a clean streak, resets on an anomaly (offline).	`cd examples/govern && go run ./earned-authority`
`compliance`	A KYC-shaped flow: parallel provable checks, a governed decision, an offline proof against a signed tree head (offline).	`cd examples/govern && go run ./compliance`
`proof-carrying-run`	A run that ships one offline-checkable certificate of behavioral-property compliance, signed under a hybrid ed25519 + ML-DSA-65 log key (offline).	`cd examples/govern && go run ./proof-carrying-run`
`quorum`	A governed model quorum: k-of-n agreement admits the commit, with the whole vote in the audit trail (offline).	`cd examples/govern && go run ./quorum`
`compose`	Compositional construction: verify a subsystem once, embed it as a black box into larger systems (offline).	`cd examples/govern && go run ./compose`
`mesh`	A coordination-free safety mesh where governed state constrains agents cyclically (offline).	`cd examples/govern && go run ./mesh`
`chaosbench`	The crash-injection benchmark: an exhaustive crash-point sweep proving a side effect never double-fires (offline).	`go run ./examples/chaosbench`
`plan`	The `plan` flow builder driving an order-triage flow on a SQLite journal: the declared diagram, a typed result, `Conform`, and an offline proof that the run followed the signed flow digest (offline). Its own module.	`cd examples/plan && go run .`
`recover`	Crash recovery: a supervisor resumes an interrupted run from its journal without re-firing side effects, then a lost outcome halts and is resolved with `ResolveHalt` (offline).	`go run ./examples/recover`
`interrupt`	Human-in-the-loop: a tool pauses the run for a durable approval decision, then resumes (offline).	`go run ./examples/interrupt`
`approval`	m-of-n human approval across separate processes on a SQLite journal: 2 of 3 approvals, each signed over the exact call, gate a refund; a forged signature and an ineligible approver are ignored without locking anyone out; and an auditor verifies the evidence offline with public keys only, in Go or with `bide audit verify-approvals` (offline). `go run ./flow` puts the same gate on a plan flow node loaded from config. `go run ./makerchecker` adds separation of duties: the requester's own approval never counts, and the audit proves who requested without the run's input. Its own module. Its keys are predictable demo keys (each is SHA-256 of a public name), so anyone can sign as any approver; never reuse them.	`cd examples/approval && go run .`
`stripe-refund`	A refund agent against Stripe's TEST mode API, killed mid-refund: the restart halts (outcome unknown) instead of refunding twice, a reconciler finds the refund in Stripe's own record by its metadata and resolves the halted step, and exactly one refund exists. A 2-of-3 approval gate covers large refunds. `net/http` only, no Stripe SDK. Needs a Stripe test key (`sk_test_`; anything else is refused); its tests run against a fake Stripe (offline). Its own module.	`cd examples/stripe-refund && ./demo.sh pi_...`
`signals`	Durable timers and external signals: a run sleeps or waits for an event and resumes on delivery (offline).	`go run ./examples/signals`
`hedge`	The hedged-model middleware: race a primary against a backup and take the first good answer (offline).	`go run ./examples/hedge`
`eval`	The statistical evaluation harness: labeled cases, metrics, repeated runs, a pass-rate report (offline).	`go run ./examples/eval`
`observability`	OpenTelemetry GenAI spans in one call (`trace.Instrument`), exported to stdout, with token usage and cost on the chat span (offline). Its own module.	`cd examples/observability && go run .`
`hsm-signing`	An agent whose audit log is signed by an Ed25519 or ECDSA P-256 key held in a PKCS#11 token (an HSM, or SoftHSM2 to try it), in Google Cloud KMS (set `BIDE_GCPKMS_KEY_VERSION`), or in Azure Key Vault or Managed HSM (set `BIDE_AZURE_KEY_ID`; ECDSA P-256 only): every journal write is anchored with a tree head signed in the token or by Cloud KMS, then the head and an evidence package are verified with the public key alone. PIN from an environment variable or a file, never an argument. Needs cgo and a token, a Cloud KMS key version with Application Default Credentials, or an Azure key with an `azidentity` credential (see `docs/guides/key-custody.md`); its PKCS#11 tests use SoftHSM2 and skip without it, and its Cloud KMS tests run against an in-process emulator, and its Azure tests use a fake Key Vault client. Its own module.	`cd examples/hsm-signing && BIDE_PKCS11_MODULE=... BIDE_PKCS11_TOKEN=... BIDE_HSM_PIN_FILE=... go run .` or `cd examples/hsm-signing && BIDE_GCPKMS_KEY_VERSION=projects/P/locations/L/keyRings/R/cryptoKeys/K/cryptoKeyVersions/N go run .` or `cd examples/hsm-signing && BIDE_AZURE_KEY_ID=https://V.vault.azure.net/keys/K/VERSION go run .`
`sso-certs`	Approver certificates issued after a single sign-on login: a step-ca OIDC provisioner and certificate template that issue what a bide `IdentityPolicy` requires, `scripts/renew.sh` for the approver, and an end-to-end test against containers (needs Docker; `BIDE_TEST_STEPCA=1`). Its own module. See SSO certificates.	`cd examples/sso-certs && BIDE_TEST_STEPCA=1 go test -v ./...`
`mcp`	Wiring runtime MCP tools into an agent from an in-memory MCP server, with trusted annotations marking a tool retry-safe (offline). Its own module.	`cd examples/mcp && go run .`
`coordination`	Multi-agent coordination through shared durable state: a gsm-synthesized repair, and a cyclic federation built under a coordination plan (offline).	`cd examples/govern && go run ./coordination`
`webhook`	Driving an agent from an inbound messenger webhook, with idempotent redelivery handling (offline).	`go run ./examples/webhook`
`intake`	The approval intake: `approvals.Handler` mounted by an application so approvers decide over HTTP (`WithGatePolicy`, `WithAuth` binding a bearer token to its approver, `WithPage`, `OnRecorded`). A 2-of-3 refund gate with separation of duties: the requester's decision is recorded and not counted, a token cannot decide for another approver, the refund runs once, and the receipt is checked against the signed heads (offline).	`go run ./examples/intake`
`notify-routing`	The notifier with routing and escalation: approvals routed by approver, a halt routed to on-call, an escalation to a lead when on-call's endpoint is down, an all-clear on resolution, a trail signed and anchored as it is written, and `audit.VerifyNotifications` passing, then failing on a trail with a record removed and on a late acknowledgement (offline).	`go run ./examples/notify-routing`

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
chaosbench Command chaosbench runs the crash-injection benchmark: it drives a non-idempotent side effect through an exhaustive crash-point sweep plus randomized multi-crash schedules, and reports whether the side effect ever fired more than once.	Command chaosbench runs the crash-injection benchmark: it drives a non-idempotent side effect through an exhaustive crash-point sweep plus randomized multi-crash schedules, and reports whether the side effect ever fired more than once.
eval Command eval shows how to use the statistical evaluation harness.	Command eval shows how to use the statistical evaluation harness.
hedge Command hedge shows the hedged-model middleware: race the primary model against a backup and take the first good answer, which cuts tail latency and fails over around a down provider.	Command hedge shows the hedged-model middleware: race the primary model against a backup and take the first good answer, which cuts tail latency and fails over around a down provider.
intake Command intake shows the approval intake: an application mounts approvals.Handler so approvers decide on a gated call over HTTP, and the application stays the only writer of its journal and the only signer of its audit log.	Command intake shows the approval intake: an application mounts approvals.Handler so approvers decide on a gated call over HTTP, and the application stays the only writer of its journal and the only signer of its audit log.
interrupt Command interrupt shows human-in-the-loop as a durable pause: a retry-safe tool calls agent.Interrupt to ask a human a typed question, Run returns *InterruptPending (the run has paused at the interrupt point), the caller records an answer with agent.Journal.AnswerInterrupt, and re-invoking Run with the SAME runID resumes past the interrupt with that answer.	Command interrupt shows human-in-the-loop as a durable pause: a retry-safe tool calls agent.Interrupt to ask a human a typed question, Run returns *InterruptPending (the run has paused at the interrupt point), the caller records an answer with agent.Journal.AnswerInterrupt, and re-invoking Run with the SAME runID resumes past the interrupt with that answer.
notify-routing Command notify-routing shows the notifier routing events to different receivers, escalating one nobody handles, sending an all-clear, and writing a trail that is signed and anchored as it is written, which bide audit notifications (audit.VerifyNotifications) then checks offline.	Command notify-routing shows the notifier routing events to different receivers, escalating one nobody handles, sending an all-clear, and writing a trail that is signed and anchored as it is written, which bide audit notifications (audit.VerifyNotifications) then checks offline.
parallel Command parallel shows agent.Journal.Parallel: a durable, auditable fan-out/fan-in.	Command parallel shows agent.Journal.Parallel: a durable, auditable fan-out/fan-in.
rag Command rag shows bring-your-own retrieval: a trivial in-memory Retriever wired two ways.	Command rag shows bring-your-own retrieval: a trivial in-memory Retriever wired two ways.
recover Command recover shows durable resume via named-step memoization: a run journals its model turns and tool results to the store, so re-invoking Run with the SAME runID against the SAME store reuses the recorded steps rather than re-running them.	Command recover shows durable resume via named-step memoization: a run journals its model turns and tool results to the store, so re-invoking Run with the SAME runID against the SAME store reuses the recorded steps rather than re-running them.
session Command session shows a durable multi-turn conversation: each Session.Send is one full agent run seeded with the transcript so far, so the agent remembers earlier turns.	Command session shows a durable multi-turn conversation: each Session.Send is one full agent run seeded with the transcript so far, so the agent remembers earlier turns.
signals Command signals shows the externally-pushed durable pauses: Await for a single-shot signal delivered from outside the run with agent.Journal.Signal, AwaitFor with a durable timeout (the signal-vs-deadline race), and an ordered per-run channel consumed exactly-once with Enqueue / Receive / Ack.	Command signals shows the externally-pushed durable pauses: Await for a single-shot signal delivered from outside the run with agent.Journal.Signal, AwaitFor with a durable timeout (the signal-vs-deadline race), and an ordered per-run channel consumed exactly-once with Enqueue / Receive / Ack.
smoke Command smoke runs the agent end-to-end against a live OpenAI-compatible endpoint (here, OpenRouter) to prove the loop + tool calling work against a real model.	Command smoke runs the agent end-to-end against a live OpenAI-compatible endpoint (here, OpenRouter) to prove the loop + tool calling work against a real model.
streaming Command streaming shows Agent.Stream: range the lifecycle Events to render progress (token deltas, turn boundaries, tool start/finish) while the durable loop runs underneath, then call Result for the terminal answer, which is what Run returns.	Command streaming shows Agent.Stream: range the lifecycle Events to render progress (token deltas, turn boundaries, tool start/finish) while the durable loop runs underneath, then call Result for the terminal answer, which is what Run returns.
subagent Command subagent shows a parent agent delegating to a SubAgent exposed as a tool.	Command subagent shows a parent agent delegating to a SubAgent exposed as a tool.
typed Command typed shows RunTyped[T]: the agent does its work with real tools, then returns a strongly-typed Go struct instead of free-form text.	Command typed shows RunTyped[T]: the agent does its work with real tools, then returns a strongly-typed Go struct instead of free-form text.
webhook Command webhook shows how to drive an agent from an inbound messenger webhook (Slack, Telegram, Twilio, Meta, Discord) without shipping any messenger-specific code in the SDK.	Command webhook shows how to drive an agent from an inbound messenger webhook (Slack, Telegram, Twilio, Meta, Discord) without shipping any messenger-specific code in the SDK.