Skip to main content
Agents running in Action Llama have access to two categories of tools: transport tools for interacting with the environment (files, shell), and scheduler tools for coordinating with other agents and the system. These tools are provided directly to the LLM as callable tools — agents use them like any other tool call, not as shell commands.

​
Transport Tools

Transport tools let the agent interact with its execution environment — reading and writing files, running shell commands, and searching code.
ToolDescription
bashRun a shell command and get the output
readRead a file’s contents
writeWrite content to a file
editMake targeted edits to a file
grepSearch file contents with regex patterns
findFind files matching a pattern
lsList directory contents
These tools operate on the agent’s execution environment — either a Docker container or a host-user directory, depending on the runtime mode.

​
Filesystem constraints

  • Docker mode: The root filesystem is read-only. /tmp is the only writable directory. The working directory is /app/static which contains the agent’s SKILL.md and config.
  • Host-user mode: The filesystem is writable. The working directory is the current CWD.

​
Scheduler Tools

Scheduler tools let agents coordinate with each other and with the system. They are in-process tool calls — no HTTP or shell commands involved.

​
acquire_lock

Acquire a distributed lock on a resource.
ParameterTypeRequiredDescription
resource_keystringYesURI identifying the resource (e.g. lock://repo/branch-name)
ttl_secondsnumberNoLock TTL in seconds (default: 1800)
Returns whether the lock was acquired. If another agent holds the lock, returns the holder’s identity.

​
release_lock

Release a distributed lock that you previously acquired.
ParameterTypeRequiredDescription
resource_keystringYesURI identifying the resource to unlock

​
call_agent

Call another agent to perform a task. Returns a call_id for polling.
ParameterTypeRequiredDescription
target_agentstringYesName of the agent to call
contextstringYesContext/instructions to pass to the target agent
The target agent runs asynchronously. Use check_call to poll for its result.

​
check_call

Check the status of a previous call_agent. Returns the status (pending, running, completed, error) and the return value if completed.
ParameterTypeRequiredDescription
call_idstringYesThe call_id returned by a previous call_agent

​
set_status

Update your status text shown in the terminal dashboard and web UI.
ParameterTypeRequiredDescription
textstringYesShort status text (e.g. “reviewing PR #42”)

​
return_value

Return a value to the agent that called you. Only useful when this agent was invoked via call_agent by another agent.
ParameterTypeRequiredDescription
valuestringYesThe value to return to the calling agent

​
wait_for_trigger

Suspend this agent and wait for a specific trigger (webhook event or agent trigger) before resuming. While waiting, the container is paused and the runner slot is released.
ParameterTypeRequiredDescription
type"webhook" or "agent_trigger"YesType of trigger to wait for
sourcestringNoWebhook source name to match (e.g. "github")
eventstringNoEvent type to match (e.g. "pull_request")
matchobjectNoDot-path equality predicates on the trigger payload
source_agentstringNoFor agent_trigger: only match triggers from this agent
timeoutstringNoHow long to wait (e.g. "30m", "2h"). Defaults to agent/project config.
Example — wait for a PR to merge: 
wait_for_trigger(
  type: "webhook",
  source: "github",
  event: "pull_request",
  match: { "action": "closed", "repo": "acme/app" }
)
Example — wait for another agent: 
wait_for_trigger(
  type: "agent_trigger",
  source_agent: "deployer"
)

​
Wait rules

  • Multiple wait_for_trigger calls per session are allowed (sequential waits)
  • While waiting, the agent’s container is paused and the runner slot is released
  • If no matching trigger arrives before the timeout, the tool returns an error message (the agent can handle this gracefully)
  • The agent resumes with the full trigger payload as the tool result
  • Environment variables are not preserved across wait/resume — use files for persistent state
  • Wait is allowed during agent-to-agent calls

​
Guidelines

​
Locking

  • You may hold at most one lock at a time. Release your current lock before acquiring another.
  • Always acquire a lock before starting work on a shared resource (issues, PRs, deployments).
  • Always release the lock when done.
  • If acquire_lock fails for ANY reason (conflict, deadlock, already holding), skip that resource — do not wait, retry, or proceed without the lock.
  • Locks expire automatically after 30 minutes. For long operations, acquire with a longer TTL.
  • Resource keys must be valid URIs (e.g. "github://acme/app/issues/42", "file:///deployments/api-prod").

​
Subagent calls

  • Calls are non-blocking — fire multiple call_agent calls, then poll with check_call.
  • Do work between polls rather than polling in a tight loop.
  • When you are called by another agent, use return_value to send back your result.
  • Called agents cannot call back to the calling agent (no cycles).
  • Call chains are allowed (A calls B, B calls C) up to maxCallDepth (default: 3).

​
Call rules

  • An agent cannot call itself (self-calls are rejected)
  • If all runners for the target agent are busy, the call is queued (up to workQueueSize, default: 100)
  • Called runs do not re-run — they respond to the single call

​
Auto-release on Exit

When an agent session ends — whether it finishes successfully, hits an error, or times out — all of its locks are released automatically by the scheduler. You don’t need to worry about cleanup in error paths.

​
See Also