update(docs): Enhance details about configuring agent search behavior

www/docs/agents/agent-platform-overview.md

@@ -1,171 +1,88 @@
 ---
 id: agent-platform-overview
-title: Agents
+title: How Vectara agents work
 sidebar_label: Agents
 ---
 
-Vectara Agents enable enterprises to build sophisticated, enterprise-grade intelligent
-applications that go beyond basic question answering. Agents interpret user
-input, reason through context, leverage external tools, and maintain continuity
-across multi-turn interactions.
+Agents are autonomous systems that understand natural language and use tools 
+and reasoning to accomplish tasks. 
 
-Unlike traditional RAG systems that simply retrieve documents and pass them to
-a language model, Vectara agents provide orchestrated workflows capable of
-taking action, retrieving information, invoking APIs, or maintaining user
-sessions.
-
-## What are agents?
-
-Agents provide a comprehensive framework for building AI-powered 
-applications with the following capabilities:
-
-- **Understand context**: Maintain conversation history across multiple 
-  interactions.
-- **Use tools**: Access and manipulate data through a variety of tools, including 
-  corpus search and web search.
-- **Follow instructions**: Execute complex workflows based on customizable 
-  instructions and templates.
-- **Stream responses**: Provide real-time updates as agents process requests.
-
-## What agents can accomplish
-
-| **Desired outcome** | **Workflow** |
-|---|---|
-| **Automate customer support workflows** | <ol><li>Agent handles L1 support</li><li>Searches knowledge bases</li><li>Escalates complex issues</li><li>Creates tickets</li></ol> |
-| **Build intelligent research assistants** | <ol><li>Agent searches multiple data sources</li><li>Synthesizes findings</li><li>Maintains research context across sessions</li></ol> |
-| **Create workflow automation systems** | <ol><li>Agent triggers business processes</li><li>Sends notifications</li><li>Updates CRM systems based on natural language requests</li></ol> |
-| **Develop conversational enterprise tools** | <ol><li>Agent maintains context</li><li>Handles multi-step processes</li><li>Integrates with existing business systems</li></ol> |
-| **Deploy autonomous business processes** | <ol><li>Agent monitors conditions</li><li>Makes decisions</li><li>Executes actions without human intervention</li></ol> |
-
-:::tip Conversational AI Platform
-Agents are perfect for building conversational AI experiences like virtual 
-assistants and chatbots. [**Learn more about Vectara's Conversational AI →**](/docs/agents/conversational-ai)
-:::
-
-## How agents work
-
-Agents use **tools** to access information and take action. Each tool provides 
-a specific capability, such as searching a specific corpus, accessing a web 
-page, or interacting with an external service. When creating or configuring an 
-agent, you select which tools it can use which helps ensure the following:
-
-* A clear separation between orchestration logic (the agent) and the 
-  capabilities provided by tools.
-* Auditable permissions for every data retrieval or external action.
-* Reusable tools that can serve multiple agents.
-
-## Agents
-
-Agents act as the orchestration layer of the platform:
-- Coordinate between different tools and data sources.
-- Maintain conversation context through sessions.
-- Follow customizable instructions to guide behavior.
-- Support streaming responses for real-time interaction.
+## Getting Started
 
-## Tools
+To build your first agent:
 
-Tools provide agents with capabilities to interact with data and external systems:
-- **Corpora Search**: Query your Vectara corpora with semantic search.
-- **Web Search**: Access current information from the internet.
-- **MCP Tools**: Integrate with external services through the [Model Context Protocol (MCP)](mcp).
+1. [**Create an agent**](/docs/console-ui/agents/create-an-agent): Define the agent's name, description, and available tools.
+2. [**Write instructions**](/docs/console-ui/agents/create-an-agent#instructions): Create templates that guide the agent's behavior.
+3. [**Configure tools**](/docs/console-ui/agents/create-an-agent#tools): Set up corpus access permissions and any external integrations.
+4. [**Test agents with sessions**](/docs/console-ui/agents/use-agents): Start conversations and iterate on your configuration.
 
-## Sessions
+## Concepts
 
-Sessions maintain the state of conversations:
-- Track all interactions (also known as events) within a conversation.
-- Preserve context across multiple turns.
-- Enable multi-turn reasoning and follow-up questions.
+The core concept to understand about agents is that their behavior is defined 
+by instructions. The agent uses these instructions alongside information from 
+a conversation session to determine how to respond to user input, including 
+which tools to use.
 
-## Instructions
+These are the other core concepts when it comes to agents:
 
-Instructions guide agent behavior using Velocity templates:
-- Define the agent's persona and objectives.
-- Customize responses based on context.
-- Support dynamic variable substitution.
+* **Tools:** Tools provide agents with capabilities to interact with data and 
+  external systems.
+* **Sessions:** Sessions preserve context throughout a conversation so the agent 
+  can consider prior information when responding to a query.
 
 <div className="mermaid-container">
 ```mermaid
 flowchart TD
     %% Nodes
-    User["User / Application"]
-    Session["**Agent Session**"]
-    Agent["**Agent**"]
+    User["User"]
+    Session["**Agent**"]
+    Agent["**Session**"]
     Inst["**Instructions**"]
     Query["**Agent Query**"]
 
-    %% Tools + execution layer
-    Tool["**Tool**"]
-    ToolServer["**Tool Server**"]
-
-    %% Data/targets
-    Corpus["Corpus Search"]
-    Web["Web Search"]
+    %% Tools layer
+    AvailableTools["**Tools** (Corpora Search, Web Search, Lambda Tools)"]
 
     %% MCP
-    MCP["**MCP Client**"]
+    MCP["**MCP Tool + Client**"]
     ExtMCP["External MCP Server"]
 
     %% Core flow
     User -->|Query| Session
-    Session -->|Provides context| Agent
-    Agent --> Inst
-    Inst --> Query
-    Agent --> Query
-    Query -->|Direct answer| Session
-    Query e4@<==> Tool
-    Tool e5@<==> Query
-
-    %% Internal tool execution paths
-    Tool e3@<--> ToolServer
-    ToolServer e7@<--> Tool
-    ToolServer --> Corpus
-    ToolServer -.-> Web
+    Session -->|Conversation state| Agent
+    Agent --> |Configured with| Inst
+    Inst --> |Guide agent behavior| Query
+    Query --> Session
+
+    %% Tool execution paths
+    Query <--> AvailableTools
 
     %% Optional MCP path (de-emphasized)
-    Tool e2@<--> MCP
-    MCP e6@<--> Tool
+    Query <--> MCP
     MCP -.-> ExtMCP
 
     %% Return to user
-    Query e1@==>|Synthesizes response| Session
-    Session -->|Answer| User
+    Query -->|Synthesizes response| Session
+    Session -->|Response| User
 
     %% Classes for color grouping
-    classDef userEntry fill:#0D2FFF,color:#fff,stroke:#0D2FFF,stroke-width:2px;
-    classDef session fill:#182033,color:#fff,stroke:#0D2FFF,stroke-width:2px;
-    classDef agentic fill:#07E3D7,color:#182033,stroke:#00ABA0,stroke-width:2px;
+    classDef userEntry fill:#182033,color:#fff,stroke:#0D2FFF,stroke-width:2px;
+    classDef session fill:#EEF2F8,color:#182033,stroke:#787878,stroke-width:2px;
+    classDef agentic fill:#EEF2F8,color:#182033,stroke:#787878,stroke-width:2px;
     classDef toolLayer fill:#EEF2F8,color:#182033,stroke:#787878,stroke-width:2px;
     classDef corpus fill:#E9368E,color:#fff,stroke:#E9368E,stroke-width:2px;
-    classDef external fill:#F3F4F6,color:#111827,stroke:#9CA3AF,stroke-width:1.5px,stroke-dasharray: 6 4;
-    classDef mcpTP fill:#FFF4B8,color:#182033,stroke:#FFD700,stroke-width:1.5px,stroke-dasharray: 6 4;
+    classDef external fill:#182033,color:#fff,stroke:#0D2FFF,stroke-width:2px;
+    classDef mcpTP fill:#EEF2F8,color:#182033,stroke:#787878,stroke-width:2px;
 
     %% Assign classes
     class User userEntry;
     class Session session;
     class Agent,Inst,Query agentic;
-    class Tool,ToolServer toolLayer;
-    class Corpus corpus;
-    class Web,ExtMCP external;
+    class AvailableTools toolLayer;
+    class ExtMCP external;
     class MCP mcpTP;
 
-    %% Animations
-    e1@{ animation: slow }
-    e2@{ animation: slow }
-    e3@{ animation: slow }
-    e4@{ animation: slow }
-    e5@{ animation: slow }
-    e6@{ animation: slow }
-    e7@{ animation: slow }
 ```
 </div>
 
-## Getting Started
-
-To build your first agent:
-
-1. [**Create an agent**](/docs/console-ui/agents/create-an-agent): Define the agent's name, description, and available tools.
-2. [**Configure tools**](/docs/console-ui/agents/create-an-agent#tools): Set up corpus access permissions and any external integrations.
-3. [**Write instructions**](/docs/console-ui/agents/create-an-agent#instructions): Create templates that guide the agent's behavior.
-4. [**Test agents with sessions**](/docs/console-ui/agents/use-agents): Start conversations and iterate on your configuration.
-
 

www/docs/agents/agents-quickstart.md

@@ -56,6 +56,11 @@ flowchart LR
 First, let's create a simple research assistant agent that can search the web. 
 This example requires no corpus setup, so you can follow along immediately.
 
+:::tip Tip
+This example only uses the web_search tool. For more details about configuring 
+the `corpora_search` tool, see [**Configure Agent Search Behavior**](/docs/agents/#configure-agent-search-behavior).
+:::
+
 ### Create an agent with the console UI (Recommended)
 
 For your first agent, we recommend using the Console UI. If you need more