The Agent Communication Protocol (ACP) is an open standard developed by the Linux Foundation AI and IBM to enable seamless communication between AI agents, tools, and applications. It defines a common language and structured message format that allows independent AI agents, LLMs, and services to exchange tasks, results, and context in real time.
ACPJava is pure Java implementation of ACP Protocol. You can use it to build Java based ACP compatible agents. These agents will work with A2A and MCP out of the box without any additional configurations !
Unlike traditional REST APIs designed for static integrations, ACP is built for dynamic, multi-agent environments where agents need to collaborate, delegate tasks, and share knowledge. It supports JSON-based messaging, event-driven workflows, and capability discovery, making it ideal for building agentic AI ecosystems.
Key Features of ACP:
🤝 Interoperability — Allows agents from different vendors and platforms to talk to each other.
⚡ Real-Time Collaboration — Enables event-driven, asynchronous communication between multiple AI agents.
🧩 Capability Discovery — Agents can dynamically discover what other agents can do.
🔌 Tool Integration — Easily integrates with APIs, databases, and external services.
🌐 Open Standard — Backed by the Linux Foundation AI and supported by multiple industry players.
Use Cases:
Multi-agent AI systems for task automation
AI-powered chatbots and assistants that coordinate with external APIs
Building agent marketplaces where third-party agents plug into a single ecosystem
Workflow orchestration for enterprises and developer platforms
Technical Details of ACP Protocol
The Agent Communication Protocol (ACP) provides a standardized RESTful API for managing, orchestrating, and executing AI agents. It supports synchronous, asynchronous, and streamed agent interactions, with both stateless and stateful execution modes.
Version: 0.2.0
Base URL: http://localhost:8000
License: Apache 2.0
Authentication
Currently, no authentication is specified in the API documentation.
Endpoints
Health Check
GET /ping
Description: Simple health check endpoint that returns a ping response.
Parameters: None
Response:
200 OK: Ping successful
{}
Example:
curl -X GET http://localhost:8000/ping
Agent Management
GET /agents
Description: Discovers and lists all available agents with their basic information.
Tags: agent
Parameters:
limit (query, optional): Maximum number of agents to return
Type: integer
Default: 10
Range: 1–1000
offset (query, optional): Number of agents to skip for pagination
Type: integer
Default: 0
Minimum: 0
Response:
200 OK: List of agents retrieved successfully
{
"agents": [
{
"name": "chat",
"description": "Conversational agent with memory, supporting real-time search",
"input_content_types": ["text/plain", "image/*"],
"output_content_types": ["text/plain", "application/json"],
"metadata": {
"tags": ["Chat"],
"capabilities": [
{
"name": "Conversational AI",
"description": "Handles multi-turn conversations with memory"
}
]
},
"status": {
"avg_run_tokens": 1500.5,
"avg_run_time_seconds": 2.3,
"success_rate": 98.5
}
}
]
}
Example
curl -X GET "http://localhost:8000/agents?limit=5&offset=0"
GET /agents/{name}
Description: Retrieves the complete manifest and details for a specific agent.
Tags: agent
Parameters:
name (path, required): The name of the agent to retrieve
Type: string
Pattern: ^a-z0-9?$
Length: 1–63 characters
Response:
200 OK: Agent manifest retrieved successfully
{
"name": "chat",
"description": "Conversational agent with memory and tool integration",
"input_content_types": ["text/plain", "image/png"],
"output_content_types": ["text/plain", "application/json"],
"metadata": {
"annotations": {
"version": "1.0.0"
},
"documentation": "# Chat Agent\nThis agent handles conversational interactions...",
"license": "Apache-2.0",
"programming_language": "Python",
"natural_languages": ["en", "es"],
"framework": "BeeAI",
"capabilities": [
{
"name": "Memory Management",
"description": "Maintains conversation context across sessions"
}
],
"domains": ["general", "customer-service"],
"tags": ["Chat", "Customer Support"],
"author": {
"name": "John Smith",
"email": "jsmith@example.com"
}
},
"status": {
"avg_run_tokens": 1200.0,
"avg_run_time_seconds": 1.8,
"success_rate": 99.2
}
}
Run Management
POST /runs
Description: Creates and starts a new run for a specified agent. Supports different execution modes (sync, async, stream).
Tags: run
Request Body:
{
"agent_name": "chat",
"session_id": "123e4567-e89b-12d3-a456-426614174000",
"input": [
{
"role": "user",
"parts": [
{
"content_type": "text/plain",
"content": "Hello, how can you help me today?"
}
]
}
],
"mode": "stream"
}
Required Fields:
agent_name: Name of the agent to run
input: Array of input messages (minimum 1 message)
Optional Fields:
session_id: UUID for session continuity
session: Complete session object (alternative to session_id)
mode: Execution mode (sync, async, stream)
Response:
200 OK: Run started successfully (streaming or immediate response)
Content-Type: application/json or text/event-stream
{
"agent_name": "chat",
"session_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "in-progress",
"output": [],
"created_at": "2024-01-15T10:30:00Z"
}
202 Accepted: Run accepted for asynchronous processing
{
"agent_name": "chat",
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "created",
"output": [],
"created_at": "2024-01-15T10:30:00Z"
}
Example
curl -X POST http://localhost:8000/runs \
-H "Content-Type: application/json" \
-d '{
"agent_name": "chat",
"input": [
{
"role": "user",
"parts": [
{
"content_type": "text/plain",
"content": "What is the weather like?"
}
]
}
],
"mode": "async"
}'
GET /runs/{run_id}
Description: Retrieves the current status and details of a specific run.
Tags: run
Parameters:
run_id (path, required): UUID of the run
Type: string (UUID format)
Response:
200 OK: Run status retrieved successfully
{
"agent_name": "chat",
"session_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "completed",
"output": [
{
"role": "agent/chat",
"parts": [
{
"content_type": "text/plain",
"content": "I can help you with various tasks including answering questions..."
}
],
"created_at": "2024-01-15T10:30:05Z",
"completed_at": "2024-01-15T10:30:10Z"
}
],
"created_at": "2024-01-15T10:30:00Z",
"finished_at": "2024-01-15T10:30:10Z"
}
Possible Status Values:
created: Run has been created but not started
in-progress: Run is currently executing
awaiting: Run is waiting for client input
cancelling: Run is in the process of being cancelled
cancelled: Run has been cancelled
completed: Run finished successfully
failed: Run encountered an error
curl -X GET http://localhost:8000/runs/456e7890-e89b-12d3-a456-426614174000
POST /runs/{run_id}
Description: Resumes a paused or awaiting run by providing additional input or responses.
Tags: run
Parameters:
run_id (path, required): UUID of the run to resume
{
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"await_resume": {
"response": "Yes, please proceed with the analysis"
},
"mode": "stream"
}
Required Fields:
run_id: UUID of the run to resume
await_resume: Response payload to continue execution
mode: Execution mode for the resumed run
Response:
200 OK: Run resumed successfully
{
"agent_name": "chat",
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "in-progress",
"output": [
{
"role": "agent/chat",
"parts": [
{
"content_type": "text/plain",
"content": "Continuing with the analysis..."
}
]
}
],
"created_at": "2024-01-15T10:30:00Z"
}
202 Accepted: Resume request accepted for processing
Example:
curl -X POST http://localhost:8000/runs/456e7890-e89b-12d3-a456-426614174000 \
-H "Content-Type: application/json" \
-d '{
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"await_resume": {
"user_confirmation": true
},
"mode": "async"
}'
POST /runs/{run_id}/cancel
Description: Cancels a running or queued run.
Tags: run
Parameters:
run_id (path, required): UUID of the run to cancel
Request Body: None
Response:
202 Accepted: Cancel request accepted
{
"agent_name": "chat",
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "cancelling",
"output": [],
"created_at": "2024-01-15T10:30:00Z"
}
Example:
curl -X POST http://localhost:8000/runs/456e7890-e89b-12d3-a456-426614174000/cancel
GET /runs/{run_id}/events
Description: Retrieves a chronological list of all events emitted during a run’s lifecycle.
Tags: run
Parameters:
run_id (path, required): UUID of the run
Response:
200 OK: List of run events
{
"events": [
{
"type": "run.created",
"run": {
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "created"
}
},
{
"type": "run.in-progress",
"run": {
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "in-progress"
}
},
{
"type": "message.created",
"message": {
"role": "agent/chat",
"parts": [
{
"content_type": "text/plain",
"content": "Processing your request..."
}
]
}
},
{
"type": "run.completed",
"run": {
"run_id": "456e7890-e89b-12d3-a456-426614174000",
"status": "completed"
}
}
]
}
Event Types:
run.created: Run was created
run.in-progress: Run started executing
run.awaiting: Run is waiting for input
run.completed: Run finished successfully
run.cancelled: Run was cancelled
run.failed: Run encountered an error
message.created: New message was generated
message.part: Message part was added (for streaming)
message.completed: Message was completed
error: An error occurred
generic: Generic event with custom data
curl -X GET http://localhost:8000/runs/456e7890-e89b-12d3-a456-426614174000/events
Session Management
GET /session/{session_id}
Description: Retrieves details of a specific session, including history and state information.
Tags: session
Parameters:
session_id (path, required): UUID of the session
Response:
200 OK: Session details retrieved successfully
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"history": [
"http://localhost:8000/runs/456e7890-e89b-12d3-a456-426614174000",
"http://localhost:8000/runs/789e0123-e89b-12d3-a456-426614174000"
],
"state": "http://localhost:8000/sessions/123e4567-e89b-12d3-a456-426614174000/state"
}
Example:
curl -X GET http://localhost:8000/session/123e4567-e89b-12d3-a456-426614174000
Data Models
Message Structure
Messages in ACP consist of multiple parts, each with specific content types:
{
"role": "user|agent|agent/{agent_name}",
"parts": [
{
"name": "optional-part-name",
"content_type": "text/plain",
"content": "message content",
"content_encoding": "plain|base64",
"metadata": {
"kind": "citation|trajectory",
"title": "Source Title",
"url": "https://example.com"
}
}
],
"created_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:10Z"
}
Run Status Lifecycle
created → in-progress → completed
↓ ↓ ↓
cancelled ← cancelling failed
↑ ↓
↑ awaiting → (resume) → in-progress
Error Responses
All endpoints may return error responses with this structure:
{
"code": "server_error|invalid_input|not_found",
"message": "Human-readable error description",
"data": {
"additional": "error context"
}
}
Content Types
Supported Input/Output Types
Agents can specify which content types they support:
text/plain: Plain text content
text/markdown: Markdown formatted text
application/json: JSON structured data
image/: Any image format
image/png: PNG images specifically
*/: Accept any content type
Streaming Responses
When using mode: "stream", responses are delivered as Server-Sent Events (SSE) with Content-Type: text/event-stream:
event: run.created
data: {"type": "run.created", "run": {...}}
event: message.part
data: {"type": "message.part", "part": {...}}
event: run.completed
data: {"type": "run.completed", "run": {...}}
Usage Examples
Agents
{
"agents": [
{
"name": "raiseticket",
"description": "Create a ticket for customer",
"inputContentTypes": [
"text/plain",
"application/json"
],
"outputContentTypes": [
"text/plain",
"application/json"
],
"metadata": {
"annotations": null,
"documentation": "Create a ticket for customer",
"license": null,
"programmingLanguage": null,
"naturalLanguages": null,
"framework": "Tools4AI",
"capabilities": [
{
"name": "raiseTicket",
"description": "Raise a ticket for customer"
}
],
"domains": null,
"tags": null,
"createdAt": "2025-08-31T08:46:16.2182285-04:00",
"updatedAt": "2025-08-31T08:46:16.2182285-04:00",
"author": null,
"contributors": null,
"links": [
{
"type": "api",
"url": "http://vishal:7860/agents/raiseticket"
}
],
"dependencies": null,
"recommendedModels": null
},
"status": {
"avgRunTokens": null,
"avgRunTimeSeconds": null,
"successRate": 100
}
},
{
"name": "whatthispersonfavfood",
"description": "Provide persons name and then find out what does that person like",
"inputContentTypes": [
"text/plain",
"application/json"
],
"outputContentTypes": [
"text/plain",
"application/json"
],
"metadata": {
"annotations": null,
"documentation": "Provide persons name and then find out what does that person like",
"license": null,
"programmingLanguage": null,
"naturalLanguages": null,
"framework": "Tools4AI",
"capabilities": [
{
"name": "whatThisPersonFavFood",
"description": "Get the favourite food of a person"
}
],
"domains": null,
"tags": null,
"createdAt": "2025-08-31T08:46:16.2193071-04:00",
"updatedAt": "2025-08-31T08:46:16.2193071-04:00",
"author": null,
"contributors": null,
"links": [
{
"type": "api",
"url": "http://vishal:7860/agents/whatthispersonfavfood"
}
],
"dependencies": null,
"recommendedModels": null
},
"status": {
"avgRunTokens": null,
"avgRunTimeSeconds": null,
"successRate": 100
}
},
{
"name": "comparecar",
"description": "Provide 2 cars and compare them",
"inputContentTypes": [
"text/plain",
"application/json"
],
"outputContentTypes": [
"text/plain",
"application/json"
],
"metadata": {
"annotations": null,
"documentation": "Provide 2 cars and compare them",
"license": null,
"programmingLanguage": null,
"naturalLanguages": null,
"framework": "Tools4AI",
"capabilities": [
{
"name": "compareCar",
"description": "compare 2 cars"
}
],
"domains": null,
"tags": null,
"createdAt": "2025-08-31T08:46:16.2193071-04:00",
"updatedAt": "2025-08-31T08:46:16.2193071-04:00",
"author": null,
"contributors": null,
"links": [
{
"type": "api",
"url": "http://vishal:7860/agents/comparecar"
}
],
"dependencies": null,
"recommendedModels": null
},
"status": {
"avgRunTokens": null,
"avgRunTimeSeconds": null,
"successRate": 100
}
},
{
"name": "gettemperature",
"description": "get weather for city",
"inputContentTypes": [
"text/plain",
"application/json"
],
"outputContentTypes": [
"text/plain",
"application/json"
],
"metadata": {
"annotations": null,
"documentation": "get weather for city",
"license": null,
"programmingLanguage": null,
"naturalLanguages": null,
"framework": "Tools4AI",
"capabilities": [
{
"name": "getTemperature",
"description": "get temperature for city"
}
],
"domains": null,
"tags": null,
"createdAt": "2025-08-31T08:46:16.2193071-04:00",
"updatedAt": "2025-08-31T08:46:16.2193071-04:00",
"author": null,
"contributors": null,
"links": [
{
"type": "api",
"url": "http://vishal:7860/agents/gettemperature"
}
],
"dependencies": null,
"recommendedModels": null
},
"status": {
"avgRunTokens": null,
"avgRunTimeSeconds": null,
"successRate": 100
}
}
]
}
Agent Run
Top comments (0)