Promptly Agent Builder

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.