Custom Agents

Build an agent with a defined role, goal, and task set that runs against your codebase.

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 . If you haven’t done this yet see API Access .

---

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

• Follow the step-by-step walkthrough → Configure a Custom Agent
• See what Potpie’s built-in agents can do → Forge
• Connect external services to extend your agent → Integrations