Human-in-the-loop Secure Credential Collection and Form Filling

What you need

a KERNEL_API_KEY, set in the environment where your agent runs the cli. don’t paste the key into its prompt.
the KERNEL cli, with vaults credentials and fill support.

npm install -g @onkernel/cli
kernel vaults list --limit 1 -o json
kernel vaults credentials --help

Try it with your agent

copy this prompt into your coding agent. it uses hacker news as an example login form. your agent will navigate to hacker news, then ask you to securely enter your login in a collection form rather than sharing the raw username and password in the conversation. the agent can then fill and complete the login flow for you.

you are a personal assistant operating on my behalf. use the KERNEL cli for
this task, not SDK calls or direct HTTP requests.

verify access with `kernel vaults list --limit 1 -o json` and check
`kernel vaults credentials --help`. stop if credential commands aren't available.

1. create a new, uniquely named vault for this test, then create a browser with
   that vault attached. remember both identifiers so you can clean them up later.
2. navigate to https://news.ycombinator.com/login and inspect the login form's
   field definitions, not populated values. distinguish the login form from
   the create-account form. create a credential item with description
   "Hacker News", a required text username with sensitive:false, and a required
   password with sensitive:true. don't include credential values in the spec.
3. present the returned collection URL to me in this private conversation.
   don't open it in your browser. i will enter my credentials and tell you when
   i'm done. never ask me to paste my password into the conversation.
4. after i confirm, retrieve the item and require ready plus an advertised fill
   operation. invoke fill once with the browser session ID, exact login URL,
   and selectors that uniquely identify the login inputs. don't read, print,
   screenshot, or return the filled values. if fill fails, returns unknown, or
   loses its response, stop rather than retrying or using another fill path.
5. if fill completed, submit login once, verify the site's response, and tell me
   my karma. if login fails or needs more interaction, ask me what to do next.
   when we're finished, delete the test browser and only the vault created for
   this test. don't delete any pre-existing resources.

the collection url is a private bearer link: share it only with the intended user. the cli displays the link and value-presence metadata, not stored field values. the human enters the password in the collection form; the agent invokes fill by field name. see fill’s browser-access boundary for what happens after values enter the page.

1. Create a vault per end-user

a vault groups one user’s credentials. use an immutable name tied to that user in your application. the prompt above creates a temporary vault instead so you can delete the demo afterward. all examples use the default project; use the same project for the vault and browser if you select a different one.

import Kernel from "@onkernel/sdk";

const kernel = new Kernel();
const vault = await kernel.vaults.upsert({ name: "user-12345" });

from kernel import Kernel

kernel = Kernel()
vault = kernel.vaults.upsert(name="user-12345")

VAULT_NAME="user-12345"
kernel vaults create --name "$VAULT_NAME"

2. Create a browser with the vault attached

attach the vault when you create the browser. the attachment can’t change afterward and grants access to all items in that vault, including credentials added later.

const browser = await kernel.browsers.create({ vaults: [{ id: vault.id }] });

browser = kernel.browsers.create(vaults=[{"id": vault.id}])

kernel browsers create --vault "$VAULT_NAME" -o json
read -r -p "paste the returned session_id: " BROWSER_ID

use the returned browser session id for fill, not a browser name. the interactive read saves it for the shell examples below; an agent can retain the returned id directly.

3. Encounter a credential form

navigate to the login page and inspect the inputs before defining the credential item. hacker news has both login and create-account forms with the same input names. use selectors specific to the login form, and recheck them if the page changes. create a field definition for each required input, leaving its value unset. use only the recognizable site name for description, and mark ordinary usernames or email addresses sensitive: false.

await kernel.browsers.playwright.execute(browser.session_id, {
  code: "await page.goto('https://news.ycombinator.com/login'); return await page.title();",
});
const item = await kernel.vaults.items.upsert("hn-login", {
  id_or_name: vault.id,
  type: "credential",
  spec: {
    description: "Hacker News",
    fields: {
      username: { type: "text", required: true, sensitive: false },
      password: { type: "password", required: true, sensitive: true },
    },
  },
});
if (item.type !== "credential") throw new Error("expected a credential item");
const collectionURL = item.action?.url;
// Show collectionURL only to the intended user, not in general application logs.

kernel.browsers.playwright.execute(
    browser.session_id,
    code="await page.goto('https://news.ycombinator.com/login'); return await page.title();",
)
item = kernel.vaults.items.upsert(
    "hn-login",
    id_or_name=vault.id,
    type="credential",
    spec={
        "description": "Hacker News",
        "fields": {
            "username": {"type": "text", "required": True, "sensitive": False},
            "password": {"type": "password", "required": True, "sensitive": True},
        },
    },
)
if item.type != "credential":
    raise RuntimeError("expected a credential item")
collection_url = item.action.url if item.action else None
# Show collection_url only to the intended user, not in general application logs.

kernel browsers playwright execute "$BROWSER_ID" \
  "await page.goto('https://news.ycombinator.com/login'); return await page.title();"
kernel vaults credentials create "$VAULT_NAME" hn-login --spec-file - <<'JSON'
{
  "description": "Hacker News",
  "fields": {
    "username": {"type": "text", "required": true, "sensitive": false},
    "password": {"type": "password", "required": true, "sensitive": true}
  }
}
JSON

the new item is pending_collection and returns a collection url. present it to the user and wait for their confirmation before continuing. in an application, render the url directly in the user’s authenticated interface. the cli prompt above instead relays the link in a private conversation. don’t open collection in the agent-controlled browser. an existing ready item may omit the action. reuse it, or invoke the advertised collect operation to reopen the form without clearing values. see credential collection for expiry and editing behavior.

4. Fill credentials

retrieve the item after the user confirms collection. ready means required values exist, not that login succeeded. invoke only an advertised fill operation, with the exact current page url and unique input selectors. no credential values appear in the fill request.

const current = await kernel.vaults.items.retrieve(item.key, {
  id_or_name: vault.id,
  wait: 60,
});
if (current.id !== item.id || current.type !== "credential" ||
    current.state.status !== "ready" ||
    !current.available_operations.some((operation) => operation.type === "fill")) {
  throw new Error("credential is not ready to fill");
}
const result = await kernel.vaults.items.performOperation(item.key, {
  id_or_name: vault.id,
  type: "fill",
  browser_id: browser.session_id,
  page_url: "https://news.ycombinator.com/login",
  fields: [
    { field: "username", selector: "form:has(input[autocomplete='current-password']) input[name='acct']" },
    { field: "password", selector: "input[autocomplete='current-password']" },
  ],
});
if (result.type !== "fill" || result.status !== "completed") {
  throw new Error("stop and reconcile the fill outcome");
}

current = kernel.vaults.items.retrieve(item.key, id_or_name=vault.id, wait=60)
if (current.id != item.id or current.type != "credential" or
        current.state.status != "ready" or
        not any(operation.type == "fill" for operation in current.available_operations)):
    raise RuntimeError("credential is not ready to fill")
result = kernel.vaults.items.perform_operation(
    item.key,
    id_or_name=vault.id,
    type="fill",
    browser_id=browser.session_id,
    page_url="https://news.ycombinator.com/login",
    fields=[
        {"field": "username", "selector": "form:has(input[autocomplete='current-password']) input[name='acct']"},
        {"field": "password", "selector": "input[autocomplete='current-password']"},
    ],
)
if result.type != "fill" or result.status != "completed":
    raise RuntimeError("stop and reconcile the fill outcome")

kernel vaults items get "$VAULT_NAME" hn-login --wait 60 -o json
# Continue only if the same item is ready and advertises fill.
kernel vaults items invoke "$VAULT_NAME" hn-login fill --spec-file - <<JSON
{
  "browser_id": "$BROWSER_ID",
  "page_url": "https://news.ycombinator.com/login",
  "fields": [
    {"field": "username", "selector": "form:has(input[autocomplete='current-password']) input[name='acct']"},
    {"field": "password", "selector": "input[autocomplete='current-password']"}
  ]
}
JSON

if the result is completed, the agent can submit login once and inspect the site’s response. filling doesn’t submit the form or confirm authentication. if the operation fails, returns unknown, or loses its response, stop instead of retrying. the fill guide explains partial outcomes. when the temporary demo is finished, delete its browser and vault. retain per-user vaults in your application according to your retention policy. for passwords on other sites, repeat the same flow with the fields and selectors you observe there; don’t reuse a credential on a different destination without the user’s authorization.

Common Patterns

Harnesses & Models

Human-in-the-loop Secure Credential Collection and Form Filling

What you need

Try it with your agent

1. Create a vault per end-user

2. Create a browser with the vault attached

3. Encounter a credential form

4. Fill credentials

​What you need

​Try it with your agent

​1. Create a vault per end-user

​2. Create a browser with the vault attached

​3. Encounter a credential form

​4. Fill credentials

What you need

Try it with your agent

1. Create a vault per end-user

2. Create a browser with the vault attached

3. Encounter a credential form

4. Fill credentials