Repository navigation
Expand file tree
/
Copy pathllms-full.txt
More file actions
3231 lines (2567 loc) · 209 KB
/
Copy pathllms-full.txt
File metadata and controls
3231 lines (2567 loc) · 209 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# OpenHuman Embed
> Embed OpenHuman runtimes and independently configured agents in Rust applications.
- [Embedding OpenHuman](docs/gitbooks/en/developing/embed/README.md): `openhuman-embed` runs the OpenHuman core inside your Rust program. Your host owns the user interface, server transport and authentication flow; the core owns agent turns, memory, tools, approvals and execution policy. Calling its typed facades does not require a JSON-RPC server or the desktop shell.
- [Embedding API reference](docs/gitbooks/en/developing/embed/api-reference.md): Generate usable local Rust API documentation with `cargo doc -p openhuman-embed --no-deps --open`. Include `--features mcp,skills,channels,storage-sqlite` for the facade gates used by the offline examples, or select the feature set your host actually builds. For all exported optional surfaces use `--all-features`.
- [Embedding architecture](docs/gitbooks/en/developing/embed/architecture.md): Embed is the library facade above `openhuman-core`. The TinyHumans layer installs the backend SDK transport and owns product login/session behavior; the RPC layer adds JSON-RPC, server listeners and shipped host boot. A Rust embedder can stay at the facade when it owns those concerns itself.
- [Concepts](docs/gitbooks/en/developing/embed/concepts/README.md): Start with Runtime and agents to understand which settings are shared. Then follow the lifecycle of a request through provider selection, tools, approvals and its durable session. The scope tables distinguish runtime composition from the state a host must isolate per agent or profile.
- [Access and approvals](docs/gitbooks/en/developing/embed/concepts/access-approvals.md): `Access` groups permission level, origin, standing grants and trusted roots. Choose an origin and tier together: a trusted local host request and an external channel message are different security contexts. `Access::full()` configures both access fields. A sandbox is an additional execution boundary, configured through `AgentDefinitionSpec`.
- [Agents](docs/gitbooks/en/developing/embed/concepts/agents.md): Register an `AgentSpec` with `Runtime::agent`. Its ID selects the agent's home, durable session identity and addressed cron/channel work. An `Agent` clone refers to the same instance; it does not copy state or start another core. Runtime-wide credentials remain shared, so two agents are not two authenticated customers.
- [Channels](docs/gitbooks/en/developing/embed/concepts/channels.md): `Runtime::channels` creates listeners addressed to a live agent ID. A listener owns its transport task; dropping or stopping it ends that listener. The agent supplies the prompt, provider and tools used for every incoming message instead of handing messages to an operator agent.
- [Completer](docs/gitbooks/en/developing/embed/concepts/completer.md): Use `Completer` for one-shot text or structured generation when you do not need an agent, its tool loop or persistent transcript. It takes an explicit route and a `CompletionRequest`; the caller supplies the model and messages for every request.
- [Cron](docs/gitbooks/en/developing/embed/concepts/cron.md): The typed `Cron` facade creates named jobs with `JobSpec` and `JobSchedule`. `upsert` preserves a job's identity when the same name is configured again; `runs` exposes execution history. An agent-targeted job resolves the configured agent ID and executes with that agent's provider, prompt, tools and derived context.
- [Errors](docs/gitbooks/en/developing/embed/concepts/errors.md): Match the error type at its boundary: `RuntimeError` describes boot/configuration, `AgentError` describes registration/layout, and `CoreError` describes typed facade calls and turns. A missing compiled or selected domain is `CoreError::Unavailable`; it is a capability decision the host can reflect in its UI.
- [Hooks and seams](docs/gitbooks/en/developing/embed/concepts/hooks-seams.md): Runtime builders accept host-owned ports for storage, sessions, memory, tools and controller extensions. These are composition seams: the host supplies an implementation of the owning library's contract, while OpenHuman retains access policy, approvals and lifecycle.
- [MCP](docs/gitbooks/en/developing/embed/concepts/mcp.md): MCP connects a native agent turn to tools served over an MCP protocol transport. Configure a server on `AgentSpec::mcp`, with its transport, authentication and allowed tool names. Another agent on the same runtime does not inherit that server configuration.
- [Memory](docs/gitbooks/en/developing/embed/concepts/memory.md): `Runtime::memory(namespace)` returns a facade bound to that namespace. The caller establishes scope before sending record data; namespace identity is not taken from model arguments or record metadata. Learning and deletion use the selected memory engine contract.
- [Observability](docs/gitbooks/en/developing/embed/concepts/observability.md): Subscribe with `Runtime::events` before starting work you want to observe. Each event has a sequence number and runtime identity, with an agent ID and per-call turn ID where applicable. Repeated calls on the same durable session receive different turn IDs; the session ID is not the observation ID.
- [Profiles and SaaS](docs/gitbooks/en/developing/embed/concepts/profiles-saas.md): Ordinary runtime agents share an operator's configuration path and credentials. Use `ProfileRuntime` when one server serves different authenticated users who must not share those resources. Provision a profile, install its credential, and retain a `ProfileHandle` while serving that user's requests.
- [Providers](docs/gitbooks/en/developing/embed/concepts/providers.md): A runtime provider is the default inference choice for its agents. An agent can override it with an OpenAI-compatible route or a native `ChatModel<()>` through `Provider::custom`. The `providers` facade exposes the request/response contracts so custom adapters do not need to implement an HTTP server.
- [Runtime defaults](docs/gitbooks/en/developing/embed/concepts/runtime-defaults.md): The runtime's default provider, access policy and `ModelDefaults` reduce repeated setup. `AgentSpec` can override those defaults for an analyst, a writing agent or another workload without changing its siblings. Temperature and token limits are forwarded to the selected native model request, rather than being merely descriptive builder values.
- [Runtime](docs/gitbooks/en/developing/embed/concepts/runtime.md): A `Runtime` boots the in-process core once. It owns the selected domains, background services, module host and runtime defaults. Its agents share that core while using separately derived contexts. Build one runtime and pass an `Arc<Runtime>` to the parts of your application that register agents.
- [Skills](docs/gitbooks/en/developing/embed/concepts/skills.md): A skill bundle contains `SKILL.md` plus any referenced resources. `AgentSpec::skills_dir` copies bundles into the agent's `agents/<id>/skills/` tree. Copying is intentional: discovery rejects symlinked bundles, so linking a shared directory does not install it.
- [Testing](docs/gitbooks/en/developing/embed/concepts/testing.md): The runnable examples default to loopback fixtures. They assert request bodies, tool results, file effects, transcript scope and event ordering; a successful Rust compilation alone does not prove those behaviors. Live example execution is explicitly opt-in through the documented environment variables.
- [Tools](docs/gitbooks/en/developing/embed/concepts/tools.md): An agent's `ToolScopeSpec` chooses built-ins, named tools or `HostOnly`. Host-only mode starts with the host's advertised tools, requires an explicit bare prompt, and does not inherit an orchestrator tool catalog. This is useful when your application already owns read-only data access or tightly scoped actions.
- [Turns and sessions](docs/gitbooks/en/developing/embed/concepts/turns-sessions.md): `Agent::run` collects a turn. `Agent::turn` lets you set an explicit session, per-turn options, progress sink and cancellation before sending. Reuse the returned session identity for follow-up messages that should see the same transcript. Two calls on the same durable session remain distinct turn executions and receive distinct observation IDs.
- [Embedding FAQ](docs/gitbooks/en/developing/embed/faq.md): An ordinary embed process supports one `Runtime`; a second build returns `AlreadyRunning`. Add agents to the existing runtime. A multi-user host uses `ProfileRuntime` instead and needs a process dedicated to that mode. See runtime and profiles.
- [Embedding guides](docs/gitbooks/en/developing/embed/guides/README.md): Choose the guide that matches your host:
- [CLI chatbot](docs/gitbooks/en/developing/embed/guides/cli-chatbot.md): Keep one `Runtime` alive for the process and create an `Agent` for the conversation. The executable example starts with a single message, checks the reply, and prints it. A CLI input loop can send subsequent messages through the same agent; choose a stable thread identity when your host exposes separate conversations.
- [Deploy a server](docs/gitbooks/en/developing/embed/guides/deploy-server.md): Your HTTP host can keep a runtime alive and invoke its agents directly. The executable example binds a loopback listener, handles one request, and sends back the agent's reply. It exercises the request path without requiring an RPC server dependency in `openhuman-embed`.
- [Lean and headless hosts](docs/gitbooks/en/developing/embed/guides/lean-headless.md): `RuntimeBuilder::lean()` selects the agent, memory, and inference families without background services. Runtime module selection controls what is active; Cargo features control what is compiled. A lean preset alone does not shed compiled dependencies.
- [Test with a mock backend](docs/gitbooks/en/developing/embed/guides/mock-backend-testing.md): Run `node scripts/run-embed-examples.mjs` from the repository root. The runner builds and executes every example with the union of required features, clears inherited live-example credentials and operator workspace settings, and requires each program's `EXAMPLE_OK` marker after its assertions.
- [Multiple agents](docs/gitbooks/en/developing/embed/guides/multi-agent.md): A runtime owns shared services and credentials. Each `AgentSpec` selects its prompt, model route, access policy, and `action_dir`. Internal agent state belongs to its agent home; the action directory is where acting tools operate.
- [SaaS with multiple tenants](docs/gitbooks/en/developing/embed/guides/saas-multi-tenant.md): Use `ProfileRuntime` for a process serving multiple users. Provision each profile, install that profile's credential, and open a handle to its workspace. Reusing a thread id in two profiles does not share their conversation history.
- [Installation](docs/gitbooks/en/developing/embed/installation.md): `openhuman-embed` is currently an unpublished workspace crate. Use a local path dependency when developing in this repository, or a Git dependency on `https://github.com/tinyhumansai/openhuman` with `package = "openhuman-embed"`. Pin a reviewed Git revision for a deployed application; the nested vendored libraries are part of that revision's build inputs.
- [Embedding integrations](docs/gitbooks/en/developing/embed/integrations/README.md): An embedded runtime composes the capabilities its host supplies. Start with the adapter your application needs:
- [Channels](docs/gitbooks/en/developing/embed/integrations/channels.md): Enable the `channels` Cargo feature to use channel adapters. Your host configures the channel credential and binds incoming messages to an agent. In the Telegram example, the Bot API endpoint is a loopback stub, so updates and replies exercise the adapter without contacting Telegram.
- [Composio](docs/gitbooks/en/developing/embed/integrations/composio.md): Composio calls use the host backend transport. Install that transport before booting a managed runtime; see TinyHumans managed inference. An explicit inference provider route supplies model inference, not the connector transport.
- [Local and custom models](docs/gitbooks/en/developing/embed/integrations/local-models.md): For a local server that implements chat completions, use `Provider::openai_compatible` with its API root and model id. The constructor requires a bearer string even when a particular local server ignores it. Set the endpoint explicitly rather than relying on another user's installed configuration. The OpenAI-compatible example controls can point a live example at that local server.
- [MCP servers](docs/gitbooks/en/developing/embed/integrations/mcp.md): Enable the `mcp` Cargo feature and declare a server with `AgentSpec::mcp`. `McpServer::http` takes a registered name and endpoint; `allow_tools` narrows the remote tool list. Server configuration and its connections belong to the agent that declared them.
- [OpenAI-compatible providers and BYOK](docs/gitbooks/en/developing/embed/integrations/openai-compatible.md): Construct a route with `Provider::openai_compatible(base_url, api_key).model(model_id)`, then set it on the runtime or an individual agent. Pass the API root, such as a provider's `/v1` URL; the adapter appends `/chat/completions`. Supply an explicit model id so the route can register that model for its workload roles.
- [Storage drivers](docs/gitbooks/en/developing/embed/integrations/storage-drivers.md): Enable `storage-sqlite` for SQLite or `storage-mongodb` for MongoDB on your Embed dependency. These Cargo gates make the driver available; choosing a URL selects the runtime backend. Set `RuntimeConfig.storage.url`, pass a URL through `RuntimeBuilder::storage`, or set the `url` field in the `[storage]` section of the host's configuration. `OPENHUMAN_STORAGE_URL` is the environment override used by host configuration resolution.
- [TinyHumans managed inference](docs/gitbooks/en/developing/embed/integrations/tinyhumans-managed.md): Embed wraps the core; neither contains a TinyHumans backend client. A managed host boots through the builder in `openhuman-tinyhumans` (`openhuman_tinyhumans::RuntimeBuilder`), or calls `openhuman_tinyhumans::install`. That layer owns the transport, the authenticated client, the hosted routes and the hosted providers, and it plugs them into the core through the core's generic registries (chat models, voice, tool sources, the channel callback and memory engines). A host can register its own provider in the same registries. The connected host layer also owns session login. `RuntimeBuilder::backend_url` selects a URL; it does not connect anything.
- [Web search](docs/gitbooks/en/developing/embed/integrations/web-search.md): An agent's web-search tools (`web_search_tool`, `web_answer_tool`, `web_contents_tool`) run through the process-wide TinySearch module. Several agents in one runtime can each search with their own provider key: pin it on that agent's config, and it is never written to `config.toml`, the environment, or a log.
- [Quickstart](docs/gitbooks/en/developing/embed/quickstart.md): Start from a checkout of the repository and run `cargo run -p openhuman-embed --example run_turn`. The example boots an ephemeral runtime, creates its own local provider/backend fixtures and prints `hello from the stub`. It needs no inference account and does not contact a real backend.
- [Embedding troubleshooting](docs/gitbooks/en/developing/embed/troubleshooting.md): Use the typed error and the effective capability report together. A method that was compiled out is a different problem from a configured method with a provider failure. Keep credentials, user prompts and raw provider payloads out of routine diagnostics.
- [OpenHuman Embed](crates/openhuman-embed/README.md): A typed Rust facade for running the OpenHuman core inside your application: one Runtime per process, with independently configured Agents.
- [Embedding OpenHuman](docs/gitbooks/en/developing/embedding.md): The embedding documentation now lives in the Embedding section.
- [Cookbook](docs/gitbooks/en/developing/embed/cookbook.md): Executable recipes are indexed from their source headers. Each entry records the declared run mode and any named Embed feature required by the example. Full source includes the surrounding setup and assertions.
- [Compiled feature matrix](docs/gitbooks/en/developing/embed/capability-matrix.md): This matrix comes from the default-feature compiled capability-report example. Runtime presets can narrow enabled domains and services; core Cargo features determine which implementations are available. Named Embed features also gate facade exports: enable `mcp` or `skills` explicitly for their public setters even when core defaults compile those implementations. Embed defaults enable the named `channels` feature. See the installation guide for these separate layers.
- [RuntimeBuilder setters](docs/gitbooks/en/developing/embed/builder-setters.md): Public consuming methods that return `Self`, extracted from the RuntimeBuilder implementations. Static host and weight presets, inspection methods and build/run methods are excluded.
- [API index](docs/gitbooks/en/developing/embed/api-index.md): Generate the complete local Rust API reference with `cargo doc -p openhuman-embed --all-features --no-deps --open`. This crate is currently unpublished; docs.rs is a future publication target. Names below are source-listed exports, including conditional Cargo-gated items; local rustdoc with your selected features describes availability. Canonical facade source.
- [Embed examples](crates/openhuman-embed/examples/README.md): Cookbook
<!-- Source: docs/gitbooks/en/developing/embed/README.md -->
---
description: "Run the OpenHuman core inside a Rust application with one Runtime and independently configured Agents."
---
# Embedding OpenHuman
`openhuman-embed` runs the OpenHuman core inside your Rust program. Your host owns the user interface, server transport and authentication flow; the core owns agent turns, memory, tools, approvals and execution policy. Calling its typed facades does not require a JSON-RPC server or the desktop shell.
Build one `Runtime` per process and register the agents your product needs. Each agent can choose its own provider, prompt, working folder, tool scope, skills and MCP servers. Agents share runtime credentials; use `ProfileRuntime` when separate customers need separate credentials and workspaces.
## Start here
- [Installation](installation.md): dependency, Cargo gates, runtime setup and configuration.
- [Quickstart](quickstart.md): run a verified offline turn, then choose a live provider explicitly.
- [Architecture](architecture.md): ownership, lifecycle and the library chain.
- [Concepts](concepts/README.md): the 18 public API concepts and their runtime/agent scope.
- [Guides](guides/README.md): chatbots, multiple agents, SaaS, server deployment and tests.
- [Integrations](integrations/README.md): inference, MCP, connectors, storage and channels.
- [Cookbook](cookbook.md): generated inventory of executable examples.
- [API reference](api-reference.md): local rustdoc, source links and generated builder knobs.
## Choose the right surface
| Requirement | Start with |
| --- | --- |
| One agent with a small host | `Harness` |
| Several independently configured agents | `Runtime` and `AgentSpec` |
| Stateless model generation | `Completer` |
| Authenticated users with isolated credentials and state | `ProfileRuntime` |
| Public JSON-RPC server or shipped desktop host | The `openhuman-rpc` host layer |
The snippets in this section are injected from compiled, offline-tested Rust examples. Their full source files include the surrounding setup. `pnpm docs:check` checks source drift, local links, the generated API inventory and the published English mirror.
See [FAQ](faq.md) for design choices and [troubleshooting](troubleshooting.md) for setup failures.
<!-- Source: docs/gitbooks/en/developing/embed/api-reference.md -->
---
description: "Use local rustdoc and source-derived indexes for the complete Embed public surface."
---
# Embedding API reference
Generate usable local Rust API documentation with `cargo doc -p openhuman-embed --no-deps --open`. Include `--features mcp,skills,channels,storage-sqlite` for the facade gates used by the offline examples, or select the feature set your host actually builds. For all exported optional surfaces use `--all-features`.
The crate is currently `publish = false`; docs.rs links are a publication metadata target, not a claim that a live package reference exists. Local rustdoc and [canonical facade source](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/src/lib.rs) are the current complete reference.
## Generated inventories
- [API index](api-index.md): names exported by the public facade and a versioned runtime report.
- [Machine-readable API index](api-index.json): export names, builder signatures, capabilities and page paths.
- [RuntimeBuilder setters](builder-setters.md): current public consuming setters with source locations.
- [Compiled feature matrix](capability-matrix.md): the actual core gates from the default-feature capability-report executable.
- [Cookbook](cookbook.md): example titles, run modes and required named facade features from source headers.
The generated setter list is the authoritative knob inventory. It excludes static presets and borrowed inspection/build/run methods; those belong in local rustdoc. Core compiled gates, runtime module/domain selection and named facade exports are separate availability layers.
## Public surface by purpose
| Purpose | API starting point |
| --- | --- |
| Boot and inspect a host | `RuntimeBuilder`, `Runtime`, `RuntimeInfo` |
| Register and remove scoped agents | `AgentSpec`, `Agent`, `AgentDefinitionSpec`, `RemoveAgent` |
| Configure execution and decisions | `Access`, `SandboxModeSpec`, `Approvals`, `ApprovalHandler` |
| Execute or stream native turns | `Turn`, `TurnOutcome`, `TurnStream`, `StreamEvent` |
| Supply custom model adapters | `Provider` and `providers::ChatModel` |
| Stateless generation | `Completer`, `CompletionRequest`, structured response helpers |
| Typed non-turn domains | Memory and cron facades, config/auth/artifacts/chat surface |
| Replace infrastructure ports | `seams`, `session_store`, memory engine and provider contracts |
| Serve isolated customer profiles | `ProfileRuntime`, `ProfileHandle`, `SaasConfig` |
## Versioned capability data
<!-- BEGIN EMBED: crates/openhuman-embed/examples/capability_report.rs#capability_report -->
```rust
let info = runtime.capabilities();
assert_eq!(info.schema_version, 1);
assert!(info.defaults.routed_provider);
let serialized = serde_json::to_string(&info)?;
assert!(!serialized.contains("sk-test"));
assert!(!serialized.contains(&provider.uri()));
assert!(!serialized.contains(&runtime.workspace_dir().display().to_string()));
println!("{}", serde_json::to_string_pretty(&info)?);
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/capability_report.rs), including runtime construction, imports and fixture setup.
The report's schema version is explicit. Read its fields rather than inferring capabilities from preset names, and handle future schema changes deliberately. It omits endpoint, credential, prompt and workspace values so hosts can expose build metadata without exposing private configuration.
<!-- Source: docs/gitbooks/en/developing/embed/architecture.md -->
---
description: "The host composes infrastructure around one core; agents derive scoped contexts over its runtime."
---
# Embedding architecture
Embed is the library facade above `openhuman-core`. The TinyHumans layer installs the backend SDK transport and owns product login/session behavior; the RPC layer adds JSON-RPC, server listeners and shipped host boot. A Rust embedder can stay at the facade when it owns those concerns itself.
## Ownership boundaries
| Component | Owns |
| --- | --- |
| Your application | UI/HTTP transport, user authentication, supplied credentials, application tools and resource lifetimes |
| OpenHuman core and Embed facade | Runtime composition, per-agent context, policy, approvals, sandbox selection and typed domain calls |
| TinyAgents | Model/tool loop, parsing, dialects, durable sessions and transcript replay |
| TinyInference | Native model/provider contracts and generic ordered fallback |
| TinyTools | Shared tool traits and contract types |
| Storage and module libraries | Their backend/module implementations; OpenHuman adapts and orchestrates them |
The library chain is core → Embed → TinyHumans → RPC → app/CLI/TUI. Shipped hosts depend on the layer immediately below them and use its curated facades. Embed users should not build new integrations on doc-hidden `__host` internals.
## Runtime composition versus agent scope
Cargo features decide which implementations exist in an artifact. Runtime domains, services, tool groups and module selection narrow those compiled choices. Agent specs narrow the runtime further and add provider, access, prompt, skills, MCP and action-directory choices.
A turn dispatches through the agent's native context, not through JSON-RPC or an operator fallback. Recursive child contexts inherit the parent host overrides, including custom provider and hook composition, while independent sibling agents remain separately scoped.
<!-- BEGIN EMBED: crates/openhuman-embed/examples/two_agents.rs#two_agents -->
```rust
let analyst_dir = tempfile::tempdir()?;
let writer_dir = tempfile::tempdir()?;
let analyst = runtime.agent(
AgentSpec::new("analyst")
.system_prompt("ANALYST_PROMPT: summarize documents")
.action_dir(analyst_dir.path())
.access(openhuman_embed::Access::readonly()),
)?;
let writer = runtime.agent(
AgentSpec::new("writer")
.system_prompt("WRITER_PROMPT: compose explanations")
.action_dir(writer_dir.path())
.access(openhuman_embed::Access::full()),
)?;
assert_ne!(analyst.action_dir(), writer.action_dir());
assert_ne!(analyst.home_dir(), writer.home_dir());
assert_ne!(analyst.workspace_dir(), analyst.action_dir());
assert!(!analyst.run("Analyze").await?.reply.is_empty());
assert!(!writer.run("Explain").await?.reply.is_empty());
if support::offline() {
let requests = support::chat_requests(&provider).await;
assert_eq!(requests.len(), 2);
assert!(String::from_utf8_lossy(&requests[0].body).contains("ANALYST_PROMPT"));
assert!(!String::from_utf8_lossy(&requests[0].body).contains("WRITER_PROMPT"));
assert!(String::from_utf8_lossy(&requests[1].body).contains("WRITER_PROMPT"));
}
println!("two distinct prompts and action workspaces verified");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/two_agents.rs), including runtime construction, imports and fixture setup.
## Lifetime and isolation
An agent handle keeps the core alive after the runtime handle is dropped. Explicit removal marks that instance removed, cancels turns and callbacks, denies parked approvals and clears its state/MCP registration. The ID remains reserved through cleanup, including natural last-handle destruction and cancellation of a started removal. Pointer-checked release prevents an old retained instance from removing a newer registry entry.
Agent separation is not credential separation: all ordinary runtime agents share the operator's config path and credential root. Use [profiles](concepts/profiles-saas.md) for independently authenticated users. See [storage architecture](../architecture/storage.md) for scope/driver ownership and [agent harness architecture](../architecture/agent-harness.md) for session execution.
<!-- Source: docs/gitbooks/en/developing/embed/concepts/README.md -->
---
description: "The ownership and lifecycle rules behind the Embed public API."
---
# Concepts
Start with Runtime and agents to understand which settings are shared. Then follow the lifecycle of a request through provider selection, tools, approvals and its durable session. The scope tables distinguish runtime composition from the state a host must isolate per agent or profile.
- [Runtime](runtime.md): A Runtime owns one initialized core and the process-wide resources that its agents share.
- [Runtime defaults](runtime-defaults.md): Runtime defaults form the starting point for newly registered agents; explicit agent settings override them.
- [Agents](agents.md): An Agent combines one identity, derived context and independently configured tool/model behavior on a shared Runtime.
- [Access and approvals](access-approvals.md): Access configures turn identity and permission policy; the host chooses how parked requests receive decisions.
- [Providers](providers.md): A provider supplies a route or native ChatModel implementation, with agent overrides and optional ordered fallback.
- [Turns and sessions](turns-sessions.md): A turn is one native model/tool loop; a session is the durable identity that makes subsequent turns a conversation.
- [Tools](tools.md): Tool catalogs expose only the allowed execution surface; host tools use the same native Tool contract as built-in tools.
- [MCP](mcp.md): MCP servers add remote tool discovery and execution to one agent, with explicit server configuration and tool allowlists.
- [Skills](skills.md): Skills are copied bundles of instructions and resources discovered inside an agent’s own home.
- [Memory](memory.md): The typed memory facade binds a namespace before learning, retrieving or forgetting records.
- [Cron](cron.md): Cron provides durable named jobs, explicit run-now execution and job history addressed to registered agents.
- [Channels](channels.md): A channel listener binds external messages to one registered agent and keeps transport lifecycle under host control.
- [Profiles and SaaS](profiles-saas.md): ProfileRuntime isolates authenticated users by workspace, credentials, conversations and event streams.
- [Completer](completer.md): Completer sends stateless model requests without booting a Runtime or entering the agent tool loop.
- [Hooks and seams](hooks-seams.md): Host seams replace infrastructure ports; hooks observe or control selected turn and tool boundaries.
- [Observability](observability.md): Runtime metadata events track lifecycle and approvals; turn streams carry per-turn progress and the final result.
- [Testing](testing.md): Deterministic local providers and explicit observations prove behavior without contacting real inference or backend services.
- [Errors](errors.md): Typed errors distinguish build availability, expected domain states, host setup failures and removed agent instances.
<!-- Source: docs/gitbooks/en/developing/embed/concepts/access-approvals.md -->
---
description: "Access configures turn identity and permission policy; the host chooses how parked requests receive decisions."
---
# Access and approvals
`Access` groups permission level, origin, standing grants and trusted roots. Choose an origin and tier together: a trusted local host request and an external channel message are different security contexts. `Access::full()` configures both access fields. A sandbox is an additional execution boundary, configured through `AgentDefinitionSpec`.
The core autonomy policy is disabled by default. Set `config.autonomy.enabled` when you require its command classification, approval gate, allowlist and budget enforcement. Platform isolation and the credential/system-root safety floor have separate responsibilities; a tool group filter is not an operating-system sandbox.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Autonomy policy defaults and installed approval gate | Origin, access tier, grants, trusted roots and scoped decisions |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/approvals.rs#approvals -->
```rust
let scratch = tempfile::tempdir()?;
let marker = scratch.path().join("approved-marker");
let write_provider = support::scripted_provider(
vec![support::tool_call_completion(
"shell",
&serde_json::json!({"command": format!("touch {}", marker.display())}).to_string(),
)],
"approved",
)
.await;
let agent = runtime.agent(
AgentSpec::new("supervised")
.provider(support::route(&write_provider, "fixture"))
.action_dir(scratch.path())
.access(
openhuman_embed::Access::supervised()
.origin(openhuman_embed::AgentTurnOrigin::WebChat {
thread_id: "demo".into(),
client_id: "host".into(),
request_id: None,
})
.auto_approve(Vec::<String>::new())
.auto_approve_all(false)
.trust(
scratch.path().display().to_string(),
openhuman_embed::TrustedAccess::ReadWrite,
),
)
.definition(
AgentDefinitionSpec::new().tools(ToolScopeSpec::Named(vec!["shell".into()])),
),
)?;
let pending_agent = agent.clone();
let turn = tokio::spawn(async move { pending_agent.run("Create a marker").await });
let pending = support::eventually("approval", || {
agent.approvals().pending().ok()?.into_iter().next()
})
.await;
assert!(!marker.exists(), "execution waits for the host decision");
assert_eq!(pending.agent_id.as_deref(), Some("supervised"));
agent.approvals().decide(
&pending.request_id,
openhuman_embed::ApprovalDecision::ApproveOnce,
)?;
assert_eq!(turn.await??.reply, "approved");
assert!(marker.exists());
assert!(agent.approvals().pending()?.is_empty());
println!("parked write executed only after approval");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/approvals.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The verified example enables autonomy before building the runtime. It starts a real shell write, observes that no marker exists while the call is parked, and creates it only after `ApproveOnce`. `agent.approvals()` lists and decides only that instance's requests. A removed instance returns an empty pending list and rejects decisions even if the same public ID has been reused.
For asynchronous integration use `AgentSpec::approval_handler` or retain the handle returned by `Agent::handle_approvals`. Dropping a subscription cancels its pending decision future; it does not silently approve the request. Agent removal cancels both builder and live callbacks. Continue with the [approval callback example](../cookbook.md#polling-and-callback-approvals-with-cancellation) and [sandbox guide](../guides/multi-agent.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/agents.md -->
---
description: "An Agent combines one identity, derived context and independently configured tool/model behavior on a shared Runtime."
---
# Agents
Register an `AgentSpec` with `Runtime::agent`. Its ID selects the agent's home, durable session identity and addressed cron/channel work. An `Agent` clone refers to the same instance; it does not copy state or start another core. Runtime-wide credentials remain shared, so two agents are not two authenticated customers.
Keep `action_dir` separate from the internal workspace. The action directory is where tools act; the agent home stores internal transcripts, skills and other state. The example gives an analyst and a writer distinct folders and prompts while sharing one provider connection setup.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Core, shared configuration path and registry capacity | ID, context, prompt, action directory, provider and per-agent stores |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/two_agents.rs#two_agents -->
```rust
let analyst_dir = tempfile::tempdir()?;
let writer_dir = tempfile::tempdir()?;
let analyst = runtime.agent(
AgentSpec::new("analyst")
.system_prompt("ANALYST_PROMPT: summarize documents")
.action_dir(analyst_dir.path())
.access(openhuman_embed::Access::readonly()),
)?;
let writer = runtime.agent(
AgentSpec::new("writer")
.system_prompt("WRITER_PROMPT: compose explanations")
.action_dir(writer_dir.path())
.access(openhuman_embed::Access::full()),
)?;
assert_ne!(analyst.action_dir(), writer.action_dir());
assert_ne!(analyst.home_dir(), writer.home_dir());
assert_ne!(analyst.workspace_dir(), analyst.action_dir());
assert!(!analyst.run("Analyze").await?.reply.is_empty());
assert!(!writer.run("Explain").await?.reply.is_empty());
if support::offline() {
let requests = support::chat_requests(&provider).await;
assert_eq!(requests.len(), 2);
assert!(String::from_utf8_lossy(&requests[0].body).contains("ANALYST_PROMPT"));
assert!(!String::from_utf8_lossy(&requests[0].body).contains("WRITER_PROMPT"));
assert!(String::from_utf8_lossy(&requests[1].body).contains("WRITER_PROMPT"));
}
println!("two distinct prompts and action workspaces verified");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/two_agents.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
IDs stay reserved until teardown completes, including while the last handle's destructor is clearing state. `remove_agent(id).await` marks retained handles removed, cancels active turns, denies parked approvals and releases the ID after cleanup. Add `.purge()` only when the agent's persisted home should also be deleted. Cancelling a started removal still performs teardown and a requested purge.
An old polling handle or approval callback never follows a reused ID to its replacement. Active host tools cancel cooperatively and may finish their external work after removal; the host still owns those external lifetimes. See [turns and sessions](turns-sessions.md) and [access and approvals](access-approvals.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/channels.md -->
---
description: "A channel listener binds external messages to one registered agent and keeps transport lifecycle under host control."
---
# Channels
`Runtime::channels` creates listeners addressed to a live agent ID. A listener owns its transport task; dropping or stopping it ends that listener. The agent supplies the prompt, provider and tools used for every incoming message instead of handing messages to an operator agent.
The named Embed `channels` feature is enabled by default. The runtime must also allow the channel family. Create listeners inside the Tokio runtime after their agents have been registered.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Channel implementation, listener registry and runtime domain ceiling | Bound agent, conversation identity and external-message access context |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/telegram.rs#telegram -->
```rust
let bot = wiremock::MockServer::start().await;
let token = "123456:EXAMPLE";
let updates = format!("/bot{token}/getUpdates");
wiremock::Mock::given(wiremock::matchers::path(updates.clone())).respond_with(
wiremock::ResponseTemplate::new(200).set_body_json(serde_json::json!({"ok":true,"result":[{
"update_id":1,"message":{"message_id":1,"date":0,"text":"hello channel",
"from":{"id":99,"is_bot":false,"username":"alice"},"chat":{"id":4242,"type":"private"}}
}]}))).up_to_n_times(1).with_priority(1).mount(&bot).await;
wiremock::Mock::given(wiremock::matchers::path(updates))
.respond_with(
wiremock::ResponseTemplate::new(200)
.set_body_json(serde_json::json!({"ok":true,"result":[]}))
.set_delay(std::time::Duration::from_millis(100)),
)
.with_priority(2)
.mount(&bot)
.await;
wiremock::Mock::given(wiremock::matchers::any())
.respond_with(
wiremock::ResponseTemplate::new(200)
.set_body_json(serde_json::json!({"ok":true,"result":{
"message_id":2,"id":1,"is_bot":true,"username":"example_bot"}})),
)
.with_priority(10)
.mount(&bot)
.await;
std::env::set_var("OPENHUMAN_TELEGRAM_BOT_API_BASE", bot.uri());
let agent = runtime.agent(
AgentSpec::new("channel-agent").definition(
AgentDefinitionSpec::new()
.bare_prompt("Reply briefly.")
.tools(ToolScopeSpec::HostOnly),
),
)?;
let listener = runtime.channels().telegram(
openhuman_embed::TelegramChannelSpec::new(token, agent.id()).allowed_users(["alice"]),
)?;
let mut sent = false;
for _ in 0..200 {
let requests = bot.received_requests().await.unwrap_or_default();
sent = requests.iter().any(|request| {
request.url.path().ends_with("/sendMessage")
&& serde_json::from_slice::<serde_json::Value>(&request.body).is_ok_and(|body| {
body["chat_id"].to_string().contains("4242")
&& body["text"]
.as_str()
.is_some_and(|text| text.contains("hello from the stub"))
})
});
if sent {
break;
}
tokio::time::sleep(std::time::Duration::from_millis(50)).await;
}
listener.stop();
assert!(
sent,
"the bound agent must send a reply to the stub Bot API"
);
std::env::remove_var("OPENHUMAN_TELEGRAM_BOT_API_BASE");
println!("Telegram update answered in the correct chat");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/telegram.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The verified Telegram example uses a local Bot API stub, so the channel test does not contact Telegram. Its live mode requires explicit example credentials and remains opt-in.
External messages use `ExternalChannel` origin and a read-only cap. Model-requested writes and other external effects are not parked for approval from the sender. Keep public-chat tools read-only and perform authorized side effects in host code or a separately configured job. When the bound agent is removed, channel work fails as unavailable instead of falling back to the operator. See [channel integration](../integrations/channels.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/completer.md -->
---
description: "Completer sends stateless model requests without booting a Runtime or entering the agent tool loop."
---
# Completer
Use `Completer` for one-shot text or structured generation when you do not need an agent, its tool loop or persistent transcript. It takes an explicit route and a `CompletionRequest`; the caller supplies the model and messages for every request.
A standalone completer does not claim the process runtime slot. An agent-backed completion uses the agent's effective configuration but still has no implicit durable session. Keep conversation state in your application if you need several completion calls to form a conversation.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| No runtime required for a standalone routed Completer | Optional effective agent configuration; no implicit tools or transcript |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/completer.rs#completer -->
```rust
let route = support::example_provider(&provider)?;
let completer = openhuman_embed::Completer::new(route.route().expect("explicit route").clone());
let response = completer
.complete(openhuman_embed::CompletionRequest::new(
route.model_id().expect("explicit model"),
vec![openhuman_embed::ChatMessage::user("Say hello")],
))
.await?;
assert!(!response.text.is_empty());
if support::offline() {
assert_eq!(response.text, "completion reply");
assert_eq!(support::chat_requests(&provider).await.len(), 1);
}
println!("{}", response.text);
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/completer.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example checks that exactly one inference request was made and verifies the returned text. It uses a local provider fixture by default; the source contains the explicit opt-in live route path.
Choose `Agent` when a model should call tools, resume a durable thread or execute with an agent's access context. Choose the structured completion helpers when the host only needs a validated data result. For routes and transport failures see [providers](providers.md) and [errors](errors.md).
## Timeouts and fallback
Set `CompletionRequest::timeout_ms(120_000)` to bound each physical provider HTTP request to 120 seconds. The optional field defaults to unset and is omitted from serialized requests when absent, retaining the provider's transport defaults. Each structured repair attempt receives its own physical timeout; this is not a total completion or ladder deadline.
A physical timeout is an RPC transport failure, so an explicit `CompletionLadder` can try its next route. By contrast, `Completer::timeout(duration)` bounds the entire logical completion, including repair attempts, and returns terminal `DeadlineExceeded`. Cancellation also stops the ladder without fallback. You can use both bounds when the host needs separate physical and logical limits.
A timed-out physical attempt has unknown reported cost. Ladder aggregate cost stays unknown, and a budgeted call keeps its conservative reservation if no authoritative usage arrived. The remaining budget may therefore refuse a fallback before it sends another request. See the [routing guide](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/ROUTING.md) for the explicit ladder API.
## Provider dispatch observation
Attach `Completer::physical_observer` to receive one content-free start and terminal outcome for each provider invocation. The observer runs inside budget admission, so a request refused by the budget produces no dispatch event. A dropped in-flight request reports cancellation; terminal outcomes carry duration and provider-reported usage when available. The existing `CompletionObserver` remains a logical completion hook and still fires once for the whole call, including structured repair attempts.
<!-- Source: docs/gitbooks/en/developing/embed/concepts/cron.md -->
---
description: "Cron provides durable named jobs, explicit run-now execution and job history addressed to registered agents."
---
# Cron
The typed `Cron` facade creates named jobs with `JobSpec` and `JobSchedule`. `upsert` preserves a job's identity when the same name is configured again; `runs` exposes execution history. An agent-targeted job resolves the configured agent ID and executes with that agent's provider, prompt, tools and derived context.
Background scheduling is a runtime service choice. Explicit `run_now` is useful for tests and host-triggered execution without relying on wall-clock scheduling. Keep the agent registered while scheduled work should be available.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Cron storage, scheduler service and system-job handlers | Addressed job target and the agent configuration used for its turn |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/cron.rs#cron -->
```rust
let agent = runtime.agent(AgentSpec::new("scheduled"))?;
let cron = runtime.cron();
let spec = openhuman_embed::JobSpec::agent(
"daily",
agent.id(),
"Say hello",
openhuman_embed::JobSchedule::Cron {
expr: "0 0 * * *".into(),
tz: None,
},
);
let first = cron.upsert(spec.clone())?;
assert_eq!(cron.upsert(spec)?.id, first.id);
let run = cron.run_now("daily").await?;
assert!(run.success, "{}", run.output);
if support::offline() {
assert!(run.output.contains("hello from the stub"));
}
assert_eq!(cron.runs("daily", 1)?[0].status, "ok");
assert!(cron.remove("daily")?);
assert!(cron.list()?.is_empty());
println!("cron execution and history verified");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/cron.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example checks stable upsert identity, executes a job immediately, inspects a successful run record, and removes the job. No test waits for a daily schedule to arrive.
Removing or dropping an agent deregisters its context, leaving addressed cron jobs dormant rather than silently running them as the operator. Hosts can register runtime system-job handlers for work they own outside a model turn. Review [runtime configuration](runtime-defaults.md) and [channels](channels.md) when mixing scheduled work with public chat input.
<!-- Source: docs/gitbooks/en/developing/embed/concepts/errors.md -->
---
description: "Typed errors distinguish build availability, expected domain states, host setup failures and removed agent instances."
---
# Errors
Match the error type at its boundary: `RuntimeError` describes boot/configuration, `AgentError` describes registration/layout, and `CoreError` describes typed facade calls and turns. A missing compiled or selected domain is `CoreError::Unavailable`; it is a capability decision the host can reflect in its UI.
A structured `CoreError::Domain` carries a stable kind and `expected_user_state`. Expected stale-session or missing-resource states should be shown as notices rather than treated as internal faults. `Decode` signals a facade/domain shape mismatch; retrying unchanged input does not repair it.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Boot errors, unavailable domains and shared transport setup | Registration errors, scoped domain failures and AgentRemoved on retained handles |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/sandbox_access.rs#sandbox_access -->
```rust
let scratch = tempfile::tempdir()?;
let marker = scratch.path().join("attempted-write");
let attempted_write = support::tool_call_completion(
"write_file",
&serde_json::json!({
"path": marker.display().to_string(), "content": "example"
})
.to_string(),
);
let read_provider = support::scripted_provider(vec![attempted_write], "write refused").await;
let read = runtime.agent(
AgentSpec::new("read")
.provider(support::route(&read_provider, "fixture"))
.action_dir(scratch.path())
.access(openhuman_embed::Access::readonly())
.definition(
AgentDefinitionSpec::new().sandbox(openhuman_embed::SandboxModeSpec::ReadOnly),
),
)?;
let full = runtime.agent(AgentSpec::new("full").access(openhuman_embed::Access::full()))?;
assert_ne!(read.config().autonomy.level, full.config().autonomy.level);
assert!(!read.run("Write a marker").await?.reply.is_empty());
assert!(
!marker.exists(),
"readonly sandbox must refuse the attempted write"
);
let requests = support::chat_requests(&read_provider).await;
assert!(!support::tool_names(&requests[0]).contains(&"write_file".to_string()));
println!("readonly sandbox refused a model-requested write");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/sandbox_access.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example's refused write is handled as a tool result while the turn can still finish with a reply. Do not assume every rejected tool action is a failed turn. Conversely, a finished stream can contain an error; always inspect `StreamEvent::Finished`.
Bearer routes refuse non-TLS remote endpoints before sending credentials. `BACKEND_UNAVAILABLE` means the embed-only host has no backend transport installed; check the host layer before rotating keys. Agent removal makes later turns on retained handles return `AgentRemoved`, even when its ID now belongs to another instance. See [troubleshooting](../troubleshooting.md) and [provider integration](../integrations/openai-compatible.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/hooks-seams.md -->
---
description: "Host seams replace infrastructure ports; hooks observe or control selected turn and tool boundaries."
---
# Hooks and seams
Runtime builders accept host-owned ports for storage, sessions, memory, tools and controller extensions. These are composition seams: the host supplies an implementation of the owning library's contract, while OpenHuman retains access policy, approvals and lifecycle.
Learning sinks and tool hooks can be registered runtime-wide or on one agent. Agent hooks compose with parent runtime hooks and do not leak into sibling contexts. Use the live API's registration key to replace or remove runtime registrations; changes apply to subsequent turns. Learning sinks receive the upstream `TurnSummary`, while tool hooks receive the turn's `OpenHumanRunContext` and tool event.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Shared port implementations and keyed global hook registrations | Scoped hooks and host overrides inherited by recursive child contexts |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/hooks.rs#hooks -->
```rust
let count = std::sync::Arc::new(std::sync::atomic::AtomicUsize::new(0));
let agent = runtime.agent(
AgentSpec::new("hooked").post_turn_hook(std::sync::Arc::new(Counter(count.clone()))),
)?;
let sibling = runtime.agent(AgentSpec::new("sibling"))?;
assert!(!agent.run("Hello hook").await?.reply.is_empty());
support::eventually("post-turn hook", || {
(count.load(std::sync::atomic::Ordering::SeqCst) == 1).then_some(())
})
.await;
assert!(!sibling.run("Hello sibling").await?.reply.is_empty());
assert_eq!(count.load(std::sync::atomic::Ordering::SeqCst), 1);
println!("post-turn hook isolated to its agent");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/hooks.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example verifies that an agent-local post-turn counter observes the configured agent and not its sibling. Runtime live add/remove behavior is demonstrated in the [runtime events example](../cookbook.md#runtime-lifecycle-events-and-live-hook-registration).
Removing or replacing a builder-installed named hook through the runtime API affects that registration too; the runtime tracks and restores prior process slots when its seam ownership ends. Keep hooks fast, cancellation-aware and free of sensitive logging. Use the generated [setter list](../builder-setters.md) and [API reference](../api-reference.md) for the actual port signatures.
<!-- Source: docs/gitbooks/en/developing/embed/concepts/mcp.md -->
---
description: "MCP servers add remote tool discovery and execution to one agent, with explicit server configuration and tool allowlists."
---
# MCP
MCP connects a native agent turn to tools served over an MCP protocol transport. Configure a server on `AgentSpec::mcp`, with its transport, authentication and allowed tool names. Another agent on the same runtime does not inherit that server configuration.
Enable the named Embed `mcp` Cargo feature for `McpServer` and the agent setter. The default core may already contain MCP code, but a core capability flag does not activate a separately gated Embed API. Runtime domain selection must also allow the MCP family.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Compiled MCP implementation and runtime domain ceiling | Server configuration, auth, discovery and allowed remote tools |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/mcp.rs#mcp -->
```rust
let mcp = wiremock::MockServer::start().await;
wiremock::Mock::given(wiremock::matchers::method("POST"))
.respond_with(McpStub)
.mount(&mcp)
.await;
let discovery = wiremock::MockServer::start().await;
wiremock::Mock::given(wiremock::matchers::path("/v1/chat/completions"))
.respond_with(ForecastModel(std::sync::atomic::AtomicUsize::new(0)))
.mount(&discovery)
.await;
let agent = runtime.agent(
AgentSpec::new("mcp-client")
.provider(support::route(&discovery, "fixture"))
.mcp(
openhuman_embed::McpServer::http("forecast", format!("{}/mcp", mcp.uri()))
.allow_tools(["forecast"]),
)
.access(openhuman_embed::Access::full()),
)?;
assert_eq!(
agent
.run("List the forecast server tools, then call its forecast tool")
.await?
.reply,
"sunny verified"
);
let requests = mcp.received_requests().await.expect("MCP requests");
let methods: Vec<String> = requests
.iter()
.filter_map(|r| {
serde_json::from_slice::<serde_json::Value>(&r.body).ok()?["method"]
.as_str()
.map(str::to_string)
})
.collect();
assert!(methods.iter().any(|m| m == "initialize"), "{methods:?}");
assert!(methods.iter().any(|m| m == "tools/list"), "{methods:?}");
assert!(methods.iter().any(|m| m == "tools/call"), "{methods:?}");
let requests = support::chat_requests(&discovery).await;
assert!(support::tool_results(&requests[1]).contains("forecast"));
assert!(support::tool_results(&requests[2]).contains("sunny"));
println!("MCP handshake, discovery and remote execution verified");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/mcp.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example uses a real loopback protocol stub: it verifies initialization, `tools/list`, and `tools/call`, then checks that the model saw the remote result. It does not call an external MCP service or require credentials.
Tool allowlists reduce the remote catalog before model disclosure. Server authentication remains host-owned input, and remote tool side effects still pass through the relevant execution/access policy. Removing the agent evicts its MCP host after old-instance teardown, before the ID can be reused. See the [MCP integration](../integrations/mcp.md) for deployment setup.
<!-- Source: docs/gitbooks/en/developing/embed/concepts/memory.md -->
---
description: "The typed memory facade binds a namespace before learning, retrieving or forgetting records."
---
# Memory
`Runtime::memory(namespace)` returns a facade bound to that namespace. The caller establishes scope before sending record data; namespace identity is not taken from model arguments or record metadata. Learning and deletion use the selected memory engine contract.
A custom `memory_engine` can replace the default engine for a host or test. An agent's `MemoryBinding` configures its own memory context, while the runtime owns engine availability. Scope namespaces separately from provider/model choices: changing inference does not move a record to another tenant.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Memory engine seam and available memory domain | MemoryBinding, acting context and bound namespace |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/memory.rs#memory -->
```rust
let acme = runtime.memory("team:acme")?;
let other = runtime.memory("team:other")?;
let params = serde_json::from_value(serde_json::json!({"text":"Acme ships on Fridays"}))?;
let learned = acme.learn(params).await?;
let hits = acme.get(vec![learned.id.clone()]).await?;
assert_eq!(hits.len(), 1);
assert_eq!(hits[0].meta.namespace.to_string(), "team:acme");
assert!(other.get(vec![learned.id.clone()]).await?.is_empty());
assert_eq!(other.forget(vec![learned.id.clone()]).await?.forgotten, 0);
assert_eq!(acme.forget(vec![learned.id]).await?.forgotten, 1);
println!("memory learning, tenant isolation and deletion verified");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/memory.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example uses the reference in-memory engine and proves that another namespace cannot retrieve or forget the first namespace's record. Forgetting succeeds only through the owning namespace. This is a scope test, not a persistence claim; choose a durable engine/backend for application state that must survive restarts.
Background conversation ingestion can run independently of a completed turn. Tests should disable unrelated learning/ingest activity when asserting ephemeral-workspace cleanup. See [runtime defaults](runtime-defaults.md), [storage drivers](../integrations/storage-drivers.md), and the [memory architecture](../../architecture/memory.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/observability.md -->
---
description: "Runtime metadata events track lifecycle and approvals; turn streams carry per-turn progress and the final result."
---
# Observability
Subscribe with `Runtime::events` before starting work you want to observe. Each event has a sequence number and runtime identity, with an agent ID and per-call turn ID where applicable. Repeated calls on the same durable session receive different turn IDs; the session ID is not the observation ID.
Runtime events contain lifecycle metadata, not user prompts or model output. Detailed text/tool progress belongs to the explicitly requested turn stream. A bounded event receiver reports lag explicitly rather than silently claiming that it delivered every event.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Runtime sequence, content-safe lifecycle feed and registered-agent filter | Per-call turn correlation and opt-in text/tool progress stream |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/runtime_events.rs#runtime_events -->
```rust
let mut events = runtime.events();
let count = Arc::new(AtomicUsize::new(0));
runtime.post_turn_hook("live-counter", Some(Arc::new(Counter(count.clone()))));
let agent = runtime.agent(AgentSpec::new("observed"))?;
assert_eq!(agent.run("private payload one").await?.reply, "event reply");
support::eventually("runtime hook", || {
(count.load(Ordering::SeqCst) == 1).then_some(())
})
.await;
runtime.post_turn_hook("live-counter", None);
assert_eq!(agent.run("private payload two").await?.reply, "event reply");
assert_eq!(
count.load(Ordering::SeqCst),
1,
"removed hook stops observing turns"
);
runtime.remove_agent(agent.id()).await?;
let mut previous = 0;
let (mut added, mut started, mut ended) = (0, 0, 0);
loop {
let event =
tokio::time::timeout(std::time::Duration::from_secs(5), events.recv()).await??;
assert!(event.sequence > previous);
previous = event.sequence;
assert_eq!(event.agent_id.as_deref(), Some("observed"));
assert!(!serde_json::to_string(&event)?.contains("private payload"));
match event.kind {
RuntimeEventKind::AgentAdded => added += 1,
RuntimeEventKind::TurnStarted => {
assert!(event.turn_id.is_some());
started += 1;
}
RuntimeEventKind::TurnEnded { success } => {
assert!(success);
ended += 1;
}
RuntimeEventKind::AgentRemoved => break,
_ => {}
}
}
assert_eq!((added, started, ended), (1, 2, 2));
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/runtime_events.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example checks ordered add/start/end/remove events and confirms that private prompt text is absent from serialized metadata. Approval events are filtered to agents registered on this runtime. Correlation follows the effective origin thread; a request's later decision keeps its original turn correlation after the turn has ended.
When simultaneous turns share an origin thread, approval correlation can be ambiguous and its turn ID is absent rather than guessed. Handle receiver lag by refreshing state, and do not send text from `AgentProgress` to content-free analytics. See [turns and sessions](turns-sessions.md), [approvals](access-approvals.md), and [testing](testing.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/profiles-saas.md -->
---
description: "ProfileRuntime isolates authenticated users by workspace, credentials, conversations and event streams."
---
# Profiles and SaaS
Ordinary runtime agents share an operator's configuration path and credentials. Use `ProfileRuntime` when one server serves different authenticated users who must not share those resources. Provision a profile, install its credential, and retain a `ProfileHandle` while serving that user's requests.
Profile mode claims the process separately from ordinary `Runtime` and `Harness`. Its root must satisfy the boot guard: absolute, existing, outside the operator's workspace and not world-writable. Remove single-user workspace/token environment variables before booting a profile server.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| One profile host, shared compiled core and managed backend transport | Per-profile credential, workspace, threads, memory and event access |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/profiles.rs#profiles -->
```rust
let profiles = openhuman_embed::ProfileRuntime::build(config).await?;
let mut handles = Vec::new();
for (user, text) in [("alice", "Alice private note"), ("bob", "Bob private note")] {
let profile = profiles.provision(user).await?;
profiles
.set_credential(
&profile.profile_id,
openhuman_embed::profiles::ProfileCredentialKind::ApiKey,
&format!("{user}-fixture"),
)
.await?;
let handle = profiles.open(user).await?;
let reply = handle.chat("shared-thread", text).await?;
assert!(reply.text.contains(text), "{}", reply.text);
handles.push(handle);
}
assert_ne!(handles[0].workspace_dir(), handles[1].workspace_dir());
for (index, own, other) in [
(0, "Alice private note", "Bob private note"),
(1, "Bob private note", "Alice private note"),
] {
let messages = handles[index].messages("shared-thread").await?;
let text = serde_json::to_string(&messages)?;
assert!(text.contains(own));
assert!(!text.contains(other));
}
drop(handles);
profiles.shutdown().await;
println!("two profiles keep same-thread conversations separate");
```
<!-- END EMBED -->
[Complete runnable example](https://github.com/tinyhumansai/openhuman/blob/main/crates/openhuman-embed/examples/profiles.rs). The full file includes imports, runtime setup and local fixtures used by this excerpt.
## Behavior to account for
The example creates Alice and Bob with the same thread name and verifies that each transcript contains only its own note. Handles keep their profiles open; release/idle eviction can close a profile only after those handles are dropped.
Production managed calls need the TinyHumans transport installed by the host layer. `ProfileHandle::call` exposes the reviewed user surface rather than arbitrary operator controllers. Profiles do not make a shared file-system action directory safe automatically; provision external application resources per user too. See [SaaS deployment guide](../guides/saas-multi-tenant.md) and [SaaS architecture](../../saas-profiles.md).
<!-- Source: docs/gitbooks/en/developing/embed/concepts/providers.md -->
---
description: "A provider supplies a route or native ChatModel implementation, with agent overrides and optional ordered fallback."
---
# Providers
A runtime provider is the default inference choice for its agents. An agent can override it with an OpenAI-compatible route or a native `ChatModel<()>` through `Provider::custom`. The `providers` facade exposes the request/response contracts so custom adapters do not need to implement an HTTP server.
Named workload roles bind an adapter to selections such as `hint:coding`. The example proves that the role-pinned model bypasses the primary fallback chain. These pins are explicit host configuration; they do not ask the model to decide its own provider.
## Runtime and agent scope
| Runtime responsibility | Agent or call responsibility |
| --- | --- |
| Default route/model and native adapter chain | Provider override, model selection and workload hint |
## Verified example
<!-- BEGIN EMBED: crates/openhuman-embed/examples/custom_provider.rs#custom_provider -->
```rust
let provider = Provider::custom_with_fallback(
Arc::new(LocalModel {
reply: None,
calls: failed.clone(),
}),
vec![Arc::new(LocalModel {
reply: Some("fallback answer"),
calls: fallback.clone(),
})],
)
.model("local-custom")