Skip to content

Commit f25d9e1

Browse files
MervinPraisonMervinPraison
authored
Merge pull request #631 from MervinPraison/claude/issue-630-20250609_145612
feat: add remote agent connectivity with Google ADK-like API
2 parents 25a0f31 + a0a45a6 commit f25d9e1

File tree

5 files changed

+715
-32
lines changed

5 files changed

+715
-32
lines changed

‎examples/python/remote/README.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
# Remote Agent Connectivity
2+
3+
This directory contains examples demonstrating PraisonAI's remote agent connectivity feature, which allows you to connect to agents running on different servers, similar to Google ADK's agent connectivity pattern.
4+
5+
## Overview
6+
7+
The remote agent connectivity feature enables:
8+
- **Direct agent-to-agent connectivity** across networks
9+
- **Session-based communication** with remote agents
10+
- **Google ADK-like API patterns** for familiar usage
11+
- **Automatic connection management** and error handling
12+
13+
## Quick Start
14+
15+
### 1. Start a Remote Agent Server
16+
17+
```bash
18+
# Start a simple remote agent server
19+
python remote_agent_server.py
20+
21+
# Or start multiple agents on one server
22+
python remote_agent_server.py --multiple
23+
```
24+
25+
### 2. Connect from Client
26+
27+
```python
28+
from praisonaiagents import Session
29+
30+
# Connect to remote agent (similar to Google ADK)
31+
session = Session(agent_url="192.168.1.10:8000/agent")
32+
33+
# Send messages to the remote agent
34+
response = session.chat("Hello from the client!")
35+
print(response)
36+
37+
# Alternative method (Google ADK pattern)
38+
response = session.send_message("What can you help me with?")
39+
print(response)
40+
```
41+
42+
## Examples
43+
44+
- **`remote_agent_server.py`** - Set up agents as remote servers
45+
- **`remote_agent_example.py`** - Connect to and communicate with remote agents
46+
47+
## API Comparison
48+
49+
### Google ADK Pattern
50+
```python
51+
from adk.agent import Agent
52+
from adk.session import Session
53+
54+
session = Session(agent_url="192.168.1.10:8000")
55+
response = session.send_message("Hello!")
56+
```
57+
58+
### PraisonAI Pattern
59+
```python
60+
from praisonaiagents import Session
61+
62+
session = Session(agent_url="192.168.1.10:8000/agent")
63+
response = session.chat("Hello!")
64+
# OR
65+
response = session.send_message("Hello!") # Google ADK compatibility
66+
```
67+
68+
## Key Features
69+
70+
### ✅ **Seamless Connectivity**
71+
- Automatic protocol detection (http/https)
72+
- Connection testing and validation
73+
- Configurable timeouts
74+
75+
### ✅ **Error Handling**
76+
- Clear error messages for connection issues
77+
- Graceful handling of network problems
78+
- Appropriate fallbacks for unavailable services
79+
80+
### ✅ **Backward Compatibility**
81+
- Existing local agent functionality unchanged
82+
- Session API works for both local and remote scenarios
83+
- No breaking changes to current code
84+
85+
### ✅ **Flexible Configuration**
86+
- Support for IP:port format (`192.168.1.10:8000`)
87+
- Full URL format (`http://server.com:8000/agent`)
88+
- Customizable endpoints and paths
89+
90+
## Usage Patterns
91+
92+
### Single Remote Agent
93+
```python
94+
# Connect to a specific remote agent
95+
session = Session(agent_url="192.168.1.10:8000/agent")
96+
response = session.chat("Hello from remote client!")
97+
```
98+
99+
### Multiple Remote Agents
100+
```python
101+
# Connect to different specialized agents
102+
research_session = Session(agent_url="192.168.1.10:8000/research")
103+
coding_session = Session(agent_url="192.168.1.10:8000/coding")
104+
105+
research_response = research_session.chat("Find info about AI trends")
106+
coding_response = coding_session.chat("Help me debug this Python code")
107+
```
108+
109+
### Error Handling
110+
```python
111+
try:
112+
session = Session(agent_url="192.168.1.10:8000/agent")
113+
response = session.chat("Test message")
114+
print(f"Response: {response}")
115+
except ConnectionError as e:
116+
print(f"Failed to connect: {e}")
117+
```
118+
119+
## Network Configuration
120+
121+
### Server Setup
122+
```python
123+
# Create and launch agent server
124+
agent = Agent(name="RemoteAgent", role="Assistant")
125+
agent.launch(path="/agent", port=8000, host="0.0.0.0")
126+
```
127+
128+
### Client Connection
129+
```python
130+
# Connect from any network location
131+
session = Session(agent_url="<server-ip>:8000/agent")
132+
```
133+
134+
## Limitations for Remote Sessions
135+
136+
When using remote agent sessions, certain local operations are not available:
137+
- **Memory operations** (`session.memory.*`)
138+
- **Knowledge operations** (`session.knowledge.*`)
139+
- **Local agent creation** (`session.Agent(...)`)
140+
- **State management** (`session.save_state/restore_state`)
141+
142+
This design keeps remote and local operations clearly separated.
143+
144+
## Testing
145+
146+
Run the examples to test the functionality:
147+
148+
```bash
149+
# Terminal 1: Start server
150+
python remote_agent_server.py
151+
152+
# Terminal 2: Test client (update IP as needed)
153+
python remote_agent_example.py
154+
```
155+
156+
## Integration with Existing Code
157+
158+
The remote connectivity feature integrates seamlessly with existing PraisonAI code:
159+
160+
```python
161+
# Existing local code works unchanged
162+
local_session = Session(session_id="local_chat")
163+
local_agent = local_session.Agent(name="LocalAgent", role="Assistant")
164+
165+
# New remote connectivity
166+
remote_session = Session(agent_url="remote-server:8000/agent")
167+
remote_response = remote_session.chat("Hello from remote!")
168+
```
169+
170+
This provides a smooth migration path for applications that need to scale across multiple servers.

‎examples/python/remote/remote_agent_example.py‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
#!/usr/bin/env python3
2+
"""
3+
Remote Agent Connectivity Example
4+
5+
This example demonstrates how to connect to agents running on remote servers,
6+
similar to Google ADK's agent connectivity pattern.
7+
8+
Usage:
9+
1. First, start a remote agent server:
10+
python remote_agent_server.py
11+
12+
2. Then run this client to connect to it:
13+
python remote_agent_example.py
14+
"""
15+
16+
from praisonaiagents import Session
17+
import time
18+
19+
def example_remote_agent_connection():
20+
"""
21+
Example demonstrating remote agent connectivity similar to Google ADK.
22+
"""
23+
print("🌐 Remote Agent Connectivity Example")
24+
print("=" * 50)
25+
26+
# Example 1: Connect to remote agent using IP:port format
27+
try:
28+
print("\n1. Connecting to remote agent at 192.168.1.10:8000...")
29+
30+
# Create a session with remote agent URL (similar to Google ADK)
31+
session = Session(agent_url="192.168.1.10:8000/agent")
32+
33+
print(f"✅ Connected! Session: {session}")
34+
35+
# Send a message to the remote agent
36+
response = session.chat("Hello from the client!")
37+
print(f"📨 Sent: 'Hello from the client!'")
38+
print(f"📨 Received: {response}")
39+
40+
# Send another message using the alias method (Google ADK pattern)
41+
response = session.send_message("What can you help me with?")
42+
print(f"📨 Sent: 'What can you help me with?'")
43+
print(f"📨 Received: {response}")
44+
45+
except ConnectionError as e:
46+
print(f"❌ Connection failed: {e}")
47+
print("💡 Make sure the remote agent server is running at 192.168.1.10:8000")
48+
49+
# Example 2: Connect to localhost for testing
50+
try:
51+
print("\n2. Connecting to localhost for testing...")
52+
53+
# Connect to local server (for testing)
54+
session = Session(agent_url="localhost:8000/agent")
55+
56+
print(f"✅ Connected! Session: {session}")
57+
58+
# Test the connection
59+
response = session.chat("Test message")
60+
print(f"📨 Response: {response}")
61+
62+
except ConnectionError as e:
63+
print(f"❌ Connection failed: {e}")
64+
print("💡 Start a local agent server first with: python remote_agent_server.py")
65+
66+
def example_error_handling():
67+
"""
68+
Example demonstrating error handling for remote sessions.
69+
"""
70+
print("\n\n🚨 Error Handling Examples")
71+
print("=" * 50)
72+
73+
try:
74+
# Create a remote session
75+
session = Session(agent_url="localhost:8000/agent")
76+
77+
# These operations are not available for remote sessions
78+
print("\n❌ Attempting to access memory (should fail)...")
79+
session.memory.store_short_term("test")
80+
81+
except ConnectionError:
82+
print("⚠️ Cannot connect to remote agent (expected if server not running)")
83+
except ValueError as e:
84+
print(f"✅ Correctly caught error: {e}")
85+
86+
try:
87+
session = Session(agent_url="localhost:8000/agent")
88+
print("\n❌ Attempting to create local agent (should fail)...")
89+
agent = session.Agent(name="Test", role="Assistant")
90+
91+
except ConnectionError:
92+
print("⚠️ Cannot connect to remote agent (expected if server not running)")
93+
except ValueError as e:
94+
print(f"✅ Correctly caught error: {e}")
95+
96+
def comparison_with_google_adk():
97+
"""
98+
Shows the comparison between Google ADK and PraisonAI patterns.
99+
"""
100+
print("\n\n🔄 Comparison with Google ADK")
101+
print("=" * 50)
102+
103+
print("\n📋 Google ADK Pattern:")
104+
print("""
105+
from adk.agent import Agent
106+
from adk.session import Session
107+
108+
# Connect to remote agent
109+
session = Session(agent_url="192.168.1.10:8000")
110+
response = session.send_message("Hello from client!")
111+
""")
112+
113+
print("📋 PraisonAI Pattern:")
114+
print("""
115+
from praisonaiagents import Session
116+
117+
# Connect to remote agent
118+
session = Session(agent_url="192.168.1.10:8000/agent")
119+
response = session.chat("Hello from client!")
120+
# OR
121+
response = session.send_message("Hello from client!")
122+
""")
123+
124+
print("✨ Key similarities:")
125+
print("• Direct agent URL connectivity")
126+
print("• Simple session-based API")
127+
print("• Similar message sending patterns")
128+
print("• Error handling for connection issues")
129+
130+
if __name__ == "__main__":
131+
example_remote_agent_connection()
132+
example_error_handling()
133+
comparison_with_google_adk()
134+
135+
print("\n\n🎯 Summary")
136+
print("=" * 50)
137+
print("✅ Remote agent connectivity implemented")
138+
print("✅ Google ADK-like API pattern supported")
139+
print("✅ Backward compatibility maintained")
140+
print("✅ Proper error handling for remote sessions")
141+
print("\n💡 To test with a real server, run remote_agent_server.py first!")

0 commit comments

Comments
 (0)