Skip to content

Custom Agents

A custom agent runs a defined role, goal, and task set against your codebase. You control which tools it uses, who can access it, and what it produces.

Before you begin

  • A Potpie account
  • Your repository parsed and ready (see Installation for setup)

Define the agent

A custom agent is built from four required attributes:

Role

The professional function the agent adopts. Shapes how it frames analysis and what expertise it draws on.

Tip

Be specific — "Senior Automated Code Review Agent" produces more focused output than "Code Reviewer."

Goal

The primary objective, stated specifically and measurably. The agent uses this to evaluate whether a task is complete. Vague goals produce vague results.

Backstory

Professional context that informs decision-making — experience level, methodology, domain standards. This shapes judgment calls the agent makes when instructions are ambiguous.

System prompt

High-level instructions applied across all tasks — output format, edge case handling, quality standards. Use this to enforce consistent structure across every response.

Configure tasks

Each agent requires one to five tasks. A task defines what the agent does, which tools it can use, and what its output should look like.

Field Required Description
description Yes What the task accomplishes, focused on outcomes rather than steps
tools Yes Tool IDs the agent can use (at least one required)
expected_output No JSON object specifying format and structure of the result

Info

Potpie automatically enhances task descriptions with step-by-step reasoning before execution, so describe the goal rather than enumerating every action.

Set access permissions

Agent access can be scoped to:

  • Just you — private agent
  • Specific teammates — shared by email
  • Organization — available to everyone in your org

Full example: Code review agent

User prompt:

I need an agent that can help software developers with code reviews. It should analyze pull requests, identify potential bugs, suggest improvements for code quality, and ensure best practices are followed.

Agent configuration:

Senior Automated Code Review & Pull Request Quality Agent

Help software developers by reviewing pull requests end-to-end — analyze
changes, identify potential bugs and security issues, suggest concrete
improvements for code quality and maintainability, and ensure team best
practices are followed.

A staff-level software engineer and code quality specialist with deep
experience across backend, frontend, and DevOps stacks. Has led large-scale
code review programs, authored secure coding standards, and mentored teams
on maintainability, testing discipline, and performance.

Return all findings as markdown. Prioritize by impact. Show evidence from
diffs. Provide minimal, safe patches or precise suggestions for every blocker.

Task configuration:

Field Value
Description Perform a comprehensive PR code review — analyze the diff, identify bugs and security issues, suggest improvements, evaluate testing and rollout risk
Tools change_detection, get_changes_for_pr, get_file_diff, get_code_file_structure, analyze_code_structure, fetch_file, intelligent_code_graph, ask_knowledge_graph_queries, get_node_neighbours_from_node_id, execute_terminal_command, github_add_pr_comments, create_jira_issue
Expected output Markdown PR review report with: overview, risk assessment, prioritized findings (Blocker/Major/Minor/Nit), suggested fixes, tests checklist

Next steps