adcp-client: Instructions file for GitHub Copilot

AdCP Client Developer Guide

📖 This guide is for GitHub Copilot. For complete AI coding assistant instructions, see ../AGENTS.md

Quick Reference

This is @adcp/sdk - the official TypeScript client library for the Ad Context Protocol (AdCP).

Critical rules (see AGENTS.md for details):

• ✅ Always use official @a2a-js/sdk and @modelcontextprotocol/sdk clients
• ❌ Never use mock data - return exactly what agents provide
• ✅ Use changesets for version management (never edit package.json version manually)
• ✅ Use Conventional Commits for commit messages and PR titles; do not prefix PR titles with agent/tool labels like [Codex] or [Claude]

Project Components

1. Library (src/lib/) - NPM package for AdCP agents communication
2. CLI (bin/) - Command-line tooling for testing agents

Architecture Quick Reference

Async Operation Patterns (AdCP PR 78)

All operations follow 5 status patterns based on agent response:

• completed - Sync completion with result
• working - Long-running, poll with tasks/get
• submitted - Webhook delivery required
• input_required - Agent needs clarification via input handlers
• deferred - Client defers decision to human/external system

// Core flow in src/lib/core/TaskExecutor.ts
const result = await executor.executeTask(agent, 'get_products', params, inputHandler);
// Status determines next steps: polling, webhook wait, or input handling

Conversation-Aware Input Handling

Agents may need clarifications during execution. Use input handlers:

const client = new ADCPClient(agent, {
  handlers: {
    onGetProductsStatusChange: (response, metadata) => {
      // Fires for ALL status changes: sync completion, webhook delivery, etc.
    },
  },
});

// Input handler pattern for clarifications
const handler = async context => {
  return context.inputRequest.field === 'budget' ? 50000 : context.deferToHuman();
};

Build & Release Process