Designing Learning-Enabled Workflows on HUMΛN

Your agent “learned” overnight. Monday’s routing looks different. Nobody approved a proposal. Nobody can roll it back. The audit trail says “model update.”

That is not adaptation. That is shadow policy—and HUMΛN refuses to let learning live in a private sidecar the operator cannot see.

Build on OS primitives, not parallel stores

A learning-enabled path should not invent a private “learning subsystem.” It should use the same HumanOS surfaces your operators already audit:

1. Emit feedback with explicit payload_type → POST /v1/humanos/feedback/events.
2. Read effective policy → GET /v1/humanos/policy/effective (includes learning).
3. Create proposals when adaptation requires it → POST /v1/humanos/learning/proposals with proposal_kind, payload (e.g. action_type for apply), optional explain metadata.
4. Move lifecycle and apply only when approved → PATCH …/proposals/:id, POST …/proposals/:id/apply.
5. Rollback when humans disagree → POST …/proposals/:id/rollback.
6. Publish packages with humanos.agent.v1 + generated learning_contract; validate locally with human humanos-manifest validate and CI with human marketplace review.

Scroll-stopper: If learning can change production behavior without a proposal humans can approve or roll back, you do not have a learning system—you have an unsupervised deploy.

So that when adaptation happens, the receipt answers: what changed, who approved, how to undo.

TypeScript (application SDK)

@human/client-sdk:

import { HumanClient } from '@human/client-sdk';

const client = new HumanClient({ delegationToken: process.env.HUMAN_DELEGATION_TOKEN! });
const effective = await client.humanos.getPolicyEffective();
await client.humanos.recordFeedbackEvent({
  payload_type: 'accepted',
  scope: 'user',
});

@human/sdk: client.humanosLearning exposes the same routes (getPolicyEffective, recordFeedbackEvent, createLearningProposal, applyLearningProposal, …).

Python / Go (agent runtimes)

Thin REST helpers ship beside the agent SDKs: human_agent.humanos_learning (Python) and human GetPolicyEffective, ApplyLearningProposal, … (Go) — same paths as above.

Academy honesty (building-toward)

Academy is the long arc for capability development and free reskilling for humans. Learning proposals and feedback events above are shipped HumanOS surfaces today. Full Academy curriculum UX and certification flows are still building-toward—do not market them as GA. Design learning-enabled paths against the OS APIs you can audit now; grow into Academy as those surfaces land.

Monorepo developer guide

End-to-end walkthrough, curl templates, and CLI matrix: clone the repo and open docs/humanos-learning-developer.md.

Series

Part 1 — Agents should learn, but not like this · Learning belongs in the OS · Preferences may adapt; policy is explicit · Docs: HumanOS · Academy concepts