Welcome to the Agent Connect Protocol (ACP) tutorial series using Galileo's Simple Agent Framework. This repository provides step-by-step tutorials, examples, and resources to help you understand and implement the Agent Connect Protocol for creating powerful, distributed AI agent applications.
The Agent Connect Protocol (ACP) is an open specification that defines a standard interface to invoke and configure agents. It enables seamless integration between different agent systems by providing a common language for agent communication.
ACP provides standardized patterns for:
- Defining and discovering agent capabilities
- Invoking agents with standardized request formats
- Supporting various execution modes (sync, async, streaming)
- Configuring remote agents with consistent parameters
- Handling responses and errors with uniform formats
- Enabling cross-framework agent interoperability
This specification is developed with the support of the Internet of Agents (IoA) community, with the goal of facilitating cross-framework agent interoperability, allowing agents built with different frameworks to communicate seamlessly.
The ACP specification defines a comprehensive set of APIs and patterns for agent interactions:
Agents expose their capabilities through Agent ACP Descriptors, which contain:
- Metadata: Unique identifiers, version information, and descriptions
- Capabilities: Supported features (threads, interrupts, callbacks, streaming)
- Schema Definitions: JSON schemas for inputs, outputs, configuration, and thread states
Clients can retrieve agent information through:
POST /agents/search- Find agents by name, version, or other criteriaGET /agents/{agent_id}/descriptor- Retrieve the full descriptor for a specific agent
ACP supports several key interaction patterns:
-
Runs: Single agent executions
- Start runs with
POST /runs - Poll for completion with
GET /runs/{run_id} - Wait for completion with
GET /runs/{run_id}/wait
- Start runs with
-
Streaming: Real-time partial results
- Receive incremental updates via Server-Sent Events
- Support for both "values" mode (complete results) and "custom" streaming
-
Threads: Conversational state management
- Create threads with
POST /threads - Start runs on threads with
POST /threads/{thread_id}/runs - Access thread history with
GET /threads/{thread_id}
- Create threads with
-
Interrupts: Agent-initiated interactions
- Receive requests for additional input from agents
- Provide needed information to resume processing
-
Callbacks: Asynchronous notifications
- Register callbacks to be notified of run status changes
This repository is organized into tutorial modules that build on each other, starting from the basics and progressing to more advanced agent implementations:
- Tutorial Overview - Start here for an introduction to the series
- Introduction to ACP with Simple Agent Framework - Understanding the foundation
- Building Your First ACP Client - Creating a client agent
- Implementing ACP Server Agents - Building server-side agents
- Implementation Summary - How it all fits together
- AGP Architecture Visualization - Visual diagrams of the architecture
Coming Soon:
- Advanced ACP Patterns - Implementing threads, interrupts, streaming
- Working with Agent ACP Descriptors - Creating and consuming descriptors
- Building Multi-Agent Systems - Coordinating agents through ACP
- Deploying ACP Applications - Production deployment strategies
This tutorial series is built around the Simple Agent Framework from Galileo, which provides a flexible foundation for building AI agents with:
- Tool-based capabilities
- State management
- Prompt templating
- Advanced logging
- Configuration management
We extend this framework to implement the Agent Connect Protocol, enabling distributed agent communication across different systems and environments.
The repository includes complete, working examples that demonstrate ACP in action:
- Remote Agent - A template for building remote agent applications TODO:
- Thread-Based Chat - Demonstrates thread state management (Coming soon!) TODO:
- Streaming Agent - Shows real-time streaming capabilities (Coming soon!) TODO:
- Interrupt-Based Workflow - Demonstrates interactive agent interrupts (Coming soon!)
Throughout these tutorials, we'll demonstrate several key patterns for implementing ACP:
TODO: highlight where these need to be done
-
Agent ACP Descriptor Implementation
- Creating schema definitions for agent capabilities
- Registering and exposing agent descriptors
-
Run Management
- Starting and tracking agent runs
- Processing inputs and outputs according to ACP standards
-
Thread State Handling
- Creating and managing conversational state
- Persisting and retrieving thread history
-
Streaming Implementation
- Implementing real-time output streaming
- Processing streaming responses on the client side
-
Interrupt Handling
- Creating agents that request additional input
- Handling and responding to agent interrupts
To work through these tutorials, you'll need:
- Python 3.12+
- Basic understanding of REST APIs and asynchronous programming
- OpenAI API key (or other LLM provider)
- Docker (for containerized deployments)
-
Clone this repository:
git clone https://github.com/agntcy/agentic-apps cd agentic-apps -
Install the Simple Agent Framework and other dependencies:
pip install git+https://github.com/rungalileo/simple-agent-framework.git pip install -r requirements.txt -
Set up your environment variables:
cp .env.example .env # Edit .env with your API keys -
Start with the tutorial overview:
open tutorials/00-overview.md
acp-tutorials/
├── tutorials/ # Tutorial markdown files
│ ├── 00-overview.md # Overview of the tutorial series
│ ├── 01-intro-to-agp.md # Introduction to ACP with Simple Agent Framework
│ ├── 02-first-agp-client.md # Building your first ACP client
│ ├── 03-agp-server.md # Implementing server-side agents
│ ├── implementation-summary.md # How all the pieces fit together
│ └── agp-architecture.md # Architectural visualizations
├── remote_agent_agp/ # Complete example of a remote agent
├── requirements.txt # Project dependencies
└── .env.example # Example environment variables
The tutorial series covers these key concepts:
- Simple Agent Framework Fundamentals - The building blocks for agent development
- Agent Connect Protocol Standards - How agents communicate using standardized formats
- Tool-Based Communication - Implementing ACP as tools within agents
- Client-Gateway-Server Pattern - Architecture for distributed agent systems
- State Management - Maintaining context across agent interactions
- Error Handling - Managing failures in distributed environments
Our tutorials will guide you through implementing these key ACP API flows:
sequenceDiagram
participant C as ACP Client
participant S as ACP Server
C->>+S: POST /runs {agent_id, input, config, metadata}
S->>-C: Run={run_id, status="pending"}
C->>+S: GET /runs/{run_id}/wait
S->>-C: RunOutput={type="result", result}
sequenceDiagram
participant C as ACP Client
participant S as ACP Server
C->>+S: POST /threads
S->>-C: Thread={thread_id, status="idle"}
C->>+S: POST /threads/{thread_id}/runs {agent_id, input}
S->>-C: Run={run_id, status="pending"}
C->>+S: GET /threads/{thread_id}/runs/{run_id}/wait
S->>-C: RunOutput={type="result", result}
sequenceDiagram
participant C as ACP Client
participant S as ACP Server
C->>+S: POST /runs/stream {agent_id, input, stream_mode='values'}
S->>-C: Run={run_id, status="pending"}
S->>C: StreamEvent={data={result="partial result 1"}}
S->>C: StreamEvent={data={result="partial result 2"}}
S->>C: StreamEvent={data={result="final result"}}
S->>C: Close Connection
- Simple Agent Framework
- Agent Connect Protocol Specification - Official ACP specification repository
- ACP Documentation - Comprehensive documentation on Agent Connect Protocol
- IoA Documentation - Information on the Internet of Agents ecosystem
- Agent Control SDK - Tools for working with ACP and Agent ACP Descriptors
- OpenAPI Visualization - Browse the API specification
The Agent Connect Protocol specification is actively evolving with these upcoming features:
- Support for streaming responses
- Support for pre-configured agents
- Support for agent invocation by name and version
These features will be incorporated into future tutorials as they become available in the specification.
We welcome contributions to improve these tutorials! Please read CONTRIBUTING.md for guidelines on how to submit improvements.
A list of IoA Agentic Apps in other Github repositores :
- Terraform Code Analzyer : tf-code-analyzer-agntcy-agent
- Terraform Code Reviewer: tf-code-reviewer-agntcy-agent
Distributed under Apache 2.0 License. See LICENSE for more information.
Copyright AGNTCY Contributors (https://github.com/agntcy)