Agents #
The agents extension exposes session relationships and operations to Python
code. Its routes are implemented by
agents/extension.gleam,
with daemon operations reached through
sdk/session_control. The
host passes the daemon's coordinator as a session_control.Control in
host.Context.control for kernel routes and extension.Daemon.control for the
agents service. Pass that value to the typed functions, such as spawn and
stop, and do not build Op values. Do not keep it in process-wide state.
The daemon's session registry installs the coordinator's handler in
daemon/session_control when it
starts, and the host binds session_control.call into both contexts. A call
runs in the caller's process, outside every actor. Before the handler is
installed it answers agents are unavailable. A handler that crashes mid-call
answers agents are unavailable; outcome unknown. The daemon's own
/kernel restart <session> command calls the same function. Each agent is a
session. See session attachment.
Starting agents #
The Python binding exposes
agents.start for a root peer and agents.self.spawn for a child. Both return
an Agent handle. Spawn also accepts a verifier and cyber access choice. The
host rejects an empty task or model, validates the name, and limits the verifier
to 4096 Unicode scalars.
dispatch passes the
request to the daemon.
with_worktree
handles the requested workspace before starting an agent. A workspace and its
files are shared resources unless the chosen worktree gives the agent a separate
directory.
Relationships and operations #
agents.self is the caller's handle. agents.get resolves another handle. A
handle's children and siblings methods report family state, while switch,
close, and cancel operate on an owned target. A deferred switch is stored
on sessions (pending_switch_*), survives a restart, and clears once applied
or replaced. agents.models asks for available models. agents.cancel_all can
include descendants. See the
Python binding and
service.act and stop_all.
agents.set_role permits changing the caller's role or that of an owned child
or peer. Only a child's parent can call child.set_verifier. agents.progress
publishes a nonempty status of at most 512 Unicode scalars. These checks are in
dispatch.
Messages and resources #
An Agent handle's messages method reads its transcript with sequence and
pagination arguments. search_messages searches that transcript.
agents.sessions searches sessions and clamps its result limit to 1
through 100. See the Python binding
and
agents/sessions.gleam.
A query reads the messages only of sessions that may hold it. The
text index keeps the trigrams of
each row's text, lowercased, in an FTS5 table that stores no text and no
positions. search.candidates asks it for the rows holding every trigram of the
query and adds the rows it has not read yet, which wait in
transcript_text_pending. Waiting rows are indexed newest first, in store turns
bounded by rows and payload bytes: all of them by a drain the registry starts
when it opens, then those written since by each maintenance sweep, for up to two
seconds. Triggers on transcript send a rewritten row back to wait and drop a
deleted one, under any build, so the index only narrows a search and its results
are those of reading every message. A query shorter than three code points has
no trigram and reads every session.
resources.query reports process and session resource observations through the
Python binding. Its host
implementation is
agents/resources.gleam.
An observation does not guarantee that a process remains alive after the read.
Agent workflow #
Read agents.models() before choosing a model for a child. agents.self.spawn
returns a handle, not the child's answer. Use
mail for the result rather than
treating an idle snapshot as proof of completion.
Use child.set_verifier(command) for an observable completion check. The
agents hook checks
normal parent submissions and stops while a reply is owed. Ask questions with
mail.request("parent", ...). Report a blocker with
mail.submit("parent", ..., blocker=True) when the verifier cannot pass. Clear
or replace a verifier whose condition is no longer relevant.
Limits #
The subagents settings section defaults to 12 open children per parent and
three generations below a root. -1 removes either cap. The declarations are in
family.limits_section, and
family.link_in enforces them when it records a child. Family tables and the
reads extensions use belong to
sdk/family. Remote lookups check the
family's own family_remote stubs first. Correspondents, sessions on another
daemon that wrote to the caller, come from mail storage, so the daemon supplies
that lookup as family.Correspondents
(family.correspondents). Use mail by
session ID to reach another session rather than adding nesting solely for
communication.
The order of agents #
Clients rank working agents before idle agents, then closed agents. More recent activity ranks first within a state. A branch uses its best descendant rank so a working child can bring its ancestors forward. Equal branches use creation order and ID. See TUI ordering and web ordering. Check both clients when changing this policy.
Deletion boundary #
agents.delete refuses the request. Its error directs the user to delete
through the session browser because deletion loses the child's work.
agents.close is a separate operation. See
dispatch and
session lifecycle.
Agent.close() marks the family member closed before cleaning up, so new mail
cannot enter during shutdown. It returns True after the kernel and its jobs
stop. The session saves its namespace before shutdown and keeps the transcript,
files, and worktree. Saving or shutdown failures raise an error while the family
member remains closed. A timeout can leave cleanup pending. Repeat close to
reconcile cleanup, including recorded kernels with no session worker. See
registry.run_agent_plan and
session.close_agent.