（上篇）基于 AWS Bedrock AgentCore 构建企业级航空客服智能体 —— 基于AIDLC方法从需求分析到生产部署的完整实践

# 初始化 Bedrock 模型
model = BedrockModel(
    model_id=os.getenv("MODEL_ID", "us.anthropic.claude-3-5-sonnet-20241022-v2:0"),
    temperature=0.7,
    max_tokens=2048
)

# 创建 AgentCore App
app = BedrockAgentCoreApp()

def create_agent_with_memory(session_id: str, actor_id: str, previous_session_history: str = ""):
    """创建带 Memory 的 Agent"""

    # 创建 Session Manager（自动管理 Memory 读写）
    session_manager = None
    if MEMORY_ID:
        retrieval_config = {
            f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
            f"/preferences/{actor_id}": RetrievalConfig(top_k=5, relevance_score=0.7),
            f"/facts/{actor_id}": RetrievalConfig(top_k=10, relevance_score=0.3)
        }

        config = AgentCoreMemoryConfig(
            memory_id=MEMORY_ID,
            session_id=session_id,
            actor_id=actor_id,
            retrieval_config=retrieval_config
        )
        session_manager = AgentCoreMemorySessionManager(
            agentcore_memory_config=config,
            region_name=os.getenv("AWS_REGION", "us-east-1")
        )

    # 获取 Gateway MCP client（通过 OAuth2 认证）
    tools = []
    mcp_client = get_gateway_mcp_client()
    if mcp_client:
        tools = [mcp_client]

    # 构建增强的 system prompt（注入历史对话上下文）
    enhanced_system_prompt = AIRLINE_AGENT_SYSTEM_PROMPT
    if previous_session_history:
        enhanced_system_prompt = f"{AIRLINE_AGENT_SYSTEM_PROMPT}\n\n{previous_session_history}"

    # 创建 Agent
    agent = Agent(
        model=model,
        system_prompt=enhanced_system_prompt,
        tools=tools,
        session_manager=session_manager,
        name="AirlineCustomerServiceAgent",
        description="Professional airline customer service agent"
    )

    return agent


@app.entrypoint
def invoke(payload: dict, context=None):
    """AgentCore Runtime 调用入口"""
    prompt = payload.get("prompt", "")

    # 获取 session_id（优先从 context 获取，支持多种来源）
    session_id = (
        getattr(context, 'session_id', None) or
        BedrockAgentCoreContext.get_session_id() or
        payload.get("session_id") or
        f"session_{datetime.now().strftime('%Y%m%d%H%M%S%f')}"
    )

    # 从 JWT token 中提取 actor_id（用户唯一标识）
    actor_id = extract_actor_id_from_context(context)

    # 获取前一个 session 的对话历史（跨会话连续性）
    previous_session_history = ""
    if LOAD_PREVIOUS_SESSION and actor_id != "default_user":
        previous_session_history = get_previous_session_history(actor_id, session_id)

    # 创建 Agent 并处理请求
    agent = create_agent_with_memory(
        session_id=session_id, 
        actor_id=actor_id,
        previous_session_history=previous_session_history
    )

    result = agent(prompt)

    return {"response": str(result.output), "session_id": session_id}

src/agent/system_prompt.py
AIRLINE_AGENT_SYSTEM_PROMPT = """You are a professional customer service agent for a major airline.

IDENTITY:
- Role: Senior Customer Service Representative
- Expertise: Flight reservations, refunds, changes, and loyalty programs
- Authority: Can process refunds, changes, and fee waivers
- Memory: You have access to customer history and preferences through AgentCore Memory

MANDATORY BEHAVIORS:
1. ALWAYS verify customer identity before accessing bookings
   - Ask for: PNR (booking reference) and Last Name
   - Use verify_customer tool first

2. ALWAYS check real-time flight status for refund requests
   - Use get_flight_status tool to verify cancellations/delays

3. ALWAYS provide reference numbers for transactions
   - Transaction IDs for refunds
   - Ticket IDs for approvals
   - Confirmation numbers for changes

WORKFLOW FOR COMMON SCENARIOS:

Scenario A: Flight Cancellation Refund (IROP)
1. Greet and understand the request
2. Verify customer identity (PNR + Last Name)
3. Check flight status using get_flight_status tool
4. If flight is CANCELLED, use full_refund tool
5. Confirm transaction and timeline

Scenario B: Regular Refund Request
1. Verify customer identity
2. Get reservation details
3. Calculate refund amount
4. Use process_refund tool
5. Handle the tool response accordingly (Gateway may block high-value refunds)

Scenario C: Flight Change Request
1. Verify customer identity
2. Check loyalty tier using get_loyalty_tier tool
3. Search available flights
4. Calculate change costs
5. Use waive_change_fee tool if applicable (Gateway checks eligibility)
6. Execute booking change

AVAILABLE TOOLS (16 total):

Identity & Loyalty (2):
1. verify_customer - Verify customer identity with PNR and last name
2. get_loyalty_tier - Get customer loyalty tier and points

Flight Query (2):
3. get_flight_status - Check real-time flight status
4. search_flights - Search available flights by route and date

Refund (3):
5. calculate_refund - Calculate refund amount for a reservation
6. process_refund - Execute regular refund
7. full_refund - Execute IROP full refund for cancelled/delayed flights

Reservation & Change (5):
8. get_reservation_details - Get full reservation information
9. calculate_change_cost - Calculate change fees and fare difference
10. waive_change_fee - Waive change fee for eligible loyalty members
11. update_booking - Execute flight change
12. process_change_payment - Process payment for change fees

Approval (3):
13. submit_manual_approval - Submit refund for manual approval
14. check_approval_status - Check status of approval request
15. approve_ticket - Approve a pending ticket (demo only)

Booking (1):
16. book_flight - Book a new flight with seat and meal preferences

IMPORTANT RULES:
- Do NOT make up information or reference numbers
- Do parse JSON responses from tools carefully
- When a tool returns policy-related status, explain it to the customer appropriately
"""

# mcp-tools-server/mcp_server.py

@mcp.tool()
def calculate_change_cost(old_flight: str, new_flight: str) -> str:
    """计算改签费用"""
    old_flight_data = FLIGHTS.get(old_flight.upper())
    new_flight_data = FLIGHTS.get(new_flight.upper())

    if not old_flight_data or not new_flight_data:
        return json.dumps({"error": "Flight not found"})

    base_change_fee = 200.00  # 基础改签费
    old_fare = old_flight_data.get("fare", 180.00)
    new_fare = new_flight_data.get("fare", 180.00)
    fare_difference = max(0, new_fare - old_fare)  # 票价差（只补不退）

    return json.dumps({
        "base_change_fee": base_change_fee,
        "fare_difference": fare_difference,
        "total_without_waiver": base_change_fee + fare_difference
    })


@mcp.tool()
def waive_change_fee(pnr: str, loyalty_tier: str) -> str:
    """
    豁免改签费（仅限 Gold/Platinum 会员）

    注意：此工具的调用受 Gateway Policy 控制
    - Gateway 会验证 loyalty_tier 是否为 gold 或 platinum
    - 如果会员等级不符，Gateway 会拦截调用
    """
    reservation = RESERVATIONS.get(pnr.upper())

    if not reservation:
        return json.dumps({"error": "Reservation not found"})

    return json.dumps({
        "fee_waived": True,
        "waived_amount": 200.00,
        "reason": f"{loyalty_tier.capitalize()} member privilege",
        "pnr": pnr.upper()
    })


@mcp.tool()
def update_booking(pnr: str, new_flight: str) -> str:
    """执行改签操作"""
    reservation = RESERVATIONS.get(pnr.upper())

    if not reservation:
        return json.dumps({"error": "Reservation not found"})

    new_confirmation = f"{pnr.upper()}-{random.randint(10, 99)}"

    return json.dumps({
        "success": True,
        "new_confirmation": new_confirmation,
        "new_flight": new_flight.upper(),
        "old_flight": reservation["flight_number"]
    })

// 低于$1000的退款：允许
permit(
  principal,
  action == Action::"process_refund",
  resource
) when {
  resource.amount <= 1000
};

// 超过$1000的退款：拦截，需要人工审批
forbid(
  principal,
  action == Action::"process_refund",
  resource
) when {
  resource.amount > 1000
};

// 金卡会员改签：豁免改签费
permit(
  principal,
  action == Action::"change_flight",
  resource
) when {
  principal.member_tier == "GOLD"
};

// 普通会员改签：需要支付改签费
permit(
  principal,
  action == Action::"change_flight",
  resource
) when {
  principal.member_tier == "REGULAR" &&
  resource.fee == 50.0
};

// IROP场景（航班取消或严重延误）：自动全额退款
permit(
  principal,
  action == Action::"process_refund",
  resource
) when {
  resource.reason == "IROP" &&
  (resource.flight_status == "CANCELLED" ||
   resource.delay_minutes > 240)
};

# 三个 Namespace 分别存储不同类型的记忆
retrieval_config = {
    # 会话摘要：当前会话的对话总结
    f"/summaries/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),

    # 用户偏好：跨会话的长期偏好（如座位、餐食、时间偏好）
    f"/preferences/{actor_id}": RetrievalConfig(top_k=5, relevance_score=0.7),

    # 用户事实：客观信息（如常用航线、会员等级）
    f"/facts/{actor_id}": RetrievalConfig(top_k=10, relevance_score=0.3)
}

# agent_with_gateway.py

def get_previous_session_history(actor_id: str, current_session_id: str) -> str:
    """
    获取用户前几个 session 的对话历史，注入到 System Prompt
    实现跨会话的对话连续性
    """
    client = boto3.client('bedrock-agentcore', region_name=os.getenv("AWS_REGION"))

    # 获取用户的历史 session 列表
    sessions_response = client.list_sessions(
        memoryId=MEMORY_ID,
        actorId=actor_id,
        maxResults=MAX_PREVIOUS_SESSIONS + 1
    )

    sessions = sessions_response.get('sessionSummaries', [])

    # 排除当前 session，获取前 N 个 session
    previous_sessions = [s['sessionId'] for s in sessions 
                         if s['sessionId'] != current_session_id][:MAX_PREVIOUS_SESSIONS]

    # 加载历史对话事件
    history_lines = ["<previous_session_history>"]
    history_lines.append("The following is the conversation history from the user's previous session(s):")

    for previous_session_id in previous_sessions:
        events_response = client.list_events(
            memoryId=MEMORY_ID,
            actorId=actor_id,
            sessionId=previous_session_id,
            maxResults=MAX_PREVIOUS_EVENTS
        )

        for event in events_response.get('events', []):
            for payload_item in event.get('payload', []):
                if 'conversational' in payload_item:
                    conv = payload_item['conversational']
                    role = conv.get('role', 'unknown')
                    text = conv.get('content', {}).get('text', '')

                    if role == 'USER':
                        history_lines.append(f"User: {text}")
                    elif role == 'ASSISTANT':
                        history_lines.append(f"Agent: {text}")

    history_lines.append("Use this history to provide continuity if the user refers to previous conversations.")
    history_lines.append("</previous_session_history>")

    return "\n".join(history_lines)

# src/agent/system_prompt.py（Memory 相关部分）

"""
MEMORY CAPABILITIES:

The system has AgentCore Memory integration that provides:
- Short-term Memory (STM): Conversation history within the same session
- Long-term Memory (LTM): Customer preferences and facts across sessions

**How Memory Works:**
- Memory is automatically managed by AgentCore Memory Session Manager
- Previous session history may be provided in <previous_session_history> tags
- Customer preferences may be provided in <user_context> tags
- You do NOT need to call any special tools - memory is automatic

**How to use <previous_session_history>:**
1. If you see <previous_session_history> tags, this contains the user's conversation from their last session
2. Use this to provide continuity: "I see from our last conversation that you were asking about..."
3. Reference specific details: "Last time you mentioned booking XYZ789..."
4. Proactively offer follow-up: "Would you like to continue where we left off?"
5. Example: "Welcome back! I see from our previous conversation that you had a pending refund request for $5,150. Would you like me to check the status?"

**How to use <user_context> preferences:**
1. Read the preferences at the start of the conversation
2. Proactively mention them: "I see you prefer morning flights around 10 AM and window seats"
3. Apply them when searching/recommending: "Based on your preferences, I recommend UA100 at 08:00"
4. Highlight matching options: "UA100 has window seats available (2A, 4A)"
"""

# src/gateway/client.py

from mcp.client.streamable_http import streamablehttp_client
from strands.tools.mcp import MCPClient

# Gateway 配置（全部从环境变量读取）
GATEWAY_MCP_URL = os.environ.get("GATEWAY_MCP_URL", "")
GATEWAY_CLIENT_ID = os.environ.get("GATEWAY_CLIENT_ID", "")
GATEWAY_CLIENT_SECRET = os.environ.get("GATEWAY_CLIENT_SECRET", "")
GATEWAY_TOKEN_ENDPOINT = os.environ.get("GATEWAY_TOKEN_ENDPOINT", "")

# Token 缓存
_token_cache = {"token": None, "expires_at": None}


def get_oauth_token() -> str:
    """获取 OAuth2 访问令牌（带缓存）"""

    # 检查缓存的 token 是否有效
    if (_token_cache["token"] and 
        _token_cache["expires_at"] and 
        datetime.now() < _token_cache["expires_at"]):
        return _token_cache["token"]

    # 请求新 token
    response = httpx.post(
        GATEWAY_TOKEN_ENDPOINT,
        data={
            "grant_type": "client_credentials",
            "client_id": GATEWAY_CLIENT_ID,
            "client_secret": GATEWAY_CLIENT_SECRET,
            "scope": GATEWAY_SCOPE
        },
        headers={"Content-Type": "application/x-www-form-urlencoded"},
        timeout=30.0
    )

    data = response.json()
    token = data["access_token"]

    # 缓存 token，提前 5 分钟过期
    expires_in = data.get("expires_in", 3600) - 300
    _token_cache["token"] = token
    _token_cache["expires_at"] = datetime.now() + timedelta(seconds=expires_in)

    return token


def get_gateway_mcp_client() -> MCPClient:
    """获取配置好的 Gateway MCP 客户端"""
    access_token = get_oauth_token()

    return MCPClient(
        lambda: streamablehttp_client(
            GATEWAY_MCP_URL,
            headers={"Authorization": f"Bearer {access_token}"}
        )
    )

用户: "My flight was cancelled, I need a refund. ABC123, Smith"

Agent 执行流程:
  [1] verify_customer(pnr="ABC123", last_name="Smith")
      → {"verified": true, "user_id": "U001", "passenger_name": "John Smith"}

  [2] get_flight_status(flight_number="UA1234")
      → {"status": "CANCELLED", "cancellation_reason": "WEATHER"}

  [3] full_refund(pnr="ABC123", flight_status="CANCELLED")
      → Gateway Policy 检查: status="CANCELLED" 匹配 irop_full_refund_permit
      → Policy 决策: PERMIT（DOT 合规要求）
      → {"status": "success", "amount": 450.00, "transaction_id": "TXN-20260125-0001",
         "refund_type": "IROP_FULL_REFUND", "reason": "Flight CANCELLED - DOT compliance"}

Agent 响应:
  "I'm very sorry to hear about your flight cancellation, Mr. Smith. I've processed 
   a full refund of $450.00 to your Visa-4321. Transaction ID: TXN-20260125-0001. 
   The refund will be reflected in 3-5 business days."

用户: "I need to cancel my international business class ticket and get a refund. 
       XYZ789, Johnson"

Agent 执行流程:
  [1] verify_customer(pnr="XYZ789", last_name="Johnson")
      → {"verified": true, "user_id": "U002", "passenger_name": "Jane Johnson"}

  [2] get_reservation_details(pnr="XYZ789")
      → {"amount_paid": 5500.00, "cabin": "Business", "route": "JFK-LHR"}

  [3] calculate_refund(pnr="XYZ789")
      → {"gross_amount": 5500.00, "cancellation_fee": 350.00, "net_refund": 5150.00}

  [4] process_refund(pnr="XYZ789", amount=5150)
      → Gateway Policy 检查: amount=5150 > threshold=1000
      → Policy 决策: BLOCK（high_value_refund_protection）
      → 返回 policy_violation，Agent 自动转入审批流程

  [5] submit_manual_approval(pnr="XYZ789", amount=5150, reason="Customer requested cancellation")
      → {"ticket_id": "APPR-20260125-001", "status": "PENDING", 
         "estimated_time": "2 hours", "priority": "high"}

Agent 响应:
  "Ms. Johnson, your refund request for $5,150.00 exceeds our automatic approval 
   threshold. I've submitted it for supervisor review. Your approval ticket ID is 
   APPR-20260125-001, and you should receive a decision within 2 hours. Is there 
   anything else I can help you with?"

用户: "I need to change my flight from Monday to Tuesday. DEF456, Williams"

Agent 执行流程:
  [1] verify_customer(pnr="DEF456", last_name="Williams")
      → {"verified": true, "user_id": "U003", "passenger_name": "Sarah Williams"}

  [2] get_loyalty_tier(user_id="U003")
      → {"loyalty_tier": "gold", "tier_points": 50000}

  [3] get_reservation_details(pnr="DEF456")
      → {"flight_number": "UA5679", "route": "SFO-LAX", "departure_date": "2026-01-27"}

  [4] search_flights(origin="SFO", destination="LAX", date="2026-01-28")
      → {"flights": [
           {"flight_number": "UA5680", "time": "10:00", "fare": 180.00},
           {"flight_number": "UA5682", "time": "14:00", "fare": 180.00},
           {"flight_number": "UA5684", "time": "18:00", "fare": 210.00}
         ]}

用户: "I'll take the 10:00 AM flight."

  [5] calculate_change_cost(old_flight="UA5679", new_flight="UA5680")
      → {"base_change_fee": 200.00, "fare_difference": 0, "total_without_waiver": 200.00}

  [6] waive_change_fee(pnr="DEF456", loyalty_tier="gold")
      → Gateway Policy 检查: loyalty_tier="gold" ∈ eligible_tiers
      → Policy 决策: PERMIT（loyalty_change_fee_waiver）
      → {"fee_waived": true, "waived_amount": 200.00, "reason": "Gold member privilege"}

  [7] update_booking(pnr="DEF456", new_flight="UA5680")
      → {"success": true, "new_confirmation": "DEF456-42", "new_flight": "UA5680"}

Agent 响应:
  "Great choice, Ms. Williams! As a valued Gold member, I've waived the $200 change 
   fee for you. Your flight has been changed to UA5680 departing at 10:00 AM on 
   Tuesday. Your new confirmation number is DEF456-42."

[第 1 次会话]
用户: "我喜欢靠窗座位"
Agent: [写入 Memory A LTM] → 存储用户偏好

[第 2 次会话，3 天后]
用户: "帮我订张票"
Agent: [从 Memory A LTM 读取] → 检索到"喜欢靠窗"
       响应: "为您选择了靠窗座位"

AIDLC 验证: ✓ No Duplication（Memory A 是唯一数据源）

[延续场景 B 的会话]

用户: "What's the status of my refund approval?"

Agent 执行流程:
  → Memory STM 检索: 当前会话中存在 ticket_id="APPR-20260125-001"

  [1] check_approval_status(ticket_id="APPR-20260125-001")
      → {"ticket_id": "APPR-20260125-001", "status": "PENDING", 
         "submitted_at": "2026-01-25T10:30:00", "estimated_time": "2 hours"}

Agent 响应:
  "Your refund approval (APPR-20260125-001) is still pending review. It was 
   submitted about 30 minutes ago, and you should hear back within the next 
   1.5 hours. I'll make sure to notify you once it's approved."

[Session 1 - 首次预订]
用户: "I'd like to book a business class ticket from SFO to NYC for Feb 4th. 
       I prefer morning flights around 10 AM and window seats."

Agent 执行流程:
  [1] search_flights(origin="SFO", destination="NYC", date="2026-02-04")
  [2] book_flight(user_id="U005", flight_number="UA100", cabin="Business", seat="2A")
      → {"pnr": "EMI001", "seat": "2A", "fare": 1200.00}

  → Memory LTM 自动提取并存储用户偏好:
    - /preferences/U005: "prefers morning flights around 10 AM"
    - /preferences/U005: "prefers window seats"

---

[Session 2 - 3 天后的新会话]
用户: "I need to book another flight, NYC to LA on Feb 10th"

Agent 执行流程:
  → Memory LTM 检索: /preferences/U005
  → 检索结果注入 <user_context>:
    "User preferences: morning flights around 10 AM, window seats"

  [1] search_flights(origin="NYC", destination="LAX", date="2026-02-10")
      → {"flights": [
           {"flight_number": "UA401", "time": "08:00", "fare": 320.00},
           {"flight_number": "UA403", "time": "10:15", "fare": 350.00},  ← 最匹配偏好
           {"flight_number": "UA405", "time": "14:30", "fare": 380.00},
           {"flight_number": "UA407", "time": "18:00", "fare": 290.00}
         ]}

Agent 响应:
  "Welcome back, Ms. Davis! I see you prefer morning flights around 10 AM and 
   window seats. Based on your preferences, I recommend UA403 departing at 10:15 AM 
   - it's closest to your preferred time and has window seats available (10A, 11A). 
   Would you like me to book this flight for you?"