# Agents and supervision > Specialist agents (primary, pentester, coder, installer, searcher, memorist, adviser, reflector, reporter), execution monitor, planning step, and tool-call hard limits. - Repository: vxcontrol/pentagi - GitHub: https://github.com/vxcontrol/pentagi - Human docs: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5 - Complete Markdown: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5/llms-full.txt ## Source Files - `backend/docs/flow_execution.md` - `backend/pkg/providers/performer.go` - `backend/pkg/providers/performers.go` - `backend/pkg/providers/provider/agents.go` - `backend/pkg/config/config.go` - `backend/pkg/graph/schema.graphqls` - `README.md` --- --- title: "Agents and supervision" description: "Specialist agents (primary, pentester, coder, installer, searcher, memorist, adviser, reflector, reporter), execution monitor, planning step, and tool-call hard limits." --- PentAGI runs each Flow subtask through a multi-agent chain on `flowProvider`: the **primary agent** orchestrates work, specialist agents execute delegated tools inside a Docker sandbox, and layered **supervision** (execution monitor, planning step, hard tool-call limits, reflector, repeating detector) bounds cost and recovers stuck loops. LLM calls are BYOK—each agent role maps to a provider config key (`primary_agent`, `pentester`, `coder`, and so on) so any wired OpenAI-compatible, cloud, or local endpoint can back that role. ## Runtime model Workers call into `flowProvider` performers. The shared loop is `performAgentChain` in `backend/pkg/providers/performer.go`: 1. Load execution context (completed and planned subtasks). 2. Call the LLM with the agent’s tool set (`callWithRetries`). 3. Execute each tool (`execToolCall`), with optional mentor injection. 4. Stop on barrier tools (`done`, `ask`), or continue until a hard iteration limit. Message chains are typed (`MsgchainTypePrimaryAgent`, `MsgchainTypePentester`, …), persisted in PostgreSQL, and summarized when the context window grows. Parent/current agent context (`PutAgentContext` / `GetAgentContext`) tags logs and vector-store writes with the delegation path. ```mermaid flowchart TB subgraph orchestration [Task / subtask orchestration] GEN[Generator] REF[Refiner] PRI[Primary agent] REP[Reporter] end subgraph specialists [Specialists] PEN[Pentester] COD[Coder] INS[Installer] SEA[Searcher] MEM[Memorist] ADV[Adviser] end subgraph supervision [Supervision] MON[Execution monitor → mentor] PLN[Planning step → planner] LIM[Hard tool-call limits] RFL[Reflector] RPT[Repeating detector] end GEN --> PRI PRI --> PEN PRI --> COD PRI --> INS PRI --> SEA PRI --> MEM PRI --> ADV PRI --> REF REF --> PRI PRI --> REP PEN --> PLN COD --> PLN INS --> PLN PRI --> MON PEN --> MON COD --> MON INS --> MON PRI --> LIM PRI --> RFL PRI --> RPT ``` ## Agent roster GraphQL exposes runtime agent identity as `AgentType` (`backend/pkg/graph/schema.graphqls`). Provider YAML and UI test paths use `AgentConfigType` / `ProviderOptionsType` keys in `backend/pkg/providers/pconfig`. | Role | Config key / options type | Performer / entry | Typical job | Result / barrier tools | | --- | --- | --- | --- | --- | | Primary | `primary_agent` | Primary chain in `provider.go` | Orchestrate a subtask; delegate specialists; finish or ask user | Delegation tools + `done` / `ask` | | Pentester | `pentester` | `performPentester` | Vulnerability assessment, exploit paths | `hack_result` | | Coder | `coder` | `performCoder` | Scripts, exploits, tooling code | `code_result` | | Installer | `installer` | `performInstaller` | Env setup, package/tool install | `maintenance_result` | | Searcher | `searcher` | `performSearcher` | Network + memory research | `search_result` | | Memorist | chain type `memorist` (LLM opts reuse `searcher`) | `performMemorist` | Long-term / execution memory retrieval | `memorist_result` | | Adviser | `adviser` | via `advice` / mentor / planner | Expert guidance; also mentor and planner modes | Natural answer through `advice` handler | | Reflector | `reflector` | `performReflector` | Correct free-text answers into tool use | Guidance as user-style message | | Reporter | uses `simple` options; chain type `reporter` | `performTaskResultReporter` | Final task report | `report_result` | | Generator | `generator` | `performSubtasksGenerator` | Decompose task → subtask list (cap 15) | `subtask_list` | | Refiner | `refiner` | `performSubtasksRefiner` | Patch planned subtasks after each run | `subtask_patch` | | Enricher | `enricher` | `performEnricher` | Context enrichment for advice/planning | `enricher_result` | | Assistant | `assistant` | Assistant provider | Interactive chat; optional agent tools + flow control | Text to user; optional flow tools | | Tool-call fixer | (internal) | arg repair path | Fix invalid JSON tool arguments | Regenerated args | | Summarizer | (internal / config) | chain summarizer | Shrink long chains | Summary messages | ### Primary agent Runs once per active subtask with a `PrimaryExecutor` that wires: - **Delegation tools**: `pentester`, `coder`, `maintenance` (installer), `search`, `memorist`, `advice` - **Environment tools**: terminal, file, browser (and network search when enabled) - **Barriers**: `done` (`FinalyToolName`), `ask` (gated by `ASK_USER`) Barrier outcomes map to `PerformResultDone`, `PerformResultWaiting`, or `PerformResultError`. ### Specialists Specialists receive a focused prompt and a restricted executor. Planning (when enabled) applies only to **pentester**, **coder**, and **installer** before `performAgentChain` starts. Searcher and memorist stay on the limited tool-call budget and do not run the planning step. ### Meta agents: generator, refiner, reporter | Agent | When | Output | | --- | --- | --- | | Generator | New task | Ordered subtasks (max 15) | | Refiner | After each finished subtask | Patch of remaining plan (add/remove/modify/reorder); empty list when task complete | | Reporter | Task completion | Structured final report | ### Reflector Invoked when a non-assistant agent returns content **without** tool calls, or when `callWithRetries` exhausts LLM attempts (`maxRetriesToCallAgentChain = 3`). Caps at `maxReflectorCallsPerChain` (3). Guides the agent toward structured tools or barriers. Assistant agents are exempt: free-text is the user-facing answer. ### Adviser as mentor and planner The same `advice` tool / adviser handler is reused with different observation names and templates: | Mode | Trigger | Template | Effect | | --- | --- | --- | --- | | Explicit advice | Agent calls `advice` | Adviser system/question prompts | Optional consultation | | Mentor | Execution monitor thresholds | `question_execution_monitor` | Injects `` next to tool output | | Planner | `AGENT_PLANNING_STEP_ENABLED` on pentester/coder/installer start | `question_task_planner` + `task_assignment` wrapper | Prepends a 3–7 step plan to the human message | ## Supervision layers Hard limits and reflector are always on. Execution monitoring and planning are **opt-in** (default off). ### Execution monitor (mentor) `executionMonitor` in `backend/pkg/providers/helpers.go` tracks tool calls inside each `performAgentChain` run: | Condition | Default | Env | | --- | --- | --- | | Same tool name consecutively | 5 | `EXECUTION_MONITOR_SAME_TOOL_LIMIT` | | Total tool calls in the chain | 10 | `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT` | | Feature gate | `false` | `EXECUTION_MONITOR_ENABLED` | When a threshold hits **and** the executor has `advice`, `performMentor` runs the adviser as `"mentor"`. On success, counters reset and the tool response becomes: ```xml …tool output… …progress review… ``` Mentor failure is non-fatal: the original tool result is returned and the chain continues. ### Planning step When `AGENT_PLANNING_STEP_ENABLED=true`, `performPlanner` runs before pentester/coder/installer chains. Failure logs a warning and proceeds without a plan. The planner wraps the original assignment: ```xml … 1. … 2. … Follow the execution plan… You may deviate if you discover better approaches. ``` ### Hard tool-call limits Always enforced in `performAgentChain`: | Cohort | Agents | Default max iterations | Env | | --- | --- | --- | --- | | General | `assistant`, `primary_agent`, `pentester`, `coder`, `installer` | 100 | `MAX_GENERAL_AGENT_TOOL_CALLS` | | Limited | all other options types (searcher, enricher, generator, refiner, adviser, reflector, simple, …) | 20 | `MAX_LIMITED_AGENT_TOOL_CALLS` | Behavior: - Within the last `maxAgentShutdownIterations` (3) of the limit, the loop injects a synthetic “approaching iteration limit” path and drives reflector-style graceful exit (barrier tools). - After the hard ceiling, the chain errors: `agent chain exceeded maximum iterations (N)`. - Config values ≤ 0 fall back to built-in defaults (100 / 20). Positive overrides are floored at `maxAgentShutdownIterations * 2` so shutdown guidance still has room. ### Repeating detector Independent of the mentor: after `RepeatingToolCallThreshold` (3) identical tool calls (args normalized), further repeats get a soft “please try another tool” response. Escalation aborts the chain at threshold + `maxSoftDetectionsBeforeAbort` (4), i.e. 7 consecutive identical calls. ### Retry and fixer stack | Layer | Limit | Behavior | | --- | --- | --- | | LLM chain call | 3 retries, 5s delay | Then `performCallerReflector` | | Tool execution | 3 retries | Invalid args → tool-call fixer schema repair | | Reflector depth | 3 per chain | Then hard fail | | Barrier tools | `done` / `ask` | End or wait for user | ## Configuration reference Set in `.env` (see `.env.example`) and passed through `docker-compose.yml` into the pentagi service. Parsed on `config.Config` in `backend/pkg/config/config.go`. Enable automatic mentor reviews on tool-call pattern thresholds. Consecutive same-tool calls before mentor invocation. Total tool calls in an agent chain before mentor invocation. Hard iteration ceiling for primary, assistant, pentester, coder, installer. Hard iteration ceiling for limited/meta agents. Run planner (adviser) before pentester, coder, and installer specialist runs. Related always-on knobs that interact with agents: | Variable | Role | | --- | --- | | `ASK_USER` | Exposes `ask` barrier on primary | | Provider keys / `LLM_SERVER_*` | BYOK models per agent config key | | Summarizer `*_SUMMARIZER_*` | Chain compression during long agent runs | | `TERMINAL_TOOL_TIMEOUT` | Cap sandbox command runtime | ### Enable supervision for smaller models Point each agent key in provider YAML or the Settings UI at your BYOK endpoint. Prefer a stronger or higher-reasoning profile for `adviser` if the same base model backs primary and specialists. ```bash EXECUTION_MONITOR_ENABLED=true EXECUTION_MONITOR_SAME_TOOL_LIMIT=5 EXECUTION_MONITOR_TOTAL_TOOL_LIMIT=10 AGENT_PLANNING_STEP_ENABLED=true ``` Leave defaults (100 / 20) unless you need tighter cost caps; do not set limits below the graceful-shutdown window. Restart the stack, start a Flow, and watch agent logs / tool-call logs for mentor wraps (`mentor_analysis`) and planner-prefixed human messages. Use provider test endpoints for `primary_agent`, `pentester`, and `adviser` before long runs. Execution monitoring and planning increase token use and wall time (mentor and planner each call the adviser). They are recommended for weaker or sub-32B local models; large commercial models often run well with defaults (`false` / hard limits only). ## Agent ↔ tool access (summary) | Agent | Can call specialists? | Typical tools | | --- | --- | --- | | Primary | Yes: pentester, coder, installer, search, memorist, advice | terminal, file, browser, barriers | | Pentester | coder, installer, search, memorist, advice | terminal, file, browser, guides | | Coder | installer, search, memorist, advice | terminal, file, code store/search | | Installer | search, memorist, advice | terminal, file, browser, guides | | Searcher | memorist | search engines, browser, memory | | Memorist | — | memory / vector tools | | Adviser | enricher → searcher/memorist | advice path | | Assistant (`UseAgents=true`) | same specialists as primary (no task barriers by default) | + optional flow management tools when `FlowWorker` is injected | Full tool schemas and sandbox images: tools reference and sandbox docs. ## Failure modes | Symptom | Likely cause | Mitigation | | --- | --- | --- | | `agent chain exceeded maximum iterations` | Hit hard limit without `done`/`ask` | Raise `MAX_*` carefully; enable monitor/planning; check stuck loops in toolcall logs | | Mentor never appears | Monitor off or no `advice` on executor | Set `EXECUTION_MONITOR_ENABLED=true`; ensure agent has adviser handler | | Plan missing on specialist | Planning off or planner error | Enable `AGENT_PLANNING_STEP_ENABLED`; check logs for “proceeding without plan” | | Free-text loop / reflector storms | Model not emitting tools | Stronger model for that agent; check tool-call ID support; max 3 reflector attempts then fail | | Identical tool spam then abort | Repeating detector | Agent must change tools/args; mentor may redirect if monitor on | | High cost with supervision | Mentor/planner on every threshold | Raise thresholds or disable monitor on large models | ## Observability hooks - **Agent logs**: initiator → executor (`AgentType`) for each delegation - **Tool call logs**: received / running / finished / failed - **Message logs**: thinking, content, barriers (`done`, `ask`, `advice`) - **Langfuse / OTEL**: agent spans named for primary, mentor (`performMentor`), planner (`performPlanner`), reflector - **GraphQL**: real-time subscriptions on agent, message, and tool-call logs; usage aggregates by agent type ## Implementation map :::files backend/pkg/providers/ performer.go # performAgentChain, execToolCall, reflector, retries performers.go # specialists, planner, mentor, generator, refiner, reporter handlers.go # Get*Handler closures for agent tools provider.go # primary subtask entry, PrimaryExecutor barriers helpers.go # executionMonitor, repeatingDetector, response wrap pconfig/config.go # ProviderOptionsType / AllAgentTypes backend/pkg/config/config.go backend/pkg/tools/registry.go backend/pkg/graph/schema.graphqls # AgentType, AgentConfigType backend/docs/flow_execution.md ::: ## Next Lifecycle states, generator/refiner plans, assistant boundaries, and user input barriers. Tool categories, Docker isolation, timeouts, and barrier tools `done` / `ask`. Named tools and argument shapes for delegation, results, and flow control. Per-agent model, temperature, reasoning, and UI testAgent/testProvider. Full Config struct defaults including supervision keys. Local sub-32B setups where execution monitor and planning are strongly recommended.