#agent-engineering-guide

Building agents that work.

A practical guide to designing, structuring, and deploying agents on OpenCompany. From seed folder layout to prompt composition to capability design — everything you need to go from idea to production agent.

#01 — The seed folder

An agent starts as a folder. Any folder. The only requirement is a valid oc-agent.yaml at the root. Everything else is up to you.

minimal

my-agent/
├── oc-agent.yaml
└── AGENT.md

The simplest valid agent. One config file, one system prompt file. Enough to deploy and run.

production

pr-reviewer/
├── oc-agent.yaml
├── AGENT.md          # identity & role
├── CONTEXT.md        # codebase conventions
├── RULES.md          # constraints & policies
├── data/
│   └── past-reviews.json
└── reports/
    └── .gitkeep

A production agent with layered prompts, persistent data from previous sessions, and a reports directory for output.

#02 — Prompt composition

The system_prompt field declares which files compose the agent's system prompt. Order matters — files are concatenated top to bottom.

AGENT.mdIdentity

Who the agent is, what it does, how it speaks. This is the foundation. Define the role, the tone, the scope of responsibility. Be specific — a vague identity produces vague work.

example

You are pr-reviewer, a code review agent for the engineering team at Acme. You review pull requests for correctness, security, and adherence to the team's style guide. You are thorough but concise. You never approve code you haven't fully read.

CONTEXT.mdKnowledge

What the agent needs to know about the environment it operates in. Codebase conventions, team preferences, architectural decisions, known issues. This file changes the most between agents.

example

Tech stack: Next.js 15, TypeScript, Tailwind. Tests: Vitest for unit, Playwright for e2e. All PRs must have a test plan. We use conventional commits. The /api directory is being migrated from Express to Hono — flag any new Express patterns.

RULES.mdConstraints

Hard boundaries the agent must not cross. Compliance requirements, forbidden actions, escalation triggers. These are non-negotiable — the agent should treat them as law.

example

Never approve a PR that modifies .env files or secrets. Never merge directly — always request human approval. If a PR touches the payments/ directory, escalate to #payments-team in Slack before reviewing.

You can use any filenames and any number of files. The three-file pattern (identity, knowledge, constraints) is a starting point, not a rule.

#03 — Designing capabilities

Capabilities are everything an agent can use during a session. Each type serves a different purpose. Start with what the agent needs to do its job — add more later.

Integrations

External services the agent can interact with through the action gateway. Each action is permission-gated (on, off, ask). The agent calls ocr, never the service directly.

examplesslack, github, linear, notion, gmail

when to useThe agent needs to read from or write to an external service.

Sub-agents

Other agents that can be spawned during a session. Each sub-agent runs in its own isolated VM with its own permissions. The parent agent can delegate work and collect results.

examplesresearcher, writer, fact-checker

when to useA task is too complex or too risky for a single agent. Decompose it.

Skills

Reusable prompt routines the agent can invoke. Think of them as functions for the system prompt — packaged instructions for a specific task pattern.

examplestriage, code-review, summarize, translate

when to useThe agent repeatedly performs a structured task that benefits from a consistent approach.

Tools

External utilities available in the sandbox. These are not integrations — they don't require permission gating. They run locally or call stateless APIs.

exampleswebsearch, transcription, screenshot, pdf-parse

when to useThe agent needs a capability that isn't an integration and doesn't need permission control.

#04 — Permission model

Every integration action is gated by one of three permission levels. Set them per-action in the agent config. Default to ask for anything destructive.

onAllow

The action executes immediately. No human in the loop. Use for read-only operations or low-risk writes the agent should handle autonomously.

github.list_prs: on

offBlock

The action is blocked. The agent is notified it cannot perform this action. Use for actions the agent should never take, even by accident.

github.delete_repo: off

askPause

The session pauses and waits for a human to approve or deny the action. Use for anything destructive, expensive, or externally visible.

github.merge_pr: ask

#05 — Sync patterns

Sync declares what survives a session. Matching files are written back to the seed folder and committed to the agent's git repo. Everything else is discarded with the VM.

data/

Persistent knowledge the agent accumulates across sessions. Metrics, learned preferences, indexed content.

reports/*.md

Session output. Summaries, reviews, analysis. Glob patterns let you capture a category without listing individual files.

logs/session-*.json

Structured session logs for debugging or auditing agent behavior over time.

Be deliberate. The sync field is the only way data escapes the sandbox. If it's not in the pattern, it doesn't persist.

#06 — Deploy and iterate

Push the folder. Run the agent. Read the output. Adjust the prompts. Repeat.

$ oc push ./pr-reviewer
  validating oc-agent.yaml ... ok
  uploading seed folder ...... ok
  agent registered: pr-reviewer

$ oc run pr-reviewer
  session: ses_8f3k2x
  sandbox ready
  agent loop running

$ oc logs pr-reviewer --session latest
  [09:41:02] reviewing PR #42
  [09:41:14] ocr github.create_review → 201
  [09:41:15] ocr slack.send → 200
  [09:41:16] session complete
  synced: reports/pr-42-review.md

$ oc diff pr-reviewer
  seed folder changes after session:
  + reports/pr-42-review.md