AIP

Agent Interaction Protocol

AIP is an open protocol and TypeScript reference workspace for agent-to-service interaction over HTTPS. Its goal is to provide a predictable, machine-readable interface that allows AI agents to discover service capabilities, understand action contracts, invoke operations, and monitor long-running work without relying on brittle UI scraping or service-specific conventions.

It should currently be understood primarily as a protocol design, architectural idea, and implementation approach for agent-native services. The repository is meant to explore and formalize that interaction model, showing how services can become easier for agents to understand, safer to integrate with, and more efficient to operate against.

One of the central design goals is token-cost efficiency. Instead of forcing an agent to consume raw HTML, long-form documentation, or large amounts of unstructured application context, AIP aims to expose compact protocol metadata and JSON Schema contracts so the agent can spend more of its context window on the actual task rather than on navigation noise.

Why AIP

Modern agent integrations still depend too often on scraped interfaces, loosely documented REST endpoints, or large amounts of unstructured application context. That creates avoidable cost and operational risk.

• Scraping is fragile. DOM structure, CSS selectors, and UI copy can change without warning, breaking agent workflows even when the underlying business capability has not changed.
• Unstructured context is expensive. Supplying raw HTML, long developer docs, or large page payloads forces models to spend tokens on navigation noise rather than on the actual task contract.
• Generic APIs are not agent-native. Conventional endpoints often expose transport details without clearly exposing action semantics, expected input shape, or result structure.

AIP addresses this by making services self-describing through a small set of predictable endpoints and JSON Schema-based action definitions. Instead of parsing pages or inferring intent from arbitrary API docs, an agent can load compact protocol metadata, fetch the action schema, and operate against a much smaller and more reliable context surface.

In that sense, AIP is not only about interoperability, but also about making integrations more agent-friendly: lower token usage, clearer action semantics, less prompt bloat, reduced fragility, and a more reliable path for both autonomous and human-supervised agent workflows.

SDKs

The protocol is intended to support multiple SDKs across frameworks and runtimes.

• tahsinkoc/aip-next - Next.js SDK for building applications and integrations on top of AIP
• Additional SDKs are planned for other ecosystems as the protocol matures

Status

This repository is in early development.

• @aip/core currently provides the protocol constants and foundational TypeScript type definitions for AIP/0.1.
• @aip/client, @aip/server, the Express adapter, and the demo services are scaffolded but not yet implemented end to end.
• The repository should currently be treated as a specification-oriented reference workspace, not a production-ready SDK.

Scope

AIP is intended to standardize the core interaction model between an autonomous agent and an HTTP service:

• Service discovery through a well-known endpoint
• Machine-readable action definitions based on JSON Schema
• Consistent synchronous execution semantics
• Optional asynchronous task creation for long-running work
• Optional server-sent event streaming for task progress and completion updates

The protocol version currently represented in this workspace is AIP/0.1.

Design Goals

• Treat agent integration as a first-class interface design problem rather than as an afterthought on top of UI flows
• Reduce token costs by replacing noisy, unstructured context with compact discovery metadata and schema-driven contracts
• Make service capabilities easier for agents to discover, reason about, and invoke safely
• Support both short synchronous actions and longer-running asynchronous workflows
• Provide an implementation approach that can evolve into real SDKs and production integrations over time

Technical Overview

AIP is organized around a small number of protocol primitives:

• A discovery document at a well-known path so agents can identify an AIP-capable service
• An action schema document that defines supported operations and JSON Schema input contracts
• A synchronous execution path for short-running operations
• An asynchronous task path for long-running operations
• Optional SSE-based event streaming for progress and completion updates

Typical interaction flow:

GET  /.well-known/agent.json
GET  /agent/schema
POST /agent/execute
POST /agent/task
GET  /agent/stream/{taskId}
GET  /agent/task/{taskId}

Planned Protocol Surface

The repository defines the following target endpoint layout for agent-facing services:

At present, this interface is represented in shared constants and types. The server and client implementations are still in progress.

Repository Layout

Workspace Requirements

• Node.js >=18.0.0
• pnpm >=8.0.0

Getting Started

Install dependencies and run the workspace commands from the repository root:

pnpm install
pnpm build
pnpm test

Additional root scripts are available for development workflows:

pnpm dev
pnpm lint
pnpm format
pnpm clean

Note that several package-level scripts currently compile or return placeholder output while implementation work is still underway.

Package Overview

@aip/core

The @aip/core package contains the shared protocol contract used across the workspace, including:

• Protocol and endpoint constants
• Discovery document types
• Action and schema types
• Execute, task, and streaming types
• Common protocol error and status constants

@aip/server

The @aip/server package is intended to provide the reference server implementation, including:

• Server factory creation
• Action registration
• Framework adapters
• Runtime configuration for auth, sessions, tasks, and streaming

The public API surface is present, but the core implementation is not yet complete.

@aip/client

The @aip/client package is intended to provide the reference client for:

• Discovery loading
• Schema retrieval
• Synchronous action invocation
• Async task creation
• Task event streaming
• Tool translation for agent runtimes

Its public methods are currently scaffolded and marked for future implementation.

Current Priorities

The next major steps for the repository are:

• Complete the reference server implementation
• Complete the reference client implementation
• Add functional demo services for synchronous and asynchronous flows
• Expand the specification package with concrete protocol examples
• Build out the documentation set beyond the current repository overview