Agents

Abstract

An AI agent is a software system that perceives a goal, plans steps to reach it, takes actions through tools, observes the results, and iterates until the goal is met or it hits a stopping condition. Where a chatbot produces a response and waits for the next prompt, an agent runs its own loop. You give it a goal at the top, then it decides what to do next at each step.

Every agent is built from five parts:

• The model — the reasoning engine. It reads the current context, decides what should happen next, and produces the next thought, tool call, or message.
• Tools — connect the model to the world: APIs, code execution, databases, and other agents it can delegate to.
• Memory — the state. Allows the agent to recall past interactions, retrieve project-specific rules, and retain context across sessions.
• Orchestration — the code that runs the loop. Assembles context for each model call, dispatches tool calls, captures results, and decides whether to continue.
• Deployment — what turns the prototype into a service: hosting, identity, observability, and production infrastructure.

flowchart TD
    G("🎯 Perceive Goal") --> P("🧠 Plan Steps")
    P --> A("⚡ Act (Tool calls)")
    A --> O("🔍 Observe Results")
    O --> G

    style G fill:#1a1a2e,stroke:#4a4a8a,color:#fff
    style P fill:#16213e,stroke:#4a4a8a,color:#fff
    style A fill:#533483,stroke:#7a5ab5,color:#fff
    style O fill:#0f3460,stroke:#4a4a8a,color:#fff

Figure 1: The Agent Loop — Perceive, Plan, Act, Observe, Iterate

Three Layers of Customization

It helps to think of agent customization in three layers. Each layer answers a different question:

Layer	Question answered	Typical form
1. Static context	Who is this agent, and how should it behave?	Markdown instruction files committed to the repo
2. Skills & tools	What can the agent do beyond text generation?	Skill definitions, function schemas, tool implementations
3. Runtime protocol	How does the agent talk to external systems?	MCP servers, API calls, multi-agent handoffs

These layers stack. A well-configured agent has all three: a clear identity set in an instruction file, a library of tools it can invoke, and a protocol for calling external services reliably.

Layer 1 — Static Context: Instruction Files

The simplest form of agent customization is a Markdown file that answers: “Who are you, and what are the rules of this project?” Every major platform has a convention for this, and they differ mostly in where the file lives.

.github/copilot-instructions.md — GitHub Copilot

GitHub Copilot reads this file automatically and uses it to shape all Copilot Chat responses within your repository. Place it at the root of .github/.

# Copilot Instructions

## Stack
This is a Python/FastAPI backend. Prefer async functions and type hints.

## Style
- Follow PEP 8. Max line length: 88 (Black default).
- Write docstrings for every public function.

## Restrictions
- Do not suggest changes to `config/production.toml`.
- Never hard-code credentials.

When to use it: Any repository where you want Copilot Chat to be project-aware without you repeating yourself in every conversation.

→ Official docs — Custom instructions for repositories

CLAUDE.md — Anthropic Claude

When Claude’s coding agent (claude CLI or the API with computer use) opens your repository, it looks for CLAUDE.md at the project root. This file is the equivalent of a README written for the agent, not for humans.

# CLAUDE.md

## Project overview
Data pipeline in Python (Polars + DuckDB). The entry point is `src/pipeline/run.py`.

## Conventions
- All new modules go in `src/`. Tests mirror the structure under `tests/`.
- Use `uv` for package management, not pip.

## What NOT to touch
- `migrations/` — run `make migrate` instead of editing files directly.
- `.env.prod` — production secrets, read-only.

## Commands
- `make test` — run the test suite
- `make lint` — ruff + mypy

When to use it: Any project where you use claude as a coding assistant. The more context you give it here, the fewer clarifying questions it asks.

→ Official docs — CLAUDE.md

AGENTS.md — OpenAI Codex & general convention

AGENTS.md is the convention adopted by OpenAI’s Codex agent and is rapidly becoming an informal cross-platform standard. It describes what agents are available in a project and how to interact with them — useful in monorepos or multi-agent setups.

# AGENTS.md

## Available agents

- **reviewer**: Reviews pull requests for security issues.
- **documenter**: Generates or updates docstrings and README sections.
- **tester**: Writes pytest test cases for a given module.

## Adding a new agent
1. Define its scope in `.agent/<name>/skill.md`.
2. Register its entry point in `agents/config.yaml`.
3. Document it here.

When to use it: Multi-agent projects, or any repo you want to be “agent-literate” regardless of which AI tool a contributor uses.

→ OpenAI Codex — AGENTS.md convention

copilot-setup-steps.yml — GitHub Copilot coding agent

The Copilot coding agent (the autonomous one that can open PRs) uses a special workflow file to bootstrap its environment before it starts working. Place it in .github/workflows/.

# .github/workflows/copilot-setup-steps.yml
name: "Copilot Setup Steps"
on:
  workflow_dispatch:

jobs:
  setup:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install -r requirements.txt

This ensures the agent has a working environment before it writes or tests code.

→ Official docs — copilot-setup-steps

Quick reference: which file for which platform?

File	Platform	Purpose
.github/copilot-instructions.md	GitHub Copilot	Chat behaviour & project context
CLAUDE.md	Anthropic Claude	Coding agent context & conventions
AGENTS.md	OpenAI Codex, general	Agent catalog & cross-platform docs
.github/workflows/copilot-setup-steps.yml	GitHub Copilot agent	Environment bootstrap