Actions and tools¶
A tool is anything the model can invoke: a name, a description and a JSON schema for its arguments. An action is LocalAGI's word for a tool implemented in Go and compiled into the binary. Every action becomes a tool; not every tool is an action — MCP tools and per-request user-defined tools are not.
The word to watch is registry key. What you write in an agent's actions list
is a registry key, and it is frequently not the name the model sees.
What an action is, in code¶
// core/types/actions.go:119-122
type Action interface {
Run(ctx context.Context, sharedState *AgentSharedState, action ActionParams) (ActionResult, error)
Definition() ActionDefinition
}
ActionDefinition (core/types/actions.go:63-68) carries Name,
Description, Properties map[string]jsonschema.Definition and Required.
ToFunctionDefinition() wraps them into an OpenAI function definition.
ActionResult (:33-38) returns Result string, an optional base64 image, and
Metadata map[string]interface{}.
The bridge to the loop is cogitoWrapper (core/types/actions.go:92-116):
func (c *cogitoWrapper) Execute(args map[string]any) (string, any, error) {
result, err := c.action.Run(ctx, c.sharedState, ActionParams(args))
return result.Result, result, nil // second value carries the whole ActionResult
}
That second return value is why action metadata survives: cogito hands it back as
ToolStatus.ResultData, and LocalAGI recovers it by type switch
(core/agent/agent.go:1109-1117). Connectors read the recovered keys —
images_url, songs_paths, pdf_paths, urls,
telegram_message_sent — to upload files alongside the text answer.
Native OpenAI-style tools / tool_calls are the only mechanism. LocalAGI's own
templates (core/agent/templates.go) still pass an Actions []ActionDefinition
field into templates that never reference it — dead scaffolding from an earlier
design where LocalAGI did its own tool prompting.
The built-in registry¶
services/actions.go maps a registry key to a constructor. Below, key is
what goes in the agent config and tool name is what the model sees.
Web and knowledge¶
| Key | Tool name | Required arguments | Config |
|---|---|---|---|
search |
search_internet |
query |
— (DuckDuckGo) |
browse |
browse |
url |
— (fetch + HTML to text) |
scraper |
scrape |
url |
— (full-site crawl) |
wikipedia |
wikipedia |
query |
— |
The wikipedia tool's query parameter is described to the model as "The
website URL." (services/actions/wikipedia.go:45) — a copy-paste defect that
the model reads on every call.
GitHub — issues¶
All seven take token, repository, owner and an optional
customActionName as configuration. Each publishes a narrow or wide schema:
when repository and owner are pre-configured the tool schema omits them, so
the model has fewer arguments to get wrong.
| Key | Tool name | Arguments (narrow) |
|---|---|---|
github-issue-opener |
create_github_issue |
title, text |
github-issue-reader |
read_github_issue |
issue_number |
github-issue-editor |
edit_github_issue |
issue_number, title, description |
github-issue-closer |
close_github_issue |
issue_number |
github-issue-commenter |
add_comment_to_github_issue |
issue_number, comment |
github-issue-labeler |
add_label_to_github_issue |
issue_number, label |
github-issue-searcher |
search_github_issue |
query |
GitHub — pull requests¶
| Key | Tool name | Arguments (narrow) |
|---|---|---|
github-pr-reader |
read_github_pr |
pr_number |
github-pr-commenter |
comment_github_pr |
pr_number, comment |
github-pr-reviewer |
review_github_pr |
pr_number, review_comment, review_action, comments[] |
github-pr-creator |
create_github_pr |
branch, title, body, files[] |
review_github_pr submits APPROVE / REQUEST_CHANGES / COMMENT with inline
line comments. create_github_pr creates a branch, commits files and opens the
PR, optionally from a fork.
GitHub — repository content¶
| Key | Tool name | Arguments (narrow) |
|---|---|---|
github-repository-get-content |
get_github_repository_content |
path |
github-get-all-repository-content |
get_all_github_repository_content |
path (not marked required on the narrow branch) |
github-repository-list-files |
list_github_repository_files |
path |
github-repository-search-files |
search_github_repository_files |
path, searchPattern |
github-repository-create-or-update-content |
github_repository_create_or_update_content |
path, content, commit_message, plus branch when no default branch is configured |
github-readme |
github_readme |
repository, owner (single schema, no narrow form) |
Generation¶
| Key | Tool name | Arguments | Config |
|---|---|---|---|
generate_image |
generate_image |
prompt, size enum |
apiKey (required), apiURL, model |
generate_song |
generate_song |
caption, plus lyrics, bpm, keyscale, language, duration_seconds, model |
apiURL, model, apiKey, outputDir, cleanOnStart |
generate_pdf |
generate_pdf |
content, plus title, filename |
outputDir (required), cleanOnStart |
generate_song posts to LocalAI's /sound-generation extension, not an OpenAI
route. generate_image's own description is the truncated string "Generate
image with.".
Memory (Bleve full-text, not the vector store)¶
| Key | Default tool name | Arguments |
|---|---|---|
add_to_memory |
add_to_memory |
name, content |
list_memory |
list_memory |
— |
remove_from_memory |
remove_from_memory |
id |
search_memory |
search_memory |
query |
All four accept custom_name and custom_description config, so the model-facing
names are changeable. These write to a Bleve index and never touch the
knowledge base — see memory, which also covers the name collision
with the knowledge-base tool of the same name.
Communication and integration¶
| Key | Tool name | Arguments | Config |
|---|---|---|---|
send-mail |
send_email |
to, subject, message |
smtpHost, smtpPort, username, password, email (all required) |
send-telegram-message |
send_telegram_message |
message (+ chat_id if not preconfigured) |
token (required), chat_id, name overrides |
twitter-post |
post_tweet |
text |
token (required), noCharacterLimit |
webhook |
webhook |
payload (no required fields declared) |
url (required), method, contentType, payloadTemplate, name overrides |
pikvm_power_control |
pikvm_power_control |
action enum on\|off\|off_hard\|reset_hard |
hostname, username, password (all required), insecure |
The twitter-post UI offers a noCharacterLimit toggle; the action reads
noCharacterLimits (plural). The toggle does nothing
(services/actions/twitter_post.go:15 versus :78).
Local and agent control¶
| Key | Tool name | Arguments | Notes |
|---|---|---|---|
shell-command |
run_command |
command (+ host, user if not preconfigured) |
Runs over SSH, either to a configured host or to the sshbox service |
call_agents |
call_agent |
agent_name (enum of live agents), message |
Blocking nested Ask; see the deadlock note in architecture |
counter |
counter |
name, adjustment |
A mutex-guarded in-memory map — not persisted, lost on restart |
call_agent's definition is built at call time: it enumerates the live pool,
filters by whitelist/blacklist, excludes the calling agent, and puts the
resulting names in a JSON-schema enum with each agent's description in the
tool description.
Scheduling¶
| Key | Tool name | Arguments |
|---|---|---|
set_recurring_reminder |
set_recurring_task |
message, cron_expr (5-field cron, no seconds) |
set_onetime_reminder |
set_onetime_task |
message, delay (accepts 1d, 2d12h) |
list_reminders |
list_tasks |
— |
remove_reminder |
remove_task |
index (1-based) |
set_reminder |
(none — broken, see below) |
Internal actions, added by the agent rather than configured¶
| Tool name | Added when | Source |
|---|---|---|
stop |
can_stop_itself, and the job is not scheduled |
core/action/noreply.go |
send_message |
the job is scheduled, or during self-evaluation with initiate_conversations |
core/action/newconversation.go |
update_state |
hud |
core/action/state.go |
no_tool_to_call |
always, unless disable_sink_state |
core/agent/agent.go:1052-1059 |
search_memory, add_memory |
kb_as_tools |
core/agent/knowledgebase.go:200-206 |
Four registry defects worth knowing before you debug¶
1. set_reminder is advertised and cannot work. The constant is in
AvailableActions (services/actions.go:105), so GET /api/actions returns it
and the UI offers it — but there is no case for it in the factory switch
(:417-503). Selecting it returns "Action not found" at agent construction.
2. set_recurring_reminder and set_onetime_reminder are implemented but
unadvertised. They exist in the factory switch (:482-485) and in the UI's
DefaultActions (:292-301) but not in AvailableActions. A client that
enumerates actions over the API will never see the two scheduling tools that
actually function.
3. Registry keys are not tool names. call_agents → call_agent,
set_recurring_reminder → set_recurring_task, list_reminders → list_tasks,
remove_reminder → remove_task. Anyone writing pool.json by hand hits this
immediately, and the remove_task description compounds it by telling the model
to "use list_reminders to see the index" — a tool name that does not exist
(core/action/reminder.go:259).
4. No credential gating. An action requiring a token declares it as a
Required: true config field and fails inside Run(). Nothing hides an
unusable action from the model, so an agent with a misconfigured GitHub action
will select it and get an error back as a tool result.
The three counts disagree with each other, which is the root of defects 1 and 2:
42 name constants, 39 entries in AvailableActions, 44 UI field groups, 41
factory cases (services/actions.go:23-64, 73-114, 116-322, 417-503).
Custom actions: interpreted Go¶
LOCALAGI_CUSTOM_ACTIONS_DIR turns each .go file in a directory into an
action, executed by the yaegi interpreter
inside the LocalAGI process (core/action/custom.go). Agent-configured
custom actions (registry key custom) carry their source in the config itself.
The script contract:
| Symbol | Signature | Required |
|---|---|---|
Run |
func(map[string]interface{}) (string, map[string]interface{}, error) |
yes |
Definition |
func() map[string][]string — each value is [jsonschemaType, description] |
yes |
Description |
func() string |
optional; overridden by config |
RequiredFields |
func() []string |
optional |
Init |
func(string) error — receives the configuration config value |
optional |
Mechanics worth knowing:
- The interpreter is created with
Env: os.Environ()andGoPath: <customActionsDir>, loadingstdlib.Symbols(core/action/custom.go:60-68). Your script sees the host's environment. - A
packagedeclaration in the file is stripped by regex and the code is re-evaluated under a generated package name (:78-85). - The
Runsymbol is type-asserted without checking (core/action/custom.go:106). A signature mismatch panics rather than reporting a configuration error. Definitionentries whose slice length is not 2 are skipped with a log line, so a malformed parameter silently disappears from the schema.
The unsafe config checkbox sets yaegi's Unrestricted mode
(core/action/custom.go:62-67). Combined with the unauthenticated-by-default
posture, an exposed LocalAGI accepts arbitrary Go over an HTTP API. The same
applies to mcp_prepare_script, which runs /bin/bash -c on agent construction.
Custom .go files in the same directory also become
dynamic prompts, keyed by filename, if they implement the prompt
interface.
Running an action without an agent¶
POST /api/action/:name/definition → the JSON schema
POST /api/action/:name/run → execute directly, 200-second timeout
GET /api/actions → AvailableActions
Useful for checking credentials without waiting for a model to decide to call something. Note the enumeration endpoint inherits defects 1 and 2 above.
Upstream references¶
core/types/actions.go—Action,ActionDefinition,cogitoWrapper,ToCogitoTools. Validated against v2.9.0, 2026-08-17.services/actions.go— the registry: name constants,AvailableActions,DefaultActions, the factory switch. Validated against v2.9.0, 2026-08-17.services/actions/— every built-in action implementation and itsDefinition(). Validated against v2.9.0, 2026-08-17.core/action/reminder.go— the four scheduling tools and their real names. Validated against v2.9.0, 2026-08-17.core/action/custom.go— yaegi setup, script contract,unsafe. Validated against v2.9.0, 2026-08-17.core/agent/agent.go— result-metadata recovery at 1109-1128, sink-state tool at 1052-1059. Validated against v2.9.0, 2026-08-17.webui/routes.go— direct action execution routes. Validated against v2.9.0, 2026-08-17.