Agents

Each agent has its own directory. The directory name is the agent ID, agent.json stores its structured definition, and instructions.md stores its standing instructions:

.polpo/agents/backend-dev/
├── agent.json
└── instructions.md

AgentDefinition

The authored agent.json format contains the portable configuration fields. It does not duplicate filesystem-derived or runtime-managed values:

type AgentDefinition = Omit<
  AgentConfig,
  "name" | "systemPrompt" | "createdAt"
> & {
  $schema?: string;
  team?: string;
};

name comes from .polpo/agents/<name>/.
systemPrompt comes from the adjacent instructions.md file.
createdAt is runtime metadata and is not authored in the project.
team is omitted for agents in the default team.

Polpo materializes these files into AgentConfig at runtime and through the Agent API.

AgentConfig

interface AgentConfig {
  name: string;
  role?: string;
  model?: string;
  image_model?: string;
  video_model?: string;
  vision_model?: string;
  transcribe_model?: string;
  tts_model?: string;
  search_provider?: string;
  systemPrompt?: string;
  allowedTools?: string[];
  allowedPaths?: string[];
  skills?: string[];
  maxTurns?: number;
  maxConcurrency?: number;
  reasoning?: ReasoningLevel;
  runtime?: string;
  executionMode?: "subprocess" | "in-process";
  sandbox?: {
    isolation?: "reuse" | "fresh" | "shared";
    lifecycle?: {
      onRelease?: "pool" | "destroy";
      stopAfterIdleMinutes?: number;
      deleteAfterStopMinutes?: number;
    };
  };
  assignedLoops?: string[];
  /** Legacy inline loop config. Prefer project-level loops. */
  loops?: Record<string, LoopConfig>;
  /** Legacy inline loop wiring. Prefer project-level loops. */
  pipeline?: Pipeline;
  reportsTo?: string;
  identity?: AgentIdentity;
  volatile?: boolean;
  missionGroup?: string;
  /** Named persistent profile for browser_* tools.
   *  Empty/omitted defaults to the agent name. */
  browserProfile?: string;
  emailAllowedDomains?: string[];
  createdAt?: string;
  version?: string;
  author?: string;
  tags?: string[];
}

ProjectLoopConfig

Agentic Loops are reusable project-level graphs stored as canonical ProjectLoopConfig JSON. Agents assign them by name with assignedLoops; chat and task requests select a loop explicitly. You can author the same contract with the TypeScript Loop DSL (export default defineLoop({...})). The compiler recognizes the DSL helpers statically, compiles them to ProjectLoopConfig, and validates the resulting JSON; runtime execution still uses the JSON graph.

interface ProjectLoopConfig {
  name: string;
  description?: string;
  context?: "shared";
  start: string;
  steps: Record<string, LoopStepConfig>;
  permissions?: LoopPermission[];
  policies?: LoopPolicy[];
  hooks?: Record<LifecycleHook, HookAction[]>;
}

type LoopStepConfig =
  | (LoopConfig & { type?: "agent"; when?: string; next?: LoopNext })
  | { type: "tool"; when?: string; tool: string; input?: unknown; saveAs?: string; next?: LoopNext }
  | { type: "human"; when?: string; output?: { schema?: unknown }; notify?: string[]; next?: LoopNext }
  | { type: "parallel"; when?: string; branches: string[]; join?: "all" | "any" | number; next?: LoopNext };

type LoopNext = string | { when?: string; to: string }[];

TypeScript authoring example:

export default defineLoop({
  name: "coding-flow",
  start: "plan",
  steps: {
    plan: agentStep({
      label: "Plan",
      systemPrompt: "Inspect the request and produce a concise implementation plan.",
      tools: ["read", "grep"],
      next: "build",
    }),
    build: agentStep({
      label: "Build",
      systemPrompt: "Implement and run the build.",
      tools: ["read", "write", "edit", "bash"],
      toolChoice: requireTool("bash"),
      next: [
        when("build.passed == true", "end"),
        otherwise("fix"),
      ],
    }),
    fix: agentStep({
      label: "Fix",
      systemPrompt: "Read the build output from context and make the smallest fix.",
      tools: ["read", "write", "edit", "bash"],
      next: "build",
    }),
  },
});

Legacy Inline Loop Config

Older agents may still carry inline loops and pipeline. New config should use project-level loops instead.

interface LoopConfig {
  name?: string;
  systemPrompt?: string;
  tools?: string[];
  toolChoice?: "auto" | "none" | "required" | { mode: "auto" | "none" | "required"; tool?: string };
  model?: string;
  reasoning?: ReasoningLevel | string;
  maxTurns?: number;
  stopWhen?: { expression: string };
  output?: { schema?: unknown };
}

interface Pipeline {
  mode?: "sequential" | "parallel";
  context?: "shared";
  steps: PipelineStep[];
}

type PipelineStep =
  | { loop: string; when?: string }
  | { tool: string; input?: unknown; saveAs?: string; when?: string }
  | { parallel: PipelineStep[]; join?: "all" | "any" | number; when?: string }
  | { switch: { cases: { when: string; steps: PipelineStep[] }[]; default?: { steps: PipelineStep[] } }; when?: string }
  | { human: string; output?: { schema?: unknown }; notify?: string[]; when?: string };

AgentIdentity

interface AgentIdentity {
  displayName?: string;
  title?: string;
  company?: string;
  email?: string;
  bio?: string;
  timezone?: string;
  avatar?: string;
  tone?: string;
  personality?: string;
  responsibilities?: (string | AgentResponsibility)[];
  socials?: Record<string, string>;
}

AgentResponsibility

interface AgentResponsibility {
  area: string;
  description: string;
  priority?: "critical" | "high" | "medium" | "low";
}

Example

A complete project-level loop file: .polpo/loops/coding-flow.json

{
  "name": "coding-flow",
  "description": "Plan and build with an approval gate.",
  "context": "shared",
  "start": "clone_repo",
  "steps": {
    "clone_repo": {
      "type": "tool",
      "tool": "clone_repository",
      "input": {
        "repoUrl": "https://github.com/acme/app.git",
        "targetDir": "workspace/app"
      },
      "saveAs": "repo.clone",
      "next": "plan"
    },
    "plan": {
      "type": "agent",
      "systemPrompt": "Create a short implementation plan.",
      "tools": ["read", "grep"],
      "next": "approval"
    },
    "approval": {
      "type": "human",
      "output": { "schema": { "decision": "string" } },
      "next": [
        { "when": "approval.decision == 'approve'", "to": "build" },
        { "to": "end" }
      ]
    },
    "build": {
      "type": "agent",
      "systemPrompt": "Implement the approved plan.",
      "tools": ["read", "write", "edit", "bash"],
      "toolChoice": { "mode": "required", "tool": "bash" },
      "next": "end"
    }
  },
  "permissions": [
    {
      "id": "approve-shell",
      "resource": "tool",
      "effect": "approval",
      "match": { "tool": "bash", "hook": "tool:before" },
      "message": "Approve shell execution before build."
    }
  ],
  "hooks": {
    "loop:start": [
      {
        "tool": "audit_event",
        "input": { "event": "coding-flow-started" },
        "saveAs": "audit.started"
      }
    ],
    "loop:end": [
      {
        "tool": "audit_event",
        "input": { "event": "coding-flow-ended" },
        "saveAs": "audit.ended",
        "onError": "continue"
      }
    ]
  }
}

Loop governance fields live on the project-level loop, not inside the agent:

interface ProjectLoop {
  name: string;
  context?: "shared";
  start: string;
  steps: Record<string, LoopStep>;
  permissions?: LoopPermission[];
  policies?: LoopPolicy[];
  hooks?: Record<LifecycleHook, HookAction[]>;
}

permissions are readable allow, deny, or approval gates for resources such as tool, step, model, human, and loop.
policies are expression-based compliance gates over runtime context and payload.
hooks run deterministic tool actions at lifecycle points such as loop:start, tool:before, tool:after, and loop:end.
Every referenced step tool, hook tool, and toolChoice.tool must exist in the project tool catalog and be enabled for the target agent.
Runtime evidence is queryable from /v1/loop-runs, /v1/permission-decisions, and /v1/hook-executions.

A complete .polpo/agents/backend-dev/agent.json assigning that loop:

{
  "role": "Senior backend engineer",
  "model": "anthropic/claude-sonnet-4-5",
  "team": "engineering",
  "allowedTools": ["read", "write", "edit", "bash", "glob", "grep"],
  "assignedLoops": ["coding-flow"],
  "skills": ["api-security", "database-design"],
  "maxTurns": 200,
  "identity": {
    "displayName": "Alex Chen",
    "title": "Senior Backend Engineer",
    "tone": "Direct, technical",
    "responsibilities": [
      {
        "area": "API Development",
        "description": "Design and implement REST APIs",
        "priority": "critical"
      },
      "Code review",
      "Database schema design"
    ]
  }
}

The adjacent .polpo/agents/backend-dev/instructions.md contains the prompt text:

Focus on clean, tested TypeScript code.

Legacy vault entries

Each agent can still have encrypted legacy credentials stored in the vault. Use Connections for new shared API keys and external integrations:

interface VaultEntry {
  type: "smtp" | "imap" | "oauth" | "api_key" | "login" | "custom";
  label?: string;
  credentials: Record<string, string>;
}

Teams

Teams are stored in .polpo/teams/<team>.json. The filename is the team ID. An agent joins a non-default team with the team field in its agent.json.

interface TeamDefinition {
  $schema?: string;
  description?: string;
}

For example, .polpo/teams/engineering.json contains:

{
  "description": "Product engineering"
}

Database access

Select database_* or exact database tool names in allowedTools, then grant the agent access through Databases. The tool allowlist does not grant database access by itself. Database grants are trusted host state; there is no data field or data/ directory in .polpo/agents/<name>/. Deploying or pulling an agent does not synchronize databases, records, migration history or grants.

CLI

SDKs

Reference

Integrations

Templates

Resources

AgentDefinition

AgentConfig

ProjectLoopConfig

Legacy Inline Loop Config

AgentIdentity

AgentResponsibility

Example

Legacy vault entries

Teams

Database access

​AgentDefinition

​AgentConfig

​ProjectLoopConfig

​Legacy Inline Loop Config

​AgentIdentity

​AgentResponsibility

​Example

​Legacy vault entries

​Teams

​Database access

AgentDefinition

AgentConfig

ProjectLoopConfig

Legacy Inline Loop Config

AgentIdentity

AgentResponsibility

Example

Legacy vault entries

Teams

Database access