Skip to main content
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

​
Define the agent

A custom agent is built from four required attributes that together determine how it thinks, what it prioritizes, and how it formats its output.
​
role
string
required
The professional function the agent adopts. Shapes how it frames analysis and what expertise it draws on. Be specific — “Senior Automated Code Review Agent” produces more focused output than “Code Reviewer.”
​
goal
string
required
The primary objective, stated specifically and measurably. The agent uses this to evaluate whether a task is complete. Vague goals produce vague results.
​
backstory
string
required
Professional context that informs the agent’s decision-making — experience level, methodology, domain standards. This shapes judgment calls the agent makes when instructions are ambiguous.
​
system_prompt
string
required
High-level instructions applied across all tasks — output format, edge case handling, quality standards. Use this to enforce consistent structure across every response the agent produces.

​
Configure tasks

Each agent requires between one and five tasks. A task defines what the agent does, which tools it can use, and what its output should look like.
​
description
string
required
What the task accomplishes, focused on outcomes rather than steps. Potpie automatically enhances this with step-by-step reasoning before the agent runs, so you don’t need to enumerate every action — describe the goal.
​
tools
array of strings
required
Tool IDs the agent can use for this task. At least one is required. See Tools Reference for all valid IDs and what each tool does.
​
expected_output
object
A JSON object specifying the format and structure of the task result. Use this to enforce consistent output — for example, a markdown report with specific sections, or a JSON object with defined keys.
​
mcp_servers
array
MCP server configurations scoped to this task. The schema is accepted but MCP execution is not active in the current release.

​
Set access permissions

Agent access can be scoped to just you, shared with specific teammates by email, or made available to everyone in your organization.

​
Full example: Code review agent

The following example shows a complete agent built from a plain-language prompt. 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.
role 
Senior Automated Code Review & Pull Request Quality Agent
goal 
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.
backstory 
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.
system_prompt 
Return all findings as markdown. Prioritize by impact. Show evidence from diffs. 
Provide minimal, safe patches or precise suggestions for every blocker.
Task
​
description
string
Perform a comprehensive pull request code review — analyze the diff, identify bugs and security issues, suggest concrete improvements, evaluate testing and rollout risk, and optionally post inline review comments and create follow-up issues.
​
tools
array of strings
change_detection, get_changes_for_pr, get_file_diff, get_code_file_structure, analyze_code_structure, fetch_file, fetch_files_batch, intelligent_code_graph, ask_knowledge_graph_queries, get_code_graph_from_node_id, get_node_neighbours_from_node_id, get_code_from_node_id, execute_terminal_command, show_diff, apply_changes, github_add_pr_comments, create_jira_issue, get_linear_issue
​
expected_output
object
Markdown PR review report containing: PR overview, risk assessment, prioritized findings (Blocker / Major / Minor / Nit) with file citations and suggested fixes, tests and quality gates, best practices checklist, and links to any created issues or PR comments.

​
What to do next