Prepare Own Agents

Prepare Own Agents

We build and operate agents that handle well-scoped tasks: code generation, review assistance, documentation, and repetitive workflows. Agents are designed with clear boundaries, guardrails, and human oversight.

Below is how we design agents: Scope defines the contract, Tooling enables safe execution, and Observability keeps behavior in check.

Scope

Each agent has a defined input/output and failure mode. We avoid “do everything” agents. Clear scope makes behavior predictable and easier to audit.

Example: defining agent scope

We document scope in a simple, machine- and human-readable form. Example for a “PR summary” agent:

# Agent: pr-summary
# Purpose: Generate a short, consistent summary of a PR for the changelog.

input:
  - pr_title: string
  - pr_body: string (markdown)
  - changed_files: string[]  # paths only

output:
  - summary: string  # one or two sentences, imperative mood
  - area: string     # one of: "docs" | "api" | "ui" | "infra" | "deps" | "other"

constraints:
  - summary max 120 characters
  - no internal ticket IDs in public changelog

failure:
  - If input is empty or invalid, return error code and message; do not guess.

This keeps the agent’s contract explicit so we can test it and change it without surprise.

PR summary agent flow:

Tooling

We use proven runtimes and frameworks (e.g. MCP, plugins) so agents can call tools and APIs safely. Integrations are versioned and documented.

Example: an agent that only needs to read repo content might expose a minimal tool set:

{
  "tools": [
    { "name": "read_file", "description": "Read file contents under repo root", "path_limit": 1 },
    { "name": "list_dir", "description": "List directory contents", "path_limit": 1 }
  ],
  "no_write": true
}

Restricting to read-only and a small surface reduces risk and makes behavior easier to reason about.

Observability

Logs, metrics, and reviews let us improve and correct behavior. We track usage and outcomes so we know where agents help and where they need guardrails.

At minimum we log:

• Input hash or size (no PII) so we can detect skew
• Output status (success / validation_error / tool_error)
• Latency so we can spot regressions

See also