Claude Architect · 课时

对话模式与代理式工具

多轮记忆、指令持久化和安全工具。

对话模式与代理式工具 是 CoddyKit 上的免费 Claude Architect 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 Claude Architect 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Claude Architect 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

The Stateless Truth

Scenario 7 of the exam is Conversational AI Architecture Patterns. The first thing it tests is whether you understand that the Claude API is stateless: the model keeps no memory between requests.

Every turn you send the full message history in the messages array. "Memory" in a conversational app is something you engineer client-side, not a server session the model holds for you.

system carries persistent instructions
messages carries the entire turn-by-turn history, every request

import anthropic

client = anthropic.Anthropic()

# Memory = the list YOU maintain and resend each turn
history = [
    {"role": "user", "content": "My order id is 8842."},
    {"role": "assistant", "content": "Got it, order 8842."},
    {"role": "user", "content": "When does it ship?"},
]

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system="You are a concise support agent.",
    messages=history,  # FULL history, every single turn
)

Instruction Persistence Lives in system

In multi-turn chat, instructions that must hold for the entire session belong in the system field, not buried in a user turn 20 messages ago.

Why this matters: models exhibit lost-in-the-middle behavior, attending more to the start and end of the context than the middle. An instruction wedged in turn 7 of a 40-turn chat is the easiest thing for the model to drift away from.

The system prompt is re-supplied verbatim on every request, so it is the most reliable home for persistent rules: tone, role, refusal policy, output constraints.

Reading the Stop Reason

Conversational turns end on a stop_reason. You drive your control flow off this signal, never by scanning the assistant's text for words like "done" or "finished."

end_turn — the model completed its reply
tool_use — the model wants a tool run before continuing
max_tokens — output was truncated
stop_sequence — a configured stop sequence fired

Parsing text for completion signals is a classic exam anti-pattern and almost always a wrong answer.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    system=SYSTEM,
    messages=history,
    tools=TOOLS,
)

if resp.stop_reason == "tool_use":
    run_tools_and_append(resp, history)   # then loop again
elif resp.stop_reason == "end_turn":
    deliver(resp)                         # turn is complete
elif resp.stop_reason == "max_tokens":
    handle_truncation(resp)               # continue / raise budget

The Agentic Loop

Agentic tools turn a chat into an actor. The loop is fixed and simple:

send the request
inspect stop_reason
if tool_use: run the tool(s), append the results to history, send again
repeat until end_turn

Decisions are model-driven. An iteration cap is a safety net to prevent runaway loops — never your primary stop mechanism. You terminate on the stop reason; the cap only catches pathological cases.

MAX_ITERS = 10  # SAFETY NET only, not the real stop condition

for _ in range(MAX_ITERS):
    resp = client.messages.create(
        model="claude-sonnet-4-5", max_tokens=1024,
        system=SYSTEM, messages=history, tools=TOOLS,
    )
    history.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        break  # end_turn -> we are genuinely done

    results = execute_tool_calls(resp.content)
    history.append({"role": "user", "content": results})

Tool Results Re-enter as Context

When you run a tool, its result is appended back to messages as a tool_result block carrying the matching tool_use_id. The model reads that result on the next request and continues reasoning.

Reliability tip from the exam: trim verbose tool output to the relevant fields before appending. Dumping a 5,000-token raw API payload into history wastes the window, worsens lost-in-the-middle, and dilutes attention. Keep the fields the model actually needs to act.

Descriptions Select Tools

For safe agentic tools, the description is the primary selection mechanism — not the tool name. The model routes by reading descriptions, so write them like a contract:

purpose — what it does and when to use it
return values — what comes back
input formats with examples
edge cases and applicability boundaries

Overlapping or ambiguous descriptions cause misrouting. Aim for 4-5 tools per agent; past ~18 tools, selection reliability degrades sharply. Scope tools tightly to the role.

lookup_order = {
    "name": "lookup_order",
    "description": (
        "Fetch the status of ONE order by its numeric id. "
        "Returns {order_id, status, ships_on}. "
        "Input: order_id as an integer, e.g. 8842. "
        "Use ONLY after the customer identity is verified. "
        "Returns an empty result (not an error) if the id does not exist."
    ),
    "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "integer"}},
        "required": ["order_id"],
    },
}

Steering with tool_choice

tool_choice controls whether and how the model uses tools on a given turn:

"auto" — the model decides between answering in text or calling a tool (the conversational default)
"any" — the model must call some tool; this guarantees structured output
{"type":"tool","name":"X"} — force a specific tool

In open conversation you usually want "auto" so Claude can chat or act as appropriate. Reach for "any" or a forced tool when you need a structured, schema-validated result rather than free text.

# Conversational default: let Claude talk OR act
resp = client.messages.create(
    model="claude-sonnet-4-5", max_tokens=1024,
    system=SYSTEM, messages=history, tools=TOOLS,
    tool_choice={"type": "auto"},
)

# Force a structured extraction instead of prose
resp = client.messages.create(
    model="claude-sonnet-4-5", max_tokens=1024,
    system=SYSTEM, messages=history, tools=[extract_tool],
    tool_choice={"type": "any"},
)

Handling Ambiguous Input

Real conversations are messy. When the user's request is ambiguous, the safe pattern is to ask for more identifiers — never guess.

Classic exam case: a lookup returns multiple customer matches. The correct behavior is to request a disambiguating identifier (email, order id), not to silently pick the first row. Guessing risks acting on the wrong account.

For emotional or frustrated users the pattern is: acknowledge the emotion, propose a concrete solution, and escalate only if the request is reiterated.

Safe Tools: Preconditions and Hooks

"Safe tools" means a sensitive action cannot fire without its guarantees met. Two layers do this:

Programmatic preconditions — e.g. block process_refund until get_customer returns a verified id. This is a deterministic guarantee prompt guidance cannot give.
Hooks — PostToolUse intercepts results before the model sees them; outgoing-call hooks block policy-violating actions (e.g. refund > $500).

Hooks are 100% deterministic; prompts are ~90% probabilistic. Enforce critical rules with hooks/preconditions whenever failure has financial, legal, or safety consequences. Enforcing such rules with prompts alone is an anti-pattern.

def process_refund(amount, customer):
    # Deterministic precondition — not a polite prompt request
    if not customer.get("verified_id"):
        raise PermissionError("Identity not verified")
    if amount > 500:
        # Out-of-prompt enforcement; hook blocks this path too
        return escalate_to_human(reason="refund_over_limit",
                                 amount=amount)
    return issue_refund(customer["id"], amount)

Structured Errors Over Generic Failures

An agent recovers only as well as its errors let it. A generic "Operation failed" blocks recovery; a structured error enables intelligent routing.

Distinguish an access failure (maybe retry) from a valid empty result (no matches — do not retry). Structured fields to surface:

errorCategory — transient / validation / business / permission
isRetryable
attempted_query and any partial_results

Recover transient faults locally in the subagent; escalate non-recoverable failures with partial results. Never silently suppress an error, and never abort the whole conversation over one failed tool call.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Order service timed out",
  "attempted_query": {"order_id": 8842},
  "partial_results": []
}

Keeping Long Conversations Reliable

As a chat grows, you must manage the context window without losing facts. Progressive summarization compresses old turns — but it makes numbers, percentages, and dates vague.

The fix: pull transactional facts (order ids, amounts, dates, verified identity) into a separate "case facts" block kept verbatim, outside the summary. Summarize the chatter; never summarize the facts the agent must act on.

Combined with trimming verbose tool output and placing persistent rules in system, this keeps multi-turn agents accurate across long sessions.

Quick Check: Stopping the Agentic Loop

A scenario-based decision from Scenario 8 (Agentic AI Tools).

Recap: Conversational Patterns & Agentic Tools

Lock these in for the exam:

Stateless model — you resend full messages history every turn; "memory" is engineered client-side.
Persistent instructions live in system; mid-history rules get lost in the middle.
Stop reasons drive control flow — loop on tool_use, finish on end_turn; never parse text for "done".
Caps are safety nets, not the primary stop.
Tool descriptions (not names) select tools; 4-5 per agent, scoped to role.
tool_choice: auto to chat-or-act, any to guarantee structured output, forced for a specific tool.
Ambiguity → ask for more identifiers, never guess.
Safe tools = preconditions + hooks (deterministic) for financial/legal/safety rules — not prompts alone.
Structured errors enable recovery; keep case facts verbatim outside summaries.

常见问题解答

「对话模式与代理式工具」课时是免费的吗？

是的 — 「对话模式与代理式工具」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Claude Architect 课程的其余内容，请升级到 CoddyKit PRO。 Claude Architect 课程共包含 4 节课。

「对话模式与代理式工具」这节课中我会学到什么？

多轮记忆、指令持久化和安全工具。你通过在浏览器中直接运行的动手代码来练习 Claude Architect，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 Claude Architect 需要有经验吗？

无需任何先前经验。CoddyKit 上的 Claude Architect 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「对话模式与代理式工具」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 Claude Architect 课中编写并运行代码吗？

能。每节 Claude Architect 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 Claude Architect