Skip to main content

Building a behavior with an agent

A behavior is one directory, and an agent can write all of it. The osapi binary has a skill, build-a-behavior, with the procedure and the decisions: what to ask before you write, which behavior to build on, and which checks prove that it works. Use this to build most behaviors. Your first behavior builds one by hand. Behaviors is the reference for each part.

A behavior is work on a host. An operation of the controller itself, such as the agents, the jobs or the audit log, is an endpoint. A second skill, build-an-endpoint, covers it in the same way. The endpoint DSL makes the spec of a group today, and the skill says to stop at the parts that are not built yet. A command that runs in the CLI and calls no API, such as osapi token generate, is a local command. A third skill, build-a-command, covers it.

Set it up​

Open a checkout of osapi with a coding agent. .claude/skills/build-a-behavior/ is a short pointer to the skill, and .agents/skills links to it. When the request is about a behavior, the agent loads the pointer. The pointer tells it to run go run . skill get --name build-a-behavior, and the binary prints the skill. Thus the binary is the only source of the skill. osapi init does not install it, because it is to change osapi, not to use it. Refer to osapi skill. Build the binary one time, because the binary embeds the UI:

mise exec -- just build

What to ask​

Say what osapi must manage, not how:

  • "Add a behavior that manages the message of the day in /etc/motd."
  • "Add a behavior that lists the host's ARP and NDP neighbors, under network."
  • "Add an internal behavior that installs and removes Debian packages, for other behaviors to require."
  • "Let sysctl's list filter by whether osapi manages a parameter."
  • "Give the sysctl behavior a provider for Fedora."
  • "Migrate the timezone domain to a behavior."

What it will ask you​

A wrong guess becomes an API someone depends on, so the agent settles these before it writes code, with a recommendation for each:

  • whether a similar behavior exists, to extend it instead
  • whether operators call it, or only other behaviors (an internal behavior)
  • which platforms it runs on. All other platforms report skipped
  • whether part of the work already exists as an internal behavior to require
  • whether a value changes with each call (an input) or with each host (a setting)
  • which programs it runs, which with sudo, and whether an input is a secret
  • where the real state is: a file that osapi writes, a file that something else owns, the output of a program, or /proc
  • how "already done" looks, so that a second run changes nothing

What it writes, and how it proves it​

It runs osapi behavior create. Then it writes the settings, the types, the provider, the methods and the definition, with examples that are also the tests. Then it runs the same checks as a person:

go generate ./internal/behaviors/all
mise exec -- just generate # the spec, SDK and UI clients, API docs
go run . behavior validate
mise exec -- just test # every check, 100% coverage per behavior

CI then runs the write examples against a real agent, as root, on its Linux runner.

Each failure names what to fix: an example with a wrong output, a write that changes the host on its second run, a field that lets a path or an option through, or a program that runs without a declaration. The table of the skill gives the fix for each one.

To review the result, read the definition in internal/behaviors/<name>/. Then read osapi behavior get --name <name> and the generated page under Behaviors. osapi generates all of the rest of the change from those.

What it will refuse​

The platform cannot do some things yet. Examples are a method that is an action, for example a restart, and not a create, update or delete; a command that the caller gives; and a resource under another resource. For those, the agent stops and says what is missing. It does not build around the gap. Each one is a change to the platform, and a person decides it.

Moving a hand-written domain​

A hand-written domain moves in one change: you build its behavior and delete the domain together. The two never run side by side. The checks name the code that is left to delete: the route check names the directory of the hand-written domain, and a test names each hand-written command that has the name of a behavior command. references/migrating.md of the skill gives the procedure.