Large language models can answer questions, summarise documents, write code, and interact with external systems. But building a reliable AI application requires more than sending a prompt and displaying the response.
\nA production-ready application must manage conversation history, provide relevant context, use tools safely, handle different response types, and evaluate whether the generated output is useful.
\nIn this tutorial, we’ll build ShopHelper, a customer-support assistant for an imaginary online shop. By the end, ShopHelper will be able to:
\nEach section adds one piece, so you can follow along in your own editor.
\nYou should have:
\nCreate a virtual environment and install the Anthropic Python SDK:
\npython -m venv .venv\nsource .venv/bin/activate\npip install anthropic python-dotenvOn Windows:
\n.venv\\Scripts\\activateCreate a .env file:
ANTHROPIC_API_KEY=your_api_key_hereAn API key is a secret credential. Never place it in browser JavaScript, mobile-app code, or client-side configuration. Never commit it to a repository:
\necho ".env" >> .gitignoreIf you add a web interface later, keep the key on your backend:
\nBrowser → Your backend → Claude APICreate app.py:
import os\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\nload_dotenv()\nMODEL = "claude-sonnet-5"\nclient = Anthropic(\n api_key=os.environ["ANTHROPIC_API_KEY"]\n)load_dotenv() loads the value from .env. The MODEL constant means you only need to change the model name in one place. Confirm that the model identifier is available to your account before running the example.
response = client.messages.create(\n model=MODEL,\n max_tokens=500,\n messages=[\n {\n "role": "user",\n "content": "Explain what an API is in simple terms."\n }\n ],\n)\nanswer = "".join(\n block.text\n for block in response.content\n if block.type == "text"\n)\nprint(answer)A request contains three important parts:
\nmodel selects the Claude model that handles the request. Models can differ in capability, speed, and cost.max_tokens limits the maximum amount of text Claude can generate. A smaller value can reduce latency, but Claude may stop before completing its answer.messages contains the conversation. Each message has arole andcontent . The role is usuallyuser orassistant .For example, a one-off request contains one user message. A multi-turn conversation contains earlier user and assistant messages.
\nClaude returns response.content, which is a list of typed content blocks. Common blocks include:
| Block type | Meaning |
|---|---|
text | Generated text |
tool_use | A request for your application to call a tool |
thinking | Reasoning content when enabled |
The example collects text blocks instead of assuming response.content[0] is always text.
You can inspect usage information for monitoring:
\nprint(response.usage.input_tokens)\nprint(response.usage.output_tokens)Claude doesn't automatically remember separate API requests. Send relevant history with every request:
\nmessages = [\n {\n "role": "user",\n "content": "What is your returns policy?"\n },\n {\n "role": "assistant",\n "content": "Items can be returned within 30 days."\n },\n {\n "role": "user",\n "content": "How long do I have?"\n },\n]\nresponse = client.messages.create(\n model=MODEL,\n max_tokens=300,\n messages=messages,\n)The assistant message records Claude’s earlier answer, allowing the final question to be interpreted in context.
\nA simple chat function can maintain the history:
\ndef chat(history, user_text):\n history.append({\n "role": "user",\n "content": user_text,\n })\n response = client.messages.create(\n model=MODEL,\n max_tokens=500,\n messages=history,\n )\n reply = "".join(\n block.text\n for block in response.content\n if block.type == "text"\n )\n history.append({\n "role": "assistant",\n "content": reply,\n })\n return reply\nhistory = []\nprint(chat(history, "What is your returns policy?"))\nprint(chat(history, "How long do I have?"))Each call adds the new user message, sends the complete history, and stores Claude’s response for the next turn. In production, store histories by customer or session ID.
\nUnlimited history increases input size and may make it harder for Claude to focus. One option is to retain only recent messages:
\ndef trim_history(history, max_messages=10):\n trimmed = history[-max_messages:]\n while trimmed and trimmed[0]["role"] != "user":\n trimmed.pop(0)\n return trimmedAnother option is to summarise older turns while keeping recent messages:
\ndef summarise_history(history, keep_last=6):\n old = history[:-keep_last]\n recent = history[-keep_last:]\n transcript = "\\n".join(\n f"{message['role']}: {message['content']}"\n for message in old\n )\n response = client.messages.create(\n model=MODEL,\n max_tokens=250,\n messages=[{\n "role": "user",\n "content": (\n "Summarise this conversation in under 100 words. "\n "Keep order numbers and unresolved issues.\\n\\n"\n f"<conversation>{transcript}</conversation>"\n ),\n }],\n )\n summary = "".join(\n block.text\n for block in response.content\n if block.type == "text"\n )\n return summary, recentKeep the summary as separate application state and include it as context in the next request. Don't insert it as an additional user message before recent, because that can create invalid consecutive user messages.
Sensitive information should also be redacted before storage or transmission:
\nimport re\ndef redact(text):\n return re.sub(\n r"\\b(?:\\d[ -]?){13,16}\\b",\n "[REDACTED CARD]",\n text,\n )XML-style tags are ordinary text, not special API commands. They make each part of a prompt explicit:
\nprompt = """\n<customer_reviews>\nThe product is comfortable, but the available colours are limited.\nCustomers also describe it as durable.\n</customer_reviews>\n<sales_data>\nJanuary: 120 units\nFebruary: 150 units\nMarch: 98 units\n</sales_data>\n<task>\nCompare the reviews with the sales data.\nIdentify possible relationships and state uncertainty.\n</task>\n"""Here, <customer_reviews> identifies reference material, <sales_data> identifies the data, and <task> identifies the instruction. Use similar boundaries for policies, user-generated content, examples, and output requirements.
A system prompt defines ShopHelper’s general behaviour:
\nsystem_prompt = """\nYou are ShopHelper, a friendly customer-support assistant.\nKeep answers concise and clear.\nDo not invent prices, policies, or order details.\nIf information is missing, ask for it.\n"""Pass it separately from the conversation:
\nresponse = client.messages.create(\n model=MODEL,\n max_tokens=500,\n system=system_prompt,\n messages=[\n {"role": "user", "content": "Where is my order?"}\n ],\n)Because the customer didn't provide an order number, ShopHelper should ask for one instead of guessing.
\nClaude can't directly access your database. A tool gives it a structured way to request information from your application:
\ndef get_order_status(order_id):\n orders = {\n "ORD-1001": "shipped",\n "ORD-1002": "processing",\n }\n return {\n "order_id": order_id,\n "status": orders.get(order_id, "not_found"),\n }The function accepts an order ID, looks it up, and returns predictable data. In production, the dictionary would be replaced by a database query. Claude doesn't execute the function. Your application does.
\nDescribe the function with a schema:
\ntools = [{\n "name": "get_order_status",\n "description": "Get the current status of a customer order.",\n "input_schema": {\n "type": "object",\n "properties": {\n "order_id": {\n "type": "string",\n "description": "An order ID such as ORD-1001."\n }\n },\n "required": ["order_id"],\n },\n}]Claude may return a tool_use block instead of a final answer:
type="tool_use"\nid="toolu_example"\nname="get_order_status"\ninput={"order_id": "ORD-1001"}The name identifies the function, input contains its arguments, and id is needed when returning the result. A stop_reason of "tool_use" means your application should handle the request before asking Claude to continue.
A tool-use response is a response containing the tool_use block described above.
Validate the tool name, arguments, and user permissions before execution:
\nimport re\nORDER_ID_PATTERN = re.compile(r"^ORD-\\d{4}$")\ndef validate_tool_request(name, tool_input, current_user):\n if name != "get_order_status":\n return False, "Unknown tool"\n order_id = tool_input.get("order_id")\n if not isinstance(order_id, str):\n return False, "order_id must be a string"\n if not ORDER_ID_PATTERN.fullmatch(order_id):\n return False, "Invalid order ID format"\n if order_id not in current_user["order_ids"]:\n return False, "The customer cannot access this order"\n return True, NoneA complete loop can then validate and execute the request:
\ndef run_conversation(user_text, current_user):\n messages = [{"role": "user", "content": user_text}]\n while True:\n response = client.messages.create(\n model=MODEL,\n max_tokens=500,\n system=system_prompt,\n tools=tools,\n messages=messages,\n )\n if response.stop_reason != "tool_use":\n return "".join(\n block.text\n for block in response.content\n if block.type == "text"\n )\n messages.append({\n "role": "assistant",\n "content": response.content,\n })\n results = []\n for block in response.content:\n if block.type != "tool_use":\n continue\n valid, error = validate_tool_request(\n block.name,\n block.input,\n current_user,\n )\n if valid:\n result = get_order_status(block.input["order_id"])\n results.append({\n "type": "tool_result",\n "tool_use_id": block.id,\n "content": str(result),\n })\n else:\n results.append({\n "type": "tool_result",\n "tool_use_id": block.id,\n "content": error,\n "is_error": True,\n })\n messages.append({\n "role": "user",\n "content": results,\n })The tool_use_id connects the result to the original request. The application remains responsible for authorisation and execution.
This assumption is fragile:
\nanswer = response.content[0].textIt assumes that the first block exists and is text. Instead, inspect each block:
\nfor block in response.content:\n if block.type == "text":\n print(block.text)\n elif block.type == "tool_use":\n print("Validate and execute:", block.name)\n elif block.type == "thinking":\n continue\n else:\n print("Unhandled block type:", block.type)ShopHelper displays text, validates and executes approved tool requests, doesn't display internal thinking, and logs unknown block types.
\nA workflow follows a predefined sequence:
\nReceive ticket\n↓\nExtract details\n↓\nDraft reply\n↓\nReview replydef ask(prompt, max_tokens=500):\n response = client.messages.create(\n model=MODEL,\n max_tokens=max_tokens,\n messages=[{"role": "user", "content": prompt}],\n )\n return "".join(\n block.text\n for block in response.content\n if block.type == "text"\n )\ndef handle_ticket_workflow(ticket):\n details = ask(\n f"<ticket>{ticket}</ticket>\\n"\n "<task>Extract the problem and desired outcome.</task>"\n )\n draft = ask(\n f"<details>{details}</details>\\n"\n "<task>Draft a concise support reply.</task>"\n )\n review = ask(\n f"<draft>{draft}</draft>\\n"\n "<task>List unsupported promises, or say OK.</task>"\n )\n return draft, reviewAn agent is more flexible: Claude decides whether to use a tool and what to do next. Agents still require validation and a maximum step count. The run_conversation() function above can be reused inside an agent loop.
Use workflows when the steps are known and repeatability matters. Use agents when the next action depends on the current result.
\nChaining passes each result to the next stage:
\ndef chained_reply(ticket, policy):\n draft = ask(\n f"<ticket>{ticket}</ticket>\\n"\n "<task>Draft a support reply.</task>"\n )\n issues = ask(\n f"<policy>{policy}</policy>\\n"\n f"<draft>{draft}</draft>\\n"\n "<task>List unsupported claims.</task>"\n )\n return ask(\n f"<draft>{draft}</draft>\\n"\n f"<issues>{issues}</issues>\\n"\n "<task>Rewrite the final reply.</task>"\n )Parallelisation runs independent tasks concurrently:
\nfrom concurrent.futures import ThreadPoolExecutor\ntickets = [\n "My headphones arrived broken.",\n "I was charged twice.",\n "How do I change my address?",\n]\ndef summarise(ticket):\n return ask(\n f"<ticket>{ticket}</ticket>\\n"\n "<task>Summarise in one sentence.</task>",\n max_tokens=100,\n )\nwith ThreadPoolExecutor(max_workers=3) as pool:\n summaries = list(pool.map(summarise, tickets))\ndigest = ask(\n "<summaries>\\n"\n + "\\n".join(summaries)\n + "\\n</summaries>\\n"\n "<task>Summarise today's support themes.</task>"\n)Routing classifies a request before selecting a specialised workflow:
\ndef route(ticket):\n label = ask(\n f"<ticket>{ticket}</ticket>\\n"\n "<task>Return exactly refund, delivery, or general.</task>",\n max_tokens=10,\n ).strip().lower()\n return label if label in {"refund", "delivery", "general"} else "general"Evaluator-optimizer generates, reviews, and revises an answer:
\ndef improve_reply(ticket, rounds=2):\n reply = ask(\n f"<ticket>{ticket}</ticket>\\n"\n "<task>Write a support reply.</task>"\n )\n for _ in range(rounds):\n review = ask(\n f"<reply>{reply}</reply>\\n"\n "<task>List accuracy or tone problems, or say PASS.</task>"\n )\n if review.strip().upper() == "PASS":\n break\n reply = ask(\n f"<reply>{reply}</reply>\\n"\n f"<review>{review}</review>\\n"\n "<task>Rewrite the reply.</task>"\n )\n return replyUse chaining for dependent stages, parallelisation for independent work, routing for specialised paths, and evaluator-optimizer loops when additional quality justifies extra API calls.
\nUse representative test cases:
\ntest_cases = [\n {\n "ticket": "I want a refund for broken headphones.",\n "expected": "refund",\n },\n {\n "ticket": "Where is ORD-1002?",\n "expected": "delivery",\n },\n {\n "ticket": "Do you sell gift cards?",\n "expected": "general",\n },\n]These cases cover different request types. Run the same cases after changing the system prompt, examples, model, token limit, or routing instructions:
\ndef evaluate(route_fn, cases):\n passed = 0\n for case in cases:\n result = route_fn(case["ticket"])\n if result == case["expected"]:\n passed += 1\n else:\n print("Failed:", case["ticket"], result)\n score = passed / len(cases)\n print(f"{passed}/{len(cases)} passed")\n return scoreUse code-based graders for labels and JSON. Use human or model-based graders for tone, accuracy, and helpfulness.
\nBuilding with the Claude API involves more than writing prompts. A reliable application needs structured context, managed conversation state, validated tool execution, deliberate response handling, suitable workflows, and repeatable evaluation.
\nThe goal isn't to find one perfect prompt. It's to build a system around Claude that provides the right context, limits unsafe actions, handles uncertainty, and measures whether changes improve the result.
","headings":[{"level":2,"text":"Table of Contents","id":"table-of-contents"},{"level":2,"text":"Prerequisites","id":"prerequisites"},{"level":2,"text":"How to Set Up the Project and Keep Your API Key Secure","id":"how-to-set-up-the-project-and-keep-your-api-key-secure"},{"level":2,"text":"How to Make Your First Request","id":"how-to-make-your-first-request"},{"level":2,"text":"How to Manage Conversation History","id":"how-to-manage-conversation-history"},{"level":3,"text":"How to Manage History as it Grows","id":"how-to-manage-history-as-it-grows"},{"level":2,"text":"How to Structure Prompts with Clear Boundaries","id":"how-to-structure-prompts-with-clear-boundaries"},{"level":2,"text":"How to Use a System Prompt","id":"how-to-use-a-system-prompt"},{"level":2,"text":"How to Add Tools","id":"how-to-add-tools"},{"level":2,"text":"How to Handle a Tool-Use Response","id":"how-to-handle-a-tool-use-response"},{"level":2,"text":"Claude Responses Can Contain Multiple Blocks","id":"claude-responses-can-contain-multiple-blocks"},{"level":2,"text":"Workflows vs Agents","id":"workflows-vs-agents"},{"level":2,"text":"Chaining, Parallelisation, Routing, and Evaluator-Optimizer","id":"chaining-parallelisation-routing-and-evaluator-optimizer"},{"level":2,"text":"How to Evaluate Prompt Quality","id":"how-to-evaluate-prompt-quality"},{"level":2,"text":"Conclusion","id":"conclusion"}]}}