Guide · Building agents · 9 min read

Building Agents in Kaptain

A Kaptain agent should have a clear job, a bounded workspace, an appropriate model route, and enough visibility for the user to review what happened.

Start with the role

Do not begin by making a large team. Begin with one responsibility. A useful agent role is specific enough to evaluate: monitor project tasks, package evidence, summarize logs, inspect a code map, draft release notes, or watch for recurring issues.

If two jobs require different tools, different memory, or different review rules, separate agents may help. If the jobs are only cosmetically different, one agent is usually clearer.

Give the agent a bounded workspace

Workspaces keep agents from becoming vague global helpers. The selected project folder and agent workspace determine what the agent can reason about and where its outputs belong. This is also why setup asks users to choose the project folder intentionally.

Choose the model route for the job

Model choice should follow task risk and complexity. A monitoring or extraction agent may not need the same route as an architecture-review agent. Kaptain's model-agnostic design keeps premium, local, lighter, and compatible custom routes available, but the user is responsible for choosing routes deliberately.

Assign tools carefully

Tools are how agent reasoning becomes action. Give an agent the tools it needs, not every tool available. A research helper may need web or retrieval tools. A project-maintenance agent may need file inspection and task tools. Riskier execution should stay behind approval boundaries.

Memory and continuity

Memory is useful when it preserves durable knowledge: user preferences, project constraints, repeated decisions, known risks, and stable operating notes. Memory becomes harmful when it drags temporary logs, stale evidence, or old assumptions into every new request.

Kaptain separates communication history, summaries, agent brain records, and project context so agents can retain useful continuity without treating every prior artifact as equally important.

Tasks and schedules

Agents can own tasks and scheduled jobs. Use schedules for recurring work such as monitoring or periodic checks. Keep automatic behavior conservative at first: review logs, inspect traces, and confirm approvals before relying on unattended operation.

Continue with Agent Communication or the User Guide.