Overview
Navigate the browser to a specific URL. This provides direct control over browser navigation, independent of agent tasks.
Request
Bearer token for authentication
Absolute URL to navigate to (must start with http:// or https://)Maximum length: 2,000 characters
Response
The URL after navigation (may differ if redirected)
{
"current_url": "https://www.kayak.com/flights"
}
Example
curl -X POST https://api.agi.tech/v1/sessions/<session_id>/navigate \
-H "Authorization: Bearer $AGI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.kayak.com/flights"
}'
Validation
URL must start with http:// or https://. Relative URLs and other protocols are not supported.
Use Cases
Pre-Navigation Setup
# Navigate to login page before starting agent task
navigate_to(session_id, "https://example.com/login")
time.sleep(2) # Let page load
# Now send agent task
send_message(session_id, "Fill out the form with my saved credentials")
Verify Navigation
# Navigate and verify successful load
target_url = "https://amazon.com"
current_url = navigate_to(session_id, target_url)
if "amazon.com" in current_url:
print("Successfully navigated to Amazon")
else:
print(f"Unexpected redirect to: {current_url}")
Multi-URL Task
# Navigate through multiple sites
urls = [
"https://amazon.com",
"https://bestbuy.com",
"https://walmart.com"
]
prices = []
for url in urls:
navigate_to(session_id, url)
send_message(session_id, "Find iPhone 15 Pro price")
# Wait for result
result = wait_for_completion(session_id)
prices.append(result)
Error Handling
def safe_navigate(session_id, url):
"""Navigate with validation"""
# Validate URL format
if not url.startswith(('http://', 'https://')):
raise ValueError("URL must start with http:// or https://")
if len(url) > 2000:
raise ValueError("URL too long (max 2000 chars)")
try:
current_url = navigate_to(session_id, url)
return current_url
except requests.HTTPError as e:
if e.response.status_code == 400:
print("Invalid URL format")
elif e.response.status_code == 404:
print("Session not found")
raise
Navigate vs Message with URL
| Method | When to Use |
|---|
| Navigate API | Direct control, immediate navigation |
| Message with start_url | Let agent handle navigation naturally |
| Message with URL in text | Agent decides how to interpret URL |
Best Practices
Use navigate before sending a message to ensure the agent starts on the right page.
The navigate endpoint changes browser state immediately. Use carefully to avoid disrupting agent tasks.
For most use cases, providing a start_url in your message is more flexible than using the navigate endpoint directly.
