AI Coding Agent Architecture:
Tools vs Subagents, Plugins, Functions & Actions

DEFINITION

What is AI coding agent architecture?

AI coding agent architecture is the design of the control loop, context pipeline, execution environment, capability interfaces, delegated workers, authority boundaries and verification process that turn a software-development objective into a reviewable, testable change. The language model is an important component, but it is not the architecture.

A basic coding assistant predicts or edits code in response to a user. A coding agent can inspect a repository, select tools, execute commands, respond to failing tests, change state and continue until it reaches a stopping condition. This makes the critical questions operational: What can it observe? What may it change? Who authorizes those changes? How does the system prove its work?

SEARCH-INTENT COMPARISON

AI coding agent platform concepts: tools vs subagents vs plugins vs functions vs actions

The key terms appear together in product menus and documentation, but they represent different layers of the system. An apples-to-apples comparison begins by asking whether an item is a worker, a capability, an invocation interface, a distribution mechanism or an effect.

These are precise analytical distinctions, not a claim that every vendor uses identical vocabulary. For example, GitHub distinguishes tools, MCP servers, skills, hooks, subagents and custom agents; OpenAI describes plugins as packages that can contain skills and MCP configuration. The authoritative names for a particular product should always come from that product's documentation. [1][2][8][9]

END-TO-END SYSTEM

How does an AI coding agent work? The complete execution loop

Suppose the task is: “Upgrade the authentication dependency, keep existing behavior, and prepare a pull request.” A serious agent architecture must connect intent to executed evidence without silently enlarging the task's scope.

OpenAI's managed-agent documentation explicitly separates the harness controlling the loop, an optional environment for files and execution, and the application server integrating external function tools and the product. This decomposition is useful even when another vendor ships all three together. [5][6][7]

CAPABILITY INTERFACES

AI agent tools vs function calling: what actually executes?

A tool is an interface the agent may invoke to read information or effect a bounded operation. The implementation could be internal to the harness (terminal, patch, browser), provided as a host-application function, or exposed by an MCP server. Function calling is a common structured invocation mechanism: the model proposes a function name and arguments, while host code validates the request, runs the handler and supplies its result.

The language model does not execute arbitrary operations merely by emitting a JSON object. A model can request run_tests; the executor must validate the path, ensure the caller is allowed, run the process under limits and return actual exit status.

# Illustrative pseudocode: not a vendor SDK signature
def handle_tool_call(request, identity, sandbox):
    target = validate_test_target(request.arguments["target"])
    policy.require(identity, "tests.execute", target)
    result = sandbox.run(["test-runner", target], timeout=120)
    return {
        "exit_code": result.exit_code,
        "report": result.report_artifact,
        "stdout": redact_and_truncate(result.stdout)
    }
# Tool invocation is a request; execution and permission live in the host.

Good interfaces expose typed inputs, stable names, timeouts, output limits, retry rules and explicit side-effect classification. A correct schema catches malformed arguments; it does not determine that an otherwise well-formed operation should be allowed.

Is a shell command a tool or an action?

The shell executor is a tool. A particular invocation such as git diff --check is an action requested through it. The exit status, output and changed repository state are results. Logging these separately is essential for post-run verification.

PROTOCOL LAYER

How MCP fits into AI coding agent architecture

The Model Context Protocol (MCP) is an interoperability boundary that lets a client discover and invoke capabilities exposed by a server. MCP tools have names and schemas, and the client can use tools/list to discover them and tools/call to invoke them. An MCP server can also expose other context capabilities, which are not automatically executable tools. [11]

The 2026-07-28 MCP specification is materially different from older examples that assume legacy initialization and session behavior. Its stateless requests and metadata rules should be followed for new integrations; version pinning and backward compatibility must be explicit. [12]

MCP is neither a subagent nor a plugin by definition. A plugin may configure an MCP server. A subagent may invoke MCP tools. Those are composition choices. See the site's deeper Model Context Protocol guide for transport, OAuth, resources, prompts and server architecture.

DELEGATION STRATEGY

Subagents vs tools: when should you create another coding agent?

A subagent is a delegated worker with a defined objective, a distinct execution context and, ideally, intentionally restricted capabilities. It may perform many tool calls to deliver a review, report, patch or research result. A tool call, by contrast, is a bounded capability invocation. GitHub's Copilot SDK documentation illustrates specialist agents with independent prompts and tool restrictions, and explicitly describes subagent lifecycle events. [4]

Extra agents cost tokens, initialization, duplicated retrieval, coordination time and conflict resolution. Parallelism is valuable only when subtasks can proceed independently and a final integrator checks the combined output. A specialist without a measurable deliverable is often overhead, not architectural sophistication.

EXTENSION MODEL

Plugins vs skills vs hooks vs custom agents explained

A plugin generally packages integrations for distribution or installation; the payload is platform-specific. OpenAI documents plugins packaging skills and MCP configuration. GitHub Copilot's extension documentation describes bundles that may include skills, custom agents, hooks and MCP server configurations. Neither makes “plugin” a synonym for a remote reasoning agent. [8][2]

A skill stores task guidance, potentially supported by reference files and scripts. It tells an agent how to approach work; it does not give the agent credentials or bypass policy. A hook is application-controlled code invoked at a lifecycle event rather than a new free-form model-selected agent. A custom agent profile defines specialist instructions and tools; a subagent is a particular delegated run. These distinctions prevent both unsafe configuration and inflated product claims.

Do skills or repository instructions give the agent new permissions?

No. A skill saying “merge this code” does not create a valid merge authorization. Tool registration determines which operations are reachable; identity and policy decide what the current principal may do. A repository file is also untrusted input relative to the application's privileged instructions. Related context: GitHub Copilot Memory discusses durable repository knowledge separately from instructions.

SIDE EFFECTS

What are actions in AI coding agents?

An action is the system's attempted operation: run a compiler, apply a patch, make a network request, delete a branch or open a pull request. The word may also name a vendor feature—GitHub Actions is a specific CI/CD product—so technical writing must distinguish general actions from branded ones.

Record three levels independently: intent (“test package A”), execution (tool, arguments, principal, environment, time and exit code) and outcome (logs, artifacts, test verdict or changed state). An agent claiming that “tests passed” is not evidence that a test command ran successfully. The executor's observed report is evidence.

Actions should also be classified by side effects: read-only, local reversible write, external write and irreversible or production-affecting operations. These classes guide approval gates and retry rules; repeating a failed read is not equivalent to retrying a payment, merge or deployment.

PRODUCTION PATTERN

A practical AI coding agent reference architecture

The following is an SXF recommended architecture pattern, derived from the verified roles and general isolation principles—not a claim that vendors implement one identical design or that it has been independently benchmarked.

USER GOAL + ACCEPTANCE CRITERIA
              |
       SCOPE / IDENTITY GATE
              |
     ORCHESTRATOR + TASK STATE
       /                 \
READ-ONLY SPECIALIST   SCOPED EXECUTOR
  (optional worker)     (typed tools)
       \                 /
           VERIFICATION
      test | diff | logs | review
                  |
        HUMAN APPROVAL / PR
                  |
          SEPARATE MERGE GATE

Start with one orchestrator and a minimal set of discover, edit and test tools. Run writes in a repository-scoped sandbox, keep external network access explicit, and require checks before proposing a reviewable change. Only then add custom skills, MCP connectors, plugins or specialist subagents.

What should a tool execution record contain?

call:
  tool: repo.run_tests
  principal: task-agent
  target: packages/auth
  workspace: isolated-worktree-73
  timeout_seconds: 120
authorization:
  permission: tests.execute
  decision: allow
result:
  exit_code: 1
  status: failed
  artifact: test-report.json
  state_delta: none
  trace_id: run-73-step-04

The goal is to make failure explicit, observable and recoverable. A failed test is useful feedback; silently rewriting it as success is an architecture failure.

ENGINEERING CASES

Three AI coding agent architectures compared in real workflows

There is no universal winner. The correct architecture depends on task coupling, isolation needs, run length, repository size, cost constraints, permission boundaries and the reliability of the tools behind it.

THREAT MODEL

AI coding agent security: where authority must stop

A coding agent routinely consumes attacker-influenced material: repository comments, issue descriptions, external docs, package metadata, web pages and tool output. A malicious instruction embedded in that material can attempt to redirect the agent to leak a secret or invoke a privileged tool. The defense is not merely to ask the model to ignore suspicious prose; the execution system must enforce the boundary.

MCP's current tools specification requires server-side input validation and access controls, and recommends client confirmations around sensitive operations. Protocol compliance alone is not a complete security model. Read the companion AI Agent Security and Prompt Injection references. [11]

MEASUREMENT

How to benchmark AI coding agent architecture—not just its model

Hold the task set, repository revision, model budget, timeout, permitted tools, environment and reviewer rubric constant across configurations. Repeat runs. Compare the full system's accepted changes—not screenshots of a successful chat response. Evaluate a single-agent baseline before adding one extension at a time.

Run ablations: baseline; baseline + skill; baseline + MCP; baseline + read-only reviewer; baseline + parallel specialists. Attribute any improvement to a mechanism, such as better repository retrieval, clearer requirements, stronger test coverage or reduced latency. Do not assume adding agents increases accuracy. For deeper consistency metrics see AI Agent Reliability; for retrieval and persistent state see AI Agent Memory.

DESIGN ERRORS

Seven AI coding agent architecture mistakes to avoid

1. Calling every integration an “agent.” A remote API capability is not automatically a delegated worker.
2. Confusing tool-call syntax with authorization. Typed arguments are necessary but do not establish a right to execute.
3. Treating skills as runtime permissions. Instructions are not credentials or policy grants.
4. Assuming MCP provides a trust boundary for free. It standardizes interfaces; clients and services still must verify.
5. Parallel editing without ownership. Shared worktrees and overlapping patches can invalidate each other's assumptions.
6. Accepting narrative success without run evidence. A claimed passing test is not an executed passing test.
7. Comparing models while changing the harness and budget. Without controlled conditions, architecture conclusions are not reproducible.

ARCHITECTURAL DECISION

Which AI coding agent architecture should you build first?

For decisions about actual developer products, see Best AI Coding Tools. For larger orchestration, consult How to Build an AI Super Agent. These references answer different search intentions: product choice, workflow design and the underlying architecture described here.

DIRECT ANSWERS

AI coding agent architecture FAQs

RESEARCH METHODOLOGY

What the evidence supports—and what it does not

This SXF article is an independently authored technical synthesis, last verified October 10, 2026, built from official vendor documentation and the published MCP specification. Our layer model, matrices, sample architecture and decision rules are original explanatory frameworks, not results of a controlled performance experiment. Vendor documentation is evidence for that vendor's interface and terminology, not proof of performance superiority. Implementation details, pricing and feature support may change; the permanent URL deliberately contains no year.

No claim is made that subagents always improve coding accuracy, that one agent framework wins every workload, or that an MCP connection alone establishes security.

PRIMARY SOURCES

Source ledger: protocols and official engineering documentation

These sources substantiate specific architecture concepts. The article distinguishes documentation-backed facts from SXF analysis.