# Pi

> For AI agents: the complete documentation index is at https://buddy.works/llms.txt

Run Pi AI agent.

## YAML parameters for Pi

```typescript
interface YAMLParameters {
  /** List of prompts for the agent. Each entry is either an inline string or a file reference (type INLINE or FILE). */
  prompts: (string | object)[];
  type: "PI";
  /** Unique identifier for the action within the pipeline. */
  action: string;
  /** Integration identifier for authenticating with the AI provider. It refers to an integration in the workspace by its identifier, not by its display name. */
  integration?: string;
  /** The Pi model to use (e.g. `claude-sonnet-5`). */
  model?: string;
  /** List of agent skills to install before the run. Each entry is an owner/repo, a repository URL, or a local path. */
  skills?: string[];
  /** MCP servers to make available to the agent, keyed by server name. Each server is either http/sse (url, headers) or stdio (command, args, env). */
  mcp_servers?: Record<string, McpServerYaml>;
  /** The directory in which the pipeline filesystem will be mounted. */
  working_directory?: string;
  /** The dependencies and directories to be cached and available to every execution in this pipeline. */
  cached_dirs?: string[];
  /** If set to true, the filesystem will not be mounted in the container. */
  mount_filesystem_disable?: boolean;
  /** The path preceding the colon is the filesystem path (the folder from the filesystem to be mounted in the container). The path after the colon is the container path (the path in the container, where this filesystem will be located). */
  volume_mappings?: string[];
  /** The hostname of the container in which the action is run. The container will be available under this name in the docker network for services. */
  main_service_name?: string;
  /** All build commands are run as the default user defined in the selected Docker image. Can be set to another username (on the condition that this user exists in the selected image). */
  run_as_user?: string;
  /** The entrypoint to use for the Docker container. */
  entrypoint?: string;
  /** If set to true, resets the default entrypoint set by the image. */
  reset_entrypoint?: boolean;
  /** If set to true, the cached version of the image is used, instead of being pulled each time. */
  cache_base_image?: boolean;
  /** If set to true, use cached image on timeouts (only for official images). */
  ignore_image_pull_failures?: boolean;
  /** The path in the container to export. */
  export_container_path?: string;
  /** The name of the Docker image. */
  docker_image_name?: string;
  /** The tag of the Docker image. */
  docker_image_tag?: string;
  /** The location of the image used by the action. */
  image_location?: "PUBLIC_REGISTRY" | "PRIVATE_REGISTRY" | "ACTION" | "ARTIFACT_REGISTRY";
  /** The type of registry from which the image is retrieved. */
  docker_registry?: "NONE" | "DOCKER_HUB" | "AMAZON_ECR" | "GOOGLE_GCR" | "GOOGLE_ARTIFACT_REGISTRY" | "OTHER" | "GIT_HUB_CONTAINER_REGISTRY" | "ARTIFACT_REGISTRY" | "DIGITAL_OCEAN_CONTAINER_REGISTRY";
  /** The identifier of the artifact from artifact registry. */
  artifact?: string;
  /** If set to true, the image from another action will be used. */
  use_image_from_action?: boolean;
  /** The name of an action in the same pipeline whose Docker image is used. Set it with `image_location: ACTION`. */
  docker_build_action_name?: string;
  /** The URL of the Docker registry. */
  registry?: string;
  /** If set to true, the registry will be accessed over HTTP instead of HTTPS. */
  insecure_registry?: boolean;
  /** The target stage of the Dockerfile. */
  target_stage?: string;
  /** If set to true, images will not be pruned after the build. */
  do_not_prune_images?: boolean;
  /** Username for a registry reached without an `integration`. A push (`repository` set) needs an `integration` or `login` and `password`, except for the artifact registry. */
  login?: string;
  /** Password for `login`, for a registry reached without an `integration`. */
  password?: string;
  /** The list of services attached to the build environment. */
  services?: ServiceYaml[];
  /** The name of the visual test suite to run tests against. */
  visual_tests_suite?: string;
  /** The list of target servers or clusters. Each item is a target definition or a filter matching existing targets by identifier: a plain string such as `sd*` (`*` as a wildcard) or an object with `type: MATCH`. */
  targets?: (string | TargetYaml)[];
  /** Specifies when the action should be executed. */
  trigger_time?: "ON_EVERY_EXECUTION" | "ON_FAILURE" | "ON_BACK_TO_SUCCESS" | "ON_WARNING" | "ON_WAIT_FOR_APPROVE" | "ON_TERMINATE";
  /** The list of variables for dynamic action execution. The action runs once for each value. */
  loop?: string[];
  /** When true, the action runs only on the first failure instead of on each failure. Used only when trigger_time is ON_FAILURE. */
  run_only_on_first_failure?: boolean;
  /** When set to true the action is disabled. By default it is set to false. */
  disabled?: boolean;
  /** The timeout in seconds. It cannot exceed the action time limit of the workspace plan; a higher value is rejected. */
  timeout?: number;
  /** If set to true the execution will proceed, mark action as a warning and jump to the next action. Doesn't apply to deployment actions. */
  ignore_errors?: boolean;
  /** Delay time between auto retries in seconds. */
  retry_interval?: number;
  /** Number of retries if the action fails. */
  retry_count?: number;
  /** Defines whether the action should run in parallel with the next one. */
  run_next?: "WAIT_ON_SUCCESS" | "IN_SOFT_PARALLEL" | "IN_HARD_PARALLEL";
  /** The list of trigger conditions to meet so that the action can be triggered. */
  trigger_conditions?: TriggerConditionYaml[];
  /** The list of variables you can use in the action. */
  variables?: VariableYaml[];
}
```

## Type Definitions

```typescript
interface McpServerYaml {
  /** Transport type: 'stdio', 'http' or 'sse'; 'integration' for a server that references an integration, set automatically */
  type?: string;
  /** Server URL, required for 'http' and 'sse' */
  url?: string;
  /** Headers sent with every request, for 'http' and 'sse' */
  headers?: object;
  /** Command starting the server, required for 'stdio' */
  command?: string;
  /** Arguments passed to the 'stdio' command */
  args?: string[];
  /** Environment variables passed to the 'stdio' server process */
  env?: object;
  /** Integration whose MCP server Buddy connects to with the integration's token; excludes all other fields */
  integration?: string;
}

interface ServiceYaml {
  /** Service type, one of: MYSQL, MARIADB, POSTGRE_SQL, MONGO_DB, REDIS, MEMCACHED, ELASTICSEARCH, CASSANDRA, RABBIT_MQ, SELENIUM_CHROME, SELENIUM_FIREFOX, MY_ADMIN, CUSTOM. */
  type: string;
  /** Version of the service to run. */
  version?: string;
  /** Path to the database dump file to restore. */
  dump_path?: string;
  /** When true, preserve service data between builds. */
  persistent?: boolean;
  /** Connection configuration for the service (host, port, user, password, db). */
  connection?: ServiceConnectionYaml;
  /** Custom Docker image name for the service. */
  docker_image_name?: string;
  /** Tag of the custom Docker image. */
  docker_image_tag?: string;
  /** Custom Docker registry URL. */
  registry?: string;
  /** Username for Docker registry authentication. */
  login?: string;
  /** Password for Docker registry authentication. */
  password?: string;
  /** Location of the Docker image. */
  image_location?: "PUBLIC_REGISTRY" | "PRIVATE_REGISTRY" | "ACTION" | "ARTIFACT_REGISTRY";
  /** The type of Docker registry. */
  docker_registry?: "NONE" | "DOCKER_HUB" | "AMAZON_ECR" | "GOOGLE_GCR" | "GOOGLE_ARTIFACT_REGISTRY" | "OTHER" | "GIT_HUB_CONTAINER_REGISTRY" | "ARTIFACT_REGISTRY" | "DIGITAL_OCEAN_CONTAINER_REGISTRY";
  /** When true, use image built by a previous action. */
  use_image_from_action?: boolean;
  /** The name of an action in the same pipeline that built the Docker image. */
  docker_build_action_name?: string;
  /** Working directory inside the container. */
  working_directory?: string;
  /** Custom volume mappings for the container. Format: host_path:container_path. */
  volume_mappings?: string[];
  /** Custom entrypoint for the container. */
  entrypoint?: string;
  /** Commands to execute inside the container. Several commands go in one multi-line string (a `|` block), one per line - not a YAML list. */
  inline_commands?: string;
  /** Cloud region for the service (when using cloud integrations). */
  region?: string;
  /** Port to wait for before considering service ready. */
  wait_for_port?: number;
  /** Integration identifier for cloud provider authentication. It refers to an integration in the workspace by its identifier, not by its display name. */
  integration?: string;
  /** Directories to cache between executions. */
  cached_dirs?: string[];
  /** When true, pass pipeline variables to the service container. */
  pass_variables?: boolean;
  /** User to run the container as. */
  run_as_user?: string;
  /** When true, continue even if pulling the Docker image fails. */
  ignore_image_pull_failures?: boolean;
  /** When true, cache the base Docker image. */
  cache_base_image?: boolean;
}

interface ServiceConnectionYaml {
  /** Service host */
  host?: string;
  /** Service port */
  port?: number;
  /** Service user */
  user?: string;
  /** Service password */
  password?: string;
  /** Database name */
  db?: string;
}

interface TriggerConditionYaml {
  /** The type of trigger condition. `ACTION_STATUS_IS` and `ACTION_STATUS_IS_NOT` are allowed only in an action's `trigger_conditions`. */
  trigger_condition: "ALWAYS" | "ON_CHANGE" | "ON_CHANGE_AT_PATH" | "VAR_IS" | "VAR_IS_NOT" | "VAR_CONTAINS" | "VAR_NOT_CONTAINS" | "DATETIME" | "SUCCESS_PIPELINE" | "DAY" | "HOUR" | "OR" | "VAR_LESS_THAN" | "VAR_LESS_THAN_OR_EQUAL" | "VAR_GREATER_THAN" | "VAR_GREATER_THAN_OR_EQUAL" | "ACTION_STATUS_IS" | "ACTION_STATUS_IS_NOT" | "TRIGGERING_USER_IS" | "TRIGGERING_USER_IS_NOT" | "TRIGGERING_USER_IS_IN_GROUP" | "TRIGGERING_USER_IS_NOT_IN_GROUP" | "ON_PAYLOAD" | "ON_PAYLOAD_AT_PATH";
  /** The value to compare the trigger variable against */
  trigger_variable_value?: string;
  /** The name of the variable to check in the trigger condition - an environment variable or a run variable (BUDDY_RUN_*), e.g. BUDDY_RUN_PR_DRAFT */
  trigger_variable_key?: string;
  /** The timezone for datetime trigger conditions (e.g., 'UTC', 'Europe/Warsaw') */
  timezone?: string;
  /** The hours when the datetime trigger should activate (0-23) */
  trigger_hours?: number[];
  /** The days when the datetime trigger should activate (1-7, where 1 is Monday) */
  trigger_days?: number[];
  /** The project name for cross-project pipeline triggers */
  project?: string;
  /** The pipeline name for cross-pipeline triggers */
  pipeline?: string;
  /** The username or email of the workspace member who can trigger the pipeline. The user must exist. */
  trigger_user?: string;
  /** The name of the workspace group that can trigger the pipeline. The group must exist. */
  trigger_group?: string;
  /** Paths for trigger_condition ON_CHANGE_AT_PATH (files that must change) and ON_PAYLOAD_AT_PATH (paths in the webhook payload); required for these two conditions and ignored by the others. */
  trigger_condition_paths?: string[];
  /** The action status to check for action status triggers */
  trigger_status?: "SUCCESSFUL" | "FAILED" | "SKIPPED" | "SUPPRESSED";
  /** The name of the action to check status for */
  trigger_action_name?: string;
  /** The list of nested trigger conditions combined with the OR operator. */
  trigger_operands?: TriggerConditionYaml[];
}

interface VariableYaml {
  /** The name of the variable */
  key: string;
  /** The value of the variable. With `encrypted: true` give the plain value - it is encrypted on import; an already encrypted value (`secure!...`, `!encrypted ...`) is accepted only in the workspace that encrypted it. For SSH_KEY give the whole private key - its format is validated and a variable reference is not accepted. For P12 give the base64-encoded PKCS12 keystore - it is opened with `password` on import. Masked to bare !encrypted without manage rights */
  value?: string;
  /** The type of the added variable */
  type?: "VAR" | "FILE" | "SSH_KEY" | "IOS_KEYCHAIN" | "IOS_PROVISION_PROFILES" | "SSH_PUBLIC_KEY" | "GPG_KEY" | "P12";
  /** If set to true the variable value will be encrypted and hidden */
  encrypted?: boolean;
  /** Initial path for the variable */
  init_path?: string;
  /** Default value for the variable */
  defaults?: string;
  /** Specifies where to copy the file on each run. Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. */
  file_path?: string;
  /** File permission set on copy to a container on each run. Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. */
  file_chmod?: string;
  /** Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. If it's NONE, the variable can be used as a parameter in an action. For CONTAINER, the given key is additionally copied to an action container on each run */
  file_place?: "NONE" | "CONTAINER";
  /** Password for certificates. Follows the same masking rules as value */
  password?: string;
  /** Passphrase for encrypted SSH keys. Follows the same masking rules as value */
  passphrase?: string;
  /** Key identifier for iOS certificates, provisioning profiles, or GPG keys */
  key_identifier?: string;
  /** Whether Buddy actions can set the variable value: DISABLED (default), ENABLED (the new value is kept for later runs) or RUN_ONLY (the new value applies to the current run only; not allowed for file, SSH key and SSH public key variables). Boolean `true` (unquoted) means ENABLED. */
  settable?: string;
  /** If set to true the variable is disabled and will not be injected anywhere */
  disabled?: boolean;
  /** Encoding of the variable value. Use `b64` for binary files (certificates, images, compiled blobs) where the value is already base64-encoded. Omit or set to `text` for plain text files (JSON, XML, config) — the system will handle encoding automatically. Only applies to non-encrypted asset variables (FILE, SSH_KEY, SSH_PUBLIC_KEY, IOS_KEYCHAIN, IOS_PROVISION_PROFILES). */
  encoding?: "text" | "b64";
  /** Note for this resource */
  note?: string;
  /** YAML note for AI agents operating on this resource */
  agent_note?: string;
}

```

## YAML examples for Pi

### Run Pi with all options

```yaml
- action: "Run Pi"
  type: "PI"
  trigger_time: "ON_EVERY_EXECUTION"
  integration: "my_anthropic_integration"
  prompts:
    - "Review the code and suggest improvements"
    - file: ".buddy/pi-prompt.md"
  model: "claude-sonnet-5"
  skills:
    - buddy-works/security-audit
  mcp_servers:
    github:
      type: "http"
      url: "https://api.githubcopilot.com/mcp/"
      headers:
        Authorization: "Bearer $GITHUB_TOKEN"
    filesystem:
      type: "stdio"
      command: "npx"
      args:
        - "-y"
        - "@modelcontextprotocol/server-filesystem"
        - "/buddy/my-repo"

```

### Minimal Pi

```yaml
- action: "Pi Review"
  type: "PI"
  trigger_time: "ON_EVERY_EXECUTION"
  integration: "my_anthropic_integration"
  prompts:
    - "Review the code"

```


---
Original source: https://buddy.works/docs/yaml/yaml-actions/pi