agents: Apply suggestions from code review

Co-authored-by: Jun Lee <[email protected]>

Author: elithrar

src/content/docs/agents/concepts/calling-llms.mdx

@@ -8,12 +8,14 @@ sidebar:
 
 import { Render } from "~/components";
 
-### Understanding LLM Providers and Model Types
+### Understanding LLM providers and model types
 
 Different LLM providers offer models optimized for specific types of tasks. When building AI systems, choosing the right model is crucial for both performance and cost efficiency.
 
 #### Reasoning Models
+
 Models like OpenAI's o1, Anthropic's Claude, and DeepSeek's R1 are particularly well-suited for complex reasoning tasks. These models excel at:
+
 - Breaking down problems into steps
 - Following complex instructions
 - Maintaining context across long conversations
@@ -22,10 +24,11 @@ Models like OpenAI's o1, Anthropic's Claude, and DeepSeek's R1 are particularly
 For example, when implementing a travel booking system, you might use a reasoning model to analyze travel requirements and generate appropriate booking strategies.
 
 #### Instruction Models
+
 Models like GPT-4 and Claude Instant are optimized for following straightforward instructions efficiently. They work well for:
 - Content generation
 - Simple classification tasks
 - Basic question answering
 - Text transformation
 
-These models are often more cost-effective for straightforward tasks that don't require complex reasoning.
+These models are often more cost-effective for straightforward tasks that do not require complex reasoning.

src/content/docs/agents/concepts/human-in-the-loop.mdx

@@ -14,39 +14,40 @@ Human-in-the-Loop (HITL) workflows integrate human judgment and oversight into a
 
 ![A human-in-the-loop diagram](~/assets/images/agents/human-in-the-loop.svg)
 
-#### Understanding Human-in-the-Loop Workflows
+#### Understanding Human-in-the-Loop workflows
 
-In a Human-in-the-Loop workflow, processes aren't fully automated. Instead, they include designated checkpoints where human intervention is required. For example, in a travel booking system, a human may want to confirm the travel before an agent follows through with a transaction. The workflow manages this interaction, ensuring that:
+In a Human-in-the-Loop workflow, processes are not fully automated. Instead, they include designated checkpoints where human intervention is required. For example, in a travel booking system, a human may want to confirm the travel before an agent follows through with a transaction. The workflow manages this interaction, ensuring that:
 
 1. The process pauses at appropriate review points
 2. Human reviewers receive necessary context
 3. The system maintains state during the review period
 4. Review decisions are properly incorporated
-5. The process continues once approval is receive
+5. The process continues once approval is received
 
-### Best Practices for Human-in-the-Loop Workflows
+### Best practices for Human-in-the-Loop workflows
 
 #### Long-Term State Persistence
 
-Human review processes don't operate on predictable timelines. A reviewer might need days or weeks to make a decision, especially for complex cases requiring additional investigation or multiple approvals. Your system needs to maintain perfect state consistency throughout this period, including:
+Human review processes do not operate on predictable timelines. A reviewer might need days or weeks to make a decision, especially for complex cases requiring additional investigation or multiple approvals. Your system needs to maintain perfect state consistency throughout this period, including:
+
 - The original request and context
 - All intermediate decisions and actions
 - Any partial progress or temporary states
 - Review history and feedback
 
-<Aside type="tip">
-[Durable Objects](https://developers.cloudflare.com/durable-objects/) provide an ideal solution for managing state in human-in-the-loop workflows, offering persistent compute instances that maintain state for hours, weeks, or months.
-</Aside>
+:::note[Tip]
+[Durable Objects](/durable-objects/) provide an ideal solution for managing state in Human-in-the-Loop workflows, offering persistent compute instances that maintain state for hours, weeks, or months.
+:::
 
 #### Continuous Improvement Through Evals
 
 Human reviewers play a crucial role in evaluating and improving LLM performance. Implement a systematic evaluation process where human feedback is collected not just on the final output, but on the LLM's decision-making process. This can include:
 
 - Decision Quality Assessment: Have reviewers evaluate the LLM's reasoning process and decision points, not just the final output.
 - Edge Case Identification: Use human expertise to identify scenarios where the LLM's performance could be improved.
-- Feedback Collection: Gather structured feedback that can be used to fine-tune the LLM or adjust the workflow. [AI Gateway](https://developers.cloudflare.com/ai-gateway/evaluations/add-human-feedback/) can be a useful tool for setting up an LLM feedback loop.
+- Feedback Collection: Gather structured feedback that can be used to fine-tune the LLM or adjust the workflow. [AI Gateway](/ai-gateway/evaluations/add-human-feedback/) can be a useful tool for setting up an LLM feedback loop.
 
-#### Error Handling and Recovery
+#### Error handling and recovery
 
 Robust error handling is essential for maintaining workflow integrity. Your system should gracefully handle various failure scenarios, including reviewer unavailability, system outages, or conflicting reviews. Implement clear escalation paths for handling exceptional cases that fall outside normal parameters.
 

src/content/docs/agents/concepts/tools.mdx

@@ -6,27 +6,29 @@ sidebar:
 
 ---
 
-### What are Tools?
+### What are tools?
 
 Tools enable AI systems to interact with external services and perform actions. They provide a structured way for agents and workflows to invoke APIs, manipulate data, and integrate with external systems. Tools form the bridge between AI decision-making capabilities and real-world actions.
 
-### Understanding Tools
+### Understanding tools
 
 In an AI system, tools are typically implemented as function calls that the AI can use to accomplish specific tasks. For example, a travel booking agent might have tools for:
+
 - Searching flight availability
 - Checking hotel rates 
 - Processing payments
 - Sending confirmation emails
 
 Each tool has a defined interface specifying its inputs, outputs, and expected behavior. This allows the AI system to understand when and how to use each tool appropriately.
 
-### Common Tool Patterns
+### Common tool patterns
 
-#### API Integration Tools
+#### API integration tools
 
 The most common type of tools are those that wrap external APIs. These tools handle the complexity of API authentication, request formatting, and response parsing, presenting a clean interface to the AI system.
 
 #### Model Context Protocol (MCP)
+
 The (Model Context Protocol)[https://modelcontextprotocol.io/introduction] provides a standardized way to define and interact with tools. Think of it as an abstraction on top of APIs designed for LLMs to interact with external resources. MCP defines a consistent interface for:
 
 - **Tool Discovery**: Systems can dynamically discover available tools
@@ -35,7 +37,8 @@ The (Model Context Protocol)[https://modelcontextprotocol.io/introduction] provi
 - **State Management**: Tools can maintain state across invocations
 
 
-#### Data Processing Tools
+#### Data processing tools
+
 Tools that handle data transformation and analysis are essential for many AI workflows. These might include:
 
 - CSV parsing and analysis

src/content/docs/agents/concepts/what-are-agents.mdx

@@ -8,28 +8,33 @@ sidebar:
 
 import { Render } from "~/components";
 
-### What are agents? 
+### What are agents?
+
 An agent is an AI system that can autonomously execute tasks by making decisions about tool usage and process flow. Unlike traditional automation that follows predefined paths, agents can dynamically adapt their approach based on context and intermediate results. Agents are also distinct from co-pilots (e.g. traditional chat applications) in that they can fully automate a task, as opposed to simply augmenting and extending human input. 
 
 - **Agents** → non-linear, non-deterministic (can change from run to run)
 - **Workflows** → linear, deterministic execution paths
 - **Co-pilots** → augmentative AI assistance requiring human intervention
 
-### Example: Booking Vacations
-If this is your first time working with, or interacting with agents, this example will illustrate how an agent works within a context like booking a vacation. If you're already familiar with the topic, read on. 
+### Example: Booking vacations
+
+If this is your first time working with, or interacting with agents, this example will illustrate how an agent works within a context like booking a vacation. If you are already familiar with the topic, read on. 
 
 Imagine you're trying to book a vacation. You need to research flights, find hotels, check restaurant reviews, and keep track of your budget. 
 
-##### Traditional Workflow Automation
+#### Traditional workflow automation
+
 A traditional automation system follows a predetermined sequence:
+
 - Takes specific inputs (dates, location, budget)
 - Calls predefined API endpoints in a fixed order
 - Returns results based on hardcoded criteria
 - Cannot adapt if unexpected situations arise
 
 ![Traditional workflow automation diagram](~/assets/images/agents/workflow-automation.svg)
 
-##### AI Co-pilot
+#### AI Co-pilot
+
 A co-pilot acts as an intelligent assistant that:
 
 - Provides hotel and itinerary recommendations based on your preferences
@@ -39,7 +44,8 @@ A co-pilot acts as an intelligent assistant that:
 
 ![A co-pilot diagram](~/assets/images/agents/co-pilot.svg)
 
-##### Agent
+#### Agent
+
 An agent combines AI's ability to make judgements and call the relevant tools to execute the task. An agent's output will be nondeterministic given:
 
 - Real-time availability and pricing changes
@@ -49,17 +55,18 @@ An agent combines AI's ability to make judgements and call the relevant tools to
 
 ![An agent diagram](~/assets/images/agents/agent-workflow.svg)
 
-An agents can dynamically generate and itinerary and execute on booking reservations, similarly to what you would expect from a travel agent. 
+An agents can dynamically generate an itinerary and execute on booking reservations, similarly to what you would expect from a travel agent. 
 
 ### Three primary components of agent systems:
 
 - **Decision Engine**: Usually an LLM (Large Language Model) that determines action steps
 - **Tool Integration**: APIs, functions, and services the agent can utilize
 - **Memory System**: Maintains context and tracks task progress
 
-#### How Agents Work
+#### How agents work
 
 Agents operate in a continuous loop of:
+
 1. **Observing** the current state or task
 2. **Planning** what actions to take, using AI for reasoning
 3. **Executing** those actions using available tools (often APIs or [MCPs](https://modelcontextprotocol.io/introduction))

src/content/docs/agents/concepts/workflows.mdx

@@ -11,13 +11,13 @@ import { Render } from "~/components";
 
 A workflow is the orchestration layer that coordinates how an agent's components work together. It defines the structured paths through which tasks are processed, tools are called, and results are managed. While agents make dynamic decisions about what to do, workflows provide the underlying framework that governs how those decisions are executed.
 
-### Understanding Workflows in Agent Systems
+### Understanding workflows in agent systems
 
 Think of a workflow like the operating procedures of a company. The company (agent) can make various decisions, but how those decisions get implemented follows established processes (workflows). For example, when you book a flight through a travel agent, they might make different decisions about which flights to recommend, but the process of actually booking the flight follows a fixed sequence of steps.
 
 Let's examine a basic agent workflow:
 
-### Core Components of a Workflow
+### Core components of a workflow
 
 A workflow typically consists of several key elements:
 

src/content/docs/agents/examples/manage-and-sync-state.mdx

@@ -18,7 +18,7 @@ Agent state is stored in SQL database that associate with each indidivual Agent
 
 ### State API
 
-Every agent has built-in state management capabilities. You can set and update the agent's state directly using `this.setState`:
+Every Agent has built-in state management capabilities. You can set and update the Agent's state directly using `this.setState`:
 
 <TypeScriptExample>
 
@@ -95,7 +95,7 @@ Clients can connect to an Agent and stay synchronized with its state using the R
 
 The state synchronization system:
 
-* Automatically syncs the agent's state to all connected clients
+* Automatically syncs the Agent's state to all connected clients
 * Handles client disconnections and reconnections gracefully
 * Provides immediate local updates
 * Supports multiple simultaneous client connections
@@ -106,7 +106,7 @@ Common use cases:
 * Multi-window/tab synchronization
 * Live updates across multiple devices
 * Maintaining consistent UI state across clients
-* When new clients connect, they automatically receive the current state from the agent, ensuring all clients start with the latest data.
+* When new clients connect, they automatically receive the current state from the Agent, ensuring all clients start with the latest data.
 
 ### SQL API
 

src/content/docs/agents/examples/schedule-tasks.mdx

@@ -66,11 +66,11 @@ Tasks that set a callback for a method that does not exist will fail silently.
 
 :::
 
-Calling `await this.schedule` returns a `Schedule`, which includes the task's randomly generated `id`. You can use this `id` to retrieve or cancel the task in the future. It also provides a `type` property that indicates the type of schedule - e.g. one of `"scheduled" | "delayed" | "cron"`.
+Calling `await this.schedule` returns a `Schedule`, which includes the task's randomly generated `id`. You can use this `id` to retrieve or cancel the task in the future. It also provides a `type` property that indicates the type of schedule, for example, one of `"scheduled" | "delayed" | "cron"`.
 
 :::note[Maximum scheduled tasks]
 
-Each task is mapped to a row in the Agent's underlying [SQLite database](/sqlite-in-durable-objects/), which means that each task can be up to 2MB in size. The maximum number of tasks must be `(task_size * tasks) + all_other_state < maximum_database_size` (currently 1GB per Agent).
+Each task is mapped to a row in the Agent's underlying [SQLite database](/sqlite-in-durable-objects/), which means that each task can be up to 2 MB in size. The maximum number of tasks must be `(task_size * tasks) + all_other_state < maximum_database_size` (currently 1GB per Agent).
 
 :::
 

src/content/docs/agents/examples/using-ai-models.mdx

@@ -8,9 +8,9 @@ sidebar:
 
 import { MetaInfo, Render, Type, TypeScriptExample, WranglerConfig } from "~/components";
 
-Agents can communicate with AI models hosted on any provider, including [Workers AI](/workers-ai/), OpenAI, Anthropic and Google's Gemini.
+Agents can communicate with AI models hosted on any provider, including [Workers AI](/workers-ai/), OpenAI, Anthropic, and Google's Gemini.
 
-Because Agents are built on top of [Durable Objects](/durable-objects/), each agent or chat session is associated with a stateful compute instance. Tradtional serverless architectures often present challenges for persistent connections needed in real-time applications like chat.
+Because Agents are built on top of [Durable Objects](/durable-objects/), each Agent or chat session is associated with a stateful compute instance. Tradtional serverless architectures often present challenges for persistent connections needed in real-time applications like chat.
 
 A user can disconnect during a long-running response from a modern reasoning model (such as `o3-mini` or DeepSeek R1), or lose conversational context when refreshing the browser. Instead of relying on request-response patterns and managing an external database to track & store conversation state, state can be stored directly within the Agent. If a client disconnects, the Agent can write to its own distributed storage, and catch the client up as soon as it reconnects: even if it's hours or days later.
 

src/content/docs/agents/examples/websockets.mdx

@@ -12,7 +12,7 @@ Users and clients can connect to an Agent directly over WebSockets, allowing lon
 
 To enable an Agent to accept WebSockets, define `onConnect` and `onMessage` methods on your Agent.
 
-* `onConnect(connection: Connection, ctx: ConnectionContext)` is called when a client establishes a new WebSocket connection. The original HTTP request, including request headers, cookies and the URL itself, are available on `ctx.request`.
+* `onConnect(connection: Connection, ctx: ConnectionContext)` is called when a client establishes a new WebSocket connection. The original HTTP request, including request headers, cookies, and the URL itself, are available on `ctx.request`.
 * `onMessage(connection: Connection, message: WSMessage)` is called for each incoming WebSocket message. Messages are one of `ArrayBuffer | ArrayBufferView | string`, and you can send messages back to a client using `connection.send()`. You can distinguish between client connections by checking `connection.id`, which is unique for each connected client.
 
 Here's an example of an Agent that echoes back any message it receives:
@@ -55,7 +55,7 @@ export class ChatAgent extends Agent {
 
 ## Connecting clients
 
-The Agent framework includes a useful helper package for connecting directly to your agent (or other agents) from a client application. Import `@cloudflare/agents/client`, create an instance of `AgentClient` and use it to connect to an instance of your Agent:
+The Agent framework includes a useful helper package for connecting directly to your Agent (or other Agents) from a client application. Import `@cloudflare/agents/client`, create an instance of `AgentClient` and use it to connect to an instance of your Agent:
 
 <TypeScriptExample>
 
@@ -120,7 +120,7 @@ function AgentInterface() {
 ```
 </TypeScriptExample>
 
-The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/examples/manage-and-sync-state/) to automatically synchronize state across all clients connected to your agent.
+The `useAgent` hook automatically handles the lifecycle of the connection, ensuring that it is properly initialized and cleaned up when the component mounts and unmounts. You can also [combine `useAgent` with `useState`](/agents/examples/manage-and-sync-state/) to automatically synchronize state across all clients connected to your Agent.
 
 ## Handling WebSocket events
 

src/content/docs/agents/index.mdx

@@ -49,7 +49,7 @@ TODO - refine
 	args={"--", "--template", "cloudflare/agents/starter"}
 />
 
-Head to the [Agents tutorial[(/getting-started/tutorial/) to dive into shipping your first Agent on Cloudflare.
+Head to the [Agents tutorial[(/agents/getting-started/tutorial/) to dive into shipping your first Agent on Cloudflare.
 
 ## Agents platform