Agntcy ACP Client

Introduction

The Agent Connect Protocol SDK is an open-source library designed to facilitate the adoption of the Agent Connect Protocol. It offers tools for client implementations, enabling seamless integration, and communication between multi-agent systems.

The SDK is current available in Python .

Getting Started with the client

To use the package, follow the steps below.

Requirements

Python 3.9+

Installation

Install the latest version from PyPi:

pip install agntcy-acp

Usage

from agntcy_acp import AsyncACPClient, AsyncApiClient, ApiException
from agntcy_acp.models import RunCreate

# Defining the host is optional and defaults to http://localhost
config = ApiClientConfiguration(
    host="https://localhost:8081/", 
    api_key={"x-api-key": os.environ["API_KEY"]}, 
    retries=3
)

# Enter a context with an instance of the API client
async with AsyncApiClient(config) as api_client:
    agent_id = 'agent_id_example' # str | The ID of the agent.
    client = AsyncACPClient(api_client)
    
    try:
      api_response = client.create_run(RunCreate(agent_id="my-agent-id"))
      print(f"Run {api_response.run_id} is currently {api_response.status}")
    except ApiException as e:
        print("Exception when calling create_run: %s\n" % e)

Documentation for API Endpoints

The complete documentation for all of the API Endpoints are available in the reference documentation for the API clients:

Using ACP with LangGraph

The SDK provides integration with LangGraph with the agntcy_acp.langgraph.ACPNode class that can be used as a graph node:

from enum import Enum
from typing import List, Optional

from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel, Field

from agntcy_acp import ApiClientConfiguration
from agntcy_acp.langgraph.acp_node import ACPNode


class Type(Enum):
    human = 'human'
    assistant = 'assistant'
    ai = 'ai'

class Message(BaseModel):
    type: Type = Field(
        ...,
        description='indicates the originator of the message, a human or an assistant',
    )
    content: str = Field(..., description='the content of the message', title='Content')

class InputSchema(BaseModel):
    messages: Optional[List[Message]] = Field(None, title='Messages')
    is_completed: Optional[bool] = Field(None, title='Is Completed')

class OutputSchema(BaseModel):
    messages: Optional[List[Message]] = Field(None, title='Messages')
    is_completed: Optional[bool] = Field(None, title='Is Completed')
    final_email: Optional[str] = Field(
        None,
        description='Final email produced by the mail composer',
        title='Final Email',
    )

class StateMeasures(BaseModel):
    input: InputSchema
    output: OutputSchema

def main():
    # Instantiate the local ACP node for the remote agent
    acp_node = ACPNode(
        name="mailcomposer",
        agent_id='50272dfd-4c77-4529-abbb-419bb1724230',
        client_config=ApiClientConfiguration.fromEnvPrefix("COMPOSER_"),
        input_path="input",
        input_type=InputSchema,
        output_path="output",
        output_type=OutputSchema,
    )

    # Create the state graph
    sg = StateGraph(StateMeasures)

    # Add edges
    sg.add_edge(START, acp_node.get_name())
    sg.add_edge(acp_node.get_name(), END)

    graph = sg.compile()
    output_state = graph.invoke({
      "input": InputSchema(content=input), 
      "output": OutputSchema(content="bad-output"),
    })

Using the CLI to generate Agent-specific bindings

The Client SDK includes a CLI tool to generate models or OpenAPI specs specific to an agent using the manifest descriptor. With these models the agent-specific data sent to ACP can be validated. By default, only the ACP parameters are validated by the SDK client.

The CLI also provides validators for the ACP descriptor and manifest files.

You can use the CLI easily:

using poetry: poetry run acp --help
with the package installed: python3 -m agntcy_acp --help

Usage: acp [OPTIONS] COMMAND [ARGS]...

Options:

--help Show this message and exit.

Commands:

generate-agent-models [OPTIONS] AGENT_DESCRIPTOR_PATH

Generate pydantic models from agent manifest or descriptor.

Options:
- --output-dir TEXT
  
  Pydantic models for specific agent based on provided agent descriptor or agent manifest [required]
- --model-file-name TEXT
  
  Filename containing the pydantic model of the agent schemas
generate-agent-oapi [OPTIONS] AGENT_DESCRIPTOR_PATH

Generate OpenAPI Spec from agent manifest or descriptor

Options:
- --output TEXT
  
  OpenAPI output file
validate-acp-descriptor [OPTIONS] AGENT_DESCRIPTOR_PATH

Validate the Agent Descriptor contained in the file AGENT_DESCRIPTOR_PATH against the ACP specification
validate-acp-manifest [OPTIONS] AGENT_MANIFEST_PATH

Validate the Agent Manifest contained in the file AGENT_MANIFEST_PATH against the Manifest specification

Testing

To run the various unit tests in the package, run make test.

Roadmap

See the open issues for a list of proposed features and known issues.

Client Reference API

For a detailed description of the classes and functions in the SDK, please see the agntcy-acp Package Documentation