Blog • AI / Agent

How Do AI Coding Agents Work? Claude Code, Codex, Xcode 27 Agent, Tool Calling, and JSON Data Explained

Open Claude Code, Codex, or Xcode 27 and the UI looks like chat. What actually edits the repo, runs tests, and taps the simulator is not that natural-language reply.

An AI Coding Agent works like this: the model decides the next step and emits Tool Calling; a local or in-IDE harness runs the tool and feeds structured results back. Arguments and results are almost always JSON.

This article covers:

• Which extra layer a Coding Agent has over autocomplete
• The shared loop: observe → decide → execute → write back
• Why Tool Calling arguments arrive as a JSON string
• Where Claude Code, Codex, and the Xcode 27 Agent put the toolbox
• Which layer validates JSON / JSON Schema, and how to inspect it locally in JSONNote

Not a chat box — a loop

Autocomplete answers “what is the next line.” A Coding Agent answers “how do we finish this goal in a real project”: read context, pick a tool, edit code, run a command, read the result, decide again.

Official docs change the wording. The shape stays the same. Claude Code writes it as gather context → take action → verify results. Xcode 27 plans first, then edits, then self-checks with build / test / Preview / simulator. Underneath, both are:

1. 1
   Observe

   Read files, search symbols, check git status, pull failing test logs. Skip this and the next patch is a guess.

2. 2
   Decide

   In context, the model picks the next step: read again, search again, edit one place, run one command, or ask you a question.

3. 3
   Execute

   The harness receives the tool call and actually runs it under permissions and the sandbox. The model does not touch disk at this point.

4. 4
   Write back

   Tool results become text or JSON and go back into context. The model continues from the new evidence, or it declares the work done.

You are in this loop too: interrupt, redirect, approve high-risk actions. The model reasons. The harness owns tools, permissions, sessions, and what “done” means. For how four products fight over that control, see

AI Coding Agents Are More Than Autocomplete: What Are Four Products Competing On?

This article only splits how the loop turns and which hop carries JSON. For the stack layers, see

2026 AI Agent Stack: LLM, MCP, Function Calling, and JSON Schema.

Tool Calling: the arguments are JSON

Tool Calling (also called Function Calling) is not another name for “the model can write code.” It is a structured function call: the model picks a name from the tools you declared, then generates JSON that should match the parameter contract.

On OpenAI-compatible APIs, the parameters field on a tool definition is itself JSON Schema:

{
  "type": "function",
  "function": {
    "name": "run_tests",
    "description": "Run the project test suite and return a structured summary.",
    "parameters": {
      "type": "object",
      "properties": {
        "suite": { "type": "string", "enum": ["unit", "integration", "e2e"] },
        "path": { "type": "string", "minLength": 1 }
      },
      "required": ["suite"],
      "additionalProperties": false
    }
  }
}

When the model returns, arguments is often a string, not an already-parsed object:

{
  "id": "call_8f21",
  "type": "function",
  "function": {
    "name": "run_tests",
    "arguments": "{\"suite\":\"unit\",\"path\":\"src/auth\"}"
  }
}

So the business layer does at least two things: parse the string into valid JSON, then validate fields, types, and enums against the schema you declared. Missing quotes, extra commas, and undeclared keys all happen on this hop — not on the “the model sounded smart” hop.

The full turn is: request with schema → model picks a tool and generates arguments → you parse and validate → run the tool → feed the result back as a tool message → the model continues. A clear schema gets the first arguments right. A vague one makes the loop spin.

How to write the contract, and how JSON Mode differs from Strict Schema, is in

Why Do AI Agents Need JSON Schema? From Tool Calling to Structured Output.

Claude Code: built-in tools plus an extension layer

Claude Code’s official docs split the agent into two parts: a model that reasons, and tools that act. Without tools, Claude can only return text. With tools, it can read the repo, edit files, run commands, and search the web.

Built-in tools fall into about five groups: file operations (Read / Edit / Write), search (Grep / Glob), execution (Bash), web (WebSearch / WebFetch), and code intelligence that needs a plugin (jump to definition, type errors). Subagents and asking you a question are tools too — they are for orchestration.

A “fix the failing tests” turn in the loop might look like this:

1. 1
   Bash runs the tests

   See which assertion blew up before you touch the code.

2. 2
   Grep / Read locate the source

   Use the stack and symbols to pull the right context into the window.

3. 3
   Edit does a precise replace

   The docs require read-then-edit: old_string → new_string, so it does not write blind.

4. 4
   Run the tests again

   Results return to context. On failure it loops again, instead of saying “should be fine” out loud.

The extension layer sits on this loop. It does not replace it:

• CLAUDE.md: project conventions every session should know
• Skills: on-demand workflows, so you do not stuff every lesson into the system prompt
• MCP: tools for outside systems, searched on demand by default to keep context smaller
• Hooks / Permissions: deterministic blocks. Dangerous commands and protected paths should not depend on the model remembering every time

Claude Code’s engineering tradeoff is clear: a probabilistic agent plus deterministic hooks. Sessions also land as JSONL so you can resume and fork. What you debug is often a stream of tool events, not “one chat.”

Codex: sandbox, approvals, and JSONL

Codex also runs an agent loop, but the product center is how a model-generated command lands. In the terminal, when you run

Codex CLI, you pick the sandbox and approvals first, then let the model act.

For automation, use codex exec --json. stdout becomes JSONL: thread / turn start and end, command execution, file changes, MCP calls, plan updates. CI scripts consume an event stream, not a paragraph.

{"type":"item.completed","item":{"id":"item_12","type":"command_execution","command":"npm test -- src/auth","exit_code":1,"aggregated_output":"FAIL src/auth/session.test.ts"}}
{"type":"item.completed","item":{"id":"item_13","type":"file_change","path":"src/auth/session.ts","kind":"update"}}
{"type":"turn.completed","usage":{"input_tokens":18420,"output_tokens":966}}

When downstream needs stable fields, use --output-schema so the final answer matches a JSON Schema. That is the same kind of contract as Tool Calling parameters. It constrains the JSON at task end, not every command along the way.

By default codex exec is a read-only sandbox. To edit files, add --sandbox workspace-write explicitly. When you need more directories, prefer --add-dir instead of jumping to danger-full-access.

Xcode 27 Agent: plan, validate, editor tools

At WWDC 2026 Apple positioned Xcode 27 as the place to write code with agents on Apple platforms. Unlike a terminal agent, its toolbox lives in the IDE.

Apple’s newsroom post and

Xcode, agents, and you,

What’s new in Xcode 27 make a few things clear:

• The conversation lives in an editor pane, so you can split it with code and review diffs and artifacts
• /planExplore the repo and produce a plan first, without editing source yet; subagents can gather context in parallel
• During implementation it validates with Xcode’s own tools: build, run tests, render SwiftUI Previews, tap the app in a simulator or Device Hub
• Build errors go straight back to the agent, which edits and builds again from the failure log
• Models are not locked to one vendor: Anthropic, Google, OpenAI, and local models
• MCP connects external tools; ACP brings external agents (including ones like OpenCode) into Xcode

A WWDC lab framed Chat versus Agent as a capability gap, not a copy gap: Chat has a small fixed tool set; Agent mode adds the command line and Xcode’s internal tools (build, test, Preview, simulator). The default safety mode is permission prompts — the agent can reach what the task needs, but it cannot wander the disk.

For JSON developers, the point of this hop in Xcode is that validation results are also structured write-back. Build failures, test summaries, and Preview artifacts become the agent’s next input. On your backend you still see your own API JSON. In the IDE, the same loop consumes Xcode tool output.

System-level Siri AI uses App Intents, not this editor agent. Do not collapse the two into “Apple has only one kind of agent.” See

Will Siri AI Become an AI Agent?.

Three products, one loop, different toolboxes

Feature lists will keep looking alike. The difference is the default tools, the execution boundary, and how a result becomes the next turn’s context.

The choice can stay short: general multilingual repos and reusable Skills → Claude Code; run on a real machine and encode permissions in CI → Codex; Apple platforms where validation must go through the Xcode toolchain → Xcode 27. ACP means the last option does not have to reject the first two — an external agent can enter the editor, but build and Preview stay Xcode tools.

Where JSON sits, and who validates it

The three UIs differ. Where JSON shows up is stable:

The key line: API-layer schema guides generation; business-layer schema rejects dirty data. Neither replaces the other. Why AI output needs a schema first is in

Why Does AI Need JSON Schema?.

For a Coding Agent tool schema, write when to call and when not to call. Put options in enum, not buried in description:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["action", "path"],
  "properties": {
    "action": { "type": "string", "enum": ["read", "edit", "test"] },
    "path": { "type": "string", "minLength": 1 },
    "suite": { "type": "string", "enum": ["unit", "integration"] },
    "old_string": { "type": "string" },
    "new_string": { "type": "string" }
  },
  "additionalProperties": false,
  "allOf": [
    {
      "if": { "properties": { "action": { "const": "edit" } } },
      "then": { "required": ["old_string", "new_string"] }
    },
    {
      "if": { "properties": { "action": { "const": "test" } } },
      "then": { "required": ["suite"] }
    }
  ]
}

If the model returns {"action":"edit","path":"src/a.ts"} without old_string, the schema stops it at the execution layer. That is cheaper than reading a diff afterward.

Debug tool arguments in JSONNote

The slowest part of agent work is often not the prompt. It is one failed tool call. JSONNote runs locally in the browser. Keys and repo contents do not upload.

1. 1
   See whether arguments can parse

   Drop the model’s returned string into JSON Formatter. Missing quotes, trailing commas, and hashes truncated by a chat app show up here.

2. 2
   Then validate against the schema

   Put the tool definition and the actual arguments into JSON Schema. A wrong enum, a missing required field, or extra keys is more useful than the model saying “sorry.”

3. 3
   Compare two calls

   After you change a description or set additionalProperties: false, use JSON Diff to check argument regressions.

4. 4
   Share the debug scene

   Use URL Hash sharing to embed a tool JSON in a link. A teammate opens it and reproduces. The data never hits a server.

FAQ

What is the real difference between an AI Coding Agent and code autocomplete?

Autocomplete only suggests the next line. A Coding Agent can read a repo, edit files, run commands, call external tools, and keep deciding from tool results in a loop. The difference is not prose quality. It is whether it can act.

Does the model edit files on my disk directly?

No. The model only emits a tool call, usually a JSON payload. The local harness writes files, runs the shell, and taps the simulator. Without a tool, if permission is denied, or if argument validation fails, nothing happens on disk.

Which is better: Claude Code, Codex, or the Xcode 27 Agent?

There is no single winner. Pick Claude Code for general repos plus Skills and MCP. Pick Codex for sandbox, approvals, and JSONL events in CI. Pick the Xcode 27 Agent for Apple platforms when you need build, Preview, and simulator validation. Xcode can also attach an external agent over ACP.

Why validate JSON yourself if the model already filled the schema?

Model-filled arguments are a soft constraint. arguments is often a string and may miss fields, use the wrong type, or add undeclared keys. Production still needs parse plus JSON Schema, then the business layer. Codex --output-schema only constrains the final answer. It does not replace checks on every tool result.

Can the Xcode 27 Agent only use Apple’s own models?

No. Xcode 27 wires Anthropic, Google, and OpenAI models and agents into the same editor workflow. It also supports local models, ACP for external agents, and MCP for external tools. What changes is the toolbox and how work is validated, not the loop itself.

Summary

The three products will keep looking like chat. The sentence underneath does not change:

Coding Agent = model decisions × Tool Calling × harness execution. JSON is the shared shape of tool arguments and write-back results.

See the loop first, then pick a toolbox: Claude Code strengthens a general agent, Codex owns the sandbox and events, Xcode 27 turns build and Preview into validation tools. Write the schema in the declaration, validate at the execution layer, and keep debugging in the local browser.

← Back to blog