Introduction to the Agent Connect Framework

The Agent Connect Framework (ACF) is a comprehensive specification that enables seamless collaboration between AI agents in multi-agent applications, including specifications like APIs and open-source middleware services. It provides the foundation for connecting agents built with different frameworks and technologies within the IBM watsonx ecosystem. ACF is built on five core principles:

​

Core Principles

ACF is founded on a set of core principles that guide its design and functionality:

• Interoperability: Enable agents built with any framework to communicate and collaborate.
• Standardization: Provide consistent interfaces and protocols for agent interaction.
• Simplicity: Make integration as straightforward as possible for developers.
• Extensibility: Allow for future expansion and adaptation as agent technologies evolve.
• Security: Ensure secure communication and data handling between agents.

​

Architecture Overview

The ACF architecture consists of several key components that enable agent collaboration:

​

1. Agent Connect Protocol

The Agent Connect Protocol defines the standard interfaces and communication patterns for agents to interact with each other and with the watsonx Orchestrate platform. It is designed to be compatible with existing agent frameworks and to provide a consistent experience for developers.

​

2. Chat API

The Chat API is the primary interface for agent-to-agent communication. It follows the familiar OpenAI chat completions format, facilitating implementation and integration with existing agent frameworks. It supports both synchronous and streaming responses for real-time interaction between agents.

​

3. Agent Discovery

The Agent Discovery component allows agents to discover and learn about other agents in the ecosystem. This enables dynamic collaboration between agents without requiring hardcoded knowledge of each other.

​

4. AI Gateway

The AI Gateway provides centralized access to AI models such as LLMs, voice models, and embeddings models. It simplifies the implementation and management of multi-agent systems by providing shared access to these models and collecting telemetry across agents.

​

How ACF enables collaboration

ACF enables collaboration between agents through several mechanisms:

​

1. Standardized communication

Agents communicate using a standardized chat completions API, which follows familiar patterns from OpenAI and other LLM providers. This standard facilitates the implementation of the required endpoints and maintains consistency in the communication between agents.

// Example chat request
{
  "model": "agent-name",
  "messages": [
    {"role": "user", "content": "Hello, I need help with a task."}
  ],
  "stream": true
}

​

2. Tool call context sharing

Agents can share tool calling details with other agents using Agent Connect events.

// Example tool call
{
  "id": "call_abc123",
  "object": "thread.run.step.delta",
  "thread_id": "thread_xyz789",
  "model": "agent-name",
  "choices": [{
    "delta": {
      "role": "assistant",
      "step_details": {
        "type": "tool_calls",
        "tool_calls": [{
          "name": "find_employee_by_name",
          "args": {"name": "John Doe"}
        }]
      }
    }
  }]
}

// Agent would themn emit the following event
event: tool_call
data: {"id": "step-abc123", "object": "thread.run.step.delta", "thread_id": "thread_xyz789", "model": "agent-name", "choices": [{"delta": {"role": "assistant", "step_details": {"type": "tool_calls", "tool_calls": [{"name": "find_employee_by_name", "args": {"name": "John Doe"}}]}}}]}

// Example tool call response
{
  "id": "call_def456",
  "object": "thread.run.step.delta",
  "thread_id": "thread_xyz789",
  "model": "agent-name",
  "choices": [{
    "delta": {
      "role": "assistant",
      "step_details": {
        "type": "tool_response",
        "content": "[{'userId': '12345', 'firstName': 'John', 'lastName': 'Doe', 'email': 'john.doe@example.com', 'department': 'Engineering', 'title': 'Senior Developer', 'location': 'New York (1000-0001)', 'hireDate': '2020-03-15'}]",
        "name": "find_employee_by_name",
        "tool_call_id": "call_abc123"
      }
    }
  }]
}

// Agent would emit the following event for the tool response
event: tool_call_response
data: {"id": "step-def456", "object": "thread.run.step.delta", "thread_id": "thread_xyz789", "model": "agent-name", "choices": [{"delta": {"role": "assistant", "step_details": {"type": "tool_response", "content": "[{'userId': '12345', 'firstName': 'John', 'lastName': 'Doe', 'email': 'john.doe@example.com', 'department': 'Engineering', 'title': 'Senior Developer', 'location': 'New York (1000-0001)', 'hireDate': '2020-03-15'}]", "name": "find_employee_by_name", "tool_call_id": "call_abc123"}}}]}

​

3. Streaming Intermediate Steps

Agents can stream their intermediate thinking steps and tool calls, providing visibility into their reasoning process and enabling more effective collaboration.

event: thread.run.step.delta
data: {"id": "step-123", "object": "thread.run.step.delta", "thread_id": "t-456", "model": "agent-1", "choices": [{"delta": {"role": "assistant", "step_details": {"type": "thinking", "content": "I need to find information about this employee..."}}}]}

​

4. Stateful Conversations

Agents can maintain state across multiple interactions using thread IDs, allowing for complex, multi-turn conversations and workflows.

​

Implementation Considerations

When implementing ACF in your agents, consider the following practices:

1. API Compatibility: Ensure your agent implements the required endpoints according to the specification.
2. Streaming Support: Implement streaming responses for better user experience and collaboration.
3. Tool Integration: Design your agent to consume tools effectively and share tool calling context when appropriate.
4. Error Handling: Implement robust error handling for resilient agent interactions.
5. Security: Follow security best practices for agent communication and data handling.

​

Next Steps

To learn more about specific components of ACF, explore the following sections: