examples/

Harbor examples

Runnable, worked examples of the Harbor runtime SDK. Everything here builds and is exercised by CI (go test ./examples/... in the examples job) — a drift in a public surface that breaks an example fails the build.

For step-by-step how-to guides, see docs/recipes/.

Layout

examples/
├── README.md              this file
├── harbor.yaml            annotated reference configuration
├── dev.yaml               `harbor dev` loop configuration
├── embed-runonce/         headless assemble → Stack.RunOnce one-call run
├── agents/
│   └── echo/              worked harbortest.Agent + test
└── tools/
    ├── weather/           worked in-process tool registration + test
    └── artifactstats/     worked pass-by-reference tool parameter + test

Example configs

Validate either with the in-tree config validator:

harbor validate ./examples/harbor.yaml

Example agents

agents/echo/ — EchoAgent implements the public harbortest.Agent interface (the same interface harbor scaffold produces) and is driven end-to-end by harbortest.RunOnce. Copy the package, keep the interface satisfaction and the compile-time assertion, and replace Run's body with your agent's real logic.

Example programs

embed-runonce/ — the embed adopter path end to end: build a config, assemble.Assemble a headless stack, then run a goal with a single blocking stack.RunOnce(ctx, goal, identity) call and print the answer envelope. Every import is the public sdk/ facade, so it builds verbatim from an external module. See docs/recipes/embed-harbor-headless.md step 4a for the walkthrough.

Example tools

tools/weather/ — registers a Go function as a Harbor in-process tool via inproc.RegisterFunc. The driver derives JSON Schemas from the typed input/output structs and wraps the function in the ToolPolicy reliability shell. The test shows the full register → resolve → invoke round-trip.

tools/artifactstats/ — takes content BY REFERENCE. It declares a field of type sdk/tools.ArtifactRef, so the derived schema shows the model a plain artifact-id string; the runtime resolves the id at dispatch, under the run's own (tenant, user, session), and hands the function the stored bytes. The tool returns only measurements of the content, never the content — the bytes enter the process and do not leave it, and the resolved value never reaches the trajectory, an event payload or a log. Use this shape whenever a tool needs to read something too large to route through a model's context.

Running the examples

# Build everything under examples/.
go build ./examples/...

# Run the worked-example tests.
go test ./examples/...