CertSafari
    Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards· Lessons

    Domain 2 · Lesson 5/24

    Claude application boundaries: surfaces, sessions and schemas

    Application Boundary and Surface Behavior

    19 min read
    5% of exam
    9 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Explain why an instruction that works on one Claude surface (Claude Code, the Agent SDK, the Messages API) is ignored on another, and move it to where that surface reads it
    • Pick a conversation-state design (a resent history, a beta message thread, or an Agent SDK continue, resume or fork) that fits a stated requirement
    • Identify what content leaves the application on each request, and what the API keeps afterwards
    • Choose between JSON outputs, strict tool use and prompting alone for a schema requirement, and check model IDs and feature availability before building on a cloud platform

    Key concept

    The request is the boundary — Claude only sees what the request carries. On the Messages API that means your system prompt, your tool definitions and the messages you send. On Claude Code and the Agent SDK it also includes whatever files that runtime is configured to load. Every design question in this lesson comes down to which content crosses into the request, and who puts it there.

    1.Where each surface gets its instructions

    The same model reads instructions from different places depending on the surface that calls it. On the Messages API the instructions come from what the request carries. When you pass tools, the API builds one system prompt from the tool definitions, the tool configuration and the system text you supplied. Nothing outside the request reaches the model: no repository files, no editor state, no settings folder.

    Claude Code is a runtime that reads a project from disk. A repository's CLAUDE.md, its .claude/settings.json and its rules files are things Claude Code loads, not things the model knows about. Suppose a team tunes prompts in Claude Code while CLAUDE.md says to format ticket references as TCK-<number>. They then send the same user prompts from a backend through the Messages API, and the rule has disappeared. Nothing is wrong with the model: the rule just never crossed into the request. Put the rule into the system parameter itself. Passing a file path there doesn't help, because the API reads the text it receives, not files that text names.

    State the rule in full when you move it. A model reading a bare system prompt has no other context to fall back on, so the prompt should spell out the format and, ideally, why it matters. A one-sentence role in system already shifts behaviour and tone.

    The Agent SDK sits between these two. It can load Claude Code's filesystem configuration, but only from the sources listed in its settingSources option. The project source loads the project settings.json and hooks, the project CLAUDE.md and .claude/rules/*.md, and project skills, commands and subagents. Paths are resolved from the working directory. Settings and hooks come from <cwd>/.claude/, and CLAUDE.md and rules from <cwd> and each of its parent directories. The user source reads from ~/.claude/, which is a separate scope that a server has no reason to copy from a laptop.

    Which settings source loads which Claude Code files in the Agent SDK
    settingSources valueWhat it loadsWhere it looks
    projectProject settings.json and hooks; project CLAUDE.md and .claude/rules/*.md; project skills, commands, subagents<cwd>/.claude/ for settings and hooks; <cwd> and every parent directory for CLAUDE.md and rules
    userUser settings.json; user CLAUDE.md and ~/.claude/rules/*.md; user skills, commands, subagents~/.claude/
    localCLAUDE.local.md, .claude/settings.local.json<cwd>/.claude/ for settings.local.json; <cwd> and every parent directory for CLAUDE.local.md

    Here is how that plays out in production. A project behaves correctly on developers' laptops, but the deployed Agent SDK service ignores both the repository's CLAUDE.md and its .claude/settings.json. Mounting the files somewhere isn't enough, and neither is pointing cwd at them: those files are only read when a source that covers them is enabled. A full fix has two parts. Include project in settingSources, and run the service with the repository checkout as its working directory so the lookup paths resolve.

    Checkpoint 1 of 9· Check yourself

    A team tunes prompts in Claude Code, where the repository's CLAUDE.md says to write ticket references as TCK-<number>. Their backend sends the same user prompts, with tools, straight to the Messages API, and the ticket format is gone from the replies. What fixes this?

    Checkpoint 2 of 9· Exam question

    A team tuned its prompts in Claude Code, where the repository's CLAUDE.md says to always format ticket references as TCK-<number>. Their new backend calls the Messages API with the same user prompts, and the format rule is ignored. What explains this, and what fixes it?

    Checkpoint 3 of 9· Exam question

    A service built on the Agent SDK uses default options. On developers' laptops the same project behaves according to the repo's CLAUDE.md and .claude/settings.json, but the deployed service ignores both. What is the best fix?

    Sources123

    2.Conversation state and session decisions

    The Messages API remembers nothing between calls, so the client owns conversation state. Each request carries every earlier user and assistant turn in messages, followed by the new user turn. Since the client controls the history, earlier turns don't have to be real model output. An application can insert synthetic assistant messages. Leaving the system prompt unchanged doesn't keep history alive, and neither API keys nor time windows do.

    A second turn: the client resends the first exchange along with the new questionpython
    message = anthropic.Anthropic().messages.create(
        model="claude-opus-5-5",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Hello, Claude"},
            {"role": "assistant", "content": "Hello!"},
            {"role": "user", "content": "Can you describe LLMs to me?"},
        ],
    )
    print(message)

    Two features change this default, and each has its own conditions. Message threads, a beta feature, let the API keep the conversation so later requests send only new messages. A thread expires five minutes after its last request, though, so a user who comes back after lunch needs a design that can rebuild the history. Mid-conversation system messages, with role: system placed right after a user turn, add an instruction partway through a conversation. They carry the same authority as the top-level system field. Their placement matters because of prompt caching: the API can cache the unchanged opening part of a request (its prefix) so that later requests reuse it, and editing anything earlier in the request invalidates that cache. A message appended at the end changes nothing before it, so earlier cached prefixes stay valid. They work only on the models listed for the feature, and the message can't be the first entry in messages.

    The Agent SDK handles state differently. It saves session history and offers three ways back into it. Continue picks up the most recent session in the current directory, which works when the application runs one conversation at a time. Resume takes a specific session ID, which the application has to track. You need resume once there are several sessions, such as one per user. Fork branches from an existing session into a new ID and leaves the original unchanged.

    Matching a session requirement to an Agent SDK mechanism
    RequirementMechanismConstraint to check
    Single prompt, no follow-upOne query() callNone
    Multi-turn chat in one processClaudeSDKClient (Python) or continue: true (TypeScript)One conversation at a time
    Return to one specific past session, e.g. one per userCapture session_id and pass it to resumeSession file must exist on the current machine
    Try an alternative without losing the originalresume plus fork_session=TrueFork gets its own ID, distinct from the original
    Nothing written to diskpersistSession: false (TypeScript only); CLAUDE_CODE_SKIP_PROMPT_HISTORY in PythonSession lives in memory for the call only

    How you key sessions decides who can see whose history. If a support portal keeps one session ID per chat room and lets different customers join that room, it hands every customer the same transcript. The session key has to follow the privacy boundary the requirement sets, which usually means one session per user. Sessions are also bound to one machine. A service spread across several hosts can't resume a session whose file lives on another host's disk.

    Checkpoint 4 of 9· Match them up

    Match each Agent SDK session mechanism to the requirement it fits.

    Tap a term, then the definition that fits it.

    Checkpoint 5 of 9· Check yourself

    A chat feature uses the beta message threads so each request sends only new messages. A user leaves for lunch and comes back 90 minutes later to carry on the same conversation. What does the design need?

    Checkpoint 6 of 9· Exam question

    Which statement correctly describes how conversation state works when an application calls the Messages API?

    Sources45

    3.What leaves the application, and what stays behind

    Everything you put in a request becomes prompt content, including content that looks like configuration. Tool definitions go into the system prompt the API builds. So do input_examples: optional sample tool inputs attached to a tool definition to show Claude how to call it. They are sent with the tool schema and cost prompt tokens, about 20–50 tokens for a simple example and 100–200 for a complex nested one. So a large tool catalogue is paid for on every call, and whatever it contains is visible to the model. Writing tool descriptions well is covered in tool design.

    Different parts of a request are kept for different lengths of time. Strict tool use and JSON outputs (both defined in the next section) share one grammar pipeline: the API compiles your schema into a grammar that constrains which tokens the model may generate, and it caches that compiled grammar, apart from message content, for up to 24 hours after its last use. Prompts and responses aren't kept past the API response. The design rule follows directly: put sensitive values in messages, never in schemas. Patient names don't belong in an enum, case identifiers don't belong in a const, and personal data doesn't belong in a pattern regex. Schemas built at runtime from user records are the risky case, because they quietly move user data into the cached part of the request.

    Checkpoint 7 of 9· Match them up

    You are reviewing what a request sends to the API. Pair each part of the request with how the API handles it once it leaves the application.

    Tap a term, then the definition that fits it.

    Sources16

    4.Choosing a schema mechanism against the requirement

    A requirement that downstream code must be able to parse every reply calls for a guarantee, not a prompt. Even a carefully prompted model can return malformed JSON, leave out required fields or use the wrong types. Two features remove that risk with constrained decoding: while Claude generates, it can only produce tokens that the compiled schema allows, so field types and required fields cannot come out wrong. JSON outputs (output_config.format with type: "json_schema") constrain Claude's reply, which arrives as JSON in a text content block. Strict tool use (strict: true on a tool definition) constrains tool names and tool inputs. For example, a booking tool that declares passengers as an integer always receives 2, never "two" or "2". You can use either feature on its own or both in the same request.

    Which mechanism meets which output requirement
    RequirementMechanismWhat it guarantees
    Claude's reply must be parseable JSON in a known shapeoutput_config.format (JSON outputs)Valid JSON matching the schema, in the text content block
    Your functions must receive correctly typed argumentsstrict: true on the toolTool input follows input_schema; tool name is always valid
    Format should usually match, failures tolerablePrompting aloneNo guarantee; expect parse errors and retries

    Neither guarantee covers every tool or every schema feature. The computer use and browser use toolsets reject strict: true outright. The schema language is a subset of JSON Schema. SDK helpers handle unsupported constraints such as minimum by removing them from the schema Claude sees, noting them in the field description, and then checking the response against your original schema in your own code. Because the grammar is built from the simplified schema, decoding never enforces the removed constraint. It holds only if your code validates it. A Pydantic dict field shows another limit. The helpers add additionalProperties: false to every object, so an object with no declared properties can contain no keys at all, and Claude can return only {} for the dict field. When you know the field's keys, declare them in a nested Pydantic model instead of a dict. Parsing and validation details are covered in structured output and defensive parsing.

    Checkpoint 8 of 9· Check yourself

    An extraction model declares quantity as an integer with minimum: 1 and is sent with JSON outputs through an SDK helper. When the reply comes back, what is actually enforcing the minimum?

    Sources76

    5.Model IDs and feature availability across platforms

    Moving to a cloud platform changes the strings you send as well as the endpoint you call. Each Claude model ID pins one model version, but the ID's format depends on the platform. The first-party API uses claude-{name}-{major}[-{minor}], for example claude-opus-5. Amazon Bedrock adds a prefix, as in anthropic.claude-opus-5. On Bedrock's bedrock-runtime endpoint, models served through cross-region inference need an inference profile ID such as global.anthropic.claude-fable-5-2. If code hard-codes first-party IDs, it breaks when it's deployed to Bedrock.

    Cross-region inference means AWS serves a model through profiles that can route requests across regions, instead of offering it as on-demand throughput in one region. An inference profile ID is the base model ID with a prefix such as global. or us.. A request that passes the base ID for such a model fails with an HTTP 400 error telling you to retry with the ID or ARN of an inference profile, and the models that need the profile form include Claude Fable 5.2 and Claude Mythos 5.2. Which prefixes a model accepts varies, so check the model's row in the Bedrock table before choosing one.

    The same model generation addressed on different surfaces
    SurfaceID formatExample
    Claude APIclaude-{name}-{major}[-{minor}]claude-opus-5
    Amazon Bedrockanthropic.claude-{name}-{major}[-{minor}]anthropic.claude-opus-5
    Bedrock bedrock-runtime, cross-region modelsInference profile prefix plus base IDglobal.anthropic.claude-fable-5-2

    Feature availability is checked per feature and per model. Mid-conversation system messages work only on a named list of models. Message threads are in beta. Structured outputs list their supported platforms explicitly: Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud, and Microsoft Foundry. So if compliance requires the application to run on a particular cloud offering, confirm before committing that every feature the design depends on is listed for that platform and model. Pinning model IDs per environment is covered in configuration and SDLC integration.

    Checkpoint 9 of 9· Check yourself

    Compliance requires an application to run on Microsoft Foundry. Its design depends on JSON outputs and on mid-conversation system messages. What should the team confirm before committing to this design?

    Sources89

    Sources

    (9)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”
      ↩︎ Where each surface gets its instructions
      “Examples are included in the prompt alongside your tool schema”
      ↩︎ What leaves the application, and what stays behind
      “An array of example input objects that show Claude how to use the tool.”
      ↩︎ What leaves the application, and what stays behind
      “the API constructs a special system prompt from the tool definitions, tool configuration, and any user-specified system prompt”
      ↩︎ Key concept
    2. 2.
      “<cwd>/.claude/ for settings.json and hooks; <cwd> and every parent directory for CLAUDE.md and rules”
      ↩︎ Where each surface gets its instructions
      “Project settings.json and hooks; project CLAUDE.md and .claude/rules/*.md”
      ↩︎ Exam trap 1
    3. 3.
      “Setting a role in the system prompt focuses Claude’s behavior and tone for your use case.”
      ↩︎ Where each surface gets its instructions
    4. 4.
      “The Messages API is stateless, which means that you always send the full conversational history to the API.”
      ↩︎ Conversation state and session decisions
      “A mid-conversation system message has the same authority as the top-level system field”
      ↩︎ Conversation state and session decisions
      “it does not invalidate any cached prefix that came before it”
      ↩︎ Conversation state and session decisions
      “A thread expires 5 minutes after its last request and is deleted no more than 1 hour after its last use.”
      ↩︎ Exam trap 2
      “A thread expires 5 minutes after its last request and is deleted no more than 1 hour after its last use.”
      ↩︎ Checkpoint
      “This works on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1”
      ↩︎ Checkpoint
    5. 5.
      “Required when you have multiple sessions (for example, one per user in a multi-user app)”
      ↩︎ Conversation state and session decisions
      “Same machine only: the session file still needs to exist on the current machine.”
      ↩︎ Conversation state and session decisions
      “Resume takes a specific session ID. You track the ID. Required when you have multiple sessions (for example, one per user in a multi-user app)”
      ↩︎ Checkpoint
    6. 6.
      “Strict tool use compiles tool input_schema definitions into grammars using the same pipeline as structured outputs.”
      ↩︎ What leaves the application, and what stays behind
      “Your prompts and Claude’s outputs are not stored. Only the JSON schema is cached, for up to 24 hours since last use.”
      ↩︎ What leaves the application, and what stays behind
      “Setting strict: true on a tool definition guarantees Claude’s tool inputs match your JSON Schema”
      ↩︎ Choosing a schema mechanism against the requirement
      “constraining the model’s token sampling to schema-valid outputs”
      ↩︎ Choosing a schema mechanism against the requirement
      “Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response.”
      ↩︎ Exam trap 3
      “Do not include PHI in input_schema property names, enum values, const values, or pattern regular expressions.”
      ↩︎ Prediction
      “Tool schemas are temporarily cached for up to 24 hours since last use. Prompts and responses are not retained beyond the API response.”
      ↩︎ Checkpoint
    7. 7.
      “Structured outputs guarantee schema-compliant responses through constrained decoding”
      ↩︎ Choosing a schema mechanism against the requirement
      “The SDK sends a dict field as an object with empty properties, so Claude can only return {} for it.”
      ↩︎ Choosing a schema mechanism against the requirement
      “Add additionalProperties: false to all objects”
      ↩︎ Choosing a schema mechanism against the requirement
      “Claude receives a simplified schema, but a helper that validates responses still enforces every constraint in your code.”
      ↩︎ Choosing a schema mechanism against the requirement
    8. 8.
      “Each Claude model ID identifies a pinned version of the model.”
      ↩︎ Model IDs and feature availability across platforms
      “On Amazon Bedrock, the corresponding format is:”
      ↩︎ Model IDs and feature availability across platforms
      “take an inference profile ID: the base model ID with a prefix such as global. or us., for example global.anthropic.claude-fable-5-2”
      ↩︎ Exam trap 4
    9. 9.
      “AWS offers newer Claude models through cross-region inference rather than on-demand throughput.”
      ↩︎ Model IDs and feature availability across platforms
      “The inference profile ID is the base model ID with a prefix from a column marked “Yes” in the following table”
      ↩︎ Model IDs and feature availability across platforms

    Ready to test yourself?

    Practise Anthropic Claude Certified Developer – Foundations (CCDV-F) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.