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.
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.
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
This repository is in early development.
@aip/corecurrently provides the protocol constants and foundational TypeScript type definitions forAIP/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.
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.
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}
The repository defines the following target endpoint layout for agent-facing services:
| Concern | Endpoint |
|---|---|
| Discovery | GET /.well-known/agent.json |
| Schema | GET /agent/schema |
| Synchronous execution | POST /agent/execute |
| Asynchronous task creation | POST /agent/task |
| Task event stream | GET /agent/stream/{taskId} |
| Task result lookup | GET /agent/task/{taskId} |
At present, this interface is represented in shared constants and types. The server and client implementations are still in progress.
| Path | Purpose | Current state |
|---|---|---|
packages/aip-core |
Shared protocol constants and TypeScript types | Available |
packages/aip-server |
Reference server package and adapter surface | Scaffolded |
packages/aip-client |
Reference client package | Scaffolded |
packages/aip-demo-weather |
Planned synchronous demo service | Placeholder |
packages/aip-demo-flights |
Planned async and streaming demo service | Placeholder |
packages/spec |
Reserved package for specification assets and examples | Placeholder |
docs |
Supporting repository documentation | Minimal |
examples |
Example usage material | Minimal |
- Node.js
>=18.0.0 - pnpm
>=8.0.0
Install dependencies and run the workspace commands from the repository root:
pnpm install
pnpm build
pnpm testAdditional root scripts are available for development workflows:
pnpm dev
pnpm lint
pnpm format
pnpm cleanNote that several package-level scripts currently compile or return placeholder output while implementation work is still underway.
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
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.
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.
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
- Repository: tahsinkoc/AIP-Agent-Interaction-Protocol
- Next.js SDK: tahsinkoc/aip-next
- Issues: GitHub Issues
This project is licensed under the MIT License.