add tools and human loop images

Author: rita3ko

src/assets/images/agents/agent-workflow.svg

@@ -2,10 +2,30 @@
 title: Calling LLMs
 pcx_content_type: concept
 sidebar:
-  order: 5
+  order: 6
 
 ---
 
 import { Render } from "~/components";
 
-calling LLMs
+### 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
+- Generating code and technical content
+
+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.

src/assets/images/agents/human-in-the-loop.svg

@@ -0,0 +1,53 @@
+---
+title: Human in the Loop
+pcx_content_type: concept
+sidebar:
+  order: 5
+
+---
+
+import { Render, Note, Aside } from "~/components";
+
+### What is Human-in-the-Loop?
+
+Human-in-the-Loop (HITL) workflows integrate human judgment and oversight into automated processes. These workflows pause at critical points for human review, validation, or decision-making before proceeding. This approach combines the efficiency of automation with human expertise and oversight where it matters most.
+
+![A human-in-the-loop diagram](~/assets/images/agents/human-in-the-loop.svg)
+
+#### 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:
+
+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
+
+### 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:
+- 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>
+
+#### 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.
+
+#### 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.
+
+The system should maintain stability during paused states, ensuring that no work is lost even during extended review periods. Consider implementing automatic checkpointing that allows workflows to be resumed from the last stable state after any interruption.

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

@@ -0,0 +1,45 @@
+---
+title: Tools
+pcx_content_type: concept
+sidebar:
+  order: 4
+
+---
+
+### 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
+
+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
+
+#### 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
+- **Parameter Validation**: Tools specify their input requirements using JSON Schema
+- **Error Handling**: Standardized error reporting and recovery
+- **State Management**: Tools can maintain state across invocations
+
+
+#### Data Processing Tools
+Tools that handle data transformation and analysis are essential for many AI workflows. These might include:
+
+- CSV parsing and analysis
+- Image processing
+- Text extraction
+- Data validation
+

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

@@ -1,5 +1,5 @@
 ---
-title: What are Agents?
+title: Agents
 pcx_content_type: concept
 sidebar:
   order: 2
@@ -8,7 +8,7 @@ sidebar:
 
 import { Render } from "~/components";
 
-### What is an agent? 
+### 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)

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

@@ -8,7 +8,24 @@ sidebar:
 
 import { Render } from "~/components";
 
-TODO - what are agents?
+### What are workflows? 
+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
+
+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
+A workflow typically consists of several key elements:
+
+1. **Input Processing**
+The workflow defines how inputs are received and validated before being processed by the agent. This includes standardizing formats, checking permissions, and ensuring all required information is present.
+2. **Tool Integration**
+Workflows manage how external tools and services are accessed. They handle authentication, rate limiting, error recovery, and ensuring tools are used in the correct sequence.
+3. **State Management**
+The workflow maintains the state of ongoing processes, tracking progress through multiple steps and ensuring consistency across operations.
+4. **Output Handling**
+Results from the agent's actions are processed according to defined rules, whether that means storing data, triggering notifications, or formatting responses.
 
-- terminology
-- diagram: orchestrator / container / task / workflow