Claude Agent SDK Integration - Location Intelligence for AI Agents

Why Claude Agent SDK + Camino AI?

• Autonomous Location Intelligence: Agents that independently search locations and plan routes
• MCP Integration: Use Camino AI as an MCP tool within the Claude Agent SDK
• Custom Tools: Define location search and routing as agent capabilities
• Multi-Step Workflows: Combine location queries with file operations and bash commands
• Cost-Effective: 17x cheaper than Google Places API

Quick Start: TypeScript

1. Install Dependencies

npm install @anthropic-ai/claude-agent-sdk axios

2. Set Up Environment

export ANTHROPIC_API_KEY="your-anthropic-key"
export CAMINO_API_KEY="your-camino-key"

3. Create Location-Aware Agent

import { Agent } from '@anthropic-ai/claude-agent-sdk';
import axios from 'axios';

const CAMINO_API_KEY = process.env.CAMINO_API_KEY;

// Define Camino AI tool
const locationSearchTool = {
  name: 'search_locations',
  description: 'Search for places and locations using natural language. Can find restaurants, hotels, shops, attractions, or any physical location. Supports context-aware queries like "quiet cafes" or "pet-friendly hotels".',
  input_schema: {
    type: 'object',
    properties: {
      query: {
        type: 'string',
        description: 'Natural language description of what to search for'
      },
      latitude: {
        type: 'number',
        description: 'Latitude coordinate for search center (optional)'
      },
      longitude: {
        type: 'number',
        description: 'Longitude coordinate for search center (optional)'
      },
      radius: {
        type: 'number',
        description: 'Search radius in meters (default: 1000)',
        default: 1000
      },
      limit: {
        type: 'number',
        description: 'Maximum results (1-100, default: 20)',
        default: 20
      }
    },
    required: ['query']
  },
  execute: async ({ query, latitude, longitude, radius = 1000, limit = 20 }) => {
    const params = new URLSearchParams({
      query,
      radius: radius.toString(),
      limit: limit.toString(),
      rank: 'true',
      answer: 'true'
    });
    
    if (latitude && longitude) {
      params.append('lat', latitude.toString());
      params.append('lon', longitude.toString());
    }
    
    const response = await axios.get(
      `https://api.getcamino.ai/query?${params}`,
      { headers: { 'X-API-Key': CAMINO_API_KEY } }
    );
    
    return {
      answer: response.data.answer,
      total_results: response.data.results?.length || 0,
      top_results: response.data.results?.slice(0, 5).map(r => ({
        name: r.name,
        address: r.address,
        distance_km: r.distance_km
      }))
    };
  }
};

// Create agent with location tool
const agent = new Agent({
  tools: [locationSearchTool],
  model: 'claude-sonnet-4.5-20250929'
});

// Run agent
const result = await agent.run(
  'Find me the top 3 Italian restaurants in Manhattan and tell me which is closest to Times Square'
);

console.log(result);

Python Implementation

1. Install Dependencies

pip install claude-agent-sdk requests

2. Create Location Agent

from claude_agent_sdk import Agent, Tool
import requests
import os

CAMINO_API_KEY = os.getenv('CAMINO_API_KEY')

class LocationSearchTool(Tool):
    name = 'search_locations'
    description = 'Search for places using natural language queries'
    
    input_schema = {
        'type': 'object',
        'properties': {
            'query': {'type': 'string'},
            'latitude': {'type': 'number'},
            'longitude': {'type': 'number'},
            'radius': {'type': 'number', 'default': 1000},
            'limit': {'type': 'number', 'default': 20}
        },
        'required': ['query']
    }
    
    async def execute(self, query: str, latitude: float = None, 
                     longitude: float = None, radius: int = 1000, 
                     limit: int = 20):
        params = {
            'query': query,
            'radius': radius,
            'limit': limit,
            'rank': True,
            'answer': True
        }
        
        if latitude and longitude:
            params['lat'] = latitude
            params['lon'] = longitude
        
        response = requests.get(
            'https://api.getcamino.ai/query',
            params=params,
            headers={'X-API-Key': CAMINO_API_KEY}
        )
        
        data = response.json()
        
        return {
            'answer': data.get('answer'),
            'total_results': len(data.get('results', [])),
            'top_results': [
                {
                    'name': r.get('name'),
                    'address': r.get('address'),
                    'distance_km': r.get('distance_km')
                }
                for r in data.get('results', [])[:5]
            ]
        }

# Create agent
agent = Agent(
    tools=[LocationSearchTool()],
    model='claude-sonnet-4.5-20250929'
)

# Run agent
result = await agent.run(
    'Find hotels near JFK airport within 5 miles and recommend the closest one'
)

print(result)

Advanced: Multi-Tool Agent

Add Route Calculation Tool

const routeCalculationTool = {
  name: 'calculate_route',
  description: 'Calculate route and get turn-by-turn directions between two locations',
  input_schema: {
    type: 'object',
    properties: {
      start_lat: { type: 'number' },
      start_lon: { type: 'number' },
      end_lat: { type: 'number' },
      end_lon: { type: 'number' },
      mode: {
        type: 'string',
        enum: ['car', 'bike', 'foot'],
        default: 'car'
      }
    },
    required: ['start_lat', 'start_lon', 'end_lat', 'end_lon']
  },
  execute: async ({ start_lat, start_lon, end_lat, end_lon, mode = 'car' }) => {
    const params = new URLSearchParams({
      start_lat: start_lat.toString(),
      start_lon: start_lon.toString(),
      end_lat: end_lat.toString(),
      end_lon: end_lon.toString(),
      mode
    });
    
    const response = await axios.get(
      `https://api.getcamino.ai/route?${params}`,
      { headers: { 'X-API-Key': CAMINO_API_KEY } }
    );
    
    return {
      distance_km: response.data.distance_km,
      duration_minutes: response.data.duration_minutes,
      directions: response.data.directions?.slice(0, 10)
    };
  }
};

// Create agent with multiple tools
const multiToolAgent = new Agent({
  tools: [locationSearchTool, routeCalculationTool],
  model: 'claude-sonnet-4.5-20250929'
});

Using MCP with Claude Agent SDK

Configure Camino AI as MCP Server

import { Agent } from '@anthropic-ai/claude-agent-sdk';

const agent = new Agent({
  mcpServers: {
    'camino-ai': {
      command: 'npx',
      args: [
        '-y',
        '@modelcontextprotocol/server-http',
        `https://api.getcamino.ai/mcp?caminoApiKey=${process.env.CAMINO_API_KEY}`
      ]
    }
  },
  model: 'claude-sonnet-4.5-20250929'
});

// Agent automatically has access to camino_query tool
const result = await agent.run(
  'Find pet-friendly hotels in San Francisco near Golden Gate Park'
);

Real-World Use Cases

Travel Planning Agent

const travelAgent = new Agent({
  tools: [locationSearchTool, routeCalculationTool],
  systemPrompt: `You are a travel planning assistant. Help users plan trips by:
    1. Finding relevant attractions, restaurants, and hotels
    2. Calculating routes between locations
    3. Providing detailed itineraries with times and distances
    4. Making recommendations based on user preferences`,
  model: 'claude-sonnet-4.5-20250929'
});

const itinerary = await travelAgent.run(
  'Plan a day trip in Paris. I want to visit 2-3 museums, have lunch at a traditional French restaurant, and end at the Eiffel Tower for sunset.'
);

Real Estate Analysis Agent

const realEstateAgent = new Agent({
  tools: [locationSearchTool],
  systemPrompt: `You are a real estate location analyst. For any property address:
    1. Find nearby schools within 2km
    2. Find grocery stores and pharmacies within 1km
    3. Find public transit within 500m
    4. Provide a walkability and convenience score`,
  model: 'claude-sonnet-4.5-20250929'
});

const analysis = await realEstateAgent.run(
  'Analyze the location for a property at 123 Main St, Seattle (47.6062, -122.3321)'
);

Customer Service Agent

const serviceAgent = new Agent({
  tools: [locationSearchTool, routeCalculationTool],
  systemPrompt: `You are a customer service agent helping users find nearby service locations.
    Always be helpful and provide clear directions.`,
  model: 'claude-sonnet-4.5-20250929'
});

const response = await serviceAgent.run(
  'I need to find the nearest service center to my location at 40.7589, -73.9851'
);

Agent Workflows

Multi-Step Location Research

const researchAgent = new Agent({
  tools: [locationSearchTool, routeCalculationTool],
  model: 'claude-sonnet-4.5-20250929'
});

// Agent autonomously:
// 1. Searches for hotels
// 2. Searches for restaurants nearby
// 3. Calculates routes between them
// 4. Makes recommendations
const result = await researchAgent.run(`
  I'm visiting New York and staying near Times Square (40.7589, -73.9851).
  Find me:
  1. Hotels within 1km
  2. Italian restaurants within walking distance of the hotels
  3. Calculate walking time from the best hotel to the best restaurant
  4. Give me your top recommendation with reasoning
`);

Agent with File Operations

Save Location Research to File

const fileAgent = new Agent({
  tools: [locationSearchTool],
  allowFileOperations: true,
  model: 'claude-sonnet-4.5-20250929'
});

// Agent searches locations and saves results to JSON
const result = await fileAgent.run(`
  Search for coffee shops in downtown Seattle (47.6062, -122.3321).
  Save the top 10 results to a file called seattle_cafes.json with:
  - Name
  - Address
  - Distance from downtown
  - Any notable tags
`);

Best Practices

• Clear Tool Descriptions: Write detailed descriptions so Claude knows when to use location tools
• Structured Outputs: Return consistent JSON schemas from tool executions
• Error Handling: Wrap API calls in try-catch and return user-friendly errors
• System Prompts: Guide agent behavior with clear system instructions
• Tool Composition: Combine location tools with file ops and bash for powerful workflows
• Rate Limiting: Implement backoff for high-volume agent usage

Performance Tips

Caching Results

const cache = new Map();

const cachedLocationSearch = {
  ...locationSearchTool,
  execute: async (params) => {
    const cacheKey = JSON.stringify(params);
    if (cache.has(cacheKey)) {
      return cache.get(cacheKey);
    }
    
    const result = await locationSearchTool.execute(params);
    cache.set(cacheKey, result);
    return result;
  }
};

Parallel Tool Execution

// Agent automatically parallelizes independent tool calls
const result = await agent.run(`
  Find me:
  1. Coffee shops in Manhattan
  2. Parks in Brooklyn
  3. Museums in Queens
  
  Compare the results and tell me which borough has the most options.
`);
// Agent executes all 3 searches in parallel

Testing Agents

import { describe, it, expect } from 'vitest';

describe('Location Agent', () => {
  it('should find hotels near coordinates', async () => {
    const result = await agent.run(
      'Find hotels near 40.7589, -73.9851'
    );
    
    expect(result).toContain('hotel');
    expect(result).toContain('Times Square');
  });
  
  it('should calculate routes', async () => {
    const result = await multiToolAgent.run(
      'Calculate walking route from 40.7589,-73.9851 to 40.7614,-73.9776'
    );
    
    expect(result).toContain('km');
    expect(result).toContain('minutes');
  });
});

Deployment

Production Agent Example

import { Agent } from '@anthropic-ai/claude-agent-sdk';
import express from 'express';

const app = express();
app.use(express.json());

const agent = new Agent({
  tools: [locationSearchTool, routeCalculationTool],
  model: 'claude-sonnet-4.5-20250929'
});

app.post('/api/agent/query', async (req, res) => {
  try {
    const { message } = req.body;
    const result = await agent.run(message);
    res.json({ result });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3000, () => {
  console.log('Location agent API running on port 3000');
});

Additional Resources

• Claude Agent SDK Documentation
• Claude Agent SDK TypeScript GitHub
• Claude Agent SDK Python GitHub
• Camino AI API Reference
• Camino AI Quick Start

Pricing