Promptly Agent Builder

Overview

Build and maintain focused Promptly-based command line agents quickly, using the provided template and Promptly module references.

Create a new agent

1. Copy the template folder from

   assets/standalone-agent-template

   into a new project directory.
2. Rename the package and target from

   PromptlyAgent

   to the new agent name in

   Package.swift

   .
3. Rename the source folder

   Sources/PromptlyAgent

   to match the target name.
4. Update

   PromptlyAgent.swift

   and

   PromptSupport.systemPrompt

   :
   • Change

     commandName

     ,

     abstract

     , and the system prompt to the agent purpose.
   • Add or remove command line options as needed.
5. Decide whether to keep tool support:
   • Keep

     ToolFactory

     and

     SubAgentToolFactory

     for shell tools and sub agents.
   • Remove them and return

     []

     from the tool provider if the agent must run without tools.
6. Build the agent to verify it compiles in the sandboxed environment:

   • mkdir -p .build/tmp .build/home && TMPDIR="$(pwd)/.build/tmp" HOME="$(pwd)/.build/home" swift build --disable-sandbox

7. Run the agent with

   --task

   or

   --interactive

   .

Update an existing agent

• Start by reading

  Package.swift

  and

  Sources/<Target>/PromptlyAgent.swift

  to understand dependencies and prompt flow.
• Update only the system prompt and command options needed for the new behavior; avoid changing configuration loading unless required.
• If adding tools, keep

  toolsFileName

  ,

  includeTools

  , and

  excludeTools

  consistent with the tools configuration file.
• If adding sub agents, keep the supervisor hint insertion so the model sees available sub agents.
• Build the agent to verify it compiles in the sandboxed environment:

  • mkdir -p .build/tmp .build/home && TMPDIR="$(pwd)/.build/tmp" HOME="$(pwd)/.build/home" swift build --disable-sandbox

General guidance

• Prefer a small set of cohesive types over one large

  main.swift

  , with one type per file when practical.
• Be careful with Swift

  @main

  : avoid top level code in the same module and avoid

  main.swift

  conflicts by choosing a clear entry file name.
• Minimize static helper sprawl by using small service or value types so responsibilities are explicit and testable.
• Avoid creating state that is never read and avoid unused closures; validate inputs but keep tools side effect free unless the user requested persistence.
• Provide sensible defaults so users can run without extra command line options; make interactive and verbosity optional toggles.
• Treat tool output and user interface output as separate concerns; add a verbose flag and keep quiet output clean by default.
• Watch

  Sendable

  and actor boundaries in asynchronous callbacks; avoid capturing

  self

  in

  @Sendable

  closures by extracting local values.
• Do not write to disk or alter the environment unless the user requested it; prefer in memory mechanisms.
• When scaffolding tools, include include and exclude filtering and keep tool names stable for prompt instructions.
• Run a build or test check when feasible to catch missing imports or type visibility issues early.

Prompt guidance

Use these when you are writing or updating the agent system prompt and tool usage instructions.

• Provide a clear workflow with numbered steps and explicit fallback behavior so the agent can proceed when follow up questions are not possible.
• Define a strict output format with required sections and ordering to avoid response drift.
• Specify tool call ordering, including any required tool calls before the assistant outputs text.
• Require plain text tool inputs without labels or code fences to avoid contaminated inputs.
• Explicitly forbid side effects and environment changes unless the user asked for them.
• State when to ask questions versus when to proceed with safe assumptions.
• Describe how to handle tool failures, including which steps are critical and which can be skipped.

Fix common issues

• Config file not found: verify the

  --config-file

  path and ensure it exists.
• Authentication failures: confirm the token is present in the environment or keychain for the chosen provider.
• No tool calls: confirm the tools configuration file is present and tools are not excluded by filters.
• Empty assistant output: ensure

  PromptConsoleRunner

  is used and the system prompt is not empty.

Resources

• Read

  references/promptly-agent-notes.md

  for the Promptly types and source references.
• Use

  assets/standalone-agent-template

  as the base project for new agents.