Planck.Agent.Tools (Planck.Agent v0.1.0)

Factory functions for built-in inter-agent tools.

These tools are closures that capture the agent's runtime context (team_id, delegator_id, available_models) at start time. They are assembled by the caller when starting an agent and passed in the tools: list.

Usage

For a worker in a team:

tools = Planck.Agent.Tools.worker_tools(team_id, delegator_id) ++ [my_custom_tool]

For an orchestrator:

tools =
  Planck.Agent.Tools.orchestrator_tools(session_id, team_id, available_models) ++
  Planck.Agent.Tools.worker_tools(team_id, nil) ++
  [my_custom_tool]

Tool descriptions

Tool	Role	Blocking
`ask_agent`	all	yes (blocks task, not GenServer)
`delegate_task`	all	no
`send_response`	all	no
`list_team`	all	no
`spawn_agent`	orchestrator only	no
`destroy_agent`	orchestrator only	no
`interrupt_agent`	orchestrator only	no
`list_models`	orchestrator only	no

Summary

Functions

ask_agent(team_id)

Build the ask_agent tool for a given team.

delegate_task(team_id)

Build the delegate_task tool for a given team.

destroy_agent(team_id)

Build the destroy_agent tool for a given team.

interrupt_agent(team_id)

Build the interrupt_agent tool for a given team.

list_models(available_models)

Build the list_models tool from a pre-filtered list of available models.

list_team(team_id)

Build the list_team tool for a given team.

orchestrator_tools(session_id, team_id, available_models, grantable_tools \\ [], grantable_skills \\ [], cwd \\ "")

Returns the four orchestrator-only tools: spawn_agent, destroy_agent, interrupt_agent, list_models.

prepend_agents_md(system_prompt, cwd)

Prepend AGENTS.md content (if found by walking up from cwd) to system_prompt.

send_response(delegator_id, sender \\ nil)

Build the send_response tool for a given delegator.

spawn_agent(session_id, team_id, grantable_tools \\ [], grantable_skills \\ [], cwd \\ "")

Build the spawn_agent tool for a given team.

worker_tools(team_id, delegator_id, sender \\ nil)

Returns the inter-agent tools available to all agents in a team: ask_agent, delegate_task, send_response, list_team.

Functions

ask_agent(team_id)

@spec ask_agent(String.t()) :: Planck.Agent.Tool.t()

Build the ask_agent tool for a given team.

delegate_task(team_id)

@spec delegate_task(String.t()) :: Planck.Agent.Tool.t()

Build the delegate_task tool for a given team.

destroy_agent(team_id)

@spec destroy_agent(String.t()) :: Planck.Agent.Tool.t()

Build the destroy_agent tool for a given team.

interrupt_agent(team_id)

@spec interrupt_agent(String.t()) :: Planck.Agent.Tool.t()

Build the interrupt_agent tool for a given team.

list_models(available_models)

@spec list_models([Planck.AI.Model.t()]) :: Planck.Agent.Tool.t()

Build the list_models tool from a pre-filtered list of available models.

list_team(team_id)

@spec list_team(String.t()) :: Planck.Agent.Tool.t()

Build the list_team tool for a given team.

Without arguments (or verbose: false) returns name, type, description, and status for each member — cheap and safe to call frequently.

With verbose: true also includes the agent's tool names and model, useful when reasoning about which worker to delegate a task to.

orchestrator_tools(session_id, team_id, available_models, grantable_tools \\ [], grantable_skills \\ [], cwd \\ "")

@spec orchestrator_tools(
  String.t(),
  String.t(),
  [Planck.AI.Model.t()],
  [Planck.Agent.Tool.t()],
  [Planck.Agent.Skill.t()],
  String.t()
) :: [Planck.Agent.Tool.t()]

Returns the four orchestrator-only tools: spawn_agent, destroy_agent, interrupt_agent, list_models.

These tools, combined with worker_tools/2, make up the full orchestrator set. The presence of spawn_agent in the tool list is what marks an agent as an orchestrator — Planck.Agent derives role: :orchestrator from it.

grantable_tools is the list of built-in tools the orchestrator may delegate to spawned agents — typically the same built-in tools the orchestrator itself holds. Spawned agents may only receive a subset of these.

prepend_agents_md(system_prompt, cwd)

@spec prepend_agents_md(String.t() | nil, String.t()) :: String.t()

Prepend AGENTS.md content (if found by walking up from cwd) to system_prompt.

send_response(delegator_id, sender \\ nil)

@spec send_response(String.t() | nil, map() | nil) :: Planck.Agent.Tool.t()

Build the send_response tool for a given delegator.

The optional sender map (%{id: String.t(), name: String.t()}) is included in the message delivered to the delegator so it knows which worker replied.

spawn_agent(session_id, team_id, grantable_tools \\ [], grantable_skills \\ [], cwd \\ "")

@spec spawn_agent(
  String.t(),
  String.t(),
  [Planck.Agent.Tool.t()],
  [Planck.Agent.Skill.t()],
  String.t()
) ::
  Planck.Agent.Tool.t()

Build the spawn_agent tool for a given team.

grantable_tools is the set of built-in tools the orchestrator may delegate. grantable_skills is the set of skills the orchestrator may attach to spawned workers — their descriptions are appended to the spawned agent's system prompt. Spawned agents always receive the full worker inter-agent tools (ask_agent, delegate_task, send_response, list_team) plus whichever built-in tools the orchestrator selects via the "tools" argument.

worker_tools(team_id, delegator_id, sender \\ nil)

@spec worker_tools(String.t(), String.t() | nil, map() | nil) :: [
  Planck.Agent.Tool.t()
]

Returns the inter-agent tools available to all agents in a team: ask_agent, delegate_task, send_response, list_team.

delegator_id is the agent the worker should respond to (nil for orchestrators).

Pass delegator_id: nil for orchestrators (they have no delegator to respond to). The optional sender map is captured in send_response so the orchestrator knows which worker replied.