README
¶
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
Example configs
| File | Purpose |
|---|---|
harbor.yaml |
Annotated reference config covering every top-level section. Copy and adapt. |
dev.yaml |
The canonical harbor dev config. Copy to harbor.yaml at your project root. |
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.
Running the examples
# Build everything under examples/.
go build ./examples/...
# Run the worked-example tests.
go test ./examples/...
Directories
¶
| Path | Synopsis |
|---|---|
|
agents
|
|
|
echo
Package echo is a worked, runnable Harbor agent example.
|
Package echo is a worked, runnable Harbor agent example. |
|
Command embed-runonce is the worked example for the embed adopter path's one-call runner: assemble a headless Harbor stack, then run a goal with a single blocking Stack.RunOnce call and print the answer.
|
Command embed-runonce is the worked example for the embed adopter path's one-call runner: assemble a headless Harbor stack, then run a goal with a single blocking Stack.RunOnce call and print the answer. |
|
protocol-clients
|
|
|
conformance-fork
Package conformancefork is the in-tree worked example for certifying a Protocol-server fork (or embedder assembly) against Harbor's conformance suite.
|
Package conformancefork is the in-tree worked example for certifying a Protocol-server fork (or embedder assembly) against Harbor's conformance suite. |
|
event-viewer
command
Command event-viewer is the worked client from the Protocol adoption track's build-a-client guide (docs/site/protocol/build-a-client.md).
|
Command event-viewer is the worked client from the Protocol adoption track's build-a-client guide (docs/site/protocol/build-a-client.md). |
|
oidc-client-example
command
Command oidc-client-example is a worked Harbor Protocol client that obtains a JWT from an OAuth2 / OIDC provider via the client-credentials grant and attaches it to a production `harbor serve` instance.
|
Command oidc-client-example is a worked Harbor Protocol client that obtains a JWT from an OAuth2 / OIDC provider via the client-credentials grant and attaches it to a production `harbor serve` instance. |
|
tools
|
|
|
weather
Package weather is a worked, runnable example of registering a Go function as a Harbor in-process tool.
|
Package weather is a worked, runnable example of registering a Go function as a Harbor in-process tool. |