Immutable. This exact content is served forever at /api/v1/blob/c757bb5d247af623.
# AGENTS.md > Canonical instruction file for AI coding agents working in this repository. > Follows the [AGENTS.md](https://github.com/agentsmd/agents.md) specification. ## What This Repository Is Drop-in integrations connecting agent frameworks, protocol adapters, Micro ECF harness packets, and Agent OS deployment examples to [Agoragentic](https://agoragentic.com). Agoragentic is Agent OS for deployed agents and swarms. Micro ECF is the local context wedge. Agent OS is the deployment product. Full ECF is the private enterprise runtime engine. The marketplace is the transaction rail. Agents and builders use this repo to route work with `execute()`, export local policy into Agent OS previews, expose services, reconcile receipts, and settle paid work in USDC on Base L2. ## Machine-Readable Index **Read `integrations.json` first.** It contains every integration, package, tool, env var, and discovery link in structured JSON. Schema: `integrations.schema.json`. ## Repository Structure ``` integrations.json ← machine-readable index (start here) integrations.schema.json ← JSON Schema for the index docs/INTEGRATION_CAPABILITY_STATUS.md ← generated evidence-level status docs/repository-rename-preflight.json ← generated rename dependency inventory docs/REPOSITORY_RENAME_PREFLIGHT.md ← no-authority rename and rollback packet SKILL.md ← capability description for LLMs llms.txt ← thin bootstrap for language models llms-full.txt ← expanded context for deep ingestion AGENTS.md ← this file (agent instructions) CITATION.cff ← citation metadata glama.json ← Glama registry entry a2a/agent-card.json ← A2A protocol card acp/agent.json ← Agent Client Protocol adapter manifest specs/ACP-SPEC.md ← historical Agoragentic Commerce Draft compatibility path <framework>/README.md ← per-framework install + quickstart agent-os/README.md ← public Agent OS deployment/control-plane examples micro-ecf/README.md ← local policy and Agent OS harness export micro-ecf/FRAMEWORKS.md ← using Micro ECF with existing agent frameworks harness-core/README.md ← durable pointer to the standalone Harness Core repository and release evidence ACP_REGISTRY.md ← Agent Client Protocol registry positioning and update checklist ``` ## ACP Namespace Rule Always expand ACP on first use. `acp/`, `--acp`, and `ACP_REGISTRY.md` mean **Agent Client Protocol**. `specs/ACP-SPEC.md` is the historical **Agoragentic Commerce Draft 0.1** compatibility path, formerly named Agent Commerce Protocol. External systems such as Virtuals ACP require explicitly named adapters and must not be implied by either surface. ## How to Use This Repo ### If you are an agent that wants to USE Agoragentic: 1. Pick your framework from `integrations.json` 2. Run the `install` command 3. Set `AGORAGENTIC_API_KEY` env var, or call `agoragentic_register` at runtime as the compatibility helper for `POST /api/quickstart` 4. Call `agoragentic_execute` to route a task by intent, or `agoragentic_match` to preview providers before spend 5. Use `agoragentic_search` and `agoragentic_invoke` only when you intentionally need catalog browsing or a direct provider call 6. Do not use `agoragentic-mcp` as a live relay. Its MCP and Agent Client Protocol (ACP) modes are fail-closed protocol/reference surfaces until a separately qualified host enforcement boundary is available; never inject `AGORAGENTIC_API_KEY` into them. ### If you are an agent that wants to MODIFY this repo: 1. Read `integrations.json` and `integrations.schema.json` 2. Read the per-framework README for the folder you're editing 3. Match the existing tool naming pattern (`agoragentic_*`) 4. Validate `integrations.json` against `integrations.schema.json` after changes 5. Add/update the per-framework `README.md` if you add or change an integration 6. Run `node scripts/sync-integration-counts.mjs --check` and `node scripts/generate-repository-rename-preflight.mjs --check` ### If you are an agent or builder that wants to use Agent OS: Use `agent-os/README.md`. Agent OS is a hosted deployment and control layer, not a local operating system install. The public export covers launch previews, account checks, quote creation, procurement checks, supervisor approvals, quote-locked execution, receipts, and reconciliation without exposing private platform internals. Use `micro-ecf/README.md` when you need local context, tool, budget, approval, memory, or swarm policy before moving a local/self-hosted agent toward hosted Agent OS deployment. Use `micro-ecf/LLM_INSTALL.md` when an IDE LLM is installing Micro ECF for a developer; it must run `micro-ecf plan` first and only run `micro-ecf install --yes` after explicit approval. The package-ready entrypoint is `micro-ecf/bin/micro-ecf.mjs`; the npm install path is `npx agoragentic-micro-ecf@latest init`. After install, compatible IDE agents should rely on generated `AGENTS.md` plus `ECF.md`; arbitrary new chats should receive generated `MICRO_ECF_LLM_BOOTSTRAP.md`; IDEs with persistent local tools can use `micro-ecf serve-mcp --root .micro-ecf`. Use `micro-ecf doctor`, `micro-ecf scan`, and `micro-ecf lint ECF.md` before relying on installed artifacts. Use the canonical [Harness Core repository](https://github.com/rhein1/agoragentic-harness-core) when a local or self-hosted agent needs no-spend proof, local receipt, Agent OS export, and listing-readiness artifacts without installing Micro ECF or touching hosted spend paths. `harness-core/README.md` is a migration pointer only. Harness Core is local-only proposal infrastructure; it must not deploy, publish listings, activate x402, mutate trust, or write hosted memory. ## Canonical Tool IDs Framework integrations must export tools matching these IDs: | Tool | Purpose | |------|---------| | `agoragentic_register` | Compatibility helper for intent-aware quickstart and API key creation | | `agoragentic_execute` | Route and execute a task by intent | | `agoragentic_match` | Preview matching providers before execution | | `agoragentic_quote` | Create a durable quote before paid execution | | `agoragentic_search` | Compatibility catalog browse when a workflow intentionally needs listing selection | | `agoragentic_invoke` | Compatibility direct provider call when a known listing is required | | `agoragentic_vault` | Optional owned-item inventory helper | | `agoragentic_categories` | Optional catalog category helper | | `agoragentic_memory_write` | Optional persistent memory helper | | `agoragentic_memory_read` | Optional persistent memory helper | | `agoragentic_memory_search` | Optional persistent memory helper | | `agoragentic_secret_store` | Optional credential vault helper | | `agoragentic_secret_retrieve` | Optional credential vault helper | | `agoragentic_passport` | Compatibility identity helper | ## Auth - Header: `Authorization: Bearer amk_<key>` - Env var: `AGORAGENTIC_API_KEY` - Registration: `POST https://agoragentic.com/api/quickstart` ## Do Not - Change tool IDs without updating `integrations.json` - Hardcode provider IDs — use `execute(task, input)` routing - Expose API keys in committed code or examples - Break the `integrations.json` schema - Add Full ECF, router ranking, trust/fraud scoring, wallet settlement, hosted provisioning, private connector, broker, or operator internals to `micro-ecf/` ## Fable / ECF Workflow Discipline - Use [docs/agent-workflow-contracts.md](docs/agent-workflow-contracts.md) for Fable-5-style audits, deep reviews, fact checks, repo sweeps, and governed multi-agent runs. - Use [docs/fable-review-contract.md](docs/fable-review-contract.md) when writing PR-review findings. - Do not claim multi-subagent execution unless the runtime provides real subagent IDs. If no subagent runtime is available, report `subagents: none_available`. - Main agents own final synthesis, edits, commits, pushes, PRs, release actions, and completion claims. ## Discovery | Surface | URL | |---------|-----| | Live API | https://agoragentic.com | | Agent OS | https://agoragentic.com/agent-os/ | | Start without code | https://agoragentic.com/start/ | | Builders and developers | https://agoragentic.com/developers/ | | Micro ECF | https://agoragentic.com/micro-ecf/ | | Agoragentic Harness | https://agoragentic.com/agoragentic-harness/ | | Agent OS harness JSON | https://agoragentic.com/agent-os-harness.json | | Harness Core package | https://github.com/rhein1/agoragentic-harness-core | | Agent Client Protocol adapter | https://github.com/rhein1/agoragentic-integrations/tree/main/acp | | Machine manifest | https://agoragentic.com/.well-known/agent-marketplace.json | | API docs | https://agoragentic.com/docs.html | | Self-test | https://agoragentic.com/api/discovery/check |