Surface parity for built-in skills and tools¶
Agentica has one built-in tool catalogue and one bundled skill catalogue per process. CLI, Web, Desktop, IM and headless runs are outlets: they may expose a different command/menu/card, but they must not change which skills exist or omit a tool the shared skill text promises. A per-surface skill list would also change the system prompt byte-for-byte and defeat prefix-cache reuse.
Product tool construction¶
agentica.tools.product.build_product_tools() is the single construction point
for product-level tools. Interactive CLI, gateway (Web/Desktop/IM) and cron/CLI
runners call it with their surface-specific context:
| Surface | Outlet | Shared construction |
|---|---|---|
| Interactive CLI | /worktree, --worktree, model worktree tool |
build_product_tools(surface="cli", ...) |
| Web / Desktop | /worktree panel, model worktree tool |
build_product_tools(surface="gateway", ...) via gateway |
| IM | gateway-bound session and model worktree tool |
build_product_tools(surface="gateway", ...) via gateway |
| Headless / cron | reuse the same tool catalogue via create_agent (no ask_user_question) |
build_product_tools(surface="cli", ...) via cron/cli_runner.py |
Every product surface gets WorktreeTool. Surface-specific callbacks (for
example entering a CLI worktree, or binding a gateway session's work_dir) are
passed into the shared binder; they are not a reason to register a different
tool set.
One system prompt¶
The identity line and the product instructions (self-awareness, the commands
each client offers, scheduled tasks, approval modes) are
PRODUCT_DESCRIPTION / PRODUCT_INSTRUCTIONS in agentica.tools.product.
The CLI and the gateway both pass them unchanged, mount the builtin
ask_user_question (only its callback differs), and give self_manage the
same restart wording. Anything that varies per client — which client this turn
came from, which model the session runs on — is answered at run time by
self_manage(action="show") or sits below the volatile marker (the per-turn
IM channel note), never in the cached prefix.
tests/gateway/test_surface_parity.py builds both agents for one project and
compares the stable system prompt and the tool schemas byte for byte.
Worktree¶
agentica.git.binding.WorktreeBinder is core-layer code. The old
agentica.cli.worktree_binding module re-exports it so existing CLI imports and
tests keep working, but new code imports from agentica.git.binding.
The worktree model tool has the same status / new / merge / remove
semantics everywhere: create or reuse a per-task checkout, return its path, do
not move the session's cwd, and pass that path as work_dir / path on later
tool calls. Gateway surfaces additionally expose /worktree and
GET|POST /api/worktrees; Bind is the outlet that changes a Web/Desktop/IM
session's work_dir and invalidates that session's cached agent. CLI has its
own human slash command and agentica --worktree <task> startup flag.
The bundled worktree skill is shared by all product surfaces. It says what
every surface has, names the differences only as outlets, and forbids writing
Python inside a product session to call agentica.git.worktree.ensure by hand.
Python SDK¶
Agent() / DeepAgent() are also a supported way to build agents. They are
not product outlets: SDK callers own the process, conversation store, working
directory and tool list. Bundled product skills and build_product_tools() are
not injected automatically, so concepts such as /worktree, session_id,
owner and cached-agent invalidation do not apply.
For an SDK escape hatch, use the core worktree API directly:
from agentica.git import worktree
wt = worktree.ensure("/path/to/repo", "gateway-peers", base="main")
work_dir = wt.path
Or explicitly mount the same model tool on an SDK agent:
from agentica import Agent
from agentica.git.binding import WorktreeBinder
from agentica.tools.worktree_tool import WorktreeTool
agent = Agent(
model=...,
work_dir="/path/to/repo",
tools=[WorktreeTool(WorktreeBinder(agent_config={"work_dir": "/path/to/repo"}))],
)
This is explicit composition, not a hidden surface="sdk" in
build_product_tools(). Do not use execute Python heredocs inside product
sessions; the SDK host is the process that should call these APIs.
What not to do¶
- Do not load a different bundled skill set by surface.
- Do not teach a skill a tool that only one surface registers.
- Do not add surface-specific text to the description, instructions or a tool description.
- Do not add an import from
agentica.cliinto core/gateway tool construction. - Do not solve a missing product tool with an
executePython heredoc; SDK callers compose the core API or tools in their own Python process.