Use supyagent run for CI/CD pipelines, GitHub Actions, batch processing, and automation.

Execution Mode

Execution mode (supyagent run) provides a stateless, non-interactive interface for running agents. It takes a task as input, runs the agent to completion, and returns the result. This is the foundation for CI/CD integration, batch processing, and automation pipelines.

Basic Usage

supyagent run <agent> "<task>"

The agent processes the task using its configured tools and LLM, then returns the result to stdout:

supyagent run coder "Add error handling to the parse_config function in src/config.py"

Output Formats

# Default: human-readable text
supyagent run myagent "Summarize this repository"

# JSON output for machine parsing
supyagent run myagent "List all TODO comments" --output json

# Quiet mode (result only, no progress indicators)
supyagent run myagent "Count lines of code" --quiet

Input Methods

# Task as command-line argument
supyagent run myagent "Fix the failing test in test_parser.py"

# Task from a file
supyagent run myagent --input task.txt

# Task from stdin
echo "Explain the authentication flow" | supyagent run myagent --input -

GitHub Actions

Use supyagent in GitHub Actions workflows for automated code tasks:

.github/workflows/agent-review.yml

name: Agent Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install supyagent
        run: |
          pip install uv
          uv pip install supyagent

      - name: Run code review agent
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          supyagent run reviewer "Review the changes in this PR and post a summary" --quiet

More GitHub Actions Examples

Auto-triage issues:

.github/workflows/triage.yml

name: Auto-Triage Issues
on:
  issues:
    types: [opened]

jobs:
  triage:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install supyagent
        run: pip install uv && uv pip install supyagent

      - name: Triage issue
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          SUPYAGENT_SERVICE_KEY: ${{ secrets.SUPYAGENT_SERVICE_KEY }}
        run: |
          supyagent run triager "Triage GitHub issue #${{ github.event.issue.number }}: ${{ github.event.issue.title }}" --quiet

Generate release notes:

.github/workflows/release-notes.yml

name: Release Notes
on:
  release:
    types: [created]

jobs:
  notes:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for git log

      - name: Generate release notes
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          supyagent run writer "Generate release notes from the git log since the last tag" --output json > notes.json

Batch Processing

Process multiple tasks in sequence using supyagent batch:

supyagent batch myagent tasks.jsonl --output results.jsonl

Where tasks.jsonl is a file with one task per line:

tasks.jsonl

{"task": "Summarize src/auth.py"}
{"task": "Summarize src/database.py"}
{"task": "Summarize src/api.py"}

Results are written to results.jsonl in the same order.

Batch with Shell Loops

For simple batch processing without the batch command:

#!/bin/bash
for file in src/*.py; do
  echo "Processing $file..."
  supyagent run reviewer "Review $file for security issues" --quiet >> results.txt
  echo "---" >> results.txt
done

CI/CD Pipeline Integration

Pre-commit Hook

Run an agent to check code quality before commits:

.git/hooks/pre-commit

#!/bin/bash
# Run agent to check for common issues
result=$(supyagent run linter "Check staged files for issues" --output json --quiet)
ok=$(echo "$result" | jq -r '.ok')

if [ "$ok" != "true" ]; then
  echo "Agent found issues. Please fix before committing."
  echo "$result" | jq -r '.message'
  exit 1
fi

Scheduled Tasks

Use cron for periodic agent tasks:

# Process inbox every 5 minutes
*/5 * * * * cd /path/to/project && supyagent run inbox_processor "Process unread events" --quiet >> /var/log/inbox.log 2>&1

# Daily code health check
0 9 * * * cd /path/to/project && supyagent run health_checker "Run daily code health check" --quiet | mail -s "Code Health" team@company.com

Agent Configuration for Execution Mode

Execution-mode agents typically have a focused system prompt and restricted tools:

agents/reviewer.yaml

name: reviewer
description: "Code review agent for CI/CD"
type: execution

model:
  provider: anthropic/claude-sonnet-4-5-20250929
  temperature: 0.3  # Lower temperature for consistent output

system_prompt: |
  You are a code review agent. Analyze the code changes and provide:
  1. A summary of the changes
  2. Potential issues or bugs
  3. Suggestions for improvement

  Be concise and actionable. Output in markdown format.

tools:
  allow:
    - "files:*"
    - "search:*"
    - "git:*"
  deny:
    - "shell:*"       # No shell access in CI
    - "edit:*"        # Read-only review

Execution vs Interactive Mode

Feature	`supyagent run` (Execution)	`supyagent chat` (Interactive)
Session persistence	No	Yes
Credential prompting	No	Yes
Streaming output	No	Yes
Input method	CLI argument or file	Interactive terminal
Use case	Automation, CI/CD	Development, exploration

Environment Variables

Set these in your CI environment:

Variable	Purpose
`ANTHROPIC_API_KEY`	Anthropic API key (for Claude models)
`OPENAI_API_KEY`	OpenAI API key (for GPT models)
`SUPYAGENT_SERVICE_KEY`	Supyagent Cloud API key (for cloud integrations)

Error Handling

Execution mode returns appropriate exit codes:

Exit Code	Meaning
`0`	Task completed successfully
`1`	Task failed (agent error or tool error)
`2`	Configuration error (missing agent, invalid config)

Use exit codes in CI/CD pipelines:

supyagent run reviewer "Check for security issues" --quiet
if [ $? -ne 0 ]; then
  echo "Security review failed"
  exit 1
fi

What's Next

Claude Code -- SKILL.md integration
Cloud Integrations -- Connect agents to external services
Building Agents -- Configure agents for different use cases

Execution Mode

On this page