AI Agents in Modern Software Development

A useful AI agent needs more than a prompt that says “finish the task.” It needs access to the right evidence, a small set of tools, a way to verify changes, and clear stopping conditions. A content edit provides a practical example: the agent must read the existing article, preserve unrelated fields, submit a valid update, and check what the reader actually receives.

This walkthrough uses the content-tool design in Nucleus, the Laravel backend behind this portfolio. The implementation described here is based on its source and documented contracts. The example requests are illustrative; they are not a claim that a particular AI client or production deployment has passed these checks.

Separate the model, the tools, and the application

The model proposes an action. A client manages the conversation and invokes tools. The application decides whether the action is valid and authorized, then performs it. Keeping these responsibilities separate prevents generated text from becoming an unrestricted database command.

Nucleus exposes content operations through Laravel MCP. Its tools reuse the existing CMS repositories and validation. Text generation happens in the AI client; the content server does not call an AI provider to rewrite articles. MCP supplies the communication interface, while the application's permissions, content rules, and transactions supply the actual safeguards. The MCP architecture guide explains the host, client, and server roles.

Human task and constraints
        ↓
AI client: read → propose → inspect results
        ↓
Nucleus content tools: validate → authorize → save
        ↓
Public Portfolio API → Next.js page → reader

Give the agent a task it can prove complete

“Improve the blog” leaves too many choices implicit. A bounded task can specify one record, the allowed fields, the expected result, and the evidence needed before completion:

Record: the existing draft article selected by the editor.
Goal: replace missing code screenshots with readable HTML code blocks.
Allowed change: body only.
Preserve: title, category, tags, status, publication date and SEO fields.
Evidence: examples match the current application contract;
          no broken instructional media; saved body matches the draft.
Stop: permission failure, conflicting revision, or unclear source material.

This is also useful for a coding agent. A cache fix, for example, should name the stale behavior, the files that own it, the consumers affected by it, and the check that demonstrates freshness. In this ecosystem, changing a Laravel payload can affect both the Next.js website and the mobile client. Reading only the nearest component would miss that dependency.

Expose narrow operations instead of general access

The Nucleus content server offers separate tools for listing, reading, creating, updating, publishing, and deleting courses, projects, and blogs. It does not expose shell execution, arbitrary SQL, account management, or unrestricted remote fetching. A read-only token cannot become a write token because the model requests it.

Authorization is checked when tools are discovered and again when a tool is invoked. That second check matters: a previously visible tool is not permanent permission. Nucleus also checks that the account is active, verified, and allowed to access the relevant content module. Its dedicated MCP tokens have expiration and read/write abilities, separate from ordinary App API tokens.

These are application rules, not automatic properties of MCP. Laravel MCP's documentation describes tool schemas and middleware; an application still needs to decide which operations its users may perform.

Read the record before constructing a partial update

A list result is enough to choose a record, but not enough to edit it. The detail tool returns editable fields and a revision. The agent should inspect that body, compare it with source material, and produce a diff before writing.

The following examples show MCP tool-call parameters, not a complete connection handshake. Record 42 is an example draft ID. Replace it with the selected record; replace the revision placeholder with the exact 64-character revision returned by the read.

{
  "name": "get_blog",
  "arguments": { "id": 42 }
}

{
  "name": "update_blog",
  "arguments": {
    "id": 42,
    "revision": "<revision from get_blog>",
    "idempotency_key": "6f641eb1-c8bb-4fc3-b624-286de37c5ee4",
    "data": {
      "body": "<p>Reviewed explanation and code examples.</p>"
    }
  }
}

The submitted data contains only the intended field. Omitted fields are preserved. Arrays, when supplied, replace the whole list; an empty array can therefore clear existing content. Sending the entire record back “just in case” creates unnecessary opportunities to overwrite work.

New records start as drafts, and publication uses a separate operation. Editing an already published record changes live content immediately, however. A separate publish tool does not turn a published-record update into a private preview. The client must know the record's current status and the editor's authorization before submitting it.

Handle retries and competing edits deliberately

Two different questions must be answered: “Did this request already succeed?” and “Has somebody changed this article since I read it?” Nucleus addresses them with an idempotency key and a content revision.

One UUID identifies one logical write. The server stores its committed result in a receipt. If the connection drops after the write, retrying the identical arguments with the same key returns that result. Generating a new key after every timeout defeats this protection. Reusing an old key for a different body is also rejected.

The revision checks the content snapshot before an update. A mismatch means the agent must read the latest record and reconsider the edit. It must not substitute a fresh revision while blindly replaying its old replacement body. The implementation serializes MCP writes for an account, but ordinary admin edits do not use the same revision protocol. This is a defined concurrency boundary, not a guarantee against every possible editor race.

Keep retrieved content outside the instruction boundary

A blog body, code comment, search result, or error response can contain text that looks like an instruction. The agent should treat that text as material to inspect. It cannot authorize publication, request a secret, or expand the human's task.

For this workflow, credentials belong in the client's protected configuration. They should not appear in prompts, HTML drafts, screenshots, or public code examples. HTML also needs review for links, executable markup, and unsupported claims; a valid tool schema only proves that the request has an accepted shape.

Verify the result at the correct layer

After saving, read the record again and compare the stored body with the approved draft. If it is published, check the public API and the rendered page as separate steps. Nucleus's content model triggers a queued Portfolio cache refresh, so a successful write response alone does not demonstrate fresh visitor HTML.

A useful local test set covers permission denial, invalid fields, draft visibility, an identical retry, a reused key with different content, and a stale revision. Run those checks with an isolated database and fake external services. Do not use production content as disposable test fixtures.

Finally, inspect the article as a reader: copy the code, follow the references, and confirm that each promised step is present. Record any remaining limitation explicitly. The engineering value of an agent is the work it can complete and verify within its tools and authority; speed and quality improvements should be measured instead of assumed.