Android Agent SDK 最后更新时间: 2026年08月27日

一、SDK 概述

1.1 产品介绍

AMap LLM Agent SDK 是阿里巴巴高德地图团队开发的AI智能助手SDK，集成了大语言模型能力，为开发者提供自然语言交互的地图服务。SDK支持语音指令识别、智能路径规划、POI搜索、实时导航等功能。

1.2 核心特性

• 智能意图理解：准确识别用户意图
• 多场景支持：涵盖出行前、行中、搜索等场景
• 跨端同步：支持与高德APP数据同步

二、环境准备与集成

2.1 依赖配置

在 build.gradle 文件中添加依赖：

dependencies {
    // LLM Agent SDK
    implementation 'com.amap.lbs.client:amap-agent:1.1.41'
}

三、快速开始

3.1 Application 初始化

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // 设置API Key - 必须在使用其他API前调用
        AMapApi.setApiKey(this, "your_amap_api_key");
        
        // 设置隐私政策同意状态
        NaviSetting.updatePrivacyShow(this, true, true);
        NaviSetting.updatePrivacyAgree(this, true);
    }
}

3.2 基础初始化流程

public class MainActivity extends AppCompatActivity {
    private static final String TAG = "MainActivity";
    
    private AMapApi mAMapApi;
    private AMapContext mAMapContext;
    private AMapNaviEnv mAMapNaviEnv;
    
    // 高德导航相关
    private AMapNavi mAMapNavi;
    private AMapNaviView mAMapNaviView;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // 初始化导航组件
        initMapNavi(savedInstanceState);
        
        // 初始化SDK
        initAMapApi();
    }
    
    private void initMapNavi(Bundle savedInstanceState) {
        // 获取导航实例
        mAMapNavi = AMapNavi.getInstance(getApplicationContext());
        
        // 初始化导航视图
        mAMapNaviView = findViewById(R.id.navi_view);
        mAMapNaviView.onCreate(savedInstanceState);
        mAMapNaviView.setAMapNaviViewListener(mNaviViewListener);
    }
    
    private void initAMapApi() {
        // 1. 创建API实例
        mAMapApi = AMapApi.create();
        
        // 2. 创建上下文
        mAMapContext = new AMapContext(this);
        
        // 3. 配置导航环境
        setupNavigationEnvironment();
        
        // 4. 配置日志（可选）
        setupLogger();
        
        // 5. 初始化SDK
        mAMapApi.init(mAMapContext);
        
        // 6. 配置各客户端
        setupClients();
        
        Log.i(TAG, "AMap LLM Agent SDK initialized, version: " + mAMapApi.getVersion());
    }
}

四、核心组件详解

4.1 AMapContext 上下文配置

private void setupNavigationEnvironment() {
    mAMapNaviEnv = new AMapNaviEnv();
    
    // 设置常用位置
    setupCommonLocations();
    
    // 设置导航类型
    mAMapNaviEnv.transportType = TransportType.Drive; // 驾车导航
    
    // 设置车辆信息
    setupCarInfo();
    
    // 设置路径偏好
    setupRoutePreferences();
    
    // 绑定导航实例
    mAMapNaviEnv.amapNavi = mAMapNavi;
    mAMapNaviEnv.amapNaviView = mAMapNaviView;
    
    // 应用配置
    mAMapContext.setAMapNaviEnv(mAMapNaviEnv);
}

private void setupCommonLocations() {
    // 家的位置
    LatLng homeLatLng = new LatLng(39.904200, 116.407396); // 天安门坐标示例
    Poi homePoi = new Poi("我的家", homeLatLng, "HOME_POI_ID");
    mAMapNaviEnv.homeLocation = homePoi;
    
    // 公司位置
    LatLng workLatLng = new LatLng(40.002577, 116.489854);
    Poi workPoi = new Poi("我的公司", workLatLng, "WORK_POI_ID");
    mAMapNaviEnv.workLocation = workPoi;
}

private void setupCarInfo() {
    AMapCarInfo carInfo = new AMapCarInfo();
    carInfo.setCarNumber("京A88888");        // 车牌号
    carInfo.setCarType("小型汽车");           // 车辆类型
    mAMapNaviEnv.amapCarInfo = carInfo;
}

private void setupRoutePreferences() {
    mAMapNaviEnv.avoidCongestion = true;     // 躲避拥堵
    mAMapNaviEnv.avoidHighway = false;       // 不躲避高速
    mAMapNaviEnv.avoidCost = false;          // 不躲避收费
    mAMapNaviEnv.prioritiseHighway = false;   // 不优先高速
}

private void setupLogger() {
    mAMapContext.setLogger(new ILogger() {
        @Override
        public void onLog(int level, String msg) {
            switch (level) {
                case LOG_LEVEL_DEBUG:
                    Log.d(TAG, msg);
                    break;
                case LOG_LEVEL_INFO:
                    Log.i(TAG, msg);
                    break;
                case LOG_LEVEL_WARN:
                    Log.w(TAG, msg);
                    break;
                case LOG_LEVEL_ERROR:
                    Log.e(TAG, msg);
                    break;
                case LOG_LEVEL_FATAL:
                    Log.wtf(TAG, msg);
                    break;
                case LOG_LEVEL_TRACK:
                    // 性能埋点日志
                    Log.i(TAG, "[TRACK] " + msg);
                    break;
            }
        }
    });
    
    // 可选：启用多路径发送
    mAMapContext.setSendMultiPath(true);
}

4.2 AgentClient - AI助手客户端

AgentClient 是SDK的核心组件，负责处理自然语言输入并返回相应的操作结果。

4.2.1 基础配置

private void setupAgentClient() {
    AgentClient agentClient = mAMapApi.getAgentClient();
    
    // 设置查询结果回调
    agentClient.setAgentCallback(mAgentCallback);
    
    // 设置命令执行目标
    // AMAP_SDK: 命令在当前应用的SDK中执行
    // AMAP_APP: 命令发送到高德APP执行
    agentClient.setAgentCommandDestination(AgentClient.AgentCommandDestination.AMAP_SDK);
}

private final AMapAgentCallback mAgentCallback = new AMapAgentCallback() {
    @Override
    public void onQueryResult(AMapAgentQueryResult result) {
        handleAgentQueryResult(result);
    }
};

4.3 NaviClient - 导航客户端

NaviClient 负责管理导航相关的功能，包括导航信息获取、导航控制等。

4.3.1 导航配置

private void setupNaviClient() {
    NaviClient naviClient = mAMapApi.getNaviClient();
    
    // 配置导航环境
    naviClient.configNaviEnv(mAMapNaviEnv);
    
    // 设置导航信息回调
    naviClient.setNaviInfoCallback(mNaviInfoCallback);
    
    // 设置位置更新频率（毫秒）
    naviClient.setLocationInfoInterval(1000);
    
    Log.i(TAG, "NaviClient configured");
}

private final AMapNaviInfoCallback mNaviInfoCallback = new AMapNaviInfoCallback() {
    @Override
    public void onNaviInfo(NaviInfo info) {
        handleNaviInfo(info);
    }
};

4.4 LinkClient - 链路客户端

详见：AmapLinkClient API

LinkClient 负责与高德APP的通信，实现数据同步和远程控制。

4.4.1 链路配置

private void setupLinkClient() {
    LinkClient linkClient = mAMapApi.getLinkClient();
    
    // 设置链接状态回调
    linkClient.setLinkStateCallback(mLinkStateCallback);
    
    // 设置导航信息回调
    linkClient.setNaviInfoCallback(mLinkNaviInfoCallback);
    
    // 设置打车信息回调
    linkClient.setTaxiInfoCallback(mTaxiInfoCallback);
    
    // 设置路线组回调
    linkClient.addNaviRouteGroupCallback(mRouteGroupCallback);
    
    // 配置自动重连
    setupAutoReconnect();
    
    // 连接服务器
    linkClient.connectLinkServer();
}

private void setupAutoReconnect() {
    // 启用自动重连，最大尝试次数100次，间隔2秒
    mAMapApi.getLinkClient().setReconnectConfig(true, 100, 2);
}

4.4.2 链路状态管理

private final AMapLinkStateCallback mLinkStateCallback = new AMapLinkStateCallback() {
    @Override
    public void onLinkState(LinkState state) {
        handleLinkStateChange(state);
    }
    
    @Override
    public void onLinkError(int errorCode, String errorMessage) {
        handleLinkError(errorCode, errorMessage);
    }
};

private void handleLinkStateChange(AMapLinkStateCallback.LinkState state) {
    switch (state) {
        case CONNECTED:
            Log.i(TAG, "Link connected successfully");
            onLinkConnected();
            break;
        case DISCONNECTED:
            Log.w(TAG, "Link disconnected");
            onLinkDisconnected();
            break;
    }
}

private void onLinkConnected() {
    // 连接成功后的处理
    updateUIConnectionStatus(true);
    
    // 可以开始发送数据
    if (mAMapApi.getAgentClient() != null) {
        // 切换到APP模式
        mAMapApi.getAgentClient().setAgentCommandDestination(
            AgentClient.AgentCommandDestination.AMAP_APP);
    }
}

private void onLinkDisconnected() {
    // 断开连接后的处理
    updateUIConnectionStatus(false);
    
    // 切换回SDK模式
    if (mAMapApi.getAgentClient() != null) {
        mAMapApi.getAgentClient().setAgentCommandDestination(
            AgentClient.AgentCommandDestination.AMAP_SDK);
    }
}

private void handleLinkError(int errorCode, String errorMessage) {
    Log.e(TAG, String.format("Link error: %d - %s", errorCode, errorMessage));
    
    // 根据错误码进行相应处理
    switch (errorCode) {
        case -1001: // 网络连接失败
            showToast("网络连接失败，请检查网络设置");
            break;
        case -1002: // 认证失败
            showToast("服务认证失败");
            break;
        default:
            showToast("连接异常: " + errorMessage);
            break;
    }
}

4.4.3 打车信息处理

private final AMapTaxiInfoCallback mTaxiInfoCallback = new AMapTaxiInfoCallback() {
    @Override
    public void onTaxiReceived(TaxiInfo info) {
        handleTaxiInfo(info);
    }
};

private void handleTaxiInfo(TaxiInfo taxiInfo) {
    Log.i(TAG, "TaxiInfo received: " + taxiInfo.toString());
    
    // 解析打车状态
    TaxiState state = parseTaxiState(taxiInfo.getState());
    
    // 更新UI显示
    updateTaxiUI(taxiInfo, state);
    
    // 根据状态执行相应操作
    handleTaxiStateChange(taxiInfo, state);
}

private TaxiState parseTaxiState(int stateCode) {
    switch (stateCode) {
        case 101: return TaxiState.DISPATCHING;
        case 102: return TaxiState.TIMEOUT_NO_RESPONSE;
        case 103: return TaxiState.DRIVER_ACCEPTED;
        case 104: return TaxiState.DRIVER_ARRIVED;
        case 105: return TaxiState.IN_TRIP;
        case 106: return TaxiState.TRIP_ENDED_PENDING_PAYMENT;
        case 107: return TaxiState.DRIVER_CANCELLED;
        case 108: return TaxiState.ORDER_REASSIGNED;
        case 109: return TaxiState.PASSENGER_CANCELLED;
        case 110: return TaxiState.COMPANY_CANCELLED;
        case 111: return TaxiState.PASSENGER_CANCELLED_WITH_FEE;
        case 112: return TaxiState.TRIP_COMPLETED;
        case 113: return TaxiState.ORDER_CLOSED_BY_SERVICE;
        default: return TaxiState.UNKNOWN;
    }
}

public enum TaxiState {
    DISPATCHING("正在派单"),
    TIMEOUT_NO_RESPONSE("超时无应答"),
    DRIVER_ACCEPTED("司机接单"),
    DRIVER_ARRIVED("司机到达"),
    IN_TRIP("行程中"),
    TRIP_ENDED_PENDING_PAYMENT("行程结束（待支付）"),
    DRIVER_CANCELLED("司机取消"),
    ORDER_REASSIGNED("订单改派"),
    PASSENGER_CANCELLED("乘客取消"),
    COMPANY_CANCELLED("订单被运营公司取消"),
    PASSENGER_CANCELLED_WITH_FEE("乘客取消，且有取消费用"),
    TRIP_COMPLETED("行程结束（支付完成）"),
    ORDER_CLOSED_BY_SERVICE("行程关单（客服）"),
    UNKNOWN("未知状态");
    
    private final String description;
    
    TaxiState(String description) {
        this.description = description;
    }
    
    public String getDescription() {
        return description;
    }
}

private void updateTaxiUI(TaxiInfo taxiInfo, TaxiState state) {
    runOnUiThread(() -> {
        // 更新标题和副标题
        updateTaxiTitle(taxiInfo.getTitle(), taxiInfo.getSubTitle());
        
        // 更新车辆信息
        updateVehicleInfo(taxiInfo);
        
        // 更新行程信息
        updateTripInfo(taxiInfo);
        
        // 更新状态显示
        updateStateDisplay(state);
    });
}

private void updateVehicleInfo(TaxiInfo taxiInfo) {
    String vehicleInfo = String.format("%s %s %s", 
            taxiInfo.getCarType(), 
            taxiInfo.getColor(), 
            taxiInfo.getLicensePlate());
    
    // 更新车辆信息显示
    TextView vehicleInfoView = findViewById(R.id.tv_vehicle_info);
    if (vehicleInfoView != null) {
        vehicleInfoView.setText(vehicleInfo);
    }
    
    // 加载车辆图片
    if (!TextUtils.isEmpty(taxiInfo.getPictureUrl())) {
        loadVehicleImage(taxiInfo.getPictureUrl());
    }
}

4.4.4 agent sdk直接使用导航能力

直接设置起点终点设置导航能力，导航数据支持投屏到 rtos sdk

Demo

五、完整应用示例

5.1 完整的Activity实现

代码示例

5.2 自定义Logger实现

public class CustomLogger implements ILogger {
    private static final String TAG = "AMapLLMAgent";
    
    @Override
    public void onLog(int level, String msg) {
        switch (level) {
            case LOG_LEVEL_DEBUG:
                if (BuildConfig.DEBUG) {
                    Log.d(TAG, msg);
                }
                break;
            case LOG_LEVEL_INFO:
                Log.i(TAG, msg);
                break;
            case LOG_LEVEL_WARN:
                Log.w(TAG, msg);
                break;
            case LOG_LEVEL_ERROR:
                Log.e(TAG, msg);
                // 可以在这里上报错误日志到服务器
                break;
            case LOG_LEVEL_FATAL:
                Log.wtf(TAG, msg);
                // 致命错误，可能需要特殊处理
                break;
            case LOG_LEVEL_TRACK:
                // 性能埋点日志
                handlePerformanceLog(msg);
                break;
        }
    }
    
    private void handlePerformanceLog(String msg) {
        // 处理性能埋点日志
        // 可以上报到性能监控系统
        Log.i(TAG, "[PERFORMANCE] " + msg);
    }
}

六、常见问题解答

6.1 初始化问题

Q: SDK初始化失败怎么办？

A: 检查以下几点：

1. 确认API Key是否正确设置
2. 检查网络权限是否授予
3. 确认高德地图SDK版本兼容性
4. 查看日志中的具体错误信息

// 初始化检查
private boolean checkInitialization() {
    // 检查API Key
    if (TextUtils.isEmpty(getApiKey())) {
        Log.e(TAG, "API Key not set");
        return false;
    }
    
    // 检查网络权限
    if (!hasNetworkPermission()) {
        Log.e(TAG, "Network permission not granted");
        return false;
    }
    
    // 检查依赖库
    if (!checkDependencies()) {
        Log.e(TAG, "Required dependencies missing");
        return false;
    }
    
    return true;
}

6.2 导航问题

Q: 导航无法开始或者导航数据异常？

A:

1. 确认定位权限已授予且定位服务正常
2. 检查起终点坐标是否有效
3. 确认网络连接正常
4. 检查AMapNaviEnv配置是否正确

// 导航问题诊断
private void diagnoseNavigationIssue() {
    // 检查定位状态
    if (!isLocationEnabled()) {
        Log.e(TAG, "Location service disabled");
        return;
    }
    
    // 检查起终点
    if (!isValidRoute()) {
        Log.e(TAG, "Invalid route points");
        return;
    }
    
    // 检查导航配置
    if (mAMapNaviEnv.amapNavi == null) {
        Log.e(TAG, "AMapNavi instance not set");
        return;
    }
}

6.3 查询问题

Q: Agent查询没有返回结果或返回错误？

A:

1. 检查查询文本格式是否正确
2. 确认当前场景状态是否合适
3. 检查网络连接
4. 查看具体的错误码和错误信息

// 查询问题诊断
private void diagnoseQueryIssue(AMapAgentQueryResult result) {
    Log.d(TAG, "Query diagnosis:");
    Log.d(TAG, "Error code: " + result.errorCode);
    Log.d(TAG, "Error message: " + result.errorMessage);
    Log.d(TAG, "Session ID: " + result.sessionId);
    Log.d(TAG, "Action type: " + result.actionType);
    Log.d(TAG, "State type: " + result.stateType);
    
    // 根据错误码给出建议
    switch (result.errorCode) {
        case AMapConstants.ERROR_CODE_ILLEGAL_STATUS_STR:
            Log.w(TAG, "Suggestion: Reset agent scene or status");
            break;
        case AMapConstants.ERROR_CODE_HOME_NOT_SET:
            Log.w(TAG, "Suggestion: Set home location in AMapNaviEnv");
            break;
        // ... 其他错误码处理
    }
}

6.4 性能问题

Q: 应用运行缓慢或内存占用过高？

A:

1. 合理设置定位频率
2. 及时释放大对象和回调
3. 使用异步处理避免阻塞主线程
4. 定期清理缓存数据