AGENTS.md Template for API Integration and Adapter Agents

Overview

Direct answer: Use this AGENTS.md Template to define a repeatable API integration workflow with adapter agents, enabling both single-agent operation and multi-agent orchestration with clear handoffs and governance.

This template governs an API integration pipeline where adapters connect to external services, transform data, and hand off context to downstream agents. It encapsulates operating context, tool access, and escalation rules so teams can scale AI coding agents across API surfaces.

When to Use This AGENTS.md Template

• Designing API adapters that require strict governance and traceability.
• Coordinating multiple agents across API surfaces for end-to-end flows.
• Establishing memory, source-of-truth, and handoff rules for agent collaboration.
• Preparing for human review and escalation in production workflows.
• Deploying to production with auditable change management and rollback plans.

Copyable AGENTS.md Template

# AGENTS.md
Project role: API Integration Lead
Agent roster and responsibilities:
  Planner: defines goals, milestones, success criteria
  AdapterAgent: implements adapters for API endpoints
  Reviewer: validates outputs, checks compliance
  Tester: runs unit, integration, and contract tests
  Researcher: gathers API docs and usage constraints
  Domain Specialist: handles domain-specific edge cases
Supervisor or orchestrator behavior:
  Orchestrator monitors progress, triggers handoffs, and enforces governance
Handoff rules:
  If Planner approves the plan, AdapterAgent begins implementation
  After AdapterAgent completes a task, Reviewer validates and passes to Tester
  If failures occur, orchestrator reassigns or escalates as needed
Context, memory, and source-of-truth rules:
  Maintain a central memory store for context and a single source of truth for API specs
  All decisions reference memory store and API docs
Tool access and permission rules:
  AdapterAgent can call API endpoints using tokens stored in a vault
  Never hard-code secrets; rotate credentials and revoke after use
  Do not access production data without explicit approval
Architecture rules:
  One adapter module per API surface; pluggable and auditable
  Central orchestrator coordinates cross-adapter flows
File structure rules:
  Keep config, secrets, and docs in dedicated folders
  Avoid duplicating logic across adapters
Data, API, or integration rules when relevant:
  Follow OpenAPI specs, respect rate limits, handle retries and backoffs
  Validate schemas at boundaries
Validation rules:
  Each adapter should have unit tests and contract tests
  Validate inputs, outputs, and error handling
Security rules:
  Secrets never committed; use secret managers
  Enforce TLS for external calls; enforce least privilege
Testing rules:
  Include unit, integration, and end-to-end tests
  Run tests on CI with deterministic seeds
Deployment rules:
  Prefer canary deployments for adapters; require approvals for production changes
Human review and escalation rules:
  Escalate to systems engineer if critical failures persist
  Require human review for schema changes
Failure handling and rollback rules:
  Rollback to last known-good adapter version on failure
  Preserve logs and audit trails for investigations
Things Agents must not do:
  Do not bypass approvals or skip test suites
  Do not mutate upstream API schemas without validation
  Do not store secrets in code or logs

Recommended Agent Operating Model

The agent operating model for API integration and adapter agents centers on clear roles, decision boundaries, and escalation paths. The Planner designs the objective and success criteria; the AdapterAgent builds and maintains API adapters; the Reviewer confirms conformance to contracts; the Tester ensures end-to-end reliability; the Researcher surfaces API docs and constraints; the Domain Specialist handles edge cases specific to the API domain. The Orchestrator coordinates handoffs, enforces governance, and raises escalations when needed.

Recommended Project Structure

api-integration/
├── adapters/
│   └── api_connector/
├── agents/
│   ├── planner/
│   ├── adapter/
│   ├── reviewer/
│   ├── tester/
│   ├── researcher/
│   └── domain-specialist/
├── orchestrator/
├── docs/
├── tests/
└── config/

Core Operating Principles

Agent Handoff and Collaboration Rules

• Planner to AdapterAgent: handoff when goals and API endpoints are defined
• AdapterAgent to Reviewer: handoff when contract adherence is demonstrated
• Reviewer to Tester: handoff on validated contracts and ready test scenarios
• Researcher to Domain Specialist: handoff for domain-specific edge cases
• Orchestrator: maintains cross-agent context and ensures end-to-end flow

Tool Governance and Permission Rules

• Commands, edits, and API calls must go through approved agents
• Secrets stored in vaults; never committed or logged
• Production environment requires explicit approval gates
• External services access limited by least privilege
• All changes recorded for audit and rollback

Code Construction Rules

• Adapters implement dedicated endpoints with interface contracts
• Code must include input validation, error handling, and retries
• Use versioned APIs and maintain backward compatibility where possible
• All code changes require tests and review

Security and Production Rules

• Zero-trust policy for external calls
• Token rotation and secret management enforced
• Audit logs retained for security incidents
• Production deployments require canary or blue-green strategies

Testing Checklist

• Unit tests for each adapter
• Contract tests between Planner, AdapterAgent, and Reviewer
• Integration tests across adapters and orchestrator
• End-to-end tests with mock external services
• CI checks and deterministic seeds

Common Mistakes to Avoid

FAQ

What is this AGENTS.md Template for API integration and adapter agents?

It defines roles, handoffs, and governance for an API integration workflow and multi-agent orchestration.

Who is the intended audience for this template?

Engineering teams, platform teams, AI practitioners building API adapters and coordinating multiple agents.

How are handoffs managed between planner, adapter, and reviewer?

The orchestrator drives transitions based on success criteria, with explicit signals for plan approval, contract validation, and test readiness.

What are the security and permission requirements?

Use vault-stored secrets, rotate credentials, enforce TLS, and require least privilege for external calls and production access.

How is change validated and rolled back?

Contract tests, unit tests, and canary deployments validate changes; on failure, rollback to last known-good state with audit trails.